Skip to main content

indexes

Creates, updates, deletes, gets or lists an indexes resource.

Overview​

Nameindexes
TypeResource
Idaws.kendra.indexes

Fields​

The following fields are returned by SELECT queries:

NameDatatypeDescription
capacity_unitsobjectFor Enterprise Edition indexes, you can choose to use additional capacity to meet the needs of your application. This contains the capacity units used for the index. A query or document storage capacity of zero indicates that the index is using the default capacity. For more information on the default capacity for an index and adjusting this, see Adjusting capacity.
created_atstring (date-time)The Unix timestamp when the index was created.
descriptionstringThe description for the index. (pattern: <code>^\P{C}*$</code>)
document_metadata_configurationsarrayConfiguration information for document metadata or fields. Document metadata are fields or attributes associated with your documents. For example, the company department name associated with each document.
editionstringThe Amazon Kendra edition used for the index. You decide the edition when you create the index. (DEVELOPER_EDITION, ENTERPRISE_EDITION, GEN_AI_ENTERPRISE_EDITION)
error_messagestringWhen the Status field value is FAILED, the ErrorMessage field contains a message that explains why. (pattern: <code>^\P{C}*$</code>)
idstringThe identifier of the index. (pattern: <code>[a-zA-Z0-9][a-zA-Z0-9-]*</code>)
index_statisticsobjectProvides information about the number of FAQ questions and answers and the number of text documents indexed.
namestringThe name of the index. (pattern: <code>[a-zA-Z0-9][a-zA-Z0-9_-]*</code>)
role_arnstringThe Amazon Resource Name (ARN) of the IAM role that gives Amazon Kendra permission to write to your Amazon CloudWatch logs. (pattern: <code>arn:[a-z0-9-.]{1,63}:[a-z0-9-.]{0,63}:[a-z0-9-.]{0,63}:[a-z0-9-.]{0,63}:[^/].{0,1023}</code>)
server_side_encryption_configurationobjectThe identifier of the KMS customer master key (CMK) that is used to encrypt your data. Amazon Kendra doesn't support asymmetric CMKs.
statusstringThe current status of the index. When the value is ACTIVE, the index is ready for use. If the Status field value is FAILED, the ErrorMessage field contains a message that explains why. (CREATING, ACTIVE, DELETING, FAILED, UPDATING, SYSTEM_UPDATING)
updated_atstring (date-time)The Unix timestamp when the index was last updated.
user_context_policystringThe user context policy for the Amazon Kendra index. (ATTRIBUTE_FILTER, USER_TOKEN)
user_group_resolution_configurationobjectWhether you have enabled IAM Identity Center identity source for your users and groups. This is useful for user context filtering, where search results are filtered based on the user or their group access to documents.
user_token_configurationsarrayThe user token configuration for the Amazon Kendra index.

Methods​

The following methods are available for this resource:

NameAccessible byRequired ParamsOptional ParamsDescription
describe_indexselectregionGets information about an Amazon Kendra index.
create_indexinsertregion, RoleArnCreates an Amazon Kendra index. Index creation is an asynchronous API. To determine if index creation has completed, check the Status field returned from a call to DescribeIndex. The Status field is set to ACTIVE when the index is ready to use. Once the index is active, you can index your documents using the BatchPutDocument API or using one of the supported data sources. For an example of creating an index and data source using the Python SDK, see Getting started with Python SDK. For an example of creating an index and data source using the Java SDK, see Getting started with Java SDK.
associate_personas_to_entitiesupdateregion, IndexId, PersonasDefines the specific permissions of users or groups in your IAM Identity Center identity source with access to your Amazon Kendra experience. You can create an Amazon Kendra experience such as a search application. For more information on creating a search application experience, see Building a search experience with no code.
disassociate_personas_from_entitiesupdateregion, IndexId, EntityIdsRemoves the specific permissions of users or groups in your IAM Identity Center identity source with access to your Amazon Kendra experience. You can create an Amazon Kendra experience such as a search application. For more information on creating a search application experience, see Building a search experience with no code.
update_indexupdateregionUpdates an Amazon Kendra index.
delete_indexdeleteregionDeletes an Amazon Kendra index. An exception is not thrown if the index is already being deleted. While the index is being deleted, the Status field returned by a call to the DescribeIndex API is set to DELETING.
batch_delete_documentexecregion, IndexId, DocumentIdListRemoves one or more documents from an index. The documents must have been added with the BatchPutDocument API. The documents are deleted asynchronously. You can see the progress of the deletion by using Amazon Web Services CloudWatch. Any error messages related to the processing of the batch are sent to your Amazon Web Services CloudWatch log. You can also use the BatchGetDocumentStatus API to monitor the progress of deleting your documents. Deleting documents from an index using BatchDeleteDocument could take up to an hour or more, depending on the number of documents you want to delete.
batch_put_documentexecregion, IndexId, DocumentsAdds one or more documents to an index. The BatchPutDocument API enables you to ingest inline documents or a set of documents stored in an Amazon S3 bucket. Use this API to ingest your text and unstructured text into an index, add custom attributes to the documents, and to attach an access control list to the documents added to the index. The documents are indexed asynchronously. You can see the progress of the batch using Amazon Web Services CloudWatch. Any error messages related to processing the batch are sent to your Amazon Web Services CloudWatch log. You can also use the BatchGetDocumentStatus API to monitor the progress of indexing your documents. For an example of ingesting inline documents using Python and Java SDKs, see Adding files directly to an index.
queryexecregion, IndexIdSearches an index given an input query. If you are working with large language models (LLMs) or implementing retrieval augmented generation (RAG) systems, you can use Amazon Kendra's Retrieve API, which can return longer semantically relevant passages. We recommend using the Retrieve API instead of filing a service limit increase to increase the Query API document excerpt length. You can configure boosting or relevance tuning at the query level to override boosting at the index level, filter based on document fields/attributes and faceted search, and filter based on the user or their group access to documents. You can also include certain fields in the response that might provide useful additional information. A query response contains three types of results. Relevant suggested answers. The answers can be either a text excerpt or table excerpt. The answer can be highlighted in the excerpt. Matching FAQs or questions-answer from your FAQ file. Relevant documents. This result type includes an excerpt of the document with the document title. The searched terms can be highlighted in the excerpt. You can specify that the query return only one type of result using the QueryResultTypeFilter parameter. Each query returns the 100 most relevant results. If you filter result type to only question-answers, a maximum of four results are returned. If you filter result type to only answers, a maximum of three results are returned. If you're using an Amazon Kendra Gen AI Enterprise Edition index, you can only use ATTRIBUTE_FILTER to filter search results by user context. If you're using an Amazon Kendra Gen AI Enterprise Edition index and you try to use USER_TOKEN to configure user context policy, Amazon Kendra returns a ValidationException error.
retrieveexecregion, IndexId, QueryTextRetrieves relevant passages or text excerpts given an input query. This API is similar to the Query API. However, by default, the Query API only returns excerpt passages of up to 100 token words. With the Retrieve API, you can retrieve longer passages of up to 200 token words and up to 100 semantically relevant passages. This doesn't include question-answer or FAQ type responses from your index. The passages are text excerpts that can be semantically extracted from multiple documents and multiple parts of the same document. If in extreme cases your documents produce zero passages using the Retrieve API, you can alternatively use the Query API and its types of responses. You can also do the following: Override boosting at the index level Filter based on document fields or attributes Filter based on the user or their group access to documents View the confidence score bucket for a retrieved passage result. The confidence bucket provides a relative ranking that indicates how confident Amazon Kendra is that the response is relevant to the query. Confidence score buckets are currently available only for English. You can also include certain fields in the response that might provide useful additional information. The Retrieve API shares the number of query capacity units that you set for your index. For more information on what's included in a single capacity unit and the default base capacity for an index, see Adjusting capacity. If you're using an Amazon Kendra Gen AI Enterprise Edition index, you can only use ATTRIBUTE_FILTER to filter search results by user context. If you're using an Amazon Kendra Gen AI Enterprise Edition index and you try to use USER_TOKEN to configure user context policy, Amazon Kendra returns a ValidationException error.
submit_feedbackexecregion, IndexId, QueryIdEnables you to provide feedback to Amazon Kendra to improve the performance of your index. SubmitFeedback is currently not supported in the Amazon Web Services GovCloud (US-West) region.

Parameters​

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

NameDatatypeDescription
regionstringAWS region (default: us-east-1)

SELECT examples​

Gets information about an Amazon Kendra index.

SELECT
capacity_units,
created_at,
description,
document_metadata_configurations,
edition,
error_message,
id,
index_statistics,
name,
role_arn,
server_side_encryption_configuration,
status,
updated_at,
user_context_policy,
user_group_resolution_configuration,
user_token_configurations
FROM aws.kendra.indexes
WHERE region = '{{ region }}' -- required
;

INSERT examples​

Creates an Amazon Kendra index. Index creation is an asynchronous API. To determine if index creation has completed, check the Status field returned from a call to DescribeIndex. The Status field is set to ACTIVE when the index is ready to use. Once the index is active, you can index your documents using the BatchPutDocument API or using one of the supported data sources. For an example of creating an index and data source using the Python SDK, see Getting started with Python SDK. For an example of creating an index and data source using the Java SDK, see Getting started with Java SDK.

INSERT INTO aws.kendra.indexes (
Name,
Edition,
RoleArn,
ServerSideEncryptionConfiguration,
Description,
ClientToken,
Tags,
UserTokenConfigurations,
UserContextPolicy,
UserGroupResolutionConfiguration,
region
)
SELECT 
'{{ Name }}',
'{{ Edition }}',
'{{ RoleArn }}' /* required */,
'{{ ServerSideEncryptionConfiguration }}',
'{{ Description }}',
'{{ ClientToken }}',
'{{ Tags }}',
'{{ UserTokenConfigurations }}',
'{{ UserContextPolicy }}',
'{{ UserGroupResolutionConfiguration }}',
'{{ region }}'
RETURNING
id
;

UPDATE examples​

Defines the specific permissions of users or groups in your IAM Identity Center identity source with access to your Amazon Kendra experience. You can create an Amazon Kendra experience such as a search application. For more information on creating a search application experience, see Building a search experience with no code.

UPDATE aws.kendra.indexes
SET 
Id = '{{ Id }}',
IndexId = '{{ IndexId }}',
Personas = '{{ Personas }}'
WHERE 
region = '{{ region }}' --required
AND IndexId = '{{ IndexId }}' --required
AND Personas = '{{ Personas }}' --required
RETURNING
failed_entity_list;

DELETE examples​

Deletes an Amazon Kendra index. An exception is not thrown if the index is already being deleted. While the index is being deleted, the Status field returned by a call to the DescribeIndex API is set to DELETING.

DELETE FROM aws.kendra.indexes
WHERE region = '{{ region }}' --required
;

Lifecycle Methods​

Removes one or more documents from an index. The documents must have been added with the BatchPutDocument API. The documents are deleted asynchronously. You can see the progress of the deletion by using Amazon Web Services CloudWatch. Any error messages related to the processing of the batch are sent to your Amazon Web Services CloudWatch log. You can also use the BatchGetDocumentStatus API to monitor the progress of deleting your documents. Deleting documents from an index using BatchDeleteDocument could take up to an hour or more, depending on the number of documents you want to delete.

EXEC aws.kendra.indexes.batch_delete_document 
@region='{{ region }}' --required 
@@json=
'{
"IndexId": "{{ IndexId }}", 
"DocumentIdList": "{{ DocumentIdList }}", 
"DataSourceSyncJobMetricTarget": "{{ DataSourceSyncJobMetricTarget }}"
}'
;
Last updated on