SDK for PHP 3.x

The requested action isn't valid.

The service is unavailable. Wait briefly and retry your request. If it continues to fail, increase your waiting time between retries.

The request was denied due to request throttling.

The request was rejected for one of the following reasons:

The KeyUsage value of the KMS key is incompatible with the API operation.
The encryption algorithm or signing algorithm specified for the operation is incompatible with the type of key material in the KMS key (KeySpec).

For more information, see InvalidKeyUsageException in the Amazon Web Services Key Management Service API Reference.

The request failed due to an internal server error.

The key state of the KMS key isn't compatible with the operation.

For more information, see KMSInvalidStateException in the Amazon Web Services Key Management Service API Reference.

Access denied.

The KMS key can't be found.

The request was rejected because the specified resource can't be found.

Your request exceeds a service quota.

The specified Amazon Web Services KMS key isn't enabled.

GetIndex

$result = $client->getIndex([/* ... */]);
$promise = $client->getIndexAsync([/* ... */]);

Amazon S3 Vectors is in preview release for Amazon S3 and is subject to change.

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.

Parameter Syntax

$result = $client->getIndex([
    'indexArn' => '<string>',
    'indexName' => '<string>',
    'vectorBucketName' => '<string>',
]);

Parameter Details

Members

indexArn

: Type: string

The ARN of the vector index.

indexName

: Type: string

The name of the vector index.

vectorBucketName

: Type: string

The name of the vector bucket that contains the vector index.

Result Syntax

[
    'index' => [
        'creationTime' => <DateTime>,
        'dataType' => 'float32',
        'dimension' => <integer>,
        'distanceMetric' => 'euclidean|cosine',
        'indexArn' => '<string>',
        'indexName' => '<string>',
        'metadataConfiguration' => [
            'nonFilterableMetadataKeys' => ['<string>', ...],
        ],
        'vectorBucketName' => '<string>',
    ],
]

Result Details

Members

index

: Required: Yes
: Type: Index structure

The attributes of the vector index.

Errors

ValidationException:: The requested action isn't valid.
ServiceUnavailableException:: The service is unavailable. Wait briefly and retry your request. If it continues to fail, increase your waiting time between retries.
TooManyRequestsException:: The request was denied due to request throttling.
InternalServerException:: The request failed due to an internal server error.
AccessDeniedException:: Access denied.
NotFoundException:: The request was rejected because the specified resource can't be found.
ServiceQuotaExceededException:: Your request exceeds a service quota.

GetVectorBucket

$result = $client->getVectorBucket([/* ... */]);
$promise = $client->getVectorBucketAsync([/* ... */]);

Amazon S3 Vectors is in preview release for Amazon S3 and is subject to change.

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.

Parameter Syntax

$result = $client->getVectorBucket([
    'vectorBucketArn' => '<string>',
    'vectorBucketName' => '<string>',
]);

Parameter Details

Members

vectorBucketArn

: Type: string

The ARN of the vector bucket to retrieve information about.

vectorBucketName

: Type: string

The name of the vector bucket to retrieve information about.

Result Syntax

[
    'vectorBucket' => [
        'creationTime' => <DateTime>,
        'encryptionConfiguration' => [
            'kmsKeyArn' => '<string>',
            'sseType' => 'AES256|aws:kms',
        ],
        'vectorBucketArn' => '<string>',
        'vectorBucketName' => '<string>',
    ],
]

Result Details

Members

vectorBucket

: Required: Yes
: Type: VectorBucket structure

The attributes of the vector bucket.

Errors

ValidationException:: The requested action isn't valid.
ServiceUnavailableException:: The service is unavailable. Wait briefly and retry your request. If it continues to fail, increase your waiting time between retries.
TooManyRequestsException:: The request was denied due to request throttling.
InternalServerException:: The request failed due to an internal server error.
AccessDeniedException:: Access denied.
NotFoundException:: The request was rejected because the specified resource can't be found.
ServiceQuotaExceededException:: Your request exceeds a service quota.

GetVectorBucketPolicy

$result = $client->getVectorBucketPolicy([/* ... */]);
$promise = $client->getVectorBucketPolicyAsync([/* ... */]);

Amazon S3 Vectors is in preview release for Amazon S3 and is subject to change.

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.

Parameter Syntax

$result = $client->getVectorBucketPolicy([
    'vectorBucketArn' => '<string>',
    'vectorBucketName' => '<string>',
]);

Parameter Details

Members

vectorBucketArn

: Type: string

The ARN of the vector bucket.

vectorBucketName

: Type: string

The name of the vector bucket.

Result Syntax

[
    'policy' => '<string>',
]

Result Details

Members

policy

: Type: string

The JSON that defines the policy.

Errors

ValidationException:: The requested action isn't valid.
ServiceUnavailableException:: The service is unavailable. Wait briefly and retry your request. If it continues to fail, increase your waiting time between retries.
TooManyRequestsException:: The request was denied due to request throttling.
InternalServerException:: The request failed due to an internal server error.
AccessDeniedException:: Access denied.
NotFoundException:: The request was rejected because the specified resource can't be found.
ServiceQuotaExceededException:: Your request exceeds a service quota.

GetVectors

$result = $client->getVectors([/* ... */]);
$promise = $client->getVectorsAsync([/* ... */]);

Amazon S3 Vectors is in preview release for Amazon S3 and is subject to change.

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.

Parameter Syntax

$result = $client->getVectors([
    'indexArn' => '<string>',
    'indexName' => '<string>',
    'keys' => ['<string>', ...], // REQUIRED
    'returnData' => true || false,
    'returnMetadata' => true || false,
    'vectorBucketName' => '<string>',
]);

Parameter Details

Members

indexArn

: Type: string

The ARN of the vector index.

indexName

: Type: string

The name of the vector index.

keys

: Required: Yes
: Type: Array of strings

The names of the vectors you want to return attributes for.

returnData

: Type: boolean

Indicates whether to include the vector data in the response. The default value is false.

returnMetadata

: Type: boolean

Indicates whether to include metadata in the response. The default value is false.

vectorBucketName

: Type: string

The name of the vector bucket that contains the vector index.

Result Syntax

[
    'vectors' => [
        [
            'data' => [
                'float32' => [<float>, ...],
            ],
            'key' => '<string>',
            'metadata' => [
            ],
        ],
        // ...
    ],
]

Result Details

Members

vectors

: Required: Yes
: Type: Array of GetOutputVector structures

The attributes of the vectors.

Errors

The requested action isn't valid.

The service is unavailable. Wait briefly and retry your request. If it continues to fail, increase your waiting time between retries.

The request was denied due to request throttling.

The request was rejected for one of the following reasons:

The KeyUsage value of the KMS key is incompatible with the API operation.
The encryption algorithm or signing algorithm specified for the operation is incompatible with the type of key material in the KMS key (KeySpec).

For more information, see InvalidKeyUsageException in the Amazon Web Services Key Management Service API Reference.

The request failed due to an internal server error.

The key state of the KMS key isn't compatible with the operation.

For more information, see KMSInvalidStateException in the Amazon Web Services Key Management Service API Reference.

Access denied.

The KMS key can't be found.

The request was rejected because the specified resource can't be found.

Your request exceeds a service quota.

The specified Amazon Web Services KMS key isn't enabled.

ListIndexes

$result = $client->listIndexes([/* ... */]);
$promise = $client->listIndexesAsync([/* ... */]);

Amazon S3 Vectors is in preview release for Amazon S3 and is subject to change.

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.

Parameter Syntax

$result = $client->listIndexes([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'prefix' => '<string>',
    'vectorBucketArn' => '<string>',
    'vectorBucketName' => '<string>',
]);

Parameter Details

Members

maxResults

: Type: int

The maximum number of items to be returned in the response.

nextToken

: Type: string

The previous pagination token.

prefix

: Type: string

Limits the response to vector indexes that begin with the specified prefix.

vectorBucketArn

: Type: string

The ARN of the vector bucket that contains the vector indexes.

vectorBucketName

: Type: string

The name of the vector bucket that contains the vector indexes.

Result Syntax

[
    'indexes' => [
        [
            'creationTime' => <DateTime>,
            'indexArn' => '<string>',
            'indexName' => '<string>',
            'vectorBucketName' => '<string>',
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members

indexes

: Required: Yes
: Type: Array of IndexSummary structures

The attributes of the vector indexes

nextToken

: Type: string

The next pagination token.

Errors

ValidationException:: The requested action isn't valid.
ServiceUnavailableException:: The service is unavailable. Wait briefly and retry your request. If it continues to fail, increase your waiting time between retries.
TooManyRequestsException:: The request was denied due to request throttling.
InternalServerException:: The request failed due to an internal server error.
AccessDeniedException:: Access denied.
NotFoundException:: The request was rejected because the specified resource can't be found.
ServiceQuotaExceededException:: Your request exceeds a service quota.

ListVectorBuckets

$result = $client->listVectorBuckets([/* ... */]);
$promise = $client->listVectorBucketsAsync([/* ... */]);

Amazon S3 Vectors is in preview release for Amazon S3 and is subject to change.

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.

Parameter Syntax

$result = $client->listVectorBuckets([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'prefix' => '<string>',
]);

Parameter Details

Members

maxResults

: Type: int

The maximum number of vector buckets to be returned in the response.

nextToken

: Type: string

The previous pagination token.

prefix

: Type: string

Limits the response to vector buckets that begin with the specified prefix.

Result Syntax

[
    'nextToken' => '<string>',
    'vectorBuckets' => [
        [
            'creationTime' => <DateTime>,
            'vectorBucketArn' => '<string>',
            'vectorBucketName' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members

nextToken

: Type: string

The element is included in the response when there are more buckets to be listed with pagination.

vectorBuckets

: Required: Yes
: Type: Array of VectorBucketSummary structures

The list of vector buckets owned by the requester.

Errors

ValidationException:: The requested action isn't valid.
ServiceUnavailableException:: The service is unavailable. Wait briefly and retry your request. If it continues to fail, increase your waiting time between retries.
TooManyRequestsException:: The request was denied due to request throttling.
InternalServerException:: The request failed due to an internal server error.
AccessDeniedException:: Access denied.
ServiceQuotaExceededException:: Your request exceeds a service quota.

ListVectors

$result = $client->listVectors([/* ... */]);
$promise = $client->listVectorsAsync([/* ... */]);

Amazon S3 Vectors is in preview release for Amazon S3 and is subject to change.

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.

Parameter Syntax

$result = $client->listVectors([
    'indexArn' => '<string>',
    'indexName' => '<string>',
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'returnData' => true || false,
    'returnMetadata' => true || false,
    'segmentCount' => <integer>,
    'segmentIndex' => <integer>,
    'vectorBucketName' => '<string>',
]);

Parameter Details

Members

indexArn

: Type: string

The Amazon resource Name (ARN) of the vector index.

indexName

: Type: string

The name of the vector index.

maxResults

: Type: int

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.

nextToken

: Type: string

Pagination token from a previous request. The value of this field is empty for an initial request.

returnData

: Type: boolean

If true, the vector data of each vector will be included in the response. The default value is false.

returnMetadata

: Type: boolean

If true, the metadata associated with each vector will be included in the response. The default value is false.

segmentCount

: Type: int

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.

segmentIndex

: Type: int

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.

vectorBucketName

: Type: string

The name of the vector bucket.

Result Syntax

[
    'nextToken' => '<string>',
    'vectors' => [
        [
            'data' => [
                'float32' => [<float>, ...],
            ],
            'key' => '<string>',
            'metadata' => [
            ],
        ],
        // ...
    ],
]

Result Details

Members

nextToken

: Type: string

Pagination token to be used in the subsequent request. The field is empty if no further pagination is required.

vectors

: Required: Yes
: Type: Array of ListOutputVector structures

Vectors in the current segment.

Errors

ValidationException:: The requested action isn't valid.
ServiceUnavailableException:: The service is unavailable. Wait briefly and retry your request. If it continues to fail, increase your waiting time between retries.
TooManyRequestsException:: The request was denied due to request throttling.
InternalServerException:: The request failed due to an internal server error.
AccessDeniedException:: Access denied.
NotFoundException:: The request was rejected because the specified resource can't be found.
ServiceQuotaExceededException:: Your request exceeds a service quota.

PutVectorBucketPolicy

$result = $client->putVectorBucketPolicy([/* ... */]);
$promise = $client->putVectorBucketPolicyAsync([/* ... */]);

Amazon S3 Vectors is in preview release for Amazon S3 and is subject to change.

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.

Parameter Syntax

$result = $client->putVectorBucketPolicy([
    'policy' => '<string>', // REQUIRED
    'vectorBucketArn' => '<string>',
    'vectorBucketName' => '<string>',
]);

Parameter Details

Members

policy

: Required: Yes
: Type: string

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.

vectorBucketArn

: Type: string

The Amazon Resource Name (ARN) of the vector bucket.

vectorBucketName

: Type: string

The name of the vector bucket.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ValidationException:: The requested action isn't valid.
ServiceUnavailableException:: The service is unavailable. Wait briefly and retry your request. If it continues to fail, increase your waiting time between retries.
TooManyRequestsException:: The request was denied due to request throttling.
InternalServerException:: The request failed due to an internal server error.
AccessDeniedException:: Access denied.
NotFoundException:: The request was rejected because the specified resource can't be found.
ServiceQuotaExceededException:: Your request exceeds a service quota.

PutVectors

$result = $client->putVectors([/* ... */]);
$promise = $client->putVectorsAsync([/* ... */]);

Amazon S3 Vectors is in preview release for Amazon S3 and is subject to change.

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.

When inserting vector data into your vector index, you must provide the vector data as float32 (32-bit floating point) values. If you pass higher-precision values to an Amazon Web Services SDK, S3 Vectors converts the values to 32-bit floating point before storing them, and GetVectors, ListVectors, and QueryVectors operations return the float32 values. Different Amazon Web Services SDKs may have different default numeric types, so ensure your vectors are properly formatted as float32 values regardless of which SDK you're using. For example, in Python, use numpy.float32 or explicitly cast your values.

Permissions: You must have the s3vectors:PutVectors permission to use this operation.

Parameter Syntax

$result = $client->putVectors([
    'indexArn' => '<string>',
    'indexName' => '<string>',
    'vectorBucketName' => '<string>',
    'vectors' => [ // REQUIRED
        [
            'data' => [ // REQUIRED
                'float32' => [<float>, ...],
            ],
            'key' => '<string>', // REQUIRED
            'metadata' => [
            ],
        ],
        // ...
    ],
]);

Parameter Details

Members

indexArn

: Type: string

The ARN of the vector index where you want to write vectors.

indexName

: Type: string

The name of the vector index where you want to write vectors.

vectorBucketName

: Type: string

The name of the vector bucket that contains the vector index.

vectors

: Required: Yes
: Type: Array of PutInputVector structures

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".

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

The requested action isn't valid.

The service is unavailable. Wait briefly and retry your request. If it continues to fail, increase your waiting time between retries.

The request was denied due to request throttling.

The request was rejected for one of the following reasons:

The KeyUsage value of the KMS key is incompatible with the API operation.
The encryption algorithm or signing algorithm specified for the operation is incompatible with the type of key material in the KMS key (KeySpec).

For more information, see InvalidKeyUsageException in the Amazon Web Services Key Management Service API Reference.

The request failed due to an internal server error.

The key state of the KMS key isn't compatible with the operation.

For more information, see KMSInvalidStateException in the Amazon Web Services Key Management Service API Reference.

Access denied.

The KMS key can't be found.

The request was rejected because the specified resource can't be found.

Your request exceeds a service quota.

The specified Amazon Web Services KMS key isn't enabled.

QueryVectors

$result = $client->queryVectors([/* ... */]);
$promise = $client->queryVectorsAsync([/* ... */]);

Amazon S3 Vectors is in preview release for Amazon S3 and is subject to change.

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.

Parameter Syntax

$result = $client->queryVectors([
    'filter' => [
    ],
    'indexArn' => '<string>',
    'indexName' => '<string>',
    'queryVector' => [ // REQUIRED
        'float32' => [<float>, ...],
    ],
    'returnDistance' => true || false,
    'returnMetadata' => true || false,
    'topK' => <integer>, // REQUIRED
    'vectorBucketName' => '<string>',
]);

Parameter Details

Members

filter

: Type: document (null|bool|string|numeric) or an (array|associative array) whose members are all valid documents

Metadata filter to apply during the query. For more information about metadata keys, see Metadata filtering in the Amazon S3 User Guide.

indexArn

: Type: string

The ARN of the vector index that you want to query.

indexName

: Type: string

The name of the vector index that you want to query.

queryVector

: Required: Yes
: Type: VectorData structure

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.

returnDistance

: Type: boolean

Indicates whether to include the computed distance in the response. The default value is false.

returnMetadata

: Type: boolean

Indicates whether to include metadata in the response. The default value is false.

topK

: Required: Yes
: Type: int

The number of results to return for each query.

vectorBucketName

: Type: string

The name of the vector bucket that contains the vector index.

Result Syntax

[
    'vectors' => [
        [
            'data' => [
                'float32' => [<float>, ...],
            ],
            'distance' => <float>,
            'key' => '<string>',
            'metadata' => [
            ],
        ],
        // ...
    ],
]

Result Details

Members

vectors

: Required: Yes
: Type: Array of QueryOutputVector structures

The vectors in the approximate nearest neighbor search.

Errors

The requested action isn't valid.

The service is unavailable. Wait briefly and retry your request. If it continues to fail, increase your waiting time between retries.

The request was denied due to request throttling.

The request was rejected for one of the following reasons:

The KeyUsage value of the KMS key is incompatible with the API operation.
The encryption algorithm or signing algorithm specified for the operation is incompatible with the type of key material in the KMS key (KeySpec).

For more information, see InvalidKeyUsageException in the Amazon Web Services Key Management Service API Reference.

The request failed due to an internal server error.

The key state of the KMS key isn't compatible with the operation.

For more information, see KMSInvalidStateException in the Amazon Web Services Key Management Service API Reference.

Access denied.

The KMS key can't be found.

The request was rejected because the specified resource can't be found.

Your request exceeds a service quota.