> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Weaviate (external store)

> Connect your Weaviate cluster — GraphQL queries, nearText or nearVector mode.

# Weaviate

Agentheya calls Weaviate's GraphQL API directly (no SDK). Two query modes are supported, chosen by a single toggle:

* **`use_built_in_vectorizer: true`** — your collection has a configured vectorizer module (`text2vec-openai`, `text2vec-cohere`, etc). Queries use `nearText`: Weaviate embeds the query string itself, billed to your Weaviate / vectorizer account. You do **not** need to supply embedding fields.
* **`use_built_in_vectorizer: false`** — your collection's vectorizer is `none` or you want Agentheya to embed the query externally. Queries use `nearVector`: Agentheya embeds with your chosen provider, then sends the vector to Weaviate.

## Connection settings

| Field                              | Required | Notes                                                                                                                                            |
| ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `weaviate_url`                     | yes      | Cluster base URL (`https://my-cluster.weaviate.network`). Trailing slash optional.                                                               |
| `weaviate_class`                   | yes      | The collection / class name to query (e.g. `Document`).                                                                                          |
| `weaviate_api_key`                 | no       | Cluster auth key. Empty allowed for fully-open clusters. Encrypted at rest.                                                                      |
| `weaviate_use_built_in_vectorizer` | no       | Default `false`. When `true`, queries use `nearText`; embedding fields below are not needed.                                                     |
| `text_field`                       | yes      | The property on each object that holds the chunk text. Default `content`.                                                                        |
| `title_field`                      | no       | Optional title property used for citations.                                                                                                      |
| `source_field`                     | no       | Optional source / URL property used for citations.                                                                                               |
| `top_k`                            | no       | Hits to fetch (1–50, default 8).                                                                                                                 |
| `filter`                           | no       | Weaviate `where` filter object. Native Weaviate shape — `{path, operator, valueString}` / `{operator: "And", operands: [...]}`. Passed verbatim. |

## Embedding settings

Required only when `weaviate_use_built_in_vectorizer` is `false`.

| Field                  | Notes                                        |
| ---------------------- | -------------------------------------------- |
| `embedding_provider`   | One of `openai`, `voyage`, `cohere`.         |
| `embedding_model`      | Model id matching how your data was indexed. |
| `embedding_api_key`    | API key for the provider. Encrypted at rest. |
| `embedding_dimensions` | Optional sanity check.                       |

## Common shapes

**Cluster with built-in `text2vec-openai`**:

```json theme={null}
{
  "kind": "weaviate",
  "name": "Acme KB",
  "weaviate_url": "https://acme-kb.weaviate.network",
  "weaviate_class": "Article",
  "weaviate_api_key": "WCDS-...",
  "weaviate_use_built_in_vectorizer": true,
  "text_field": "content",
  "title_field": "title",
  "source_field": "url",
  "top_k": 8
}
```

**Self-vectorized cluster, English filter**:

```json theme={null}
{
  "kind": "weaviate",
  "name": "Acme docs (English only)",
  "weaviate_url": "https://acme-docs.weaviate.network",
  "weaviate_class": "Doc",
  "weaviate_api_key": "WCDS-...",
  "weaviate_use_built_in_vectorizer": false,
  "embedding_provider": "openai",
  "embedding_model": "text-embedding-3-small",
  "embedding_api_key": "sk-...",
  "embedding_dimensions": 1536,
  "filter": {
    "path": ["lang"],
    "operator": "Equal",
    "valueString": "en"
  },
  "text_field": "content",
  "top_k": 10
}
```

## "Test connection" button

Hits `GET <url>/v1/meta`. If credentials work and `use_built_in_vectorizer` is `false`, it also runs an embedding round-trip with the configured provider so the dimensions can be verified up front.

## Gotchas

* **Filter shape**: Weaviate's `where` syntax uses bare-word enum values for `operator` (e.g. `Equal`, `GreaterThan`, `And`, `Or`). Agentheya's serializer treats CamelCase strings as enum keywords and other strings as literals — you generally don't need to think about this, but if you embed a value that happens to be CamelCase you'll see a GraphQL error.
* **Class name casing**: Weaviate class names are case-sensitive. `Document` and `document` are different classes.
* **Anonymous clusters**: leave `weaviate_api_key` empty. The Authorization header is omitted entirely.
* **certainty vs distance**: Weaviate may return either depending on the vectorizer module. Agentheya prefers `certainty` and falls back to `1 - distance` when only `distance` is present, so scores are always 0..1 with higher = better.