# weaviate

Lets your agent search, query and manage Weaviate vector database collections, including imports from PDF, CSV and JSON files.

Skill by Weaviate. Category: Data and backend.

## Install

Project (for this project only):

```sh
npx skills add weaviate/agent-skills --skill weaviate
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add weaviate/agent-skills --skill weaviate -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Warn
- Runlayer: Warn
- ZeroLeaks: Pass

Installs: 401. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/weaviate/agent-skills/weaviate)

## Source

[Open the source](https://github.com/weaviate/agent-skills/tree/HEAD/skills/weaviate). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
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.

## 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.** 
- [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; a PDF import is refused.** `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, and free-tier clusters refuse that create with `422 CONFIG_NOT_ALLOWED`; if the user asks for a PDF import, tell them it is refused on a free-tier cluster and 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:

   ```bash
   uv run 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.

   ```bash
   uv run scripts/example_data.py
   ```

3. **Get collection details** to understand the schema:

   ```bash
   uv run scripts/get_collection.py --name "COLLECTION_NAME"
   ```

4. **Explore collection data** to see values and statistics:

   ```bash
   uv run scripts/explore_collection.py "COLLECTION_NAME"
   ```

5. **Create a collection** if importing a new CSV, JSON, or JSONL file — the collection must exist before importing:

   ```bash
   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.

6. **Import data** into an existing collection:

   ```bash
   uv run scripts/import.py "data.csv" --collection "CollectionName"
   ```
   > For PDF imports, the collection is created automatically — skip step 5.

7. **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 variable
- `Collection not found` → Use `list_collections.py` to see available collections
- `Authentication error` → Check API keys for both Weaviate and vectorizer providers
````

- Previous: [effect-v3-to-v4](https://syn4pse.dev/terminal/effect-v3-to-v4.md)
- Next: [weaviate-cookbooks](https://syn4pse.dev/terminal/weaviate-cookbooks.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
