RetrieveCommand

Suggest an Edit

Queries a knowledge base and retrieves information from it.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { BedrockAgentRuntimeClient, RetrieveCommand } from "@aws-sdk/client-bedrock-agent-runtime"; // ES Modules import
// const { BedrockAgentRuntimeClient, RetrieveCommand } = require("@aws-sdk/client-bedrock-agent-runtime"); // CommonJS import
const client = new BedrockAgentRuntimeClient(config);
const input = { // RetrieveRequest
  knowledgeBaseId: "STRING_VALUE", // required
  retrievalQuery: { // KnowledgeBaseQuery
    text: "STRING_VALUE", // required
  },
  retrievalConfiguration: { // KnowledgeBaseRetrievalConfiguration
    vectorSearchConfiguration: { // KnowledgeBaseVectorSearchConfiguration
      numberOfResults: Number("int"),
      overrideSearchType: "HYBRID" || "SEMANTIC",
      filter: { // RetrievalFilter Union: only one key present
        equals: { // FilterAttribute
          key: "STRING_VALUE", // required
          value: "DOCUMENT_VALUE", // required
        },
        notEquals: {
          key: "STRING_VALUE", // required
          value: "DOCUMENT_VALUE", // required
        },
        greaterThan: {
          key: "STRING_VALUE", // required
          value: "DOCUMENT_VALUE", // required
        },
        greaterThanOrEquals: {
          key: "STRING_VALUE", // required
          value: "DOCUMENT_VALUE", // required
        },
        lessThan: {
          key: "STRING_VALUE", // required
          value: "DOCUMENT_VALUE", // required
        },
        lessThanOrEquals: "<FilterAttribute>",
        in: "<FilterAttribute>",
        notIn: "<FilterAttribute>",
        startsWith: "<FilterAttribute>",
        listContains: "<FilterAttribute>",
        stringContains: "<FilterAttribute>",
        andAll: [ // RetrievalFilterList
          {//  Union: only one key present
            equals: "<FilterAttribute>",
            notEquals: "<FilterAttribute>",
            greaterThan: "<FilterAttribute>",
            greaterThanOrEquals: "<FilterAttribute>",
            lessThan: "<FilterAttribute>",
            lessThanOrEquals: "<FilterAttribute>",
            in: "<FilterAttribute>",
            notIn: "<FilterAttribute>",
            startsWith: "<FilterAttribute>",
            listContains: "<FilterAttribute>",
            stringContains: "<FilterAttribute>",
            andAll: [
              "<RetrievalFilter>",
            ],
            orAll: [
              "<RetrievalFilter>",
            ],
          },
        ],
        orAll: [
          "<RetrievalFilter>",
        ],
      },
      rerankingConfiguration: { // VectorSearchRerankingConfiguration
        type: "BEDROCK_RERANKING_MODEL", // required
        bedrockRerankingConfiguration: { // VectorSearchBedrockRerankingConfiguration
          modelConfiguration: { // VectorSearchBedrockRerankingModelConfiguration
            modelArn: "STRING_VALUE", // required
            additionalModelRequestFields: { // AdditionalModelRequestFields
              "<keys>": "DOCUMENT_VALUE",
            },
          },
          numberOfRerankedResults: Number("int"),
          metadataConfiguration: { // MetadataConfigurationForReranking
            selectionMode: "SELECTIVE" || "ALL", // required
            selectiveModeConfiguration: { // RerankingMetadataSelectiveModeConfiguration Union: only one key present
              fieldsToInclude: [ // FieldsForReranking
                { // FieldForReranking
                  fieldName: "STRING_VALUE", // required
                },
              ],
              fieldsToExclude: [
                {
                  fieldName: "STRING_VALUE", // required
                },
              ],
            },
          },
        },
      },
      implicitFilterConfiguration: { // ImplicitFilterConfiguration
        metadataAttributes: [ // MetadataAttributeSchemaList // required
          { // MetadataAttributeSchema
            key: "STRING_VALUE", // required
            type: "STRING" || "NUMBER" || "BOOLEAN" || "STRING_LIST", // required
            description: "STRING_VALUE", // required
          },
        ],
        modelArn: "STRING_VALUE", // required
      },
    },
  },
  guardrailConfiguration: { // GuardrailConfiguration
    guardrailId: "STRING_VALUE", // required
    guardrailVersion: "STRING_VALUE", // required
  },
  nextToken: "STRING_VALUE",
};
const command = new RetrieveCommand(input);
const response = await client.send(command);
// { // RetrieveResponse
//   retrievalResults: [ // KnowledgeBaseRetrievalResults // required
//     { // KnowledgeBaseRetrievalResult
//       content: { // RetrievalResultContent
//         type: "TEXT" || "IMAGE" || "ROW",
//         text: "STRING_VALUE",
//         byteContent: "STRING_VALUE",
//         row: [ // RetrievalResultContentRow
//           { // RetrievalResultContentColumn
//             columnName: "STRING_VALUE",
//             columnValue: "STRING_VALUE",
//             type: "BLOB" || "BOOLEAN" || "DOUBLE" || "NULL" || "LONG" || "STRING",
//           },
//         ],
//       },
//       location: { // RetrievalResultLocation
//         type: "S3" || "WEB" || "CONFLUENCE" || "SALESFORCE" || "SHAREPOINT" || "CUSTOM" || "KENDRA" || "SQL", // required
//         s3Location: { // RetrievalResultS3Location
//           uri: "STRING_VALUE",
//         },
//         webLocation: { // RetrievalResultWebLocation
//           url: "STRING_VALUE",
//         },
//         confluenceLocation: { // RetrievalResultConfluenceLocation
//           url: "STRING_VALUE",
//         },
//         salesforceLocation: { // RetrievalResultSalesforceLocation
//           url: "STRING_VALUE",
//         },
//         sharePointLocation: { // RetrievalResultSharePointLocation
//           url: "STRING_VALUE",
//         },
//         customDocumentLocation: { // RetrievalResultCustomDocumentLocation
//           id: "STRING_VALUE",
//         },
//         kendraDocumentLocation: { // RetrievalResultKendraDocumentLocation
//           uri: "STRING_VALUE",
//         },
//         sqlLocation: { // RetrievalResultSqlLocation
//           query: "STRING_VALUE",
//         },
//       },
//       score: Number("double"),
//       metadata: { // RetrievalResultMetadata
//         "<keys>": "DOCUMENT_VALUE",
//       },
//     },
//   ],
//   guardrailAction: "INTERVENED" || "NONE",
//   nextToken: "STRING_VALUE",
// };

RetrieveCommand Input

See RetrieveCommandInput for more details

Parameter
Type
Description
knowledgeBaseId
Required
string | undefined

The unique identifier of the knowledge base to query.

retrievalQuery
Required
KnowledgeBaseQuery | undefined

Contains the query to send the knowledge base.

guardrailConfiguration
GuardrailConfiguration | undefined

Guardrail settings.

nextToken
string | undefined

If there are more results than can fit in the response, the response returns a nextToken. Use this token in the nextToken field of another request to retrieve the next batch of results.

retrievalConfiguration
KnowledgeBaseRetrievalConfiguration | undefined

Contains configurations for the knowledge base query and retrieval process. For more information, see Query configurations .

RetrieveCommand Output

See RetrieveCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
retrievalResults
Required
KnowledgeBaseRetrievalResult[] | undefined

A list of results from querying the knowledge base.

guardrailAction
GuadrailAction | undefined

Specifies if there is a guardrail intervention in the response.

nextToken
string | undefined

If there are more results than can fit in the response, the response returns a nextToken. Use this token in the nextToken field of another request to retrieve the next batch of results.

Throws

Name
Fault
Details
AccessDeniedException
client

The request is denied because of missing access permissions. Check your permissions and retry your request.

BadGatewayException
server

There was an issue with a dependency due to a server issue. Retry your request.

ConflictException
client

There was a conflict performing an operation. Resolve the conflict and retry your request.

DependencyFailedException
client

There was an issue with a dependency. Check the resource configurations and retry the request.

InternalServerException
server

An internal server error occurred. Retry your request.

ResourceNotFoundException
client

The specified resource Amazon Resource Name (ARN) was not found. Check the Amazon Resource Name (ARN) and try your request again.

ServiceQuotaExceededException
client

The number of requests exceeds the service quota. Resubmit your request later.

ThrottlingException
client

The number of requests exceeds the limit. Resubmit your request later.

ValidationException
client

Input validation failed. Check your request parameters and retry the request.

BedrockAgentRuntimeServiceException
Base exception class for all service exceptions from BedrockAgentRuntime service.