Tair (Redis® OSS-Compatible):Vector

Category

Description

Syntax

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

time complexity

O(1)

Command description

Create a vector index and specify the indexing and query algorithms and distance formula. You can delete this object only using the TVS.DELINDEX command.

Options

• 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 and query the index. Valid values:

  • FLAT: uses the Flat Search algorithm to search for vectors without creating indexes. This algorithm is suitable for datasets that contain fewer 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: squared Euclidean distance.

  • IP: inner product. Calculate the distance between two vectors using the following formula: 1 - Inner product of the two vectors.

  • COSINE: cosine distance. Calculate the distance between two vectors using the following formula: 1 - Cosine of the angle between the two vectors. This method converts written vectors into unit vectors (L2 normalization). Therefore, the vector results may differ from the original vector values.

  • JACCARD: Jaccard distance. Calculate the Jaccard distance between two vectors 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 2-byte half-precision floating-point number (IEEE 754-2008 standard). This data type saves vector storage space but results in a loss of some precision. The value range for FLOAT16 is [-65519, 65519].

    • BINARY: a binary vector that contains 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 increases 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 increases performance overhead.

    • auto_gc: specifies whether to enable automatic memory space reclamation for the index. Valid values: false (default, disables auto GC) and true (enables auto GC). This feature requires a minor version of 6.2.8.2 or later. An HNSW index uses marked deletion to delete vectors. After you enable this feature, the index automatically reclaims memory space, which helps reduce memory usage. However, this feature affects the index performance of nearest-neighbor queries. We recommend that you enable this feature only in scenarios where memory usage is critical and a decrease in nearest-neighbor query performance is acceptable.

  • Parameters specific to HybridIndex (hybrid indexes):

    • To create an inverted index for a specific tag field, specify the field name and its corresponding data type in advance.

      Use the syntax inverted_index_<field_name> int|long|float|double|string to create an inverted index for the field_name field. Supported data types are INT, LONG, FLOAT, DOUBLE, and STRING. The field_name and the data type keyword must be lowercase.

      For example, to create an inverted index on a field named productname of the STRING type, use inverted_index_productname string.

    • lexical_algorithm: Specifies the full-text index algorithm.

      • bm25: the Okapi BM25 algorithm, suitable for full-text search.

        • When you use the TVS.HSET command to insert data later, set the attribute_key to the TEXT keyword (case-sensitive). The attribute_value will be automatically indexed for full-text search.

        • You can pass raw text to the Tair vector service to build the index.

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

        You must encode raw 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. 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 configure the following additional parameters:

      • analyzer: the analyzer used for text segmentation. Valid values: jieba (default) and ik_smart.

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

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

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

      • lexical_use_hnsw: specifies whether to use HNSW indexes for sparse vectors. Valid values: 1 (use HNSW indexes) and 0 (default, use inverted indexes).

      • lexical_hnsw_m: when lexical_use_hnsw is set to 1, this parameter represents the M parameter specific to HNSW indexes. For details, see Parameters specific to HNSW indexes.

      • lexical_hnsw_ef_construct: when lexical_use_hnsw is set to 1, this parameter represents the ef_construct parameter specific to HNSW indexes. For details, see Parameters specific to HNSW indexes.

    • hybrid_ratio: the default weight assigned to vector search during queries. Valid values: 0 to 1. Default value: 0.5. The value must be of the FLOAT type. The weight assigned to full-text search 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

Category

Description

Syntax

TVS.GETINDEX index_name

Time complexity

O(1)

Command description

Query a specific vector index and retrieve its metadata.

Options

• index_name: the name of the vector index.

Return value

• 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"   // Number of tokens in the full-text index. Data type: INT.
 2) "0"
 3) "lexical_record_count" // Number of documents in the full-text index. Data type: INT.
 4) "0"
 5) "lexical_algorithm"    // Full-text indexing algorithm.
 6) "bm25"
 7) "auto_gc"              // Indicates whether automatic memory space reclamation is enabled for the index. This parameter appears only if you use the HNSW algorithm.
 8) "1"
 9) "dimension"            // Vector dimension.
10) "2"
11) "attribute_data_size"  // Memory used by attribute information. Unit: bytes.
12) "3720"
13) "distance_method"      // Method used to calculate the distance between two vectors.
14) "L2"
15) "data_type"            // Data type of the vectors.
16) "FLOAT32"
17) "algorithm"            // Indexing algorithm.
18) "HNSW"
19) "index_data_size"      // Memory used by vectors. Unit: bytes.
20) "105128040"
21) "M"                    // Maximum number of outgoing neighbors on each layer in a graph index structure. This parameter appears only if you use the HNSW algorithm.
22) "16"
23) "data_count"           // Number of user records.
24) "3"
25) "current_record_count" // Total number of vectors.
26) "3"
27) "ef_construct"         // Length of the dynamic array when you use the HNSW algorithm.
28) "100"
29) "inverted_index_productname" // Inverted index information: field name, data type, and size.
30) "field: productname, type: string, size: 1"
31) "delete_record_count"  // Number of vectors scheduled for deletion.
32) "0"

Category

Description

Syntax

TVS.DELINDEX index_name

Time complexity

O(N), where N is the number of keys in the vector index.

Command description

Delete a specified vector index and all data in it.

Options

• index_name: the name of the vector index.

Return value

• 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

Category

Description

Syntax

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

Time complexity

O(N), where N is the number of vector indexes in the Tair instance.

Command description

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

options

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

• pattern: The expression used for pattern matching.

• count: the number of keys 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.

  • Second element: The vector index name (index_name) for the current query.

• 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 command (including the pattern parameter):

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

Sample output:

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

Category

Description

Syntax

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

Time complexity

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

Command description

Inserts a data record (key) into the vector index. If the record already exists, updates and overwrites the existing record.

options

• index_name: the name of the vector index.

• key: The primary key identifier of the record. You can delete the object using the TVS.DEL command.

• attribute_key and attribute_value: The record's value, specified in key-value format.

  • To insert a vector, set attribute_key to VECTOR (case-sensitive) 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 HybridIndex that has required parameters specified, set attribute_key to TEXT (case-sensitive) 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

Category

Description

Syntax

TVS.HGETALL index_name key

Time complexity

O(1)

Command description

Query all data records associated with a key in a specified vector index.

options

• index_name: the name of the vector index.

• key: The primary key identifier for the record.

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"

Category

Description

Syntax

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

Time complexity

O(1)

Command description

Query the value associated with the key in the attribute_key of a specified vector index.

options

• index_name: the name of the vector index.

• key: The primary key identifier of this record.

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

Returns

• If the operation is successful, the values of the attribute_key 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"

Category

Description

Syntax

TVS.DEL index_name key [key ...]

Time complexity

O(1)

Command description

Delete specified data records (key) from a specified vector index.

Options

• index_name: the name of the vector index.

• key: The primary key identifier for this record. You can specify multiple values.

return value

• If the operation is successful, the specified key is deleted and the number of deleted key 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

Category

Description

Syntax

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

Time complexity

O(1)

Command description

Deletes the specified attribute_key and its value from the data record (key) in the vector index.

Options

• index_name: the name of the vector index.

• key: The primary key identifier for the record. You can specify multiple values.

• attribute_key: the attribute key to manage. You can specify multiple keys. To delete vector data, set attribute_key to VECTOR (case-sensitive). To delete full index data, set attribute_key to TEXT (case-sensitive).

(return value)

• If the operation is successful, the specified attributes are deleted and the number of deleted attribute_key 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

Category

Description

Syntax

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

Time complexity

O(N), where N is the number of keys in the vector index.

Command description

Scan data records (key) in a specified vector index that meet specific criteria.

Options

• index_name: the name of the vector index.

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

• The pattern parameter specifies pattern matching.

• count: the number of keys 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 key.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.SCAN index_name0 0

Sample output:

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

Category

Description

Syntax

TVS.HINCRBY index_name key attribute_key num

Time complexity

O(1)

Command description

In a specified vector index, increase the value of the specified key by an integer num.

If the specified attribute_key does not exist, it is automatically created and assigned the specified value. If the attribute_key already exists, the corresponding record is updated and the initial value is overwritten.

Options

• index_name: the name of the vector index.

• key: the primary key identifier of the record.

• attribute_key: the attribute key to manage.

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

Output

• The operation succeeded. The value after adding num is returned.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HINCRBY index_name0 key0 tv01 20 

Sample output:

(integer) 20

Category

Description

Syntax

TVS.HINCRBYFLOAT index_name key attribute_key num

Time complexity

O(1)

Command description

In a specified vector index, increase the value of the specified key by a floating-point number num.

If the specified `attribute_key` does not exist, the system automatically creates it and assigns the value. If the record already exists, the system updates it and overwrites the initial value.

options

• index_name: the name of the vector index.

• key: The primary key identifier of this record.

• attribute_key: the attribute key to manage.

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

Output

• The operation succeeded. The value is the result of adding num.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HINCRBYFLOAT index_name0 key0 tv02 9.34

Sample output:

"9.34"

Category

Description

Syntax

TVS.HPEXPIREAT index_name key milliseconds-timestamp

Time complexity

O(1)

Command description

In a specified vector index, set an absolute expiration time for a specified key, accurate to the millisecond.

Options

• index_name: the name of the vector index.

• key: The primary key identifier of the record.

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

return value

• 1: The key exists and has been successfully set.

• If the 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

Category

Description

Syntax

TVS.HPEXPIRE index_name key milliseconds-timestamp

Time complexity

O(1)

Command description

In a specified vector index, set a relative expiration time for a specified key, accurate to the millisecond.

options

• index_name: the name of the vector index.

• key: The primary key identifier for a record.

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

(return value)

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

• If the 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

Category

Description

Syntax

TVS.HEXPIREAT index_name key timestamp

Time complexity

O(1)

Command description

In a specified vector index, set an absolute expiration time for a specified key, accurate to the second.

options

• index_name: the name of the vector index.

• key: The primary key identifier of the record.

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

Returns

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

• If the 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

Category

Description

Syntax

TVS.HEXPIRE index_name key timestamp

Time complexity

O(1)

Command description

In a specified vector index, set a relative expiration time fora specified key, accurate to the second.

options

• index_name: the name of the vector index.

• key: The primary key identifier of the record.

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

Return value

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

• If the 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

Category

Description

Syntax

TVS.HPTTL index_name key

Time complexity

O(1)

Command description

In a specified vector index, check the remaining time-to-live (TTL) of a specified key, accurate to the millisecond.

Options

• index_name: the name of the vector index.

• key: The primary key identifier of this record.

Output

• If the key exists and has a TTL configured, the remaining TTL is returned. Unit: milliseconds.

• If the key exists but does not have a TTL configured, a value of -1 is returned.

• If the key or index_name 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

Category

Description

Syntax

TVS.HTTL index_name key

Time complexity

O(1)

Command description

In a specified vector index, check the remaining TTL of a specified key, accurate to the second.

Options

• index_name: the name of the vector index.

• key: The primary key identifier of the record.

Return value

• If the key exists and has a TTL configured, the remaining TTL is returned. Unit: seconds.

• If the key exists but does not have a TTL configured, a value of -1 is returned.

• If the key or index_name 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

Category

Description

Syntax

TVS.HPEXPIRETIME index_name key

Time complexity

O(1)

Command description

In a specified vector index, check the absolute expiration time of a specified key, accurate to the millisecond.

Options

• index_name: the name of the vector index.

• key: the primary key identifier of the record.

Output

• key exists and has a time-to-live (TTL) set to an absolute expiration time, specified as a Unix timestamp in milliseconds.

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

• If the key or index_name 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

Category

Description

Syntax

TVS.HEXPIRETIME index_name key

Time complexity

O(1)

Command description

In a specified vector index, check the absolute expiration time of a specified key, accurate to the second.

Options

• index_name: the name of the vector index.

• key: The primary key identifier of the record.

return value

• If the key exists and has a time-to-live (TTL) set, the expiration time is an absolute Unix timestamp in seconds.

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

• If the key or index_name 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

Category

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 is the number of keys in the vector index.

Command description

Perform a nearest-neighbor query on a specified vector (VECTOR) in a specified vector index. The query returns up to topN results.

Options

• index_name: the name of the vector index.

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

• vector: the vector used for the nearest-neighbor query. If you want to perform only full-text search using a hybrid index, set this field to "".

• 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: operational parameters for the query. Valid values:

  • ef_search: the length of the dynamic array when querying the index. Default value: 100. Valid values: 1 to 1000. A greater value indicates higher search accuracy. This increases performance overhead. This parameter is specific to the HNSW algorithm.

    sparse_ef_search: if you use HNSW indexes for sparse vectors when creating hybrid indexes, use the sparse_ef_search parameter for the ef_search parameter of the HNSW indexes.

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

  • TEXT: the text used for 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, 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 enough 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 enough 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, 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 these parameters ensure acceptable latency while maintaining accuracy. You can adjust them per request to better fit your use case. However, increasing their values may increase 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"

Category

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 is the number of keys in the vector index.

Command description

Perform a nearest-neighbor query on a specified vector (VECTOR) in a specified vector index. The search logic is identical to that of TVS.KNNSEARCH. In addition, this command returns tag attributes with the results.

Options

• index_name: the name of the vector index.

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

• vector: the vector used for the nearest-neighbor query. If you want to perform only full-text search using a hybrid index, set this field to "".

• field_count: the number of tag attributes to return. To return all tags, set field_count to 0.

• field_name: the tag name. The number of tags must match the field_count value.

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

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

Output

• If the operation is successful, it returns the keys of the nearest neighbors and their distances from the target vector in ascending order of distance, along with the corresponding tag attribute 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"

Category

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 is the number of keys in the vector index.

Command description

Perform a vector nearest-neighbor query on a specified list of keys in a specified vector index.

options

• index_name: the name of the vector index.

• vector: the vector used for the nearest-neighbor query.

• key_count: the number of candidate keys.

• key: the names of the keys. The number of keys must match the key_count value.

• TOPN: the number of keys to return. Default value: key_count. Valid values: 1 to key_count.

• 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 exceeds this value, the key of the neighbor vector is filtered out and excluded from the search results.

Return value

• 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"

Category

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 is the number of keys in the vector index.

Command description

Perform nearest-neighbor queries on multiple vectors (VECTOR) in a specified vector index.

Options

• 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 vectors to query.

• vector: the vector used for the nearest-neighbor query. If you want to perform only full-text search using a hybrid index, set this field to "".

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

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

Return Value

• If the operation is successful, multiple query result arrays are returned in the order of the vector queries. 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"

Category

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 is the number of keys in the vector index.

Command description

Perform a nearest-neighbor query on a specified vector (VECTOR) across multiple vector indexes.

Options

• 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 topN neighbor vectors of the specified vector in each vector index, aggregates the obtained vectors, and returns the topN neighbor vectors that are the nearest to the specified vector. Valid values: 1 to 10000.

• vector: the vector used for the nearest-neighbor query.

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

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

Return value

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

• 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"

Category

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 is the number of keys in the vector index.

Command description

Perform a nearest-neighbor query on a specified vector (VECTOR) across multiple vector indexes. Tag attributes are returned with the results.

options

• index_count: the number of vector indexes.

• index_name: the names of the vector indexes.

• topN: the number of results to return. By default, the system queries the topN results from each vector index, aggregates all query results, and returns the topN nearest results. Valid values: 1 to 10000.

• vector: the vector used for the nearest-neighbor query.

• field_count: the number of tag attributes to return. To return all tags, set field_count to 0.

• field_name: the tag name. The number of tags must match the field_count value.

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

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

Return value

• 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"

Category

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 is the number of keys in the vector index.

Command description

Perform nearest-neighbor queries on multiple vectors (VECTOR) across multiple vector indexes.

Options

• index_count: the number of vector indexes.

• index_name: the names of the vector indexes.

• topN: the number of results returned for each vector query. By default, the system queries the topN results from each vector index, aggregates all query results, and returns the topN results that are nearest. Valid values: 1 to 10000.

• vector_count: the number of vectors to query.

• vector: the vectors used for the nearest-neighbor queries.

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

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

Output

• If the operation is successful, a result array is returned for each query in the order that the queries were submitted. Each array contains the key of each nearest neighbor and its distance to the target vector, sorted in ascending order of distance.

• 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"