Select your cookie preferences

We use essential cookies and similar tools that are necessary to provide our site and services. We use performance cookies to collect anonymous statistics, so we can understand how customers use our site and make improvements. Essential cookies cannot be deactivated, but you can choose “Customize” or “Decline” to decline performance cookies.

If you agree, AWS and approved third parties will also use cookies to provide useful site features, remember your preferences, and display relevant content, including relevant advertising. To accept or decline all non-essential cookies, choose “Accept” or “Decline.” To make more detailed choices, choose “Customize.”

Preferences
Contact Us
Feedback
AWS Documentation
Create an AWS Account

Query a knowledge base and retrieve data

PDF
RSS
Focus mode
Query a knowledge base and retrieve data - Amazon Bedrock
Important

Guardrails are applied only to the input and the generated response from the LLM. They are not applied to the references retrieved from Knowledge Bases at runtime.

After your knowledge base is set up, you can query it and retrieve chunks from your source data that is relevant to the query by using the Retrieve API operation. You can also use a reranking model instead of the default Amazon Bedrock Knowledge Bases ranker to rank source chunks for relevance during retrieval.

To learn how to query your knowledge base, choose the tab for your preferred method, and then follow the steps:

Console
To test your knowledge base

  1. Sign in to the AWS Management Console using an IAM role with Amazon Bedrock permissions, and open the Amazon Bedrock console at https://console.aws.amazon.com/bedrock/.

  2. In the left navigation pane, choose Knowledge bases.

  3. In the Knowledge bases section, do one of the following actions:

    • Choose the radio button next to the knowledge base you want to test and select Test knowledge base. A test window expands from the right.

    • Choose the knowledge base that you want to test. A test window expands from the right.

  4. In the test window, clear Generate responses for your query to return information retrieved directly from your knowledge base.

  5. (Optional) Select the configurations icon ( ) to open up Configurations. For information about configurations, see Configure and customize queries and response generation.

  6. Enter a query in the text box in the chat window and select Run to return responses from the knowledge base.

  7. The source chunks are returned directly in order of relevance. Images extracted from your data source can also be returned as a source chunk.

  8. To see details about the returned chunks, select Show source details.

    • To see the configurations that you set for query, expand Query configurations.

    • To view details about a source chunk, expand it by choosing the right arrow ( ) next to it. You can see the following information:

      • The raw text from the source chunk. To copy this text, choose the copy icon ( ). If you used Amazon S3 to store your data, choose the external link icon ( ) to navigate to the S3 object containing the file.

      • The metadata associated with the source chunk, if you used Amazon S3 to store your data. The attribute/field keys and values are defined in the .metadata.json file that's associated with the source document. For more information, see the Metadata and filtering section in Configure and customize queries and response generation.

Chat options

  • Switch to generating responses based on the retrieved source chunks by turning on Generate responses. If you change the setting, the text in the chat window will be completely cleared.

  • To clear the chat window, select the broom icon ( ).

  • To copy all the output in the chat window, select the copy icon ( ).

API

To query a knowledge base and only return relevant text from data sources, send a Retrieve request with an Agents for Amazon Bedrock runtime endpoint.

The following fields are required:

Field Basic description
knowledgeBaseId To specify the knowledge base to query.
retrievalQuery Contains a text field to specify the query.
guardrailsConfiguration Include guardrailsConfiguration fields such as guardrailsId and guardrailsVersion to use your guardrail with the request

The following fields are optional:

Field Use case
nextToken To return the next batch of responses (see response fields below).
retrievalConfiguration To include query configurations for customizing the vector search. See KnowledgeBaseVectorSearchConfiguration for more information.

You can use a reranking model over the default Amazon Bedrock Knowledge Bases ranking model by including the rerankingConfiguration field in the KnowledgeBaseVectorSearchConfiguration. The rerankingConfiguration field maps to a VectorSearchRerankingConfiguration object, in which you can specify the reranking model to use, any additional request fields to include, metadata attributes to filter out documents during reranking, and the number of results to return after reranking. For more information, see VectorSearchRerankingConfiguration.

Note

If you the numberOfRerankedResults value that you specify is greater than the numberOfResults value in the KnowledgeBaseVectorSearchConfiguration, the maximum number of results that will be returned is the value for numberOfResults. An exception is if you use query decomposition (for more information, see the Query modifications section in Configure and customize queries and response generation. If you use query decomposition, the numberOfRerankedResults can be up to five times the numberOfResults.

The response returns the source chunks from the data source as an array of KnowledgeBaseRetrievalResult objects in the retrievalResults field. Each KnowledgeBaseRetrievalResult contains the following fields:

Field Description
content Contains a text source chunk in the text or an image source chunk in the byteContent field. If the content is an image, the data URI of the base64-encoded content is returned in the following format: data:image/jpeg;base64,${base64-encoded string}.
metadata Contains each metadata attribute as a key and the metadata value as a JSON value that the key maps to.
location Contains the URI or URL of the document that the source chunk belongs to.
score The relevancy score of the document. You can use this score to analyze the ranking of results.

If the number of source chunks exceeds what can fit in the response, a value is returned in the nextToken field. Use that value in another request to return the next batch of results.

If the retrieved data contains images, the response also returns the following response headers, which contain metadata for source chunks returned in the response:

  • x-amz-bedrock-kb-byte-content-source – Contains the Amazon S3 URI of the image.

  • x-amz-bedrock-kb-description – Contains the base64-encoded string for the image.

Note

You can't filter on these metadata response headers when configuring metadata filters.

anchoranchor
To test your knowledge base

  1. Sign in to the AWS Management Console using an IAM role with Amazon Bedrock permissions, and open the Amazon Bedrock console at https://console.aws.amazon.com/bedrock/.

  2. In the left navigation pane, choose Knowledge bases.

  3. In the Knowledge bases section, do one of the following actions:

    • Choose the radio button next to the knowledge base you want to test and select Test knowledge base. A test window expands from the right.

    • Choose the knowledge base that you want to test. A test window expands from the right.

  4. In the test window, clear Generate responses for your query to return information retrieved directly from your knowledge base.

  5. (Optional) Select the configurations icon ( ) to open up Configurations. For information about configurations, see Configure and customize queries and response generation.

  6. Enter a query in the text box in the chat window and select Run to return responses from the knowledge base.

  7. The source chunks are returned directly in order of relevance. Images extracted from your data source can also be returned as a source chunk.

  8. To see details about the returned chunks, select Show source details.

    • To see the configurations that you set for query, expand Query configurations.

    • To view details about a source chunk, expand it by choosing the right arrow ( ) next to it. You can see the following information:

      • The raw text from the source chunk. To copy this text, choose the copy icon ( ). If you used Amazon S3 to store your data, choose the external link icon ( ) to navigate to the S3 object containing the file.

      • The metadata associated with the source chunk, if you used Amazon S3 to store your data. The attribute/field keys and values are defined in the .metadata.json file that's associated with the source document. For more information, see the Metadata and filtering section in Configure and customize queries and response generation.

Chat options

  • Switch to generating responses based on the retrieved source chunks by turning on Generate responses. If you change the setting, the text in the chat window will be completely cleared.

  • To clear the chat window, select the broom icon ( ).

  • To copy all the output in the chat window, select the copy icon ( ).

Note

If you receive an error that the prompt exceeds the character limit while generating responses, you can shorten the prompt in the following ways:

Related resources

Amazon Bedrock API Reference
AWS CLI commands for Amazon Bedrock
SDKs & Tools 

Related resources

Amazon Bedrock API Reference
AWS CLI commands for Amazon Bedrock
SDKs & Tools 
PrivacySite termsCookie preferences
© 2025, Amazon Web Services, Inc. or its affiliates. All rights reserved.