2025/07/15 - Amazon S3 Vectors - 16 new api methods
Changes Amazon S3 Vectors provides cost-effective, elastic, and durable vector storage for queries based on semantic meaning and similarity.
Deletes a vector bucket. All vector indexes in the vector bucket must be deleted before the vector bucket can be deleted. To perform this operation, you must use either the vector bucket name or the vector bucket Amazon Resource Name (ARN).
Permissions
You must have the s3vectors:DeleteVectorBucket permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.delete_vector_bucket(
vectorBucketName='string',
vectorBucketArn='string'
)
string
The name of the vector bucket to delete.
string
The ARN of the vector bucket to delete.
dict
Response Syntax
{}
Response Structure
(dict) --
Adds one or more vectors to a vector index. 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).
For more information about limits, see Limitations and restrictions in the Amazon S3 User Guide.
You must have the s3vectors:PutVectors permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.put_vectors(
vectorBucketName='string',
indexName='string',
indexArn='string',
vectors=[
{
'key': 'string',
'data': {
'float32': [
...,
]
},
'metadata': {...}|[...]|123|123.4|'string'|True|None
},
]
)
string
The name of the vector bucket that contains the vector index.
string
The name of the vector index where you want to write vectors.
string
The ARN of the vector index where you want to write vectors.
list
[REQUIRED]
The vectors to add to a vector index. The number of vectors in a single request must not exceed the resource capacity, otherwise the request will be rejected with the error ServiceUnavailableException with the error message "Currently unable to handle the request".
(dict) --
The attributes of a vector to add to a vector index.
key (string) -- [REQUIRED]
The name of the vector. The key uniquely identifies the vector in a vector index.
data (dict) -- [REQUIRED]
The vector data of the vector.
Vector dimensions must match the dimension count that's configured for the vector index.
For the cosine distance metric, zero vectors (vectors containing all zeros) aren't allowed.
For both cosine and euclidean distance metrics, vector data must contain only valid floating-point values. Invalid values such as NaN (Not a Number) or Infinity aren't allowed.
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) --
metadata (:ref:`document<document>`) --
Metadata about the vector. All metadata entries undergo validation to ensure they meet the format requirements for size and data types.
dict
Response Syntax
{}
Response Structure
(dict) --
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.
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',
]
}
)
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) -- [REQUIRED]
Non-filterable metadata keys allow you to enrich vectors with additional context during storage and retrieval. Unlike default metadata keys, these keys can’t be used as query filters. Non-filterable metadata keys can be retrieved but can’t be searched, queried, or filtered. You can access non-filterable metadata keys of your vectors 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) --
dict
Response Syntax
{}
Response Structure
(dict) --
Creates a vector bucket in the Amazon Web Services Region that you want your bucket to be in.
Permissions
You must have the s3vectors:CreateVectorBucket permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.create_vector_bucket(
vectorBucketName='string',
encryptionConfiguration={
'sseType': 'AES256'|'aws:kms',
'kmsKeyArn': 'string'
}
)
string
[REQUIRED]
The name of the vector bucket to create.
dict
The encryption configuration for 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.
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
Response Syntax
{}
Response Structure
(dict) --
Creates a bucket policy for a vector bucket. To specify the bucket, you must use either the vector bucket name or the vector bucket Amazon Resource Name (ARN).
Permissions
You must have the s3vectors:PutVectorBucketPolicy permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.put_vector_bucket_policy(
vectorBucketName='string',
vectorBucketArn='string',
policy='string'
)
string
The name of the vector bucket.
string
The Amazon Resource Name (ARN) of the vector bucket.
string
[REQUIRED]
The JSON that defines the policy. For more information about bucket policies for S3 Vectors, see Managing vector bucket policies in the Amazon S3 User Guide.
dict
Response Syntax
{}
Response Structure
(dict) --
Returns vector bucket attributes. To specify the bucket, you must use either the vector bucket name or the vector bucket Amazon Resource Name (ARN).
Permissions
You must have the s3vectors:GetVectorBucket permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.get_vector_bucket(
vectorBucketName='string',
vectorBucketArn='string'
)
string
The name of the vector bucket to retrieve information about.
string
The ARN of the vector bucket to retrieve information about.
dict
Response Syntax
{
'vectorBucket': {
'vectorBucketName': 'string',
'vectorBucketArn': 'string',
'creationTime': datetime(2015, 1, 1),
'encryptionConfiguration': {
'sseType': 'AES256'|'aws:kms',
'kmsKeyArn': 'string'
}
}
}
Response Structure
(dict) --
vectorBucket (dict) --
The attributes of the vector bucket.
vectorBucketName (string) --
The name of the vector bucket.
vectorBucketArn (string) --
The Amazon Resource Name (ARN) of the vector bucket.
creationTime (datetime) --
Date and time when the vector bucket was created.
encryptionConfiguration (dict) --
The encryption configuration for 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
Deletes a vector bucket policy. To specify the bucket, you must use either the vector bucket name or the vector bucket Amazon Resource Name (ARN).
Permissions
You must have the s3vectors:DeleteVectorBucketPolicy permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.delete_vector_bucket_policy(
vectorBucketName='string',
vectorBucketArn='string'
)
string
The name of the vector bucket to delete the policy from.
string
The ARN of the vector bucket to delete the policy from.
dict
Response Syntax
{}
Response Structure
(dict) --
Performs an approximate nearest neighbor search query in a vector index using a query vector. By default, it returns the keys of approximate nearest neighbors. You can optionally include the computed distance (between the query vector and each vector in the response), the vector data, and metadata of each vector in the response.
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 any metadata filters and don't request vector data or metadata (by keeping the returnMetadata parameter set to false or not specified).
If you specify a metadata filter or set returnMetadata to true, you must have both s3vectors:QueryVectors and s3vectors:GetVectors permissions. The request fails with a 403 Forbidden error if you request metadata filtering, vector data, or metadata without the s3vectors:GetVectors permission.
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,
returnMetadata=True|False,
returnDistance=True|False
)
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
[REQUIRED]
The query vector. Ensure that the query vector has the same dimension as the dimension of the vector index that's being queried. For example, if your vector index contains vectors with 384 dimensions, your query vector must also have 384 dimensions.
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.
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.
dict
Response Syntax
{
'vectors': [
{
'key': 'string',
'data': {
'float32': [
...,
]
},
'metadata': {...}|[...]|123|123.4|'string'|True|None,
'distance': ...
},
]
}
Response Structure
(dict) --
vectors (list) --
The vectors in the approximate nearest neighbor search.
(dict) --
The attributes of a vector in the approximate nearest neighbor search.
key (string) --
The key of the vector in the approximate nearest neighbor search.
data (dict) --
The vector data associated with the vector, if requested.
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) --
metadata (:ref:`document<document>`) --
The metadata associated with the vector, if requested.
distance (float) --
The measure of similarity between the vector in the response and the query vector.
Returns vector 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:GetVectors permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.get_vectors(
vectorBucketName='string',
indexName='string',
indexArn='string',
keys=[
'string',
],
returnData=True|False,
returnMetadata=True|False
)
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.
list
[REQUIRED]
The names of the vectors you want to return attributes for.
(string) --
boolean
Indicates whether to include the vector data in the response. The default value is false.
boolean
Indicates whether to include metadata in the response. The default value is false.
dict
Response Syntax
{
'vectors': [
{
'key': 'string',
'data': {
'float32': [
...,
]
},
'metadata': {...}|[...]|123|123.4|'string'|True|None
},
]
}
Response Structure
(dict) --
vectors (list) --
The attributes of the vectors.
(dict) --
The attributes of a vector returned by the GetVectors operation.
key (string) --
The name of the vector.
data (dict) --
The vector data of the vector.
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) --
metadata (:ref:`document<document>`) --
Metadata about the vector.
Returns a list of all the vector buckets that are owned by the authenticated sender of the request.
Permissions
You must have the s3vectors:ListVectorBuckets permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.list_vector_buckets(
maxResults=123,
nextToken='string',
prefix='string'
)
integer
The maximum number of vector buckets to be returned in the response.
string
The previous pagination token.
string
Limits the response to vector buckets that begin with the specified prefix.
dict
Response Syntax
{
'nextToken': 'string',
'vectorBuckets': [
{
'vectorBucketName': 'string',
'vectorBucketArn': 'string',
'creationTime': datetime(2015, 1, 1)
},
]
}
Response Structure
(dict) --
nextToken (string) --
The element is included in the response when there are more buckets to be listed with pagination.
vectorBuckets (list) --
The list of vector buckets owned by the requester.
(dict) --
Summary information about a vector bucket.
vectorBucketName (string) --
The name of the vector bucket.
vectorBucketArn (string) --
The Amazon Resource Name (ARN) of the vector bucket.
creationTime (datetime) --
Date and time when the vector bucket was created.
Deletes a vector index. To specify the vector index, you can either use both the vector bucket name and vector index name, or use the vector index Amazon Resource Name (ARN).
Permissions
You must have the s3vectors:DeleteIndex permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.delete_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 to delete.
string
The ARN of the vector index to delete.
dict
Response Syntax
{}
Response Structure
(dict) --
Gets details about a vector bucket policy. To specify the bucket, you must use either the vector bucket name or the vector bucket Amazon Resource Name (ARN).
Permissions
You must have the s3vectors:GetVectorBucketPolicy permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.get_vector_bucket_policy(
vectorBucketName='string',
vectorBucketArn='string'
)
string
The name of the vector bucket.
string
The ARN of the vector bucket.
dict
Response Syntax
{
'policy': 'string'
}
Response Structure
(dict) --
policy (string) --
The JSON that defines the policy.
List vectors in the specified vector index. 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).
ListVectors operations proceed sequentially; however, for faster performance on a large number of vectors in a vector index, applications can request a parallel ListVectors operation by providing the segmentCount and segmentIndex parameters.
Permissions
You must have the s3vectors:ListVectors permission to use this operation. Additional permissions are required based on the request parameters you specify:
With only s3vectors:ListVectors permission, you can list vector keys when returnData and returnMetadata are both set to false or not specified..
If you set returnData or returnMetadata to true, you must have both s3vectors:ListVectors and s3vectors:GetVectors permissions. The request fails with a 403 Forbidden error if you request vector data or metadata without the s3vectors:GetVectors permission.
See also: AWS API Documentation
Request Syntax
client.list_vectors(
vectorBucketName='string',
indexName='string',
indexArn='string',
maxResults=123,
nextToken='string',
segmentCount=123,
segmentIndex=123,
returnData=True|False,
returnMetadata=True|False
)
string
The name of the vector bucket.
string
The name of the vector index.
string
The Amazon resource Name (ARN) of the vector index.
integer
The maximum number of vectors to return on a page.
If you don't specify maxResults, the ListVectors operation uses a default value of 500.
If the processed dataset size exceeds 1 MB before reaching the maxResults value, the operation stops and returns the vectors that are retrieved up to that point, along with a nextToken that you can use in a subsequent request to retrieve the next set of results.
string
Pagination token from a previous request. The value of this field is empty for an initial request.
integer
For a parallel ListVectors request, segmentCount represents the total number of vector segments into which the ListVectors operation will be divided. The value of segmentCount corresponds to the number of application workers that will perform the parallel ListVectors operation. For example, if you want to use four application threads to list vectors in a vector index, specify a segmentCount value of 4.
If you specify a segmentCount value of 1, the ListVectors operation will be sequential rather than parallel.
If you specify segmentCount, you must also specify segmentIndex.
integer
For a parallel ListVectors request, segmentIndex is the index of the segment from which to list vectors in the current request. It identifies an individual segment to be listed by an application worker.
Segment IDs are zero-based, so the first segment is always 0. For example, if you want to use four application threads to list vectors in a vector index, then the first thread specifies a segmentIndex value of 0, the second thread specifies 1, and so on.
The value of segmentIndex must be less than the value provided for segmentCount.
If you provide segmentIndex, you must also provide segmentCount.
boolean
If true, the vector data of each vector will be included in the response. The default value is false.
boolean
If true, the metadata associated with each vector will be included in the response. The default value is false.
dict
Response Syntax
{
'nextToken': 'string',
'vectors': [
{
'key': 'string',
'data': {
'float32': [
...,
]
},
'metadata': {...}|[...]|123|123.4|'string'|True|None
},
]
}
Response Structure
(dict) --
nextToken (string) --
Pagination token to be used in the subsequent request. The field is empty if no further pagination is required.
vectors (list) --
Vectors in the current segment.
(dict) --
The attributes of a vector returned by the ListVectors operation.
key (string) --
The name of the vector.
data (dict) --
The vector data of the vector.
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) --
metadata (:ref:`document<document>`) --
Metadata about the vector.
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',
]
}
}
}
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. Unlike default metadata keys, these keys can’t be used as query filters. Non-filterable metadata keys can be retrieved but can’t be searched, queried, or filtered. You can access non-filterable metadata keys of your vectors 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) --
Returns a list of all the vector indexes within the specified vector bucket. To specify the bucket, you must use either the vector bucket name or the vector bucket Amazon Resource Name (ARN).
Permissions
You must have the s3vectors:ListIndexes permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.list_indexes(
vectorBucketName='string',
vectorBucketArn='string',
maxResults=123,
nextToken='string',
prefix='string'
)
string
The name of the vector bucket that contains the vector indexes.
string
The ARN of the vector bucket that contains the vector indexes.
integer
The maximum number of items to be returned in the response.
string
The previous pagination token.
string
Limits the response to vector indexes that begin with the specified prefix.
dict
Response Syntax
{
'nextToken': 'string',
'indexes': [
{
'vectorBucketName': 'string',
'indexName': 'string',
'indexArn': 'string',
'creationTime': datetime(2015, 1, 1)
},
]
}
Response Structure
(dict) --
nextToken (string) --
The next pagination token.
indexes (list) --
The attributes of the vector indexes
(dict) --
Summary information about a 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.
Deletes one or more vectors in a vector index. To specify the vector index, you can either use both the vector bucket name and vector index name, or use the vector index Amazon Resource Name (ARN).
Permissions
You must have the s3vectors:DeleteVectors permission to use this operation.
See also: AWS API Documentation
Request Syntax
client.delete_vectors(
vectorBucketName='string',
indexName='string',
indexArn='string',
keys=[
'string',
]
)
string
The name of the vector bucket that contains the vector index.
string
The name of the vector index that contains a vector you want to delete.
string
The ARN of the vector index that contains a vector you want to delete.
list
[REQUIRED]
The keys of the vectors to delete.
(string) --
dict
Response Syntax
{}
Response Structure
(dict) --