Tair (Redis® OSS-Compatible):Vector

Item

Description

Syntax

TVS.CREATEINDEX index_name dims algorithm distance_method [algo_param_key alog_param_value] ...

Time complexity

O(1)

Command description

Creates a vector index based on the specified distance formula and algorithm. The algorithm is used to create the index and perform queries. The index can be deleted only by running the TVS.DELINDEX command.

Parameter

• index_name: the name of the vector index.

• dims: the dimension of a vector. Vectors inserted into the index must have the same dimension. Valid values: 1 to 32768.

• algorithm: the algorithm used to create the index and perform queries. Valid values:

  • FLAT: uses the Flat Search algorithm to search for vectors without creating indexes. This algorithm is suitable for datasets that contain less than 10,000 records.

  • HNSW: uses HNSW graphs to create indexes and uses the HNSW algorithm to search for vectors. This algorithm is suitable for large datasets.

• distance_method: the method used to calculate the distance between two vectors. Valid values:

  • L2: the squared Euclidean distance between two vectors.

  • IP: the inner product of two vectors. You can calculate the distance between two vectors by using the following formula: 1 - Inner product of the two vectors.

  • COSINE: the cosine distance between two vectors. You can calculate the distance between two vectors by using the following formula: 1 - Cosine of the angle between the two vectors. This method involves converting the written vectors into unit vectors, which is known as L2 normalization. Therefore, the vector results may not be the same as the original vector values.

  • JACCARD: the Jaccard distance between two vectors. You can calculate the Jaccard distance between two vectors by using the following formula: 1 - Jaccard coefficient. If you set this parameter to JACCARD, you must set the data_type parameter to BINARY.

• algo_param_key and alog_param_value:

  • data_type: the data type of the (dense) vector. Valid values:

    • FLOAT32 (default): a four-byte single-precision floating-point number.

    • FLOAT16: a two-byte half-precision floating-point number that conforms to the IEEE 754-2008 standard. This data type reduces the storage usage of vectors, but compromises data precision. Valid values: -65519 to 65519.

    • BINARY: a binary vector that can include only 0 and 1 and supports only the Jaccard distance formula.

  • Parameters specific to HNSW indexes:

    • ef_construct: the length of the dynamic array if you use the HNSW algorithm to create a vector index. Default value: 100. Valid values: 1 to 1000. A greater value indicates higher approximate nearest neighbor (ANN) search accuracy. This results in higher performance overhead.

    • M: the maximum number of outgoing neighbors on each layer in a graph index structure. Default value: 16. Valid values: 1 to 100. A greater value indicates higher ANN search accuracy. This results in higher performance overhead.

    • auto_gc: specifies whether to enable automatic memory space reclamation for the index. Valid values: true and false. Default value: false. This parameter is available only for Tair instances whose minor version is 6.2.8.2 or later. An HNSW index uses the marked deletion method to delete vectors. After you enable this feature, the index automatically reclaims memory space, which helps reduce memory usage. However, this feature can affect the index performance of nearest-neighbor queries. Therefore, we recommend that your enable this feature only in scenarios where memory usage is a concern, and a decrease in nearest-neighbor query performance can be tolerated.

  • Parameters specific to hybrid indexes:

    • If you want to create an inverted index for a specific tag field, you must specify the field name and the corresponding data type in advance.

      The inverted_index_<field_name> int|long|float|double|string syntax is used to create an inverted index for the field specified by field_name. The supported data types are INT, LONG, FlOAT, DOUBLE, and STRING. The field name and the corresponding data type must be in lowercase.

      For example, if you want to create an inverted index on a field called productname of the STRING type, the syntax is inverted_index_productname string.

    • lexical_algorithm: the full-text search algorithm. Valid values:

      • bm25: the Okapi BM25 algorithm. You can pass in the original text and use the Tair vector service to create an index.

      • vector: the vector algorithm, which is suitable for sparse vectors.

        You must encode the original text into sparse vectors and provide them as input to the vector algorithm. Specify the input in the "[[2,0.221],[42,09688],..]" format. The Key field specifies an index and must be of the uint32_t type, and the Value field specifies the lexical frequency profile and must be of the FLOAT type.

    • If you set the lexical_algorithm parameter to bm25, you can further configure the following parameters:

      • analyzer: the analyzer that you want to use for text segmentation. Valid values: jieba and ik_smart. Default value: jieba.

      • k1: the term frequency saturation in the BM25 algorithm. The value must be greater than 0. Default value: 1.2.

      • b: the impact of the document length on the relevance score in the BM25 algorithm. Valid values: 0 to 1. Default value: 0.75.

    • If you set the lexical_algorithm parameter to vector, you can further configure the following parameters:

      • lexical_use_hnsw: specifies whether to use HNSW indexes for sparse vectors. Valid values: 1 and 0. A value of 1 specifies that HNSW indexes are used. A value of 0 specifies that HNSW indexes are not used.

      • lexical_hnsw_m: When the lexical_use_hnsw parameter is set to 1, this parameter represents the M parameter specific to HNSW indexes. For information about the purpose and description of the M parameter, see Parameters specific to HNSW indexes.

      • lexical_hnsw_ef_construct: When the lexical_use_hnsw parameter is set to 1, this parameter represents the ef_construct parameter specific to HNSW indexes. For information about the purpose and description of the ef_construct parameter, see Parameters specific to HNSW indexes.

    • hybrid_ratio: the default weight assigned to vector search during the query. Valid values: 0 to 1. Default value: 0.5. The value must be of the FLOAT type. The weight assigned to full-text search in the query results is equal to 1 minus the hybrid_ratio value.

Output

• If the operation is successful, OK is returned.

• Otherwise, an error message is returned.

Example

Sample commands:

# Create a vector index that uses the HNSW algorithm and the Jaccard distance formula for vectors whose dimension is 2 and data type is BINARY. 
TVS.CREATEINDEX index_name0 2 HNSW JACCARD data_type BINARY

# Create a vector index that uses the HNSW algorithm and the Euclidean distance formula for vectors whose dimension is 2 and data type is FLOAT32. 
TVS.CREATEINDEX index_name1 2 HNSW L2 

# Create a vector index that uses the Flat Search algorithm and the inner product formula for vectors whose dimension is 2 and data type is FLOAT32. 
TVS.CREATEINDEX index_name2 2 FLAT IP 

# Create a vector index that uses the Flat Search algorithm and the Jaccard distance formula for vectors whose dimension is 2 and data type is BINARY. 
TVS.CREATEINDEX index_name3 2 FLAT JACCARD data_type BINARY

# Create a vector index that uses the HNSW algorithm, the BM25 full-text search algorithm, and the inner product formula for vectors whose dimension is 2 and data type is FLOAT32. Specify the productname field of the STRING type as an inverted index. 
TVS.CREATEINDEX index_name4 2 HNSW IP lexical_algorithm bm25 inverted_index_productname string

# Create a sparse vector that uses the HNSW algorithm and the inner product formula for vectors whose dimension is 2. 
TVS.CREATEINDEX index_name5 2 HNSW IP lexical_algorithm vector lexical_use_hnsw 1 lexical_hnsw_m 8 lexical_hnsw_ef_construct 100

Sample output:

OK

Item

Description

Syntax

TVS.GETINDEX index_name

Time complexity

O(1)

Command description

Queries the specified vector index and retrieves the metadata of the index.

Parameter

• index_name: the name of the vector index.

Output

• If the operation is successful, the metadata of the vector index is returned.

• If the specified vector index does not exist, (empty array) is returned.

• Otherwise, an error message is returned.

Example

Run the following commands in advance:

TVS.CREATEINDEX my_index 2 HNSW L2 auto_gc true lexical_algorithm bm25
TVS.HSET my_index key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index key2 VECTOR [5,6] creation_time 1750

Sample command (with the algorithm parameter set to HNSW):

TVS.GETINDEX my_index

Sample output:

 1) "lexical_term_count"   // The number of tokens in the full-text index. The value is of the INT data type. 
 2) "0"
 3) "lexical_record_count" // The number of documents in the full-text index. The value is of the INT data type. 
 4) "0"
 5) "lexical_algorithm"    // The full-text indexing algorithm. 
 6) "bm25"
 7) "auto_gc"              // Indicates whether automatic memory space reclamation is enabled for the index. This parameter is returned if you use the HNSW algorithm. 
 8) "1"
 9) "dimension"            // The dimension of the vectors. 
10) "2"
11) "attribute_data_size" // The amount of memory used by attribute information. Unit: bytes. 
12) "3720"
13) "distance_method" // The method that is used to calculate the distance between two vectors. 
14) "L2"
15) "data_type"            // The data type of the vectors. 
16) "FLOAT32"
17) "algorithm"            // The indexing algorithm. 
18) "HNSW"
19) "index_data_size"      // The amount of memory used by vectors. Unit: bytes. 
20) "105128040"
21) "M"                    // The maximum number of outgoing neighbors on each layer in a graph index structure. This parameter is returned if you use the HNSW algorithm. 
22) "16"
23) "data_count"           // The number of records or data points associated with a user. 
24) "3"
25) "current_record_count" // The total number of vectors. 
26) "3"
27) "ef_construct"         // The length of the dynamic array when you use the HNSW algorithm. 
28) "100"
29) "inverted_index_productname" // The inverted index information, including the field name, data type, and quantity. 
30) "field: productname, type: string, size: 1"
31) "delete_record_count" // The number of vectors to be deleted. 
32) "0"

Item

Description

Syntax

TVS.DELINDEX index_name

Time complexity

O(N), in which N indicates the number of keys in the vector index.

Command description

Deletes the specified vector index and all data of the index.

Parameter

• index_name: the name of the vector index.

Output

• If the operation is successful, the vector index is deleted and a value of 1 is returned.

• If the specified vector index does not exist, a value of 0 is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.DELINDEX index_name0

Sample output:

 (integer) 1

Item

Description

Syntax

TVS.SCANINDEX cursor [MATCH pattern] [COUNT count]

Time complexity

O(N), in which N indicates the number of vector indexes in the Tair instance.

Command description

Scans the vector indexes that meet specific criteria in the Tair instance.

Parameter

• cursor: the cursor used in this scan. The cursor position starts from 0.

• pattern: the pattern used in this scan.

• count: the number of keys that you want to scan. Default value: 10. The system may not always return the precise number of keys specified by the count parameter in each iteration.

Output

• If the operation is successful, an array is returned.

  • Element 1 of the array: the cursor used for the next scan. If the scan is complete, a value of 0 is returned.

  • Element 2 of the array: the names of scanned vector indexes, which is the value of the index_name parameter.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.SCANINDEX 0

Sample output:

1) "0"
2) 1) "index_name1"
   2) "index_name0"
   3) "index_name2"
   4) "index_name3"

Sample output (including the pattern parameter):

TVS.SCANINDEX 0 MATCH **name[0|1]

Sample output:

1) "0"
2) 1) "index_name1"
   2) "index_name0"

Item

Description

Syntax

TVS.HSET index_name key attribute_key attribute_value [attribute_key attribute_value] ...

Time complexity

If the operation of inserting or updating data does not involve the creation or update of a vector value, the time complexity is O(1). Otherwise, the time complexity is O(log(N)), where N indicates the number of keys in the vector index.

Command description

Inserts a vector into the specified vector index. If the vector already exists, the existing data is overwritten.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector. You can run the TVS.DEL command to delete the key.

• attribute_key and attribute_value: the vector that you want to insert in the key-value format.

  • To insert a vector, set attribute_key to VECTOR and attribute_value to a vector string that has the same dimension as that of the vector index specified by the dims parameter. Example: VECTOR [1,2]. You can write only one vector to a key. If you write a vector more than once, the existing data is overwritten.

  • To insert text data into a hybrid index that has required parameters specified, set attribute_key to TEXT and attribute_value to text data such as "TairVector is an in-house vector database service of Tair" or vectorized data such as "[[2,0.221],[42,09688],...]".

  • To insert other attributes, specify custom parameters related to these attributes. Examples: create_time 1663637425 and location Hangzhou.

Output

• If the operation is successful, the number of inserted keys is returned. If an existing field is updated, a value of 0 is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HSET my_index key5 VECTOR [7,8] TEXT "TairVector is an in-house vector database service of Tair" create_time 1800

Sample output:

(integer) 3

Item

Description

Syntax

TVS.HGETALL index_name key

Time complexity

O(1)

Command description

Queries all data records of the specified key in the specified vector index.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector.

Output

• If the operation is successful, all data records of the key are returned.

• If the specified vector index or key does not exist, (empty array) is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HGETALL index_name0 key0

Sample output:

1) "VECTOR"
2) "[1,2]"
3) "location"
4) "Hangzhou"
5) "create_time"
6) "1663637425"

Item

Description

Syntax

TVS.HMGET index_name key attribute_key [attribute_key ...]

Time complexity

O(1)

Command description

Queries the values of attribute keys in the specified key of the specified vector index.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector.

• attribute_key: the attribute key that you want to manage. You can specify multiple keys. To query a specific vector, set attribute_key to VECTOR. To query the raw text data in the full-text index, set attribute_key to TEXT.

Output

• If the operation is successful, the values of the attribute keys are returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HMGET index_name0 key0 create_time location VECTOR TEXT

Sample output:

1) "1800"
2) "[7,8]"
3) "TairVector is an in-house vector database service of Tair"

Item

Description

Syntax

TVS.DEL index_name key [key ...]

Time complexity

O(1)

Command description

Deletes the specified vectors from the specified vector index by using the key parameter.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector. You can specify multiple keys.

Output

• If the operation is successful, the specified keys are deleted and the number of deleted keys is returned.

• If the specified vector index does not exist, a value of 0 is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.DEL index_name0 keyV

Sample output:

 (integer) 1

Item

Description

Syntax

TVS.HDEL index_name key attribute_key [attribute_key ...]

Time complexity

O(1)

Command description

Deletes the specified attributes of the specified vector from the specified vector index.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector. You can specify multiple keys.

• attribute_key: the attribute key that you want to manage. You can specify multiple attribute keys. To delete vector data, set attribute_key to VECTOR. To delete full index data, set attribute_key to TEXT.

Output

• If the operation is successful, the specified attributes are deleted and the number of deleted attributes is returned.

• If the specified vector index does not exist, a value of 0 is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HDEL index_name0 keyc VECTOR

Sample output:

 (integer) 1

Item

Description

Syntax

TVS.SCAN index_name cursor [MATCH pattern] [COUNT count] [FILTER filter_string] [VECTOR vector] [MAX_DIST max_distance]

Time complexity

O(N), in which N indicates the number of keys in the vector index.

Command description

Scans the keys that meet specific criteria in the specified vector index.

Parameter

• index_name: the name of the vector index.

• cursor: the cursor used in this scan. The cursor position starts from 0.

• pattern: the pattern used in this scan.

• count: the number of keys that you want to scan. Default value: 10. The system may not always return the precise number of keys specified by the count parameter in each iteration.

• filter_string: the filter conditions.

  • Operators such as + - * / < > ! = ( ) && || are supported. You cannot compare the sizes of strings. If you want to enter a string, you must add escape characters (\). Example: create_time > 1663637425 && location == \"Hangzhou\".

  • You must add spaces to both sides of an operator. Example: "creation_time > 1735".

  • The flag == true format that uses the BOOLEAN data type is not supported. You can use the flag == \"true\" format, which passes the boolean value as a string.

• vector: the query vector. This parameter must be used together with the max_distance parameter.

• max_distance: the maximum distance allowed. This parameter must be used together with the vector parameter. After you specify these two parameters, the returned array includes all vectors that are within the distance specified by the max_distance parameter from the query vector.

Output

• If the operation is successful, an array is returned.

  • Element 1 of the array: the cursor used for the next scan. If the scan is complete, a value of 0 is returned.

  • Element 2 of the array: the names of scanned keys.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.SCAN index_name0 0

Sample output:

1) "0"
2) 1) "key0"
   2) "keyV"

Item

Description

Syntax

TVS.HINCRBY index_name key attribute_key num

Time complexity

O(1)

Command description

Increases the value of the specified attribute key for the specified key in the specified vector index by a given integer value (num).

If the specified attribute key does not exist, the attribute key is automatically created and assigned the provided num value. If the attribute key already exists, TairVector updates the value of the attribute key by adding the specified num value to the existing value.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector.

• attribute_key: the attribute key that you want to manage.

• num: the integer value by which you want to increase the value of the attribute key.

Output

• If the operation is successful, the value of the attribute key is increased by the num value.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HINCRBY index_name0 key0 tv01 20 

Sample output:

(integer) 20

Item

Description

Syntax

TVS.HINCRBYFLOAT index_name key attribute_key num

Time complexity

O(1)

Command description

Increases the value of the specified attribute key for the specified key in the specified vector index by a given floating-point number (num).

If the specified attribute key does not exist, the attribute key is automatically created and assigned the provided num value. If the attribute key already exists, TairVector updates the value of the attribute key by adding the specified num value to the existing value.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector.

• attribute_key: the attribute key that you want to manage.

• num: the floating-point number by which you want to increase the value of the attribute key.

Output

• If the operation is successful, the value of the attribute key is increased by the num value.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HINCRBYFLOAT index_name0 key0 tv02 9.34

Sample output:

"9.34"

Item

Description

Syntax

TVS.HPEXPIREAT index_name key milliseconds-timestamp

Time complexity

O(1)

Command description

Specifies an absolute expiration time that is accurate to the millisecond for the specified key in the specified vector index.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector.

• milliseconds-timestamp: a UNIX timestamp that is accurate to the millisecond. If the specified timestamp is earlier than the current time, the key immediately expires.

Output

• If the specified key exists and is successfully configured, a value of 1 is returned.

• If the specified key does not exist, a value of 0 is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HPEXPIREAT index_name0 key1 16914619090000

Sample output:

(integer) 1

Item

Description

Syntax

TVS.HPEXPIRE index_name key milliseconds-timestamp

Time complexity

O(1)

Command description

Specifies a relative expiration time that is accurate to the millisecond for the specified key in the specified vector index.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector.

• milliseconds-timestamp: the relative expiration time. Unit: milliseconds.

Output

• If the specified key exists and is successfully configured, a value of 1 is returned.

• If the specified key does not exist, a value of 0 is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HPEXPIRE index_name0 key1 1000

Sample output:

(integer) 1

Item

Description

Syntax

TVS.HEXPIREAT index_name key timestamp

Time complexity

O(1)

Command description

Specifies an absolute expiration time that is accurate to the second for the specified key in the specified vector index.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector.

• timestamp: a UNIX timestamp that is accurate to the second. If the specified timestamp is earlier than the current time, the key immediately expires.

Output

• If the specified key exists and is successfully configured, a value of 1 is returned.

• If the specified key does not exist, a value of 0 is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HPEXPIREAT index_name0 key2 1691466981

Sample output:

(integer) 1

Item

Description

Syntax

TVS.HEXPIRE index_name key timestamp

Time complexity

O(1)

Command description

Specifies a relative expiration time that is accurate to the second for the specified key in the specified vector index.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector.

• timestamp: the relative expiration time. Unit: seconds.

Output

• If the specified key exists and is successfully configured, a value of 1 is returned.

• If the specified key does not exist, a value of 0 is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HPEXPIREAT index_name0 key2 100

Sample output:

(integer) 1

Item

Description

Syntax

TVS.HPTTL index_name key

Time complexity

O(1)

Command description

Queries the TTL of the specified key in the specified vector index, accurate to the millisecond.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector.

Output

• If the specified key exists and has a TTL configured, the TTL is returned.

• If the specified key exists but does not have an absolute expiration time configured, a value of -1 is returned.

• If the specified key or index does not exist, a value of -2 is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HPTTL index_name0 key2

Sample output:

(integer) 65417

Item

Description

Syntax

TVS.HTTL index_name key

Time complexity

O(1)

Command description

Queries the TTL of the specified key in the specified vector index, accurate to the second.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector.

Output

• If the specified key exists and has a TTL configured, the TTL is returned.

• If the specified key exists but does not have an absolute expiration time configured, a value of -1 is returned.

• If the specified key or index does not exist, a value of -2 is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HTTL index_name0 key2

Sample output:

(integer) 58

Item

Description

Syntax

TVS.HPEXPIRETIME index_name key

Time complexity

O(1)

Command description

Queries the absolute expiration time of the specified key in the specified vector index, accurate to the millisecond.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector.

Output

• If the specified key exists and has an absolute expiration time configured, the absolute expiration time (UNIX timestamp) is returned.

• If the specified key exists but does not have an absolute expiration time configured, a value of -1 is returned.

• If the specified key or index does not exist, a value of -2 is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HPEXPIRETIME index_name0 key2

Sample output:

(integer) 1691473985764

Item

Description

Syntax

TVS.HEXPIRETIME index_name key

Time complexity

O(1)

Command description

Queries the absolute expiration time of the specified key in the specified vector index, accurate to the second.

Parameter

• index_name: the name of the vector index.

• key: the primary key identifier of the vector.

Output

• If the specified key exists and has an absolute expiration time configured, the absolute expiration time (UNIX timestamp) is returned.

• If the specified key exists but does not have an absolute expiration time configured, a value of -1 is returned.

• If the specified key or index does not exist, a value of -2 is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HEXPIRETIME index_name0 key2

Sample output:

(integer) 1691473985

Item

Description

Syntax

TVS.KNNSEARCH index_name topN vector [filter_string] [param_key param_value]

Time complexity

• HNSW algorithm: O(log(N)).

• FLAT algorithm: O(N).

N indicates the number of keys in the vector index.

Command description

Queries the nearest-neighbor vectors of the specified vector in the specified vector index. Up to 10,000 vectors can be returned.

Parameter

• index_name: the name of the vector index.

• topN: the number of vectors to return. Valid values: 1 to 10000.

• vector: the vector whose nearest neighbors you want to query. If you want to perform only full-text search by using the hybrid indexing method, you can set the vector field to an empty string ("").

• filter_string: the filter conditions.

  • Operators such as + - * / < > ! = ( ) && || are supported. You cannot compare the sizes of strings. If you want to enter a string, you must add escape characters (\). Example: "create_time > 1663637425 && location == \"Hangzhou\"".

  • You must add spaces to both sides of an operator. Example: "creation_time > 1735".

  • The flag == true format that uses the BOOLEAN data type is not supported. You can use the flag == \"true\" format, which passes the boolean value as a string.

• param_key and param_value: the operational parameters of the query. Valid values:

  • ef_search: the length of the dynamic array. Default value: 100. Valid values: 1 to 1000. A greater value indicates higher search accuracy. This results in higher performance overhead. This parameter is available only if you use the HNSW algorithm.

    sparse_ef_search: If you use HNSW indexes for sparse vectors when you create hybrid indexes, use the ef_search parameter as the sparse_ef_search parameter for the HNSW indexes.

  • MAX_DIST: the maximum distance allowed, which must be of the FLOAT type. If the distance between the specified vector and a neighbor vector is greater than the value of this parameter, the key of the neighbor vector is filtered out and excluded from the search results.

  • TEXT: the text on which you want to perform a hybrid search. You can pass text or vector data to this field. If you do not specify this field or if you pass an empty string ("") to this field, only vector search is performed.

  • hybrid_ratio: the weight assigned to vector search during the query. By default, this field takes the value specified in the hybrid_ratio parameter of the TVS.CREATEINDEX command. Valid values: 0 to 1. The value must be of the FLOAT type. The weight assigned to full-text search in the query results is equal to 1 minus the hybrid_ratio value.

  • By default, the system performs k-nearest neighbors (KNN) vector search followed by scalar filtering, which is known as the PostFilter policy.

    • vector_filter_count: the maximum number of records that can be filtered during a vector search. Default value: 10000.

      In the PostFilter policy, if the number of records filtered from the vector search results exceeds the vector_filter_count value, but the operation still cannot gather a sufficient amount of data to return, the system terminates the vector search.

    • fulltext_filter_count: the maximum number of records that can be filtered during a full-text search. Default value: 10000.

      In the PostFilter policy, if the number of records filtered from the full-text search results exceeds the fulltext_filter_count value, but the operation still cannot gather a sufficient amount of data to return, the system terminates the full-text search.

    • If you want the system to perform scalar filtering based on inverted indexes before performing KNN vector search, you can use the PreFilter policy by adding the search_policy scala parameter to the query.

      The ivf_filter_count parameter is also available to specify the maximum number of records that can be filtered based on inverted indexes. The default value is 10000. In the PreFilter policy, if the number of records processed during this initial scalar filtering stage exceeds the ivf_filter_count value, the system automatically degrades to the PostFilter policy.

    Note

    In most cases, the default settings of the preceding parameters can ensure that the system operates with acceptable latency while maintaining accuracy. You can adjust these parameters on a per-request basis to better fit the specific needs of your use case. However, increasing the values of the preceding parameters may lead to higher query latency.

Output

• If the operation is successful, the keys of the neighbor vectors are returned in ascending order of their distances to the specified vector.

• If the specified vector index does not exist, (empty array) is returned.

• Otherwise, an error message is returned.

Example

TVS.CREATEINDEX my_index_k 2 HNSW L2 inverted_index_productname string
TVS.HSET my_index_k key0 VECTOR [1,2] creation_time 1730 productname "Aliyun"
TVS.HSET my_index_k key1 VECTOR [3,4] creation_time 1740 productname "other"
TVS.HSET my_index_k key2 VECTOR [5,6] creation_time 1750 productname "Aliyun"

Sample command 1:

TVS.KNNSEARCH my_index_k 2 [3,3.1] "creation_time > 1735"

Sample output 1:

1) "key1"
2) "0.81000018119812012"
3) "key2"
4) "12.410000801086426"

Sample command 2:

TVS.KNNSEARCH my_index_k 2 [3,3.1]  "creation_time > 1735 && productname ==  \"Aliyun\"" search_policy scala ivf_filter_count 15000

Sample output 2:

1) "key2"
2) "12.410000801086426"

Item

Description

Syntax

TVS.KNNSEARCHFIELD index_name topN vector field_count field_name [field_name ...] [filter_string] [param_key param_value]

Time complexity

• HNSW algorithm: O(log(N)).

• FLAT algorithm: O(N).

N indicates the number of keys in the vector index.

Command description

Queries the nearest-neighbor vectors of the specified vector in the specified vector index. The search logic of this command is the same as that of TVS.KNNSEARCH, with the additional capability to return tag attributes along with the search results.

Parameter

• index_name: the name of the vector index.

• topN: the number of vectors to return. Valid values: 1 to 10000.

• vector: the vector whose nearest neighbors you want to query. If you want to perform only full-text search by using the hybrid indexing method, you can set the vector field to an empty string ("").

• field_count: the number of tag attributes to return. If you want to return all tags, set the field_count parameter to 0.

• field_name: the tag name. The number of tags must be the same as the field_count value.

• filter_string: the filter conditions. For more information, see the description of TVS.KNNSEARCH.

• param_key and param_value: the operational parameters of the query. For more information, see the description of TVS.KNNSEARCH.

Output

• If the operation is successful, the keys of the neighbor vectors are returned in ascending order of their distances to the specified vector. The tag attributes of the vectors are also returned in the form of key-value pairs.

• If the specified vector index does not exist, (empty array) is returned.

• Otherwise, an error message is returned.

Example

TVS.CREATEINDEX my_index_k 2 HNSW L2
TVS.HSET my_index_k key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index_k key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index_k key2 VECTOR [5,6] creation_time 1750

Sample command:

TVS.KNNSEARCHFIELD my_index_k 2 [3,3.1] 0 "creation_time > 1735"

Sample output:

1) 1) "key1"
   2) "0.81000018119812012"
   3) "VECTOR"
   4) "[3,4]"
   5) "creation_time"
   6) "1740"
2) 1) "key2"
   2) "12.410000801086426"
   3) "VECTOR"
   4) "[5,6]"
   5) "creation_time"
   6) "1750"

Item

Description

Syntax

TVS.GETDISTANCE index_name vector key_count key [key, ...] [TOPN topN] [FILTER filter_string] [MAX_DIST max_distance]

Time complexity

• HNSW algorithm: O(log(N)).

• FLAT algorithm: O(N).

N indicates the number of keys in the vector index.

Command description

Performs vector nearest-neighbor queries for the specified keys in the specified vector index.

Parameter

• index_name: the name of the vector index.

• vector: the vector whose nearest neighbors you want to query.

• key_count: the number of keys that you want to query.

• key: the names of the keys. The number of keys must be the same as the value of key_count.

• TOPN: the number of keys to return. By default, this parameter is set to the value of key_count. Valid values: [1,key_count value].

• FILTER: the filter conditions.

  • Operators such as + - * / < > ! = ( ) && || are supported. You cannot compare the sizes of strings. If you want to enter a string, you must add escape characters (\). Example: create_time > 1663637425 && location == \"Hangzhou\".

  • You must add spaces to both sides of an operator. Example: "creation_time > 1735".

  • The flag == true format that uses the BOOLEAN data type is not supported. You can use the flag == \"true\" format, which passes the boolean value as a string.

• MAX_DIST: the maximum distance allowed. If the distance between the specified vector and a neighbor vector is greater than the value of this parameter, the key of the neighbor vector is filtered out and excluded from the search results.

Output

• If the operation is successful, the distances of neighbor vectors to each specified vector are returned in the order of their keys. If you specify the TOPN parameter, the keys of the neighbor vectors are returned in ascending order of their distances to each specified vector.

• If the specified vector index does not exist, (empty array) is returned.

• Otherwise, an error message is returned.

Example

TVS.CREATEINDEX my_index_k 2 HNSW L2
TVS.HSET my_index_k key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index_k key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index_k key2 VECTOR [5,6] creation_time 1750

Sample command:

TVS.GETDISTANCE my_index_k [1,1] 2 key1 key2

Sample output:

1) "key1"
2) "13"
3) "key2"
4) "41"

Item

Description

Syntax

TVS.MKNNSEARCH index_name topN vector_count vector [vector ...] [filter_string] [param_key param_value]

Time complexity

• HNSW algorithm: vector_count * O(log(N)).

• FLAT algorithm: vector_count * O(N).

N indicates the number of keys in the vector index.

Command description

Queries the nearest-neighbor vectors of the specified vectors in the specified vector index.

Parameter

• index_name: the name of the vector index.

• topN: the number of neighbor vectors to return for each vector. Valid values: 1 to 10000.

• vector_count: the number of specified vectors.

• vector: the vector whose nearest neighbors you want to query. If you want to perform only full-text search by using the hybrid indexing method, you can set the vector field to an empty string ("").

• filter_string: the filter conditions. For more information, see the description of TVS.KNNSEARCH.

• param_key and param_value: the operational parameters of the query. For more information, see the description of TVS.KNNSEARCH.

Output

• If the operation is successful, the results are returned in arrays. Each array contains the keys of the neighbor vectors in ascending order of their distances to each specified vector.

• If the specified vector index does not exist, (empty array) is returned.

• Otherwise, an error message is returned.

Example

TVS.CREATEINDEX my_index_m 2 HNSW L2
TVS.HSET my_index_m key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index_m key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index_m key2 VECTOR [5,6] creation_time 1750

Sample command:

TVS.MKNNSEARCH my_index_m 2 2 [3,4] [5,6] "creation_time > 1735"

Sample output:

1) 1) "key1"
   2) "0"
   3) "key2"
   4) "8"
2) 1) "key2"
   2) "0"
   3) "key1"
   4) "8"

Item

Description

Syntax

TVS.MINDEXKNNSEARCH index_count index_name [index_name ...] topN vector [filter_string] [param_key param_value]

Time complexity

• HNSW algorithm: index_count * O(log(N)).

• FLAT algorithm: index_count * O(N).

N indicates the number of keys in the vector index.

Command description

Queries the nearest-neighbor vectors of the specified vector across multiple vector indexes.

Parameter

• index_count: the number of vector indexes.

• index_name: the names of the vector indexes.

• topN: the number of neighbor vectors to return. By default, the system queries the neighbor vectors of the specified vector in each index, aggregates the obtained vectors, and returns the neighbor vectors that are the nearest to the specified vector. Valid values: 1 to 10000.

• vector: the vector whose nearest neighbors you want to query.

• filter_string: the filter conditions. For more information, see the description of TVS.KNNSEARCH.

• param_key and param_value: the operational parameters of the query. For more information, see the description of TVS.KNNSEARCH.

Output

• If the operation is successful, the keys of the neighbor vectors are returned in ascending order of their distances to the specified vector.

• If the specified vector index does not exist, (empty array) is returned.

• Otherwise, an error message is returned.

Example

TVS.CREATEINDEX my_index_mk 2 HNSW L2
TVS.HSET my_index_mk key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index_mk key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index_mk key2 VECTOR [5,6] creation_time 1750
TVS.CREATEINDEX my_index_mx 2 HNSW L2
TVS.HSET my_index_mx key5 VECTOR [8,7] creation_time 1730
TVS.HSET my_index_mx key6 VECTOR [6,5] creation_time 1740
TVS.HSET my_index_mx key7 VECTOR [4,3] creation_time 1750

Sample command:

TVS.MINDEXKNNSEARCH 2 my_index_mk my_index_mx 2 [0,0]

Sample output:

1) "key0"
2) "5"
3) "key7"
4) "25"

Item

Description

Syntax

TVS.MINDEXKNNSEARCHFIELD index_count index_name [index_name ...] topN vector field_count field_name [field_name ...] [filter_string] [param_key param_value]

Time complexity

• HNSW algorithm: index_count * O(log(N)).

• FLAT algorithm: index_count * O(N).

N indicates the number of keys in the vector index.

Command description

Queries the nearest-neighbor vectors of the specified vector across multiple vector indexes. Tag attributes can be returned along with the search results.

Parameter

• index_count: the number of vector indexes.

• index_name: the names of the vector indexes.

• topN: the number of neighbor vectors to return. By default, the system queries the neighbor vectors of the specified vector in each index, aggregates the obtained vectors, and returns the neighbor vectors that are the nearest to the specified vector. Valid values: 1 to 10000.

• vector: the vector whose nearest neighbors you want to query.

• field_count: the number of tag attributes to return. If you want to return all tags, set the field_count parameter to 0.

• field_name: the tag name. The number of tags must be the same as the field_count value.

• filter_string: the filter conditions. For more information, see the description of TVS.KNNSEARCH.

• param_key and param_value: the operational parameters of the query. For more information, see the description of TVS.KNNSEARCH.

Output

• If the operation is successful, the keys of the neighbor vectors are returned in ascending order of their distances to the specified vector. The tag attributes of the vectors are also returned in the form of key-value pairs.

• If the specified vector index does not exist, (empty array) is returned.

• Otherwise, an error message is returned.

Example

TVS.CREATEINDEX my_index_mk 2 HNSW L2
TVS.HSET my_index_mk key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index_mk key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index_mk key2 VECTOR [5,6] creation_time 1750
TVS.CREATEINDEX my_index_mx 2 HNSW L2
TVS.HSET my_index_mx key5 VECTOR [8,7] creation_time 1730
TVS.HSET my_index_mx key6 VECTOR [6,5] creation_time 1740
TVS.HSET my_index_mx key7 VECTOR [4,3] creation_time 1750

Sample command:

TVS.MINDEXKNNSEARCHFIELD 2 my_index_mk my_index_mx 2 [0,0] 0

Sample output:

1) 1) "key0"
   2) "5"
   3) "my_index_mk"
   4) "VECTOR"
   5) "[1,2]"
   6) "creation_time"
   7) "1730"
2) 1) "key1"
   2) "25"
   3) "my_index_mk"
   4) "VECTOR"
   5) "[3,4]"
   6) "creation_time"
   7) "1740"

Item

Description

Syntax

TVS.MINDEXMKNNSEARCH index_count index_name [index_name ...] topN vector_count vector [vector ...] [filter_string] [param_key param_value]

Time complexity

• HNSW algorithm: index_count * vector_count * O(log(N)).

• FLAT algorithm: index_count * vector_count * O(N).

N indicates the number of keys in the vector index.

Command description

Queries the nearest-neighbor vectors of the specified vectors across multiple vector indexes.

Parameter

• index_count: the number of vector indexes.

• index_name: the names of the vector indexes.

• topN: the number of neighbor vectors to return for each vector. By default, the system queries the neighbor vectors of the specified vector in each index, aggregates the obtained vectors, and returns the neighbor vectors that are the nearest to the specified vector. Valid values: 1 to 10000.

• vector_count: the number of specified vectors.

• vector: the vectors whose nearest neighbors you want to query.

• filter_string: the filter conditions. For more information, see the description of TVS.KNNSEARCH.

• param_key and param_value: the operational parameters of the query. For more information, see the description of TVS.KNNSEARCH.

Output

• If the operation is successful, the results are returned in arrays. Each array contains the keys of the neighbor vectors in ascending order of their distances to each specified vector.

• If the specified vector index does not exist, (empty array) is returned.

• Otherwise, an error message is returned.

Example

TVS.CREATEINDEX my_index_mk 2 HNSW L2
TVS.HSET my_index_mk key0 VECTOR [1,2] creation_time 1730
TVS.HSET my_index_mk key1 VECTOR [3,4] creation_time 1740
TVS.HSET my_index_mk key2 VECTOR [5,6] creation_time 1750
TVS.CREATEINDEX my_index_mx 2 HNSW L2
TVS.HSET my_index_mx key5 VECTOR [8,7] creation_time 1730
TVS.HSET my_index_mx key6 VECTOR [6,5] creation_time 1740
TVS.HSET my_index_mx key7 VECTOR [4,3] creation_time 1750

Sample command:

TVS.MINDEXMKNNSEARCH 2 my_index_mk my_index_mx 2 2 [0,0] [3,3]

Sample output:

1) 1) "key0"
   2) "5"
   3) "key7"
   4) "25"
2) 1) "key1"
   2) "1"
   3) "key7"
   4) "1"