Skip to content

← Training overview

5. Vector store backends

The consumer agent's SEARCH, DEFINITION, and USAGE skills fall back to semantic search when an exact catalog lookup returns nothing. That semantic search needs somewhere to keep the embedded business descriptions — a vector store. Since version 0.3.1.37 you can choose between two backends: ChromaDB (default, local) and the Teradata Enterprise Vector Store (in-database).

Why a vector store at all

build_vector_index() reads the three business-dictionary tables and creates three collections:

Collection Source Used by
objects FS_BUSINESS_DICTIONARY_OBJECTS SEARCH (object-level matches)
sections FS_BUSINESS_DICTIONARY_SECTIONS SEARCH (FEATURE_THEMES, BUSINESS_QUESTIONS)
columns FS_BUSINESS_DICTIONARY_COLUMNS DEFINITION (per-feature descriptions)

Embeddings are computed once and re-queried on every chatbot turn that needs them. Without a vector store, the agent can only answer questions that match catalog names verbatim.

Backend choice at a glance

Chroma (default) Teradata Vector Store
Where vectors live Local file system or a separate Chroma HTTP server Inside Vantage, alongside your features
Governance Outside Teradata RBAC Uses Teradata privileges (DB role-based)
Setup cost pip install only Requires Enterprise Vector Store entitlement
Embedding source LangChain Embeddings (your vLLM / TEI / OpenAI) LangChain or in-DB TeradataAI
Incremental update Per-id upsert Tries add_documents, falls back to rebuild
Best for Local dev, notebooks, single-user demos Shared deployments, governed environments, "no data leaves Vantage" mandates

ChromaDB — and its limitations

Chroma is the default because it works out of the box and needs no infrastructure. Two operating modes:

tdfs4ds.VECTOR_STORE_BACKEND = 'chroma'   # default
tdfs4ds.CHROMA_MODE = 'local'             # persist to disk
tdfs4ds.CHROMA_PATH = './tdfs4ds_chroma'  # persist directory

# or
tdfs4ds.CHROMA_MODE = 'server'            # connect to a Chroma server
tdfs4ds.CHROMA_HOST = 'localhost'
tdfs4ds.CHROMA_PORT = 8000

Each feature store has its own three Chroma collections, tdfs4ds__<database>__objects / _sections / _columns (since 0.3.3.15), so switching stores never wipes another store's embeddings, and a search covers every attached store (connect(databases_readonly=[...])). The collections named tdfs4ds_objects / _sections / _columns by earlier versions are no longer used: the first build after upgrading re-embeds the primary store once.

Indexing date. Each build records, per store, the database's time when it started. The next build of the primary store reads only the documentation written since then (and the list of current rows, so documentation that was removed also leaves the index), and the Maintenance panel says whether a store's index is behind:

from tdfs4ds.agent.vector_index import index_freshness
index_freshness()            # {'state': 'behind', 'changed': 3, 'sources': {...}}
index_freshness('DB_PROD')   # a read-only store: 'unknown' (compared row by row at its next build)

A changed embedding model, force_rebuild=True or a read-only store use the full row-by-row comparison.

Be aware of these limitations before promoting Chroma beyond development:

  • Single-machine, single-process. The local persist directory uses file-system locks; two concurrent Python processes writing to the same directory can corrupt the index.
  • Separate process in server mode. CHROMA_MODE='server' requires you to run and operate a Chroma HTTP daemon — that's another binary to manage, monitor, and back up.
  • No Teradata governance. Chroma sits outside Teradata RBAC; anyone with file-system or HTTP access to the index can read the embedded business descriptions, regardless of their Teradata privileges.
  • Client-side embedding. Vectors are computed by the Python client through your LangChain Embeddings object, which can hit your LLM proxy's rate-limits. tdfs4ds throttles to batches of 8 to soften this, but it is still a client-side bottleneck.

Teradata Vector Store

The Teradata backend stores the same three collections as named vector stores inside Vantage:

tdfs4ds.VECTOR_STORE_BACKEND         = 'teradata'
tdfs4ds.TERADATA_VECTOR_STORE_PREFIX = 'tdfs4ds'
# becomes: tdfs4ds_objects, tdfs4ds_sections, tdfs4ds_columns

Two embedding paths are supported. By default the Teradata backend reuses the same LangChain Embeddings object as Chroma — so if you have a working vLLM / TEI / OpenAI / Bedrock setup, switching VECTOR_STORE_BACKEND is the only change you need. TeradataVectorStore accepts a LangChain Embeddings at its embedding= argument.

For environments where no client-side embedding is allowed, the in-database TeradataAI path produces embeddings inside Vantage:

tdfs4ds.TERADATA_AI_API_TYPE   = 'aws'                         # also: azure, gcp, nim, hugging_face, onnx
tdfs4ds.TERADATA_AI_MODEL_NAME = 'amazon.titan-embed-text-v2:0'
tdfs4ds.TERADATA_AI_REGION     = 'us-west-2'
tdfs4ds.TERADATA_AI_ACCESS_KEY = os.getenv('AWS_ACCESS_KEY')

Known limitation: the Enterprise Vector Store API does not yet guarantee per-id upsert, so build_vector_index(force_rebuild=False) first tries add_documents and falls back to a destroy + rebuild if the call is not supported.

Switching backends

The two functions the chatbot already uses — build_vector_index and search_vector_index — dispatch on VECTOR_STORE_BACKEND at call time, so flipping the switch and re-indexing is the whole operation:

tdfs4ds.VECTOR_STORE_BACKEND = 'teradata'
from tdfs4ds.agent import build_vector_index
build_vector_index(force_rebuild=True)

No other code changes are needed; the SEARCH skill keeps using search_vector_index(...) and the chatbot launcher is the same.

Learn more