DynamoDB / Client / search_vectors

search_vectors¶

DynamoDB.Client.search_vectors(**kwargs)¶

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.

Request Syntax

response = client.search_vectors(
    TableName='string',
    IndexName='string',
    ReturnConsumedCapacity='INDEXES'|'TOTAL'|'NONE',
    ExpressionAttributeNames={
        'string': 'string'
    },
    ExpressionAttributeValues={
        'string': {
            'S': 'string',
            'N': 'string',
            'B': b'bytes',
            'SS': [
                'string',
            ],
            'NS': [
                'string',
            ],
            'BS': [
                b'bytes',
            ],
            'M': {
                'string': {'... recursive ...'}
            },
            'L': [
                {'... recursive ...'},
            ],
            'NULL': True|False,
            'BOOL': True|False
        }
    },
    ProjectionExpression='string',
    SearchVector=[
        {
            'S': 'string',
            'N': 'string',
            'B': b'bytes',
            'SS': [
                'string',
            ],
            'NS': [
                'string',
            ],
            'BS': [
                b'bytes',
            ],
            'M': {
                'string': {'... recursive ...'}
            },
            'L': [
                {'... recursive ...'},
            ],
            'NULL': True|False,
            'BOOL': True|False
        },
    ],
    SearchConditionExpression='string',
    TopK=123
)

Parameters:

TableName (string) –
[REQUIRED]

The name or Amazon Resource Name (ARN) of the table containing the vector index.
IndexName (string) –
[REQUIRED]

The name of the vector index to search. The index must be in the ACTIVE state.
ReturnConsumedCapacity (string) –
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.
ExpressionAttributeNames (dict) –
One or more substitution tokens for attribute names in an expression. Use the # character in an expression to dereference an attribute name.
- (string) –
  - (string) –
ExpressionAttributeValues (dict) –
One or more values that can be substituted in an expression. Use the : character in an expression to dereference an attribute value.
- (string) –
  - (dict) –
    
    Represents the data for an attribute.
    
    Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.
    
    For more information, see Data Types in the Amazon DynamoDB Developer Guide.
    - S (string) –
      
      An attribute of type String. For example:
      
      "S": "Hello"
    - N (string) –
      
      An attribute of type Number. For example:
      
      "N": "123.45"
      
      Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.
    - B (bytes) –
      
      An attribute of type Binary. For example:
      
      "B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"
    - SS (list) –
      
      An attribute of type String Set. For example:
      
      "SS": ["Giraffe", "Hippo" ,"Zebra"]
      - (string) –
    - NS (list) –
      
      An attribute of type Number Set. For example:
      
      "NS": ["42.2", "-19", "7.5", "3.14"]
      
      Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.
      - (string) –
    - BS (list) –
      
      An attribute of type Binary Set. For example:
      
      "BS": ["U3Vubnk=", "UmFpbnk=", "U25vd3k="]
      - (bytes) –
    - M (dict) –
      
      An attribute of type Map. For example:
      
      "M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}
      - (string) –
        
        (dict) –
        
        Represents the data for an attribute.
        
        Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.
        
        For more information, see Data Types in the Amazon DynamoDB Developer Guide.
    - L (list) –
      
      An attribute of type List. For example:
      
      "L": [ {"S": "Cookies"} , {"S": "Coffee"}, {"N": "3.14159"}]
      - (dict) –
        
        Represents the data for an attribute.
        
        Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.
        
        For more information, see Data Types in the Amazon DynamoDB Developer Guide.
    - NULL (boolean) –
      
      An attribute of type Null. For example:
      
      "NULL": true
    - BOOL (boolean) –
      
      An attribute of type Boolean. For example:
      
      "BOOL": true
ProjectionExpression (string) –
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.
SearchVector (list) –
[REQUIRED]

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.
- (dict) –
  
  Represents the data for an attribute.
  
  Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.
  
  For more information, see Data Types in the Amazon DynamoDB Developer Guide.
  - S (string) –
    
    An attribute of type String. For example:
    
    "S": "Hello"
  - N (string) –
    
    An attribute of type Number. For example:
    
    "N": "123.45"
    
    Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.
  - B (bytes) –
    
    An attribute of type Binary. For example:
    
    "B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"
  - SS (list) –
    
    An attribute of type String Set. For example:
    
    "SS": ["Giraffe", "Hippo" ,"Zebra"]
    - (string) –
  - NS (list) –
    
    An attribute of type Number Set. For example:
    
    "NS": ["42.2", "-19", "7.5", "3.14"]
    
    Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.
    - (string) –
  - BS (list) –
    
    An attribute of type Binary Set. For example:
    
    "BS": ["U3Vubnk=", "UmFpbnk=", "U25vd3k="]
    - (bytes) –
  - M (dict) –
    
    An attribute of type Map. For example:
    
    "M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}
    - (string) –
      - (dict) –
        
        Represents the data for an attribute.
        
        Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.
        
        For more information, see Data Types in the Amazon DynamoDB Developer Guide.
  - L (list) –
    
    An attribute of type List. For example:
    
    "L": [ {"S": "Cookies"} , {"S": "Coffee"}, {"N": "3.14159"}]
    - (dict) –
      
      Represents the data for an attribute.
      
      Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.
      
      For more information, see Data Types in the Amazon DynamoDB Developer Guide.
  - NULL (boolean) –
    
    An attribute of type Null. For example:
    
    "NULL": true
  - BOOL (boolean) –
    
    An attribute of type Boolean. For example:
    
    "BOOL": true
SearchConditionExpression (string) –
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.
TopK (integer) –
[REQUIRED]

The number of most similar results to return.

Return type:

dict

Returns:

Response Syntax

{
    'ConsumedCapacity': {
        'VectorSearchRequestBytes': 123.0,
        'VectorWriteRequestBytes': 123.0
    },
    'SearchResults': [
        {
            'Item': {
                'string': {
                    'S': 'string',
                    'N': 'string',
                    'B': b'bytes',
                    'SS': [
                        'string',
                    ],
                    'NS': [
                        'string',
                    ],
                    'BS': [
                        b'bytes',
                    ],
                    'M': {
                        'string': {'... recursive ...'}
                    },
                    'L': [
                        {'... recursive ...'},
                    ],
                    'NULL': True|False,
                    'BOOL': True|False
                }
            },
            'Score': 123.0
        },
    ]
}

Response Structure

(dict) –
- ConsumedCapacity (dict) –
  
  The capacity units consumed by the SearchVectors operation. Contains VectorSearchRequestBytes, which represents the vector search capacity consumed.
  - VectorSearchRequestBytes (float) –
    
    The number of vector search request bytes consumed by a SearchVectors operation.
  - VectorWriteRequestBytes (float) –
    
    The number of vector write request bytes consumed when writing to a vector index. Reported for write operations that modify attributes indexed by a vector index.
- SearchResults (list) –
  
  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.
  - (dict) –
    
    A single result from a SearchVectors operation.
    - Item (dict) –
      
      A map of attribute names to AttributeValue objects, representing the projected attributes of the item returned by the vector search.
      - (string) –
        
        (dict) –
        
        Represents the data for an attribute.
        
        Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.
        
        For more information, see Data Types in the Amazon DynamoDB Developer Guide.
        
        S (string) –
        
        An attribute of type String. For example:
        
        "S": "Hello"
        
        N (string) –
        
        An attribute of type Number. For example:
        
        "N": "123.45"
        
        Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.
        
        B (bytes) –
        
        An attribute of type Binary. For example:
        
        "B": "dGhpcyB0ZXh0IGlzIGJhc2U2NC1lbmNvZGVk"
        
        SS (list) –
        
        An attribute of type String Set. For example:
        
        "SS": ["Giraffe", "Hippo" ,"Zebra"]
        
        (string) –
        
        NS (list) –
        
        An attribute of type Number Set. For example:
        
        "NS": ["42.2", "-19", "7.5", "3.14"]
        
        Numbers are sent across the network to DynamoDB as strings, to maximize compatibility across languages and libraries. However, DynamoDB treats them as number type attributes for mathematical operations.
        
        (string) –
        
        BS (list) –
        
        An attribute of type Binary Set. For example:
        
        "BS": ["U3Vubnk=", "UmFpbnk=", "U25vd3k="]
        
        (bytes) –
        
        M (dict) –
        
        An attribute of type Map. For example:
        
        "M": {"Name": {"S": "Joe"}, "Age": {"N": "35"}}
        
        (string) –
        
        (dict) –
        
        Represents the data for an attribute.
        
        Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.
        
        For more information, see Data Types in the Amazon DynamoDB Developer Guide.
        
        L (list) –
        
        An attribute of type List. For example:
        
        "L": [ {"S": "Cookies"} , {"S": "Coffee"}, {"N": "3.14159"}]
        
        (dict) –
        
        Represents the data for an attribute.
        
        Each attribute value is described as a name-value pair. The name is the data type, and the value is the data itself.
        
        For more information, see Data Types in the Amazon DynamoDB Developer Guide.
        
        NULL (boolean) –
        
        An attribute of type Null. For example:
        
        "NULL": true
        
        BOOL (boolean) –
        
        An attribute of type Boolean. For example:
        
        "BOOL": true
    - Score (float) –
      
      The similarity score for this item relative to the search vector. The interpretation depends on the distance function configured for the vector index.

search_vectors¶

Request Syntax

Response Syntax

Response Structure

Exceptions