/weaviate

name: weaviate
description: Search, query, and manage Weaviate vector database collections. Use for semantic search, hybrid search, keyword search, natural language queries with AI-generated answers, collection management, data exploration, filtered fetching, data imports from PDF/CSV/JSON/JSONL files, create example data and collection creation.

Weaviate Database Operations

This skill provides comprehensive access to Weaviate vector databases including search operations, natural language queries, schema inspection, data exploration, filtered fetching, collection creation, and data imports.

Weaviate Cloud Instance

If the user does not have an instance yet, direct them to the cloud console to register and create a free sandbox. Create a Weaviate instance via [Weaviate Cloud](https://console.weaviate.cloud/signin?utm_source=github&utm_campaign=agent_skills).

Environment Variables

**Required:**

• `WEAVIATE_URL` - Your Weaviate Cloud cluster URL
• `WEAVIATE_API_KEY` - Your Weaviate API key

**External Provider Keys (auto-detected):** Set only the keys your collections use, refer to [Environment Requirements](references/environment_requirements.md) for more information.

Running Scripts

Commands start from `SKILL_DIR`, the absolute path of the folder that contains this `SKILL.md`. Replace it before running, and run the command from the user's project so file arguments such as `data.csv` resolve against the project:

uv run /path/to/skills/weaviate/scripts/list_collections.py

Script Index

Search & Query

• [Query Agent - Ask Mode](references/ask.md): Use when the user wants a **direct answer** to a question based on collection data. The Query Agent synthesizes information from one or more collections and returns a structured response with source citations (collection name and object ID).
• [Query Agent - Search Mode](references/query_search.md): Use when the user wants to **explore or browse raw objects** across one or more collections. Unlike ask mode, this returns the actual data objects rather than a synthesized answer.
• [Hybrid Search](references/hybrid_search.md): **Default choice for most searches.** Provides a good balance of semantic understanding and exact keyword matching. Use this when you are unsure which search type to pick.
• [Semantic Search](references/semantic_search.md): Use for finding **conceptually similar content** regardless of exact wording. Best when the intent matters more than specific keywords.
• [Keyword Search](references/keyword_search.md): Use for finding **exact terms, IDs, SKUs, or specific text patterns**. Best when precise keyword matching is needed rather than semantic similarity.

Collection Management

• [List Collections](references/list_collections.md): Use to **discover what collections exist** in the Weaviate instance. This should typically be the first step before performing any search or data operation.
• [Get Collection Details](references/get_collection.md): Use to **understand a collection's schema** — its properties, data types, vectorizer configuration, replication factor, and multi-tenancy status. Helpful before running searches or imports.
• [Explore Collection](references/explore_collection.md): Use to **analyze data distribution, top values, and inspect actual content** in a collection. Helpful for understanding what data looks like before querying.
• [Create Collection](references/create_collection.md): Use to **create new collections with custom schemas** before importing data. Do not specify a vectorizer unless the user explicitly requests one (the default `text2vec_weaviate` is used).

Data Operations

• [Fetch and Filter](references/fetch_filter.md): Use to **retrieve specific objects by ID** or **strictly filtered subsets** of data. Best for precise data retrieval rather than search.
• [Import Data](references/import_data.md): **Use this when the user asks to import, load, or ingest a file (CSV, JSON, JSONL, PDF) into a collection.** A PDF import that has to create its collection is refused on a free-tier cluster; see [Free-Tier Clusters](#free-tier-clusters).
• [Create Example Data](references/example_data.md): Use to create example data for immediate use of other skills, if no data is available or user requests some toy data.

Free-Tier Clusters

Weaviate Cloud free-tier clusters have limits that can change; if a script's error contradicts this section, trust the error.

• **One collection only.** A second create is refused with `429 USAGE_LIMIT_EXCEEDED` ("collections count limit of 1 reached"). Run `list_collections.py` first. If a collection exists, import into it instead of creating another, and ask the user before using the only slot.
• **`example_data.py` uses that slot.** `example_data.py` creates one collection whose name depends on `--domain` (`AI_Arxiv` for the default `academic`; `Income_Tax_Returns`, `Product_Catalog`, `Hair_Medical` or `IT_Support_Tickets` for the others). Do not run it unless the user agrees to spend the slot. `import.py` on a PDF creates its collection automatically when it is absent, and a PDF import that has to create its collection is refused on a free-tier cluster with `422 CONFIG_NOT_ALLOWED`; if the user asks for one, let them decide. No script here deletes a collection.
• **Only the `hfresh` vector index is accepted.** A create that asks for another type (for example `hnsw`) is refused with `422 CONFIG_NOT_ALLOWED`. The scripts pin `weaviate-client` 4.23.1, which leaves the index type to the server; older clients request `hnsw` and are refused. If a `422` says `hnsw` is not allowed on 4.23.1 or newer, tell the user rather than retrying.

Recommendations

1. **Start by listing collections** if you don't know what's available:

   uv run SKILL_DIR/scripts/list_collections.py

2. **Ask the user** if they want to **create example data** if nothing is available and the user requests it. Otherwise continue.