2026/11/16 - Amazon S3 Vectors - 1 new3 updated api methods
Changes Amazon S3 Vectors now supports hybrid search, providing metadata text search along with vector search.
Adds or deletes text search configurations on a vector index. Specify either add or delete, but not both. The vector index must be in ENHANCED mode.
Permissions
You must have the s3vectors:UpdateMetadataConfiguration permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.update_metadata_configuration(
vectorBucketName='string',
indexName='string',
indexArn='string',
add={
'textSearchConfigurations': [
{
'metadataKey': 'string',
'language': 'en'|'fr'|'es'|'pt'|'it'|'de'|'nl'|'zh'|'ja'|'ko',
'status': 'ACTIVE'|'BUILDING'
},
]
},
delete={
'textSearchConfigurations': [
{
'metadataKey': 'string'
},
]
}
)
string
The name of the vector bucket that contains the vector index.
string
The name of the vector index to update.
string
The Amazon Resource Name (ARN) of the vector index to update.
dict
Text search configurations to add to the vector index.
textSearchConfigurations (list) --
Text search configurations to add. Amazon S3 Vectors begins building the corresponding full-text indexes after the update is accepted.
(dict) --
A full-text search configuration for a single metadata key.
metadataKey (string) -- [REQUIRED]
The metadata key to make full-text searchable.
language (string) --
The language that the text search analyzer uses. Valid values are en (English), fr (French), es (Spanish), pt (Portuguese), it (Italian), de (German), nl (Dutch), zh (Chinese), ja (Japanese), and ko (Korean). If you don't specify a language, Amazon S3 Vectors uses the default standard analyzer.
status (string) --
The backfill status of the text search configuration. Valid values are ACTIVE, which indicates that the analyzer is built and serving queries, and BUILDING, which indicates that the analyzer is being backfilled and isn't yet serving queries. This field is returned by GetIndex.
dict
Text search configurations to delete from the vector index.
textSearchConfigurations (list) --
Searchable metadata keys whose text search configurations to delete.
(dict) --
A searchable metadata key that identifies a text search configuration.
metadataKey (string) -- [REQUIRED]
The searchable metadata key whose text search configuration to delete.
dict
Response Syntax
{
'indexArn': 'string'
}
Response Structure
(dict) --
indexArn (string) --
The Amazon Resource Name (ARN) of the updated vector index.
{'metadataConfiguration': {'textSearchConfigurations': [{'language': 'en | fr '
'| es | '
'pt | it '
'| de | '
'nl | zh '
'| ja | '
'ko',
'metadataKey': 'string',
'status': 'ACTIVE | '
'BUILDING'}]}}
Creates a vector index within a vector bucket. To specify the vector bucket, you must use either the vector bucket name or the vector bucket Amazon Resource Name (ARN).
Permissions
You must have the s3vectors:CreateIndex permission to use this operation.
You must have the s3vectors:TagResource permission in addition to s3vectors:CreateIndex permission to create a vector index with tags.
See also: AWS API Documentation
Request Syntax
client.create_index(
vectorBucketName='string',
vectorBucketArn='string',
indexName='string',
dataType='float32',
dimension=123,
distanceMetric='euclidean'|'cosine',
metadataConfiguration={
'nonFilterableMetadataKeys': [
'string',
],
'textSearchConfigurations': [
{
'metadataKey': 'string',
'language': 'en'|'fr'|'es'|'pt'|'it'|'de'|'nl'|'zh'|'ja'|'ko',
'status': 'ACTIVE'|'BUILDING'
},
]
},
encryptionConfiguration={
'sseType': 'AES256'|'aws:kms',
'kmsKeyArn': 'string'
},
tags={
'string': 'string'
}
)
string
The name of the vector bucket to create the vector index in.
string
The Amazon Resource Name (ARN) of the vector bucket to create the vector index in.
string
[REQUIRED]
The name of the vector index to create.
string
[REQUIRED]
The data type of the vectors to be inserted into the vector index.
integer
[REQUIRED]
The dimensions of the vectors to be inserted into the vector index.
string
[REQUIRED]
The distance metric to be used for similarity search.
dict
The metadata configuration for the vector index.
nonFilterableMetadataKeys (list) --
Non-filterable metadata keys allow you to enrich vectors with additional context during storage and retrieval. You can't use these keys in metadata filters. You can still make a non-filterable key full-text searchable by configuring it separately in textSearchConfigurations. You can retrieve non-filterable metadata keys after finding the vectors. For more information about non-filterable metadata keys, see Vectors and Limitations and restrictions in the Amazon S3 User Guide.
(string) --
textSearchConfigurations (list) --
Full-text search configurations for searchable metadata keys.
(dict) --
A full-text search configuration for a single metadata key.
metadataKey (string) -- [REQUIRED]
The metadata key to make full-text searchable.
language (string) --
The language that the text search analyzer uses. Valid values are en (English), fr (French), es (Spanish), pt (Portuguese), it (Italian), de (German), nl (Dutch), zh (Chinese), ja (Japanese), and ko (Korean). If you don't specify a language, Amazon S3 Vectors uses the default standard analyzer.
status (string) --
The backfill status of the text search configuration. Valid values are ACTIVE, which indicates that the analyzer is built and serving queries, and BUILDING, which indicates that the analyzer is being backfilled and isn't yet serving queries. This field is returned by GetIndex.
dict
The encryption configuration for a vector index. By default, if you don't specify, all new vectors in the vector index will use the encryption configuration of the vector bucket.
sseType (string) --
The server-side encryption type to use for the encryption configuration of the vector bucket. By default, if you don't specify, all new vectors in Amazon S3 vector buckets use server-side encryption with Amazon S3 managed keys (SSE-S3), specifically AES256.
kmsKeyArn (string) --
Amazon Web Services Key Management Service (KMS) customer managed key ID to use for the encryption configuration. This parameter is allowed if and only if sseType is set to aws:kms.
To specify the KMS key, you must use the format of the KMS key Amazon Resource Name (ARN).
For example, specify Key ARN in the following format: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
dict
An array of user-defined tags that you would like to apply to the vector index that you are creating. A tag is a key-value pair that you apply to your resources. Tags can help you organize, track costs, and control access to resources. For more information, see Tagging for cost allocation or attribute-based access control (ABAC).
(string) --
(string) --
dict
Response Syntax
{
'indexArn': 'string'
}
Response Structure
(dict) --
indexArn (string) --
The Amazon Resource Name (ARN) of the newly created vector index.
{'index': {'metadataConfiguration': {'textSearchConfigurations': [{'language': 'en '
'| '
'fr '
'| '
'es '
'| '
'pt '
'| '
'it '
'| '
'de '
'| '
'nl '
'| '
'zh '
'| '
'ja '
'| '
'ko',
'metadataKey': 'string',
'status': 'ACTIVE '
'| '
'BUILDING'}]}}}
Returns vector index attributes. To specify the vector index, you can either use both the vector bucket name and the vector index name, or use the vector index Amazon Resource Name (ARN).
Permissions
You must have the s3vectors:GetIndex permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.get_index(
vectorBucketName='string',
indexName='string',
indexArn='string'
)
string
The name of the vector bucket that contains the vector index.
string
The name of the vector index.
string
The ARN of the vector index.
dict
Response Syntax
{
'index': {
'vectorBucketName': 'string',
'indexName': 'string',
'indexArn': 'string',
'creationTime': datetime(2015, 1, 1),
'dataType': 'float32',
'dimension': 123,
'distanceMetric': 'euclidean'|'cosine',
'metadataConfiguration': {
'nonFilterableMetadataKeys': [
'string',
],
'textSearchConfigurations': [
{
'metadataKey': 'string',
'language': 'en'|'fr'|'es'|'pt'|'it'|'de'|'nl'|'zh'|'ja'|'ko',
'status': 'ACTIVE'|'BUILDING'
},
]
},
'encryptionConfiguration': {
'sseType': 'AES256'|'aws:kms',
'kmsKeyArn': 'string'
},
'indexMode': 'CLASSIC'|'ENHANCED'
}
}
Response Structure
(dict) --
index (dict) --
The attributes of the vector index.
vectorBucketName (string) --
The name of the vector bucket that contains the vector index.
indexName (string) --
The name of the vector index.
indexArn (string) --
The Amazon Resource Name (ARN) of the vector index.
creationTime (datetime) --
Date and time when the vector index was created.
dataType (string) --
The data type of the vectors inserted into the vector index.
dimension (integer) --
The number of values in the vectors that are inserted into the vector index.
distanceMetric (string) --
The distance metric to be used for similarity search.
metadataConfiguration (dict) --
The metadata configuration for the vector index.
nonFilterableMetadataKeys (list) --
Non-filterable metadata keys allow you to enrich vectors with additional context during storage and retrieval. You can't use these keys in metadata filters. You can still make a non-filterable key full-text searchable by configuring it separately in textSearchConfigurations. You can retrieve non-filterable metadata keys after finding the vectors. For more information about non-filterable metadata keys, see Vectors and Limitations and restrictions in the Amazon S3 User Guide.
(string) --
textSearchConfigurations (list) --
Full-text search configurations for searchable metadata keys.
(dict) --
A full-text search configuration for a single metadata key.
metadataKey (string) --
The metadata key to make full-text searchable.
language (string) --
The language that the text search analyzer uses. Valid values are en (English), fr (French), es (Spanish), pt (Portuguese), it (Italian), de (German), nl (Dutch), zh (Chinese), ja (Japanese), and ko (Korean). If you don't specify a language, Amazon S3 Vectors uses the default standard analyzer.
status (string) --
The backfill status of the text search configuration. Valid values are ACTIVE, which indicates that the analyzer is built and serving queries, and BUILDING, which indicates that the analyzer is being backfilled and isn't yet serving queries. This field is returned by GetIndex.
encryptionConfiguration (dict) --
The encryption configuration for a vector index. By default, if you don't specify, all new vectors in the vector index will use the encryption configuration of the vector bucket.
sseType (string) --
The server-side encryption type to use for the encryption configuration of the vector bucket. By default, if you don't specify, all new vectors in Amazon S3 vector buckets use server-side encryption with Amazon S3 managed keys (SSE-S3), specifically AES256.
kmsKeyArn (string) --
Amazon Web Services Key Management Service (KMS) customer managed key ID to use for the encryption configuration. This parameter is allowed if and only if sseType is set to aws:kms.
To specify the KMS key, you must use the format of the KMS key Amazon Resource Name (ARN).
For example, specify Key ARN in the following format: arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
indexMode (string) --
The mode that determines how the vector index processes queries.
Valid values:
CLASSIC - Applies metadata filters during the vector search.
ENHANCED - Applies metadata filters before the vector search.
{'queryTexts': [{'metadataKey': 'string', 'text': 'string'}],
'returnScores': 'boolean'}
Response {'vectors': {'scores': {'bm25Scores': [{'metadataKey': 'string',
'score': 'float'}],
'fused': 'float',
'vectorDistance': 'float'}}}
Returns matching vector keys from a vector index ranked by vector similarity, full-text relevance, or both. Specify queryVector to perform a vector search, specify queryTexts to perform a full-text search, or specify both to perform a hybrid search. Full-text search ranks results using BM25. Hybrid search combines the vector and full-text rankings using Reciprocal Rank Fusion (RRF).
Amazon S3 Vectors ranks results by distance for a vector-only search, by BM25 score for a full-text-only search, and by RRF score for a hybrid search. You can optionally include computed distances, relevance scores, and vector metadata in the response. Full-text and hybrid searches require a vector index in ENHANCED mode.
To specify the vector index, you can either use both the vector bucket name and the vector index name, or use the vector index Amazon Resource Name (ARN).
Permissions
You must have the s3vectors:QueryVectors permission to use this operation. Additional permissions are required based on the request parameters you specify:
With only s3vectors:QueryVectors permission, you can retrieve vector keys of approximate nearest neighbors and computed distances between these vectors. This permission is sufficient only when you don't set queryTexts, don't set any metadata filters, and don't request metadata (by keeping the returnMetadata parameter set to false or not specified).
To use queryTexts, a metadata filter, or returnMetadata set to true with this operation, you must have both the s3vectors:QueryVectors and s3vectors:GetVectors permissions. If you use any of these options without the s3vectors:GetVectors permission, Amazon S3 Vectors returns an AccessDeniedException.
See also: AWS API Documentation
Request Syntax
client.query_vectors(
vectorBucketName='string',
indexName='string',
indexArn='string',
topK=123,
queryVector={
'float32': [
...,
]
},
filter={...}|[...]|123|123.4|'string'|True|None,
queryMode='CLASSIC'|'ENHANCED',
returnMetadata=True|False,
returnDistance=True|False,
queryTexts=[
{
'text': 'string',
'metadataKey': 'string'
},
],
returnScores=True|False,
nextToken='string'
)
string
The name of the vector bucket that contains the vector index.
string
The name of the vector index that you want to query.
string
The ARN of the vector index that you want to query.
integer
[REQUIRED]
The number of results to return for each query.
dict
The query vector for vector similarity search. The query vector must have the same dimension as the vector index. For example, if the vector index has 384 dimensions, the query vector must also have 384 dimensions. You can omit this parameter when you supply queryTexts to perform a full-text-only search. A request must include queryVector, queryTexts, or both.
float32 (list) --
The vector data as 32-bit floating point numbers. The number of elements in this array must exactly match the dimension of the vector index where the operation is being performed.
(float) --
:ref:`document<document>`
Metadata filter to apply during the query. For more information about metadata keys, see Metadata filtering in the Amazon S3 User Guide.
string
The mode to use to process the query. If you don't specify a query mode, the operation uses the mode that's currently configured for the vector index.
Valid values:
CLASSIC - Applies metadata filters during the vector search. You can't specify CLASSIC for an ENHANCED index.
ENHANCED - Applies metadata filters before the vector search.
boolean
Indicates whether to include metadata in the response. The default value is false.
boolean
Indicates whether to include the computed distance in the response. The default value is false.
list
Full-text queries for searchable metadata keys. Omit queryVector to run a full-text-only search, or provide both fields to run a hybrid search. Each entry must target a distinct searchable metadata key.
(dict) --
A full-text search query for a single metadata key.
text (string) -- [REQUIRED]
The full-text query string.
metadataKey (string) -- [REQUIRED]
The searchable metadata key to query.
boolean
Indicates whether to include relevance scores in the response. Full-text-only results can include BM25 scores. Hybrid results can also include a Reciprocal Rank Fusion (RRF) score and vector distance. This setting doesn't add scores to vector-only requests. The default value is false.
string
Pagination token from a previous request. The value of this field is empty for an initial request.
dict
Response Syntax
{
'vectors': [
{
'distance': ...,
'scores': {
'fused': ...,
'bm25Scores': [
{
'metadataKey': 'string',
'score': ...
},
],
'vectorDistance': ...
},
'key': 'string',
'metadata': {...}|[...]|123|123.4|'string'|True|None
},
],
'distanceMetric': 'euclidean'|'cosine',
'nextToken': 'string'
}
Response Structure
(dict) --
vectors (list) --
The matching vector results in ranked order. Results are ranked by vector distance for a vector-only search, by BM25 relevance for a full-text-only search, and by RRF score for a hybrid search.
(dict) --
Contains the key and optional distance, relevance scores, and metadata for a vector returned by the QueryVectors operation.
distance (float) --
The measure of similarity between the vector in the response and the query vector.
scores (dict) --
The relevance scores for a full-text-only or hybrid result, when requested through returnScores.
fused (float) --
The Reciprocal Rank Fusion (RRF) score that combines the vector and full-text rankings. This field is returned only for hybrid requests.
bm25Scores (list) --
The BM25 scores for the searchable metadata keys that the result matched.
(dict) --
The raw BM25 relevance score for a single searchable metadata key.
metadataKey (string) --
The searchable metadata key that the score applies to.
score (float) --
The BM25 relevance score.
vectorDistance (float) --
The distance from the query vector. This field is returned when a hybrid result matches the vector search.
key (string) --
The key of the matching vector.
metadata (:ref:`document<document>`) --
The metadata associated with the vector, if requested.
distanceMetric (string) --
The distance metric that was used for the similarity search calculation. This is the same distance metric that was configured for the vector index when it was created.
nextToken (string) --
Pagination token to be used in the subsequent page request. The field is empty if no further pagination is required.