Request Syntax Request Parameters Response Syntax Response Elements Errors See Also

Query

Searches an active index. Use this API to search your documents using query. The Query operation enables to do faceted search and to filter results based on document attributes.

It also enables you to provide user context that Amazon Kendra uses to enforce document access control in the search results.

Amazon Kendra searches your index for text content and question and answer (FAQ) content. By default the response contains three types of results.

Relevant passages
Matching FAQs
Relevant documents

You can specify that the query return only one type of result using the QueryResultTypeConfig parameter.

Request Syntax


{
   "AttributeFilter": { 
      "AndAllFilters": [ 
         "AttributeFilter"
      ],
      "ContainsAll": { 
         "Key": "string",
         "Value": { 
            "DateValue": number,
            "LongValue": number,
            "StringListValue": [ "string" ],
            "StringValue": "string"
         }
      },
      "ContainsAny": { 
         "Key": "string",
         "Value": { 
            "DateValue": number,
            "LongValue": number,
            "StringListValue": [ "string" ],
            "StringValue": "string"
         }
      },
      "EqualsTo": { 
         "Key": "string",
         "Value": { 
            "DateValue": number,
            "LongValue": number,
            "StringListValue": [ "string" ],
            "StringValue": "string"
         }
      },
      "GreaterThan": { 
         "Key": "string",
         "Value": { 
            "DateValue": number,
            "LongValue": number,
            "StringListValue": [ "string" ],
            "StringValue": "string"
         }
      },
      "GreaterThanOrEquals": { 
         "Key": "string",
         "Value": { 
            "DateValue": number,
            "LongValue": number,
            "StringListValue": [ "string" ],
            "StringValue": "string"
         }
      },
      "LessThan": { 
         "Key": "string",
         "Value": { 
            "DateValue": number,
            "LongValue": number,
            "StringListValue": [ "string" ],
            "StringValue": "string"
         }
      },
      "LessThanOrEquals": { 
         "Key": "string",
         "Value": { 
            "DateValue": number,
            "LongValue": number,
            "StringListValue": [ "string" ],
            "StringValue": "string"
         }
      },
      "NotFilter": "AttributeFilter",
      "OrAllFilters": [ 
         "AttributeFilter"
      ]
   },
   "Facets": [ 
      { 
         "DocumentAttributeKey": "string"
      }
   ],
   "IndexId": "string",
   "PageNumber": number,
   "PageSize": number,
   "QueryResultTypeFilter": "string",
   "QueryText": "string",
   "RequestedDocumentAttributes": [ "string" ]
}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

The request accepts the following data in JSON format.

AttributeFilter

Enables filtered searches based on document attributes. You can only provide one attribute filter; however, the AndAllFilters, NotFilter, and OrAllFilters parameters contain a list of other filters.

The AttributeFilter parameter enables you to create a set of filtering rules that a document must satisfy to be included in the query results.

Type: AttributeFilter object

Required: No

Facets

An array of documents attributes. Amazon Kendra returns a count for each attribute key specified. You can use this information to help narrow the search for your user.

Type: Array of Facet objects

Required: No

IndexId

The unique identifier of the index to search. The identifier is returned in the response from the CreateIndex operation.

Type: String

Length Constraints: Fixed length of 36.

Pattern: [a-zA-Z0-9][a-zA-Z0-9-]*

Required: Yes

PageNumber

Query results are returned in pages the size of the PageSize parameter. By default, Amazon Kendra returns the first page of results. Use this parameter to get result pages after the first one.

Type: Integer

Required: No

PageSize

Sets the number of results that are returned in each page of results. The default page size is 10. The maximum number of results returned is 100. If you ask for more than 100 results, only 100 are returned.

Type: Integer

Required: No

QueryResultTypeFilter

Sets the type of query. Only results for the specified query type are returned.

Type: String

Valid Values: DOCUMENT | QUESTION_ANSWER | ANSWER

Required: No

QueryText

The text to search for.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: ^\P{C}*$

Required: Yes

RequestedDocumentAttributes

An array of document attributes to include in the response. No other document attributes are included in the response. By default all document attributes are included in the response.

Type: Array of strings

Array Members: Minimum number of 1 item. Maximum number of 100 items.

Length Constraints: Minimum length of 1. Maximum length of 200.

Pattern: [a-zA-Z0-9_][a-zA-Z0-9_-]*

Required: No

Response Syntax


{
   "FacetResults": [ 
      { 
         "DocumentAttributeKey": "string",
         "DocumentAttributeValueCountPairs": [ 
            { 
               "Count": number,
               "DocumentAttributeValue": { 
                  "DateValue": number,
                  "LongValue": number,
                  "StringListValue": [ "string" ],
                  "StringValue": "string"
               }
            }
         ]
      }
   ],
   "QueryId": "string",
   "ResultItems": [ 
      { 
         "AdditionalAttributes": [ 
            { 
               "Key": "string",
               "Value": { 
                  "TextWithHighlightsValue": { 
                     "Highlights": [ 
                        { 
                           "BeginOffset": number,
                           "EndOffset": number,
                           "TopAnswer": boolean
                        }
                     ],
                     "Text": "string"
                  }
               },
               "ValueType": "string"
            }
         ],
         "DocumentAttributes": [ 
            { 
               "Key": "string",
               "Value": { 
                  "DateValue": number,
                  "LongValue": number,
                  "StringListValue": [ "string" ],
                  "StringValue": "string"
               }
            }
         ],
         "DocumentExcerpt": { 
            "Highlights": [ 
               { 
                  "BeginOffset": number,
                  "EndOffset": number,
                  "TopAnswer": boolean
               }
            ],
            "Text": "string"
         },
         "DocumentId": "string",
         "DocumentTitle": { 
            "Highlights": [ 
               { 
                  "BeginOffset": number,
                  "EndOffset": number,
                  "TopAnswer": boolean
               }
            ],
            "Text": "string"
         },
         "DocumentURI": "string",
         "Id": "string",
         "Type": "string"
      }
   ],
   "TotalNumberOfResults": 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.

FacetResults

Contains the facet results. A FacetResult contains the counts for each attribute key that was specified in the Facets input parameter.

Type: Array of FacetResult objects

QueryId

The unique identifier for the search. You use QueryId to identify the search when using the feedback API.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 36.

ResultItems

The results of the search.

Type: Array of QueryResultItem objects

TotalNumberOfResults

The number of items returned by the search. Use this to determine when you have requested the last set of results.

Type: Integer

Errors

For information about the errors that are common to all actions, see Common Errors.

AccessDeniedException: HTTP Status Code: 400
ConflictException: HTTP Status Code: 400
InternalServerException: HTTP Status Code: 500
ResourceNotFoundException: HTTP Status Code: 400
ServiceQuotaExceededException: HTTP Status Code: 400
ThrottlingException: HTTP Status Code: 400
ValidationException: HTTP Status Code: 400