search_vectors¶
Operation¶
search_vectors
¶
search_vectors(request: SearchVectorsInput | SearchVectorsInputDict | None = None, /, *, plugins: list[Plugin] | None = None, **kwargs: Unpack[SearchVectorsInputDict]) -> 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 |
|---|---|---|---|
request
|
SearchVectorsInput | SearchVectorsInputDict | None
|
The input as a model or dictionary. Pass this or keyword arguments, not both. |
None
|
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
|
**kwargs
|
Unpack[SearchVectorsInputDict]
|
The input fields as keyword arguments. |
{}
|
Returns:
| Type | Description |
|---|---|
SearchVectorsOutput
|
An instance of |
search_vectors
async
¶
search_vectors(request: SearchVectorsInput | SearchVectorsInputDict | None = None, /, *, plugins: list[Plugin] | None = None, **kwargs: Unpack[SearchVectorsInputDict]) -> 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 |
|---|---|---|---|
request
|
SearchVectorsInput | SearchVectorsInputDict | None
|
The input as a model or dictionary. Pass this or keyword arguments, not both. |
None
|
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
|
**kwargs
|
Unpack[SearchVectorsInputDict]
|
The input fields as keyword arguments. |
{}
|
Returns:
| Type | Description |
|---|---|
SearchVectorsOutput
|
An instance of |
Input¶
Pass the input as keyword arguments, a positional dictionary, or a positional model object. Pass plugins separately as a keyword argument.
SearchVectorsInputDict
¶
Bases: TypedDict
Dictionary form of SearchVectorsInput.
Attributes¶
expression_attribute_names
instance-attribute
¶
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
instance-attribute
¶
expression_attribute_values: Mapping[str, AttributeValue | AttributeValueDict] | 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
instance-attribute
¶
The name of the vector index to search. The index must be in the
ACTIVE state.
projection_expression
instance-attribute
¶
projection_expression: str | 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
instance-attribute
¶
return_consumed_capacity: str | 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 aggregateConsumedCapacityfor the operation, together withConsumedCapacityfor 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 aggregateConsumedCapacityfor the operation. -
NONE- NoConsumedCapacitydetails are included in the response.
search_condition_expression
instance-attribute
¶
search_condition_expression: str | 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.
The HASH and INLINE_FILTER attributes support only the equality
operator (=). You can reference only top-level attributes from the
search schema.
search_vector
instance-attribute
¶
search_vector: Required[Sequence[AttributeValue | AttributeValueDict]]
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
instance-attribute
¶
The name or Amazon Resource Name (ARN) of the table containing the vector index.
SearchVectorsInput
dataclass
¶
Bases: _SerdeShape
Dataclass for SearchVectorsInput structure.
Attributes¶
expression_attribute_names
class-attribute
instance-attribute
¶
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 = ...
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 = ...
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 = ...
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: str | 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 aggregateConsumedCapacityfor the operation, together withConsumedCapacityfor 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 aggregateConsumedCapacityfor the operation. -
NONE- NoConsumedCapacitydetails are included in the response.
search_condition_expression
class-attribute
instance-attribute
¶
search_condition_expression: str | 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.
The HASH and INLINE_FILTER attributes support only the equality
operator (=). You can reference only top-level attributes from the
search schema.
search_vector
class-attribute
instance-attribute
¶
search_vector: list[AttributeValue] | 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.
Output¶
SearchVectorsOutput
dataclass
¶
Bases: _SerdeShape
Dataclass for SearchVectorsOutput structure.
Attributes¶
consumed_capacity
class-attribute
instance-attribute
¶
consumed_capacity: VectorCapacity | None = ...
The capacity units consumed by the SearchVectors operation. Contains
VectorSearchRequestBytes, which represents the vector search capacity
consumed.
response_metadata
class-attribute
instance-attribute
¶
Metadata about the response that produced this output. Use this to recover the request identifiers a service's support team needs in order to investigate a call. Members of the metadata are individually optional.
search_results
class-attribute
instance-attribute
¶
search_results: list[SearchResultItem] | 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.