searchVectors method

Future<SearchVectorsOutput> searchVectors({
  1. required String indexName,
  2. required List<AttributeValue> searchVector,
  3. required String tableName,
  4. required int topK,
  5. Map<String, String>? expressionAttributeNames,
  6. Map<String, AttributeValue>? expressionAttributeValues,
  7. String? projectionExpression,
  8. ReturnConsumedCapacity? returnConsumedCapacity,
  9. String? searchConditionExpression,
})

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.

May throw InternalServerError. May throw RequestLimitExceeded. May throw ResourceNotFoundException. May throw ThrottlingException.

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

Parameter searchVector : 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.

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

Parameter topK : The number of most similar results to return.

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

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

Parameter projectionExpression : 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.

Parameter searchConditionExpression : 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.

Implementation

Future<SearchVectorsOutput> searchVectors({
  required String indexName,
  required List<AttributeValue> searchVector,
  required String tableName,
  required int topK,
  Map<String, String>? expressionAttributeNames,
  Map<String, AttributeValue>? expressionAttributeValues,
  String? projectionExpression,
  ReturnConsumedCapacity? returnConsumedCapacity,
  String? searchConditionExpression,
}) async {
  _s.validateNumRange(
    'topK',
    topK,
    1,
    1152921504606846976,
    isRequired: true,
  );
  final headers = <String, String>{
    'Content-Type': 'application/x-amz-json-1.0',
    'X-Amz-Target': 'DynamoDB_20120810.SearchVectors'
  };
  final jsonResponse = await _protocol.send(
    method: 'POST',
    requestUri: '/',
    exceptionFnMap: _exceptionFns,
    // TODO queryParams
    headers: headers,
    payload: {
      'IndexName': indexName,
      'SearchVector': searchVector,
      'TableName': tableName,
      'TopK': topK,
      if (expressionAttributeNames != null)
        'ExpressionAttributeNames': expressionAttributeNames,
      if (expressionAttributeValues != null)
        'ExpressionAttributeValues': expressionAttributeValues,
      if (projectionExpression != null)
        'ProjectionExpression': projectionExpression,
      if (returnConsumedCapacity != null)
        'ReturnConsumedCapacity': returnConsumedCapacity.value,
      if (searchConditionExpression != null)
        'SearchConditionExpression': searchConditionExpression,
    },
    endpoint: _resolveEndpoint(
      isSearchOperation: true,
      resourceArn: tableName,
    ),
  );

  return SearchVectorsOutput.fromJson(jsonResponse.body);
}