Connecting to an Astra DB content repository

Connect an Astra DB content repository to support high-performance vector and hybrid search. At run time, the agent queries Astra DB to retrieve relevant content for accurate, context-based results.

Astra DB is a vector-enabled database that improves retrieval accuracy for both structured and unstructured data. Agent knowledge supports the following Astra DB search types: vector search, lexical, or keyword search, hybrid search, which combines both vector search and lexical search in a single step for improved accuracy. For vector search, agent knowledge supports Astra DB client embedding, along with server embedding. Server embedding does not require an extra callout to an embedding model to embed the query from watsonx Orchestrate. Agent knowledge supports the search on unstructured data and structured data that is stored in Astra DB collections and tables.

Use the following products or tools to connect to an Astra DB repository:

Astra DB, where you provision the database instance.
watsonx.ai (optional), used to manage embeddings with IBM services. To use third-party embedding models, integrate them through the Agent Development Kit (ADK). For more information, see Managing custom LLMs with the AI gateway.
agent builder, where you build agents and set up the connection to Astra DB.

Comply with the prerequisites for connecting Astra DB before you start the procedure.

Prerequisites for connecting to Astra DB

You must have an active Astra DB account.
Provision an Astra DB instance in your account.
Create an API key to authenticate the connection.
Ensure that you have the required access role in agent builder to create a knowledge source.

Connecting to the Astra DB instance

Use data on your Astra DB instance to connect your agent:

On the agent configuration page, go to the Knowledge section.
Click Choose knowledge +.
Under Add source, click New knowledge.
Select Astra DB > Next.
From Connect Astra DB, provide the connection data.
- URL: Enter the endpoint URL of the Astra DB instance.
- Port (optional): By default, Astra DB listens on port 443. Enter a custom port only if your instance uses a nonstandard configuration.
Complete the API key field.
Click Next to proceed.

Astra DB organizes data into keyspaces, similar to databases in relational systems. By default, a keyspace is created automatically, but you can select from any existing keyspace in your Astra DB instance.
Select the Data type that the agent queries:
- Collection: For structured and unstructured data.
- Table: For structured data stored in rows and columns.
Select an option from either Collections or Tables type, depending on which Data type you chose.
Select the Embedding mode. For more information, see Configure embedding and search mode.
Select the Search mode. For more information, see Configure embedding and search mode.
Map the Astra DB fields to the corresponding agent response fields. For more information, see Mapping results

Optional: To configure the Advanced Astra DB settings, see Advanced Astra DB settings.
Click Next to proceed.
In the Knowledge details section,
- Name: Enter a display name for the knowledge source.
- Description: Provide a short description. For more information, see Providing context about the knowledge to the agent.
Save your settings.

You return to the Agent Builder page. The Astra DB repository is now connected Supports . To verify the setup, run a query in your agent.

Update Astra DB settings

To update your configuration:

Go to the Knowledge section.
Click the vertical ellipsis (⋮) next to the selected knowledge source.
Select Edit details and update the configuration.
Save your settings.

Delete Astra DB repository

To delete the repository:

Go to the Knowledge section.
Click the vertical ellipsis (⋮) next to the selected knowledge source.
Click Remove.

Configure embedding and search mode

Astra DB supports multiple embedding and search options to balance accuracy and performance:

Option	Description	When to use
Vector search	Converts queries to vectors for semantic matching.	Best for long or complex queries.
Lexical search	Performs traditional keyword-based matching.	Best for exact matches and structured terms.
Hybrid search	Combines vector and lexical search, then reranks the results.	Use for the highest retrieval accuracy.
Client embedding	The query is first embedded in watsonx.ai or another embedding service, then sent to Astra DB.	Use when you want to manage embeddings outside Astra DB.
Server embedding	Astra DB automatically embeds the query during search.	Use for simpler one-step queries without external embedding calls.

Note: The search mode must align with how the collection or table was configured in Astra DB.

Mapping results

Map the Astra DB fields to the agent response in Configure result content:

Title: Select the field for the result title.
Body: Select the field for the result text.
URL (optional): Select the field for the source link.

Advanced Astra DB settings

Configure advanced filters to refine the results. For example:

Return results where the order items are not checked out:

{"is_checked_out": False}

Return results where the ordered books are not checked out and books have fewer than 300 pages:

    {
        "$and": [
            {"is_checked_out": False},
            {"number_of_pages": {"$lt": 300}},
        ]
    }

Filter syntax follows Astra DB’s query rules.
For details about Filter operators for collections, see Filter operators for collections.
For details about Filter operators for tables, see Filter operators for tables.

Pass context variables

You can make your filters dynamic by referencing context variables in your Astra DB filter templates. This enables runtime substitution of values based on user or session context, making your queries more flexible and personalized.

How it works

In your content repository, set up filters and reference context variables in the format: {context_var}
When the agent runs, it fetches context from:
- The runs endpoint payload, or
- The JWT token associated with the session
The knowledge runtime replaces the context variables in your filter template with actual values from the context

Example for Astra DB filter substitution

The example includes:

filter: A template with references to context variables, entered in the filter field for dynamic substitution.
final_filter: The template after replacing context variables with actual values. The query is sent to Astra DB for data retrieval.
context_variable: A set of key-value pairs defining the context variables used in substitution.

Example:

    filter = '{"product_partNumber": "{part}"}'
    context_variable = {"part": "PS-SL-KIT"}
    final_filter = {"product_partNumber": "PS-SL-KIT"}

    filter = '{"number_of_pages": {"$eq": "{count}"}}'
    context_variable = {"count": 400}
    final_filter  = {"number_of_pages": {"$eq": 400}}

    filter = '{"genres": {"$in": "{genres}"}}'
    context_variable = {"genres": ["ABC", "DEF"]}
    final_filter  = {"genres": {"$in": ["ABC", "DEF"]}}

    filter = '{"borrower": {"$exists": "{borrower}"}}'
    context_variable = {"borrower": False}
    final_filter  = {"borrower": {"$exists": False}}

    filter='{"value": {"$in": [82500, {value}]}}'
    context_variable = {"value": [82400, 165000]}
    final_filter  = {"value": {"$in": [82500, 82400, 165000]}}
    
    filter = '{"product_partNumber": "{part}-SL-KIT"}'
    context_variable = {"part": "PS"}
    final_filter  = {"product_partNumber": "PS-SL-KIT"}

What to do next

After you connect to Astra DB, you can modify the repository connection data or the settings you provided to fetch the documents.

To fine-tune how your agent to use the search results, see Editing the settings of the search results.
Start learning more about Astra DB with the Build context-aware AI agents with watsonx Orchestrate and Astra DB tutorial.