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.
Environment Variables
Required:
WEAVIATE_URL - Your Weaviate Cloud cluster URLWEAVIATE_API_KEY - Your Weaviate API key
External Provider Keys (auto-detected):
Set only the keys your collections use, refer to Environment Requirements for more information.
Script Index
Search & Query
- Query Agent - Ask Mode: 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: 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: 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: Use for finding conceptually similar content regardless of exact wording. Best when the intent matters more than specific keywords.
- Keyword Search: 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: 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: 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: 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: 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: Use to retrieve specific objects by ID or strictly filtered subsets of data. Best for precise data retrieval rather than search.
- Import Data: Use this when the user asks to import, load, or ingest a file (CSV, JSON, JSONL, PDF) into a collection.
- Create Example Data: Use to create example data for immediate use of other skills, if no data is available or user requests some toy data.
Recommendations
Start by listing collections if you don't know what's available:
uv run scripts/list_collections.py
Ask the user if they want to create example data if nothing is available and the user requests it. Otherwise continue.
uv run scripts/example_data.py
Get collection details to understand the schema:
uv run scripts/get_collection.py --name "COLLECTION_NAME"
Explore collection data to see values and statistics:
uv run scripts/explore_collection.py "COLLECTION_NAME"
Create a collection if importing a new CSV, JSON, or JSONL file — the collection must exist before importing:
uv run scripts/create_collection.py CollectionName \
--properties '[{"name": "title", "data_type": "text"}, {"name": "body", "data_type": "text"}]'
Do not specify a vectorizer unless the user explicitly requests one.
Import data into an existing collection:
uv run scripts/import.py "data.csv" --collection "CollectionName"
For PDF imports, the collection is created automatically — skip step 5.
Choose the right search type:
- Get AI-powered answers with source citations across multiple collections →
ask.py
- Get raw objects from multiple collections →
query_search.py
- General search →
hybrid_search.py (default)
- Conceptual similarity →
semantic_search.py
- Exact terms/IDs →
keyword_search.py
Output Formats
All scripts support:
- Markdown tables (default and recommended)
- JSON (
--json flag)
Error Handling
Common errors:
WEAVIATE_URL not set → Set the environment variableCollection not found → Use list_collections.py to see available collectionsAuthentication error → Check API keys for both Weaviate and vectorizer providers
1---2name: weaviate3description: 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.4---5
6# Weaviate Database Operations
7
8This 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.
9
10### Weaviate Cloud Instance
11
12If 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).
13
14## Environment Variables
15
16**Required:**
17
18- `WEAVIATE_URL` - Your Weaviate Cloud cluster URL
19- `WEAVIATE_API_KEY` - Your Weaviate API key
20
21**External Provider Keys (auto-detected):**
22Set only the keys your collections use, refer to [Environment Requirements](references/environment_requirements.md) for more information.
23
24## Script Index
25
26### Search & Query
27
28- [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).
29- [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.
30- [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.
31- [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.
32- [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.
33
34### Collection Management
35
36- [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.
37- [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.
38- [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.
39- [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).
40
41### Data Operations
42
43- [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.
44- [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.**
45- [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.
46
47## Recommendations
48
491. **Start by listing collections** if you don't know what's available:
50
51 ```bash
52 uv run scripts/list_collections.py
53 ```
54
552. **Ask the user** if they want to **create example data** if nothing is available and the user requests it. Otherwise continue.
56
57 ```bash
58 uv run scripts/example_data.py
59 ```
60
613. **Get collection details** to understand the schema:
62
63 ```bash
64 uv run scripts/get_collection.py --name "COLLECTION_NAME"
65 ```
66
674. **Explore collection data** to see values and statistics:
68
69 ```bash
70 uv run scripts/explore_collection.py "COLLECTION_NAME"
71 ```
72
735. **Create a collection** if importing a new CSV, JSON, or JSONL file — the collection must exist before importing:
74
75 ```bash
76 uv run scripts/create_collection.py CollectionName \
77 --properties '[{"name": "title", "data_type": "text"}, {"name": "body", "data_type": "text"}]'
78 ```
79 > Do not specify a vectorizer unless the user explicitly requests one.
80
816. **Import data** into an existing collection:
82
83 ```bash
84 uv run scripts/import.py "data.csv" --collection "CollectionName"
85 ```
86 > For PDF imports, the collection is created automatically — skip step 5.
87
887. **Choose the right search type:**
89 - Get AI-powered answers with source citations across multiple collections → `ask.py`
90 - Get raw objects from multiple collections → `query_search.py`
91 - General search → `hybrid_search.py` (default)
92 - Conceptual similarity → `semantic_search.py`
93 - Exact terms/IDs → `keyword_search.py`
94
95## Output Formats
96
97All scripts support:
98
99- **Markdown tables** (default and recommended)
100- **JSON** (`--json` flag)
101
102## Error Handling
103
104Common errors:
105
106- `WEAVIATE_URL not set` → Set the environment variable
107- `Collection not found` → Use `list_collections.py` to see available collections
108- `Authentication error` → Check API keys for both Weaviate and vectorizer providers
gabrielmoreira