Weaviate Database Operations
Iron Law
ALWAYS LIST COLLECTIONS FIRST — never assume collection names or schemas exist.
Running any search or import against a non-existent collection returns a cryptic error. list_collections.py takes under 1 second and prevents every "collection not found" failure.
Process
- List collections — discover what exists before any operation
- Ask user — confirm which collection(s) to target, or offer example data if empty
- Get collection details — inspect schema, vectorizer, multi-tenancy status
- Explore collection — check data distribution and sample objects
- Run operation — search, import, fetch, or ask
Script Index
| Script |
Command |
When to Use |
ask.py |
uv run scripts/ask.py |
AI-generated answer with source citations across collections |
query_search.py |
uv run scripts/query_search.py |
Browse raw objects across collections (no synthesis) |
hybrid_search.py |
uv run scripts/hybrid_search.py |
Default search — BM25 + vector, balanced recall |
semantic_search.py |
uv run scripts/semantic_search.py |
Conceptual similarity, intent matters more than keywords |
keyword_search.py |
uv run scripts/keyword_search.py |
Exact terms, IDs, SKUs, specific text patterns |
list_collections.py |
uv run scripts/list_collections.py |
Discover all collections in the instance |
get_collection.py |
uv run scripts/get_collection.py --name NAME |
Schema, vectorizer config, multi-tenancy status |
explore_collection.py |
uv run scripts/explore_collection.py NAME |
Data distribution, top values, sample objects |
create_collection.py |
uv run scripts/create_collection.py |
Create collection with custom schema |
fetch_filter.py |
uv run scripts/fetch_filter.py |
Retrieve by ID or structured filter criteria |
import.py |
uv run scripts/import.py data.csv --collection NAME |
Bulk import from CSV, JSON, or JSONL |
example_data.py |
uv run scripts/example_data.py |
Load toy data when no real data exists |
Reference Files
| File |
Content |
When to Use |
references/ask.md |
Query Agent ask mode — answer synthesis, source citation format |
Building Q&A interfaces |
references/query_search.md |
Query Agent search mode — raw object retrieval |
Browsing/exploring objects |
references/hybrid_search.md |
Hybrid BM25 + vector, alpha tuning, fusion types |
General-purpose search |
references/semantic_search.md |
nearText query patterns, distance thresholds |
Conceptual/intent-based search |
references/keyword_search.md |
BM25 patterns, tokenization, exact match |
Keyword/ID/SKU lookup |
references/list_collections.md |
Collection discovery, schema overview |
Discovery step |
references/get_collection.md |
Schema inspection, vectorizer config, properties |
Pre-query schema check |
references/explore_collection.md |
Data stats, value distribution, sample objects |
Understanding data shape |
references/create_collection.md |
Collection creation, properties, vectorizer config |
Schema design |
references/fetch_filter.md |
ID fetch, where filter, structured retrieval |
Precise data retrieval |
references/import_data.md |
Batch import, error handling, UUID strategy |
Data ingestion |
references/example_data.md |
Pre-built toy datasets |
Demos, testing |
references/environment_requirements.md |
All env vars and provider keys |
Environment setup |
Environment Variables
Required:
WEAVIATE_URL — Weaviate Cloud cluster URLWEAVIATE_API_KEY — Weaviate API key
External provider keys (set only what your collections use):
→ See references/environment_requirements.md for the full list.
If the user has no Weaviate instance, direct them to Weaviate Cloud to create a free sandbox, then run /weaviate:quickstart.
Documentation Sources
Before generating code, consult these sources for current APIs:
| Source |
Tool |
Purpose |
| Weaviate Python v4 |
weaviate-docs MCP |
Collection creation, query APIs, vectorizer config |
| Weaviate general docs |
weaviate-docs MCP |
Best practices, multi-tenancy, named vectors |
| Python client fallback |
Context7 MCP |
weaviate-client package, async patterns |
Output Formats
All scripts support --json flag. Default output is markdown tables.
Error Handling
| Error |
Cause |
Fix |
WEAVIATE_URL not set |
Missing env var |
Export env var in terminal |
Collection not found |
Wrong name or not yet created |
Run list_collections.py first |
Authentication error |
Bad API key |
Check both Weaviate key and vectorizer provider key |
Dimension mismatch |
Collection vectorizer ≠ query vectorizer |
Match vectorizer on import and query |
Post-Code Review
After writing Weaviate code, dispatch:
weaviate-schema-reviewer — collection schema, v4 API, multi-tenancy, distance metricrag-pipeline-reviewer — if building a retrieval pipeline
1---2name: weaviate3description: Search, query, and manage Weaviate vector database collections. Use when running semantic search, hybrid search, keyword search, natural language Q&A with source citations, collection schema inspection, data exploration, filtered fetching, bulk imports, or creating example data. Triggers: 'Weaviate', 'vector search', 'hybrid search', 'semantic search', 'Query Agent', 'collection management', 'import data', 'explore collection'.4---56# Weaviate Database Operations78## Iron Law910**ALWAYS LIST COLLECTIONS FIRST — never assume collection names or schemas exist.**1112Running any search or import against a non-existent collection returns a cryptic error. `list_collections.py` takes under 1 second and prevents every "collection not found" failure.1314## Process15161. **List collections** — discover what exists before any operation172. **Ask user** — confirm which collection(s) to target, or offer example data if empty183. **Get collection details** — inspect schema, vectorizer, multi-tenancy status194. **Explore collection** — check data distribution and sample objects205. **Run operation** — search, import, fetch, or ask2122## Script Index2324| Script | Command | When to Use |25|--------|---------|-------------|26| `ask.py` | `uv run scripts/ask.py` | AI-generated answer with source citations across collections |27| `query_search.py` | `uv run scripts/query_search.py` | Browse raw objects across collections (no synthesis) |28| `hybrid_search.py` | `uv run scripts/hybrid_search.py` | **Default search** — BM25 + vector, balanced recall |29| `semantic_search.py` | `uv run scripts/semantic_search.py` | Conceptual similarity, intent matters more than keywords |30| `keyword_search.py` | `uv run scripts/keyword_search.py` | Exact terms, IDs, SKUs, specific text patterns |31| `list_collections.py` | `uv run scripts/list_collections.py` | Discover all collections in the instance |32| `get_collection.py` | `uv run scripts/get_collection.py --name NAME` | Schema, vectorizer config, multi-tenancy status |33| `explore_collection.py` | `uv run scripts/explore_collection.py NAME` | Data distribution, top values, sample objects |34| `create_collection.py` | `uv run scripts/create_collection.py` | Create collection with custom schema |35| `fetch_filter.py` | `uv run scripts/fetch_filter.py` | Retrieve by ID or structured filter criteria |36| `import.py` | `uv run scripts/import.py data.csv --collection NAME` | Bulk import from CSV, JSON, or JSONL |37| `example_data.py` | `uv run scripts/example_data.py` | Load toy data when no real data exists |3839## Reference Files4041| File | Content | When to Use |42|------|---------|-------------|43| `references/ask.md` | Query Agent ask mode — answer synthesis, source citation format | Building Q&A interfaces |44| `references/query_search.md` | Query Agent search mode — raw object retrieval | Browsing/exploring objects |45| `references/hybrid_search.md` | Hybrid BM25 + vector, alpha tuning, fusion types | General-purpose search |46| `references/semantic_search.md` | nearText query patterns, distance thresholds | Conceptual/intent-based search |47| `references/keyword_search.md` | BM25 patterns, tokenization, exact match | Keyword/ID/SKU lookup |48| `references/list_collections.md` | Collection discovery, schema overview | Discovery step |49| `references/get_collection.md` | Schema inspection, vectorizer config, properties | Pre-query schema check |50| `references/explore_collection.md` | Data stats, value distribution, sample objects | Understanding data shape |51| `references/create_collection.md` | Collection creation, properties, vectorizer config | Schema design |52| `references/fetch_filter.md` | ID fetch, `where` filter, structured retrieval | Precise data retrieval |53| `references/import_data.md` | Batch import, error handling, UUID strategy | Data ingestion |54| `references/example_data.md` | Pre-built toy datasets | Demos, testing |55| `references/environment_requirements.md` | All env vars and provider keys | Environment setup |5657## Environment Variables5859**Required:**60- `WEAVIATE_URL` — Weaviate Cloud cluster URL61- `WEAVIATE_API_KEY` — Weaviate API key6263**External provider keys** (set only what your collections use):64→ See `references/environment_requirements.md` for the full list.6566If the user has no Weaviate instance, direct them to [Weaviate Cloud](https://console.weaviate.cloud/) to create a free sandbox, then run `/weaviate:quickstart`.6768## Documentation Sources6970Before generating code, consult these sources for current APIs:7172| Source | Tool | Purpose |73|--------|------|---------|74| Weaviate Python v4 | `weaviate-docs` MCP | Collection creation, query APIs, vectorizer config |75| Weaviate general docs | `weaviate-docs` MCP | Best practices, multi-tenancy, named vectors |76| Python client fallback | `Context7` MCP | `weaviate-client` package, async patterns |7778## Output Formats7980All scripts support `--json` flag. Default output is markdown tables.8182## Error Handling8384| Error | Cause | Fix |85|-------|-------|-----|86| `WEAVIATE_URL not set` | Missing env var | Export env var in terminal |87| `Collection not found` | Wrong name or not yet created | Run `list_collections.py` first |88| `Authentication error` | Bad API key | Check both Weaviate key and vectorizer provider key |89| `Dimension mismatch` | Collection vectorizer ≠ query vectorizer | Match vectorizer on import and query |9091## Post-Code Review9293After writing Weaviate code, dispatch:94- `weaviate-schema-reviewer` — collection schema, v4 API, multi-tenancy, distance metric95- `rag-pipeline-reviewer` — if building a retrieval pipeline
kumaran-is