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:

{
  "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:

{
  "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.