Skip to content
Nappai Documentation

Astra DB

Astra DB stores documents in a DataStax Astra DB collection and searches it by meaning.

A vector database stores texts so they can be searched by meaning, not just by exact words. That way an agent can find the paragraph of a manual that answers a question even if it uses different words.

When to use it

  • You already use Astra DB and want your flows to store and search in it.
  • You want Astra to compute the text representation itself with its vectorize option.
  • You need a cloud-managed vector database.

Configuration

The Operation field decides what the component does, and the fields and outputs change with your choice:

  • Add (default): stores in the database the documents it receives in Ingest Data.
  • Search: finds the documents closest to the text in Search Query.
  • Retriever: offers the database as a search engine for another component to use, for example an agent or a question-answering chain.

You need an Astra DB API credential with your Astra database token and address. See Credentials.

FieldWhat it does
Credential (required)The Astra DB API credential with the connection details.
OperationWhat the component does: Add, Search or Retriever.
Ingest Data (required)With Add. The documents to store, usually those coming out of a text splitter or a file loader.
Search QueryWith Search. The text to search for. If left empty, nothing is returned.
EmbeddingThe connector where you plug the component that turns texts into numbers to compare them by meaning, such as OpenAI Embeddings. Always use the same one to store and to search.
Collection Name (required)The Astra collection where documents are stored.

Advanced options

FieldWhat it does
Number Of ResultsHow many documents each search returns. Default: 4.
NamespaceAstra namespace that holds the collection. Empty, the default one.
MetricHow similarity is measured when the collection is created: cosine, dot_product or euclidean.
Pre Delete CollectionDeletes the collection before storing. Off by default; use with care.
Setup ModeHow the collection is set up: Sync (default), Async or Off.
Batch SizeTogether with Bulk Insert Batch Concurrency, Bulk Insert Overwrite Concurrency, Bulk Delete Concurrency, Metadata Indexing Include, Metadata Indexing Exclude and Collection Indexing Policy: Astra performance and indexing settings. Leave them empty unless whoever runs your database says otherwise.
Search TypeHow to search: Similarity, Similarity with score threshold, MMR (Max Marginal Relevance). Similarity returns the closest; with a threshold, only those above Search Score Threshold; MMR looks for close but varied results.
Search Score ThresholdMinimum similarity score, only with the threshold search. Default: 0.0.
Search Metadata FilterField and value pairs to search only among the documents that match them.

In Astra DB the connector is called Embedding Or Astra Vectorize: it accepts an embeddings component or Astra’s vectorize configuration, see Astra Vectorize.

Output

The outputs depend on Operation:

  • Results: with Add and Search. With Search, the list of documents found, which you can pass to a prompt or an agent.
  • Vector Store: with Add. The database, to connect it to components that work with a vector database.
  • Retriever: with Retriever. The search engine, to connect it to components that ask for one.

In tool mode, an agent can use the component to search by itself. See Tool Mode.

Example

An insurer keeps its policies in Astra DB.

  1. Connect the policies, split into pieces, to Ingest Data of Astra DB with Operation set to Add.
  2. Choose the Astra DB API credential, type the collection and connect an embeddings component.
  3. Run the flow and, in another one, search with Operation set to Search.