Query and manage Weaviate vector database collections

Weaviate Database Operations gives an agent comprehensive access to Weaviate vector databases through official scripts run with uv: search, natural language queries, schema inspection, data exploration, filtered fetching, collection creation and data import. It is an official Weaviate skill under the BSD-3-Clause license. If the user has no instance yet, they can register for Weaviate Cloud and create a free sandbox.

Configuration is through environment variables. WEAVIATE_URL (the cluster URL) and WEAVIATE_API_KEY are required. External inference provider keys are needed only if a collection uses that provider, and they are not forwarded automatically: set WEAVIATE_PROVIDER_KEYS to a comma-separated allowlist such as OPENAI_API_KEY,COHERE_API_KEY. Supported providers include Anthropic, Anyscale, AWS, Cohere, Databricks, Friendli, Google Vertex AI and AI Studio, HuggingFace, Jina AI, Mistral, NVIDIA, OpenAI, Azure OpenAI, Voyage AI and xAI, each mapped to a specific X-...-Api-Key header sent to Weaviate.

The scripts fall into three groups.

• Search and query. Ask mode (ask.py) uses the Query Agent to synthesize a direct answer with source citations (collection name and object ID) across one or more collections. Query search mode (query_search.py) returns the raw objects instead. Hybrid search is the default for most searches, balancing semantic understanding and keyword matching with an --alpha parameter (default 0.7, where 1.0 is pure vector and 0.0 pure keyword). Semantic search finds conceptually similar content, and keyword search finds exact terms, IDs and SKUs. Search scripts take --query, --collection, --limit (default 10), --properties, --target-vector for named vectors and --json.
• Collection management. list_collections.py discovers what exists and is usually the first step; get_collection.py shows a schema with properties, data types, vectorizer configuration, replication factor and multi-tenancy status; explore_collection.py reports per-type metrics (text counts and top 5 values; min, max, mean, median, mode and sum for numbers; true and false percentages for booleans; min, max, median and mode for dates) plus sample objects, with --no-metrics for speed; and create_collection.py creates collections with custom schemas.
• Data operations. fetch_filter.py retrieves objects by UUID, by filters or as a random sample; import.py loads CSV, JSON, JSONL or PDF files; and example_data.py creates toy data.

Use it to inspect Weaviate collections, schemas or data distribution; to run semantic, hybrid, keyword, filtered or Query Agent searches; to import CSV, JSON, JSONL or PDF data; and to create example data or a collection for a Weaviate-backed workflow.

It needs a reachable Weaviate instance and valid credentials. Import, collection creation and Query Agent operations can change or expose user data, so confirm the target instance and collection before running scripts. The scripts are Weaviate-focused and do not replace data governance, backup or production migration procedures.

The recommended order is to list collections first:

uv run scripts/list_collections.py

Then offer example data if nothing exists and the user wants it (domains are academic, finance, ecommerce, medical and customer support, each downloaded from Hugging Face into its own collection), get collection details, explore the data, create a collection if importing a new CSV, JSON or JSONL file, import, and choose a search type. Errors are handled simply: if WEAVIATE_URL is not set, set the variable; if a collection is not found, list the available ones; and for authentication errors, check the API keys for both Weaviate and the vectorizer providers. All scripts print Markdown tables by default and JSON with --json.

When creating a collection, do not specify a vectorizer unless the user asks; the default is text2vec_weaviate, and 17 vectorizer options are supported, including OpenAI, Cohere, HuggingFace, Jina, Voyage, Contextionary, Transformers, Ollama, CLIP and none. Collection and property descriptions are strongly recommended because the Query Agent reads them to choose collections and build queries; good descriptions include units, formats and valid values. Property options include tokenization (word, lowercase, whitespace or field), index_filterable, index_searchable and index_range_filters (default false, so set it to true for numeric or date fields that will be range-filtered). Supported data types are text, boolean, int, number, date, uuid, geoCoordinates, phoneNumber, blob and object, with array variants. Multi-tenancy and auto tenant creation are optional. Inspect a few sample rows before inferring the schema, and note that id, _id and _additional are reserved names.

Filters use JSON with operators equal, not_equal, less_than, less_or_equal, greater_than, greater_or_equal, like, contains_any, contains_all and is_none, combined with and or or, or as a list with implicit AND.

Imports need a header row in CSV files whose columns match property names, an array of objects in JSON (loaded fully into memory, so JSONL is preferred for large data because it streams), and one object per line in JSONL. Values are converted to the schema type with fallbacks, dates gain an RFC3339 time, and empty values are skipped. Options include --mapping to rename fields, --skip-fields, --tenant and --batch-size (default 100); renaming a reserved field such as id is preferred over dropping it when it holds meaningful data. PDFs are converted page by page into base64 JPEG objects with page number and file name, the collection is created automatically for multimodal vectors, later runs append, and poppler must be installed.

It works with Weaviate Cloud, the Weaviate Query Agent, Hugging Face datasets, the listed inference providers, uv and poppler for PDF conversion.

It suits developers and data teams building semantic or hybrid search on Weaviate who want safe, scripted ways to explore, load and query collections.