Configure and customize queries for managed knowledge bases

You can configure and customize retrieval, further improving the relevancy of results. For example, you can apply filters to document metadata fields/attributes to use the most recently updated documents or documents with recent modification times.

Note

All of the following configurations are only applicable to unstructured data sources.

To learn more about these configurations in the console or the API, select from the following topics:

Number of source chunks

When you query a knowledge base, Amazon Bedrock returns up to five results in the response by default. Each result corresponds to a source chunk.

Note

The actual number of results in the response might be less than the specified numberOfResults value, since this parameter sets the maximum number of results to return. If you have configured hierarchical chunking for your chunking strategy, the numberOfResults parameter maps to the number of child chunks that the knowledge base will retrieve. Since child chunks that share the same parent chunk are replaced with the parent chunk in the final response, the number of results returned might be less than the requested amount.

To modify the maximum number of results to return, choose the tab for your preferred method, and then follow the steps:

Console

Follow the console steps at Query a knowledge base and retrieve data. In the Configurations pane, expand the Source chunks section and enter the maximum number of source chunks to return.

API

When you make a Retrieve or RetrieveAndGenerate request, include a retrievalConfiguration field, mapped to a KnowledgeBaseRetrievalConfiguration object. To see the location of this field, refer to the Retrieve and RetrieveAndGenerate request bodies in the API reference.

The following JSON object shows the minimal fields required in the KnowledgeBaseRetrievalConfiguration object to set the maximum number of results to return:

"retrievalConfiguration": {
    "vectorSearchConfiguration": {
        "numberOfResults": number
    }
}

Specify the maximum number of retrieved results (see the numberOfResults field in KnowledgeBaseRetrievalConfiguration for the range of accepted values) to return in the numberOfResults field.

Manual metadata filtering

You can apply filters to document fields/attributes to help you further improve the relevancy of responses. Your data sources can include document metadata attributes/fields to filter on and can specify which fields to include in the embeddings.

Managed knowledge base considerations

When using metadata filtering with a managed knowledge base:

• The startsWith and stringContains metadata filters are not supported. Use equals, greaterThan, lessThan, in, or notIn operators instead.

• The range operators (greaterThan, greaterThanOrEquals, lessThan, and lessThanOrEquals) accept either a number or a date-time value. To filter on a date-time, provide the value as a string in ISO-8601 offset date-time format. Use the full offset form, for example, 2026-03-02T19:02:18Z. Range operators support date-time string values only for managed knowledge bases.

• For custom knowledge bases, metadata fields prefixed with x-amz-bedrock are reserved by the service. For fully managed knowledge bases, reserved metadata fields use an underscore prefix (for example, _source_uri, _data_source_id). You cannot override reserved metadata fields in either knowledge base type.

For example, "epoch_modification_time" represents the time in number of seconds since January 1, 1970 (UTC) when the document was last updated. You can filter on the most recent data, where "epoch_modification_time" is greater than a certain number. These most recent documents can be used for the query.

To use filters when querying a knowledge base, check that your knowledge base fulfills the following requirements:

• When configuring your data source connector, most connectors crawl the main metadata fields of your documents. If you're using an Amazon S3 bucket as your data source, the bucket must include at least one fileName.extension.metadata.json for the file or document it's associated with. See Document metadata fields in Connection configuration for more information about configuring the metadata file.

• If your knowledge base's vector index is in an Amazon OpenSearch Serverless vector store, check that the vector index is configured with the faiss engine. If the vector index is configured with the nmslib engine, you'll have to do one of the following:

  • Create a new knowledge base in the console and let Amazon Bedrock automatically create a vector index in Amazon OpenSearch Serverless for you.

  • Create another vector index in the vector store and select faiss as the Engine. Then Create a new knowledge base and specify the new vector index.

• If your knowledge base uses a vector index in an S3 vector bucket, you cannot use the startsWith and stringContains filters.

• If you're adding metadata to an existing vector index in an Amazon Aurora database cluster, we recommend that you provide the field name of the custom metadata column to store all your metadata in a single column. During data ingestion, this column will be used to populate all the information in your metadata files from your data sources. If you choose to provide this field, you must create an index on this column.

  • When you create a new knowledge base in the console and let Amazon Bedrock configure your Amazon Aurora database, it will automatically create a single column for you and populate it with the information from your metadata files.

  • When you choose to create another vector index in the vector store, you must provide the custom metadata field name to store information from your metadata files. If you don't provide this field name, you must create a column for each metadata attribute in your files and specify the data type (text, number, or boolean). For example, if the attribute genre exists in your data source, you would add a column named genre and specify text as the data type. During ingestion, these separate columns will be populated with the corresponding attribute values.

If you have PDF documents in your data source and use Amazon OpenSearch Serverless or Amazon Aurora for your vector store: Amazon Bedrock knowledge bases will generate document page numbers and store them in a metadata field/attribute called x-amz-bedrock-kb-document-page-number. Note that page numbers stored in a metadata field is not supported if you choose no chunking for your documents.

You can use the following filtering operators to filter results when you query:

Filtering operators

Operator	Console	API filter name	Supported attribute data types	Filtered results
Equals	=	equals	string, number, boolean	Attribute matches the value you provide
Not equals	!=	notEquals	string, number, boolean	Attribute doesn’t match the value you provide
Greater than	>	greaterThan	number	Attribute is greater than the value you provide
Greater than or equals	>=	greaterThanOrEquals	number	Attribute is greater than or equal to the value you provide
Less than	<	lessThan	number	Attribute is less than the value you provide
Less than or equals	<=	lessThanOrEquals	number	Attribute is less than or equal to the value you provide
In	:	in	string list	Attribute is in the list you provide (currently best supported with Amazon OpenSearch Serverless and Neptune Analytics GraphRAG vector stores)
Not in	!:	notIn	string list	Attribute isn’t in the list you provide (currently best supported with Amazon OpenSearch Serverless and Neptune Analytics GraphRAG vector stores)
String contains	Not available	stringContains	string	Attribute must be a string. Attribute name matches the key and whose value is a string that contains the value that you provided as a substring, or a list with a member that contains the value that you provided as a substring (currently best supported with Amazon OpenSearch Serverless vector store. The Neptune Analytics GraphRAG vector store supports the string variant but not the list variant of this filter).
List contains	Not available	listContains	string	Attribute must be a string list. Attribute name matches the key and whose value is a list that contains the value that you provided as one of its members (currently best supported with Amazon OpenSearch Serverless vector stores).

To combine filtering operators, you can use the following logical operators:

Logical operators

Operator	Console	API filter field name	Filtered results
And	and	andAll	Results fulfill all of the filtering expressions in the group
Or	or	orAll	Results fulfill at least one of the filtering expressions in the group

To learn how to filter results using metadata, choose the tab for your preferred method, and then follow the steps:

Console

Follow the console steps at Query a knowledge base and retrieve data. When you open the Configurations pane, you'll see a Filters section. The following procedures describe different use cases:

• To add a filter, create a filtering expression by entering a metadata attribute, filtering operator, and value in the box. Separate each part of the expression with a whitespace. Press Enter to add the filter.

  For a list of accepted filtering operators, see the Filtering operators table above. You can also see a list of filtering operators when you add a whitespace after the metadata attribute.

  Note

  You must surround strings with quotation marks.

  For example, you can filter for results from source documents that contain a genre metadata attribute whose value is "entertainment" by adding the following filter: genre = "entertainment".

  

• To add another filter, enter another filtering expression in the box and press Enter. You can add up to 5 filters in the group.

  

• By default, the query will return results that fulfill all the filtering expressions you provide. To return results that fulfill at least one of the filtering expressions, choose the and dropdown menu between any two filtering operations and select or.

  

• To combine different logical operators, select + Add Group to add a filter group. Enter filtering expressions in the new group. You can add up to 5 filter groups.

  

• To change the logical operator used between all the filtering groups, choose the AND dropdown menu between any two filter groups and select OR.

  

• To edit a filter, select it, modify the filtering operation, and choose Apply.

  

• To remove a filter group, choose the trash can icon ( ) next to the group. To remove a filter, choose the delete icon ( ) next to the filter.

  

The following image shows an example filter configuration that returns all documents written after 2018 whose genre is "entertainment", in addition to documents whose genre is "cooking" or "sports" and whose author starts with "C".

API

When you make a Retrieve or RetrieveAndGenerate request, include a retrievalConfiguration field, mapped to a KnowledgeBaseRetrievalConfiguration object. To see the location of this field, refer to the Retrieve and RetrieveAndGenerate request bodies in the API reference.

The following JSON objects show the minimal fields required in the KnowledgeBaseRetrievalConfiguration object to set filters for different use cases:

1. Use one filtering operator (see the Filtering operators table above).

   "retrievalConfiguration": {
       "vectorSearchConfiguration": {
           "filter": {
               "<filter-type>": {
                   "key": "string",
                   "value": "string" | number | boolean | ["string", "string", ...]
               }
           }
       }
   }

2. Use a logical operator (see the Logical operators table above) to combine up to 5.

   "retrievalConfiguration": {
       "vectorSearchConfiguration": {
           "filter": {
               "andAll | orAll": [
                   "<filter-type>": {
                       "key": "string",
                       "value": "string" | number | boolean | ["string", "string", ...]
                   },
                   "<filter-type>": {
                       "key": "string",
                       "value": "string" | number | boolean | ["string", "string", ...]
                   },
                   ...
               ]
           }
       }
   }

3. Use a logical operator to combine up to 5 filtering operators into a filter group, and a second logical operator to combine that filter group with another filtering operator.

   "retrievalConfiguration": {
       "vectorSearchConfiguration": {
           "filter": {
               "andAll | orAll": [
                   "andAll | orAll": [
                       "<filter-type>": {
                           "key": "string",
                           "value": "string" | number | boolean | ["string", "string", ...]
                       },
                       "<filter-type>": {
                           "key": "string",
                           "value": "string" | number | boolean | ["string", "string", ...]
                       },
                       ...
                   ],
                   "<filter-type>": {
                       "key": "string",
                       "value": "string" | number | boolean | ["string", "string", ...]
                   }
               ]
           }
       }
   }

4. Combine up to 5 filter groups by embedding them within another logical operator. You can create one level of embedding.

   "retrievalConfiguration": {
       "vectorSearchConfiguration": {
           "filter": {
               "andAll | orAll": [
                   "andAll | orAll": [
                       "<filter-type>": {
                           "key": "string",
                           "value": "string" | number | boolean | ["string", "string", ...]
                       },
                       "<filter-type>": {
                           "key": "string",
                           "value": "string" | number | boolean | ["string", "string", ...]
                       },
                       ...
                   ],
                   "andAll | orAll": [
                       "<filter-type>": {
                           "key": "string",
                           "value": "string" | number | boolean | ["string", "string", ...]
                       },
                       "<filter-type>": {
                           "key": "string",
                           "value": "string" | number | boolean | ["string", "string", ...]
                       },
                       ...
                   ]
               ]
           }
       }
   }

The following table describes the filter types that you can use:

Field	Supported value data types	Filtered results
equals	string, number, boolean	Attribute matches the value you provide
notEquals	string, number, boolean	Attribute doesn't match the value you provide
greaterThan	number	Attribute is greater than the value you provide
greaterThanOrEquals	number	Attribute is greater than or equal to the value you provide
lessThan	number	Attribute is less than the value you provide
lessThanOrEquals	number	Attribute is less than or equal to the value you provide
in	list of strings	Attribute is in the list you provide
notIn	list of strings	Attribute isn't in the list you provide
startsWith	string	Attribute starts with the string you provide (only supported for Amazon OpenSearch Serverless vector stores)

To combine filter types, you can use one of the following logical operators:

Field	Maps to	Filtered results
andAll	List of up to 5 filter types	Results fulfill all of the filtering expressions in the group
orAll	List of up to 5 filter types	Results fulfill at least one of the filtering expressions in the group

For examples, see Send a query and include filters (Retrieve) and Send a query and include filters (RetrieveAndGenerate).

Guardrails

You can implement safeguards for your knowledge base for your use cases and responsible AI policies. You can create multiple guardrails tailored to different use cases and apply them across multiple request and response conditions, providing a consistent user experience and standardizing safety controls across your knowledge base. You can configure denied topics to disallow undesirable topics and content filters to block harmful content in model inputs and responses. For more information, see Detect and filter harmful content by using Amazon Bedrock Guardrails.

Note

Using guardrails with contextual grounding for knowledge bases is currently not supported on Claude 3 Sonnet and Haiku.

For general prompt engineering guidelines, see Prompt engineering concepts.

Choose the tab for your preferred method, and then follow the steps:

Console

Follow the console steps at Query a knowledge base and retrieve data. In the test window, turn on Generate responses. Then, in the Configurations pane, expand the Guardrails section.

1. In the Guardrails section, choose the Name and the Version of your guardrail. If you would like to see the details for your chosen guardrail and version, choose View.

   Alternatively, you can create a new one by choosing the Guardrail link.

2. When you're finished editing, choose Save changes. To exit without saving choose Discard changes.

API

When you make a RetrieveAndGenerate request, include the guardrailConfiguration field within the generationConfiguration to use your guardrail with the request. To see the location of this field, refer to the RetrieveAndGenerate request body in the API reference.

The following JSON object shows the minimal fields required in the GenerationConfiguration to set the guardrailConfiguration:

"generationConfiguration": {
    "guardrailConfiguration": {
        "guardrailId": "string",
        "guardrailVersion": "string"
    }
}

Specify the guardrailId and guardrailVersion of your chosen guardrails.

Reranking

You can use a reranker model to rerank results from knowledge base query. Follow the console steps at Query a knowledge base and retrieve data. When you open the Configurations pane, expand the Reranking section. Select a reranker model, update permissions if necessary, and modify any additional options. Enter a prompt and select Run to test the results after reranking.