Skip to content

DynamoDB  >  Operations  >  search_vectors

search_vectors

Operation

search_vectors async 

search_vectors(input: SearchVectorsInput, plugins: list[Plugin] | None = None) -> SearchVectorsOutput

Performs a vector similarity search on a vector index associated with an Amazon DynamoDB table, and returns the most similar items sorted by similarity score based on the distance function configured for the index.

Score interpretation depends on the distance function:

  • COSINE - Returns the items with the k smallest scores. Scores range from 0 (identical) to 2 (opposite). Lower scores indicate higher similarity.

  • EUCLIDEAN - Returns the items with the k smallest scores. Scores represent the Euclidean distance between vectors. Lower scores indicate higher similarity.

  • DOT_PRODUCT - Returns the items with the k highest scores. Higher scores indicate higher similarity.

Parameters:

Name Type Description Default
input SearchVectorsInput

An instance of SearchVectorsInput.

 required
plugins list[Plugin] | None

A list of callables that modify the configuration dynamically. Changes made by these plugins only apply for the duration of the operation execution and will not affect any other operation invocations.

 None

Returns:

Type Description
SearchVectorsOutput

An instance of SearchVectorsOutput.

Input

SearchVectorsInput dataclass

Dataclass for SearchVectorsInput structure.

Attributes

expression_attribute_names class-attribute instance-attribute 
expression_attribute_names: dict[str, str] | None = None

One or more substitution tokens for attribute names in an expression. Use the # character in an expression to dereference an attribute name.

expression_attribute_values class-attribute instance-attribute 
expression_attribute_values: dict[str, AttributeValue] | None = None

One or more values that can be substituted in an expression. Use the : character in an expression to dereference an attribute value.

index_name class-attribute instance-attribute 
index_name: str | None = None

The name of the vector index to search. The index must be in the ACTIVE state.

projection_expression class-attribute instance-attribute 
projection_expression: str | None = None

A string that identifies one or more attributes to retrieve from the index. Separate attribute names with commas. If not specified, the operation returns all attributes projected into the vector index.

Only attributes projected into the vector index can be retrieved.

return_consumed_capacity class-attribute instance-attribute 
return_consumed_capacity: ReturnConsumedCapacity | None = None

Determines the level of detail about either provisioned or on-demand throughput consumption that is returned in the response:

  • INDEXES - The response includes the aggregate ConsumedCapacity for the operation, together with ConsumedCapacity for each table and secondary index that was accessed.

Note that some operations, such as GetItem and BatchGetItem, do not access any indexes at all. In these cases, specifying INDEXES will only return ConsumedCapacity information for table(s).

  • TOTAL - The response includes only the aggregate ConsumedCapacity for the operation.

  • NONE - No ConsumedCapacity details are included in the response.

search_condition_expression class-attribute instance-attribute 
search_condition_expression: str | None = None

A condition expression used to filter the vector search results. The expression can reference attributes defined in the vector index search schema, including HASH and INLINE_FILTER key elements.

Only the equality operator (=) is supported for HASH attributes. Comparison and range operators are supported for INLINE_FILTER attributes. Only top-level attributes from the search schema can be referenced.

search_vector class-attribute instance-attribute 
search_vector: list[AttributeValue] | None = None

The search vector to compare against the indexed vectors. Each element is a 32-bit IEEE-754 floating point number, provided in DynamoDB list format.

The number of dimensions must match the number of dimensions configured for the vector index.

table_name class-attribute instance-attribute 
table_name: str | None = None

The name or Amazon Resource Name (ARN) of the table containing the vector index.

top_k class-attribute instance-attribute 
top_k: int | None = None

The number of most similar results to return.

Output

SearchVectorsOutput dataclass

Dataclass for SearchVectorsOutput structure.

Attributes

consumed_capacity class-attribute instance-attribute 
consumed_capacity: VectorCapacity | None = None

The capacity units consumed by the SearchVectors operation. Contains VectorSearchRequestBytes, which represents the vector search capacity consumed.

search_results class-attribute instance-attribute 
search_results: list[SearchResultItem] | None = None

A list of items returned by the vector similarity search, sorted by similarity with the most similar item first. Each item contains the projected attributes and a similarity score.