Retrieve
Queries a knowledge base and retrieves information from it.
Request Syntax
POST /knowledgebases/knowledgeBaseId
/retrieve HTTP/1.1
Content-type: application/json
{
"guardrailConfiguration": {
"guardrailId": "string
",
"guardrailVersion": "string
"
},
"nextToken": "string
",
"retrievalConfiguration": {
"vectorSearchConfiguration": {
"filter": { ... },
"implicitFilterConfiguration": {
"metadataAttributes": [
{
"description": "string
",
"key": "string
",
"type": "string
"
}
],
"modelArn": "string
"
},
"numberOfResults": number
,
"overrideSearchType": "string
",
"rerankingConfiguration": {
"bedrockRerankingConfiguration": {
"metadataConfiguration": {
"selectionMode": "string
",
"selectiveModeConfiguration": { ... }
},
"modelConfiguration": {
"additionalModelRequestFields": {
"string
" : JSON value
},
"modelArn": "string
"
},
"numberOfRerankedResults": number
},
"type": "string
"
}
}
},
"retrievalQuery": {
"text": "string
"
}
}
URI Request Parameters
The request uses the following URI parameters.
- knowledgeBaseId
-
The unique identifier of the knowledge base to query.
Length Constraints: Minimum length of 0. Maximum length of 10.
Pattern:
^[0-9a-zA-Z]+$
Required: Yes
Request Body
The request accepts the following data in JSON format.
- guardrailConfiguration
-
Guardrail settings.
Type: GuardrailConfiguration object
Required: No
- nextToken
-
If there are more results than can fit in the response, the response returns a
nextToken
. Use this token in thenextToken
field of another request to retrieve the next batch of results.Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
^\S*$
Required: No
- retrievalConfiguration
-
Contains configurations for the knowledge base query and retrieval process. For more information, see Query configurations.
Type: KnowledgeBaseRetrievalConfiguration object
Required: No
- retrievalQuery
-
Contains the query to send the knowledge base.
Type: KnowledgeBaseQuery object
Required: Yes
Response Syntax
HTTP/1.1 200
Content-type: application/json
{
"guardrailAction": "string",
"nextToken": "string",
"retrievalResults": [
{
"content": {
"byteContent": "string",
"row": [
{
"columnName": "string",
"columnValue": "string",
"type": "string"
}
],
"text": "string",
"type": "string"
},
"location": {
"confluenceLocation": {
"url": "string"
},
"customDocumentLocation": {
"id": "string"
},
"kendraDocumentLocation": {
"uri": "string"
},
"s3Location": {
"uri": "string"
},
"salesforceLocation": {
"url": "string"
},
"sharePointLocation": {
"url": "string"
},
"sqlLocation": {
"query": "string"
},
"type": "string",
"webLocation": {
"url": "string"
}
},
"metadata": {
"string" : JSON value
},
"score": number
}
]
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The following data is returned in JSON format by the service.
- guardrailAction
-
Specifies if there is a guardrail intervention in the response.
Type: String
Valid Values:
INTERVENED | NONE
- nextToken
-
If there are more results than can fit in the response, the response returns a
nextToken
. Use this token in thenextToken
field of another request to retrieve the next batch of results.Type: String
Length Constraints: Minimum length of 1. Maximum length of 2048.
Pattern:
^\S*$
- retrievalResults
-
A list of results from querying the knowledge base.
Type: Array of KnowledgeBaseRetrievalResult objects
Errors
For information about the errors that are common to all actions, see Common Errors.
- AccessDeniedException
-
The request is denied because of missing access permissions. Check your permissions and retry your request.
HTTP Status Code: 403
- BadGatewayException
-
There was an issue with a dependency due to a server issue. Retry your request.
HTTP Status Code: 502
- ConflictException
-
There was a conflict performing an operation. Resolve the conflict and retry your request.
HTTP Status Code: 409
- DependencyFailedException
-
There was an issue with a dependency. Check the resource configurations and retry the request.
HTTP Status Code: 424
- InternalServerException
-
An internal server error occurred. Retry your request.
HTTP Status Code: 500
- ResourceNotFoundException
-
The specified resource Amazon Resource Name (ARN) was not found. Check the Amazon Resource Name (ARN) and try your request again.
HTTP Status Code: 404
- ServiceQuotaExceededException
-
The number of requests exceeds the service quota. Resubmit your request later.
HTTP Status Code: 400
- ThrottlingException
-
The number of requests exceeds the limit. Resubmit your request later.
HTTP Status Code: 429
- ValidationException
-
Input validation failed. Check your request parameters and retry the request.
HTTP Status Code: 400
Examples
Send a basic query
The following example queries a knowledge base.
Sample Request
POST /knowledgebases/KB12345678/retrieve HTTP/1.1
Content-type: application/json
{
"retrievalQuery": {
"text": "What is AWS?"
}
}
Send a query and include filters
To include filters in a knowledge base query, at least one of the data source files must include a .metadata.json
file. For example, if you had a data source of articles called articles.pdf
, accompanied by a metadata file called articles.metadata.json
, you could tag it for genre
, year
, and author
. In the Retrieve
request, you could apply the following filter to return all entertainment articles written after 2018
, in addition to cooking
or sports
articles written by authors starting with C
.
Sample Request
POST /knowledgebases/KB12345678/retrieve HTTP/1.1
Content-type: application/json
{
"retrievalQuery": {
"text": "What is AWS?",
},
"vectorSearchConfiguration": {
"numberOfResults": 5,
"filter": {
"orAll": [
{
"andAll": [
{
"equals": {
"key": "genre",
"value": "entertainment"
}
},
{
"greaterThan": {
"key": "year",
"value": 2018
}
}
]
},
{
"andAll": [
{
"in": {
"key": "genre",
"value": ["cooking", "sports"]
}
},
{
"startsWith": {
"key": "author",
"value": "C"
}
}
]
}
]
}
}
}
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: