Tair (Redis® OSS-Compatible):Vector

Item

Description

Syntax

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

Time complexity

O(1)

Command description

Creates a vector index, specifying the algorithm for building and querying the index, and the distance function. The index can be deleted only with the TVS.DELINDEX command.

Parameters

• index_name: The name of the vector index.

• dims: The vector dimension. All vectors inserted into the index must have the same dimension. The value must be in the range [1, 32768].

• algorithm: The algorithm for building and querying the index. Valid values:

  • FLAT: Performs queries by using brute-force search without creating a separate index. This algorithm is suitable for small datasets with fewer than 10,000 records.

  • HNSW: Builds an HNSW graph-based index for queries. This algorithm is suitable for large datasets.

• distance_method: The method for calculating the distance between vectors. Valid values:

  • L2: The squared Euclidean distance.

  • IP: The inner product. The distance is calculated as 1 - inner product.

  • COSINE: The cosine distance. The distance is calculated as 1 - cosine similarity. When you use cosine distance, input vectors are converted to unit vectors (L2 normalization). As a result, the returned vectors may not be identical to the original vectors.

  • JACCARD: The Jaccard distance. The distance is calculated as 1 - Jaccard coefficient. Requires the data_type parameter to be set to BINARY.

• algo_param_key and algo_param_value:

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

    • FLOAT32 (default): A 4-byte single-precision floating-point number.

    • FLOAT16: A 2-byte half-precision floating-point number that conforms to the IEEE 754-2008 standard. This data type can reduce storage usage for vectors but may result in some loss of precision. The value range for FLOAT16 is [-65519, 65519].

    • BINARY: A binary vector containing only 0s and 1s. This data type can only be used with the Jaccard distance function.

  • Parameters specific to HNSW indexes:

    • ef_construct: The size of the dynamic list used during index construction with the HNSW algorithm. The default value is 100 and the valid range is [1, 1000]. A larger value generally improves query accuracy but reduces performance.

    • M: The maximum number of outgoing connections for each node on each layer of the graph. The default value is 16 and the valid range is [1, 100]. A larger value generally improves query accuracy but reduces performance.

    • auto_gc: Enables or disables automatic index space reclamation. Valid values are false (default) and true. This feature requires the instance minor version to be 6.2.8.2 or later. HNSW indexes use marked deletion. Enabling this feature allows for automatic space reclamation, which reduces memory usage but may affect nearest-neighbor query performance. We recommend enabling this feature for memory-sensitive scenarios.

  • Parameters specific to hybrid indexes:

    • To create an inverted index on a specific tag field, you must specify the field name and its data type.

      Use the syntax inverted_index_<field_name> int|long|float|double|string to create an inverted index on the field_name. Supported data types are int, long, float, double, and string. The field_name and data type keywords must be in lowercase.

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

    • lexical_algorithm: The full-text search algorithm.

      • bm25: The BM25 (Okapi BM25) algorithm, which is suitable for full-text search.

        • When you subsequently write data using TVS.HSET, set the attribute_key to TEXT (must be uppercase). A full-text index is then automatically built on the corresponding attribute_value.

        • You provide the original text, and the Tair builds the index.

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

        You must encode the original text (embedding) and provide the sparse vector. The data format is "[[,],[,],...]", where index is a uint32_t and value is a Float that represents the term's weight or frequency.

    • If you set lexical_algorithm to bm25, you can also configure the following parameters.

      • analyzer: The analyzer. Currently, jieba (default) and ik_smart are supported.

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

      • b: Controls the influence of document length in the BM25 algorithm. The value must be in the range [0, 1]. The default value is 0.75.

    • If you set lexical_algorithm to vector, you can also configure the following parameters.

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

      • lexical_hnsw_m: When lexical_use_hnsw is set to 1, this parameter specifies the M value for the HNSW index, as described in Parameters specific to HNSW indexes above.

      • lexical_hnsw_ef_construct: When lexical_use_hnsw is set to 1, this parameter specifies the ef_construct value for the HNSW index, as described in Parameters specific to HNSW indexes above.

    • hybrid_ratio: The default weight for vector search in a query. The value must be a float in the range [0, 1]. The default value is 0.5. The weight for full-text search is calculated as 1 - hybrid_ratio.

Return value

• Returns OK on success.

• Otherwise, returns an error message.

Example

Sample commands:

# Create a vector index with a vector dimension of 2, the HNSW algorithm, the Jaccard distance function, and the BINARY data type.
TVS.CREATEINDEX index_name0 2 HNSW JACCARD data_type BINARY

# Create a vector index with a vector dimension of 2, the HNSW algorithm, the L2 distance function, and the FLOAT32 data type.
TVS.CREATEINDEX index_name1 2 HNSW L2 

# Create a vector index with a vector dimension of 2, the FLAT algorithm, the IP distance function, and the FLOAT32 data type.
TVS.CREATEINDEX index_name2 2 FLAT IP 

# Create a vector index with a vector dimension of 2, the FLAT algorithm, the Jaccard distance function, and the BINARY data type.
TVS.CREATEINDEX index_name3 2 FLAT JACCARD data_type BINARY

# Create a hybrid index combining HNSW vector search with bm25 full-text search.
TVS.CREATEINDEX index_name4 2 HNSW IP lexical_algorithm bm25 inverted_index_productname string

# Create a sparse vector index with a vector dimension of 2, the IP distance function, and an HNSW index.
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

Retrieves the metadata of a specified vector index.

Parameter

• index_name: The name of the vector index.

Output

• If the command succeeds, it returns the metadata of the vector index.

• If the specified vector index does not exist, it returns (empty array).

• Otherwise, it returns an error message.

Example

Run the following commands first:

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 for an HNSW index:

TVS.GETINDEX my_index

Sample output:

 1) "lexical_term_count"   // The number of terms in the full-text index.
 2) "0"
 3) "lexical_record_count" // The number of documents in the full-text index.
 4) "0"
 5) "lexical_algorithm"    // The full-text indexing algorithm.
 6) "bm25"
 7) "auto_gc"              // Specifies if automatic memory space reclamation is enabled for the HNSW index.
 8) "1"
 9) "dimension"            // The vector dimension.
10) "2"
11) "attribute_data_size"  // The memory usage of attribute data, in bytes.
12) "3720"
13) "distance_method"      // The distance method.
14) "L2"
15) "data_type"            // The vector data type.
16) "FLOAT32"
17) "algorithm"            // The indexing algorithm.
18) "HNSW"
19) "index_data_size"      // The memory usage of vector data, in bytes.
20) "105128040"
21) "M"                    // The maximum number of outgoing neighbors for each node in the graph index structure. This parameter is returned only for HNSW indexes.
22) "16"
23) "data_count"           // The number of user records.
24) "3"
25) "current_record_count" // The total number of vectors.
26) "3"
27) "ef_construct"         // The size of the dynamic array used during index construction. This parameter is returned only for HNSW indexes.
28) "100"
29) "inverted_index_productname" // Information about the inverted index, including the field name, data type, and count.
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), where N is the number of keys in the vector index.

description

Deletes a specified vector index and all the data it contains.

parameter

• index_name: The name of the vector index.

return value

• Returns 1 if the vector index is successfully deleted.

• Returns 0 if the specified index does not exist.

• Otherwise, returns an error message.

example

Command:

TVS.DELINDEX index_name0

Output:

(integer) 1

Item

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

Incrementally scans for vector indexes in a Tair instance that match the specified criteria.

Options

• cursor: The cursor for the scan. Use 0 for the initial scan. For subsequent scans, use the cursor returned by the previous call.

• pattern: A glob-style pattern used to filter vector indexes by name.

• count: A hint for the suggested number of items to scan per iteration. The default is 10, and the actual number of returned items may vary.

Output

• Returns an array that contains two elements:

  • The cursor for the next iteration. A value of "0" means the scan is complete.

  • An array of vector index names (index_name) found in the current scan.

• If the command fails, it returns an error message.

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 with a pattern:

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

The time complexity is O(1) if no vector data is created or updated; otherwise, it is O(log(N)), where N is the number of keys in the vector index.

Command description

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

Parameters

• index_name: The name of the vector index.

• key: The primary key for the data record. You can use the TVS.DEL command to delete the record.

• attribute_key and attribute_value: The attributes of the record, specified as one or more key-value pairs.

  • To insert vector data, set attribute_key to the keyword VECTOR (must be uppercase). The corresponding attribute_value must be a vector data string that matches the dimension (dims) of the vector index. For example: VECTOR [1,2]. Each key can have only one VECTOR attribute. If you set this attribute again for the same key, the existing data is overwritten.

  • To insert text data, you must have configured the hybrid index parameters when you created the index. Set attribute_key to the keyword TEXT (must be uppercase). The corresponding attribute_value can be either text data, such as "TairVector is a proprietary vector database service developed by Tair", or an embedding, such as "[[2,0.221],[42,09688],...]".

  • You can also add other custom attributes or metadata, such as create_time 1663637425 (creation time) or location Hangzhou (location).

Return value

• On success, the command returns the number of new attributes added to the data record. If only existing attributes were updated, it returns 0.

• Otherwise, it returns an error message.

Example

Sample command:

TVS.HSET my_index key5 VECTOR [7,8] TEXT "TairVector is a proprietary vector database service developed by Tair" create_time 1800

Sample output:

(integer) 3

Item

Description

Syntax

TVS.HGETALL index_name key

Time complexity

O(1)

Command description

Retrieves all attributes and values of the data record for the specified key in a vector index.

Parameter

• index_name: The name of the vector index.

• key: The primary key of the data record.

Return value

• On success, returns an array of alternating attributes and their corresponding values for the specified key.

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

• Otherwise, an error message is returned.

Example

Command example:

TVS.HGETALL index_name0 key0

Return example:

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

Returns the values of the specified attribute keys for a given key in a vector index.

Parameters

• index_name: The name of the vector index.

• key: The primary key of the record.

• attribute_key: The attribute key or keys to retrieve. To retrieve the vector, specify the VECTOR keyword (must be in uppercase). To retrieve raw text data from the full-text index, specify the TEXT keyword (must be in uppercase).

Returns

• On success, returns an array of values for the specified attribute_keys, in the order requested. If an attribute key does not exist, the command returns nil in its place.

• Otherwise, the command returns an error message.

Example

Sample command:

TVS.HMGET index_name0 key0 create_time location VECTOR TEXT

Sample output:

1) "1800"
2) "[7,8]"
3) "TairVector is a proprietary vector database service developed by Tair"

Item

Description

Syntax

TVS.DEL index_name key [key ...]

Time complexity

O(1)

Command description

Deletes the specified data record (key) from the specified vector index.

Parameter

• index_name: The name of the vector index.

• key: The primary key of a data record.

Return value

• Success: Deletes the specified data record (key) and returns the deletion count for the key.

• Returns 0 if the vector index does not exist.

• Otherwise, returns an error message.

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 one or more attribute_keys and their values from a record (key) in a vector index.

Parameters

• index_name: The name of the vector index.

• key: The primary key of the record.

• attribute_key: The attribute key for the operation. You can specify multiple keys. To delete vector data, pass the VECTOR keyword in uppercase. To delete full index data, pass the TEXT keyword in uppercase.

Return value

• Returns the number of removed attribute_keys.

• Returns 0 if the vector index does not exist.

• Returns an error message in other cases.

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

Scans for data records (identified by key) that meet specified conditions within a given vector index.

Parameters

• index_name: The name of the vector index.

• cursor: The cursor for the scan. Use 0 for the first scan. For subsequent scans, use the cursor returned by the previous call.

• pattern: A glob-style pattern for matching keys.

• count: The suggested number of items to scan in each iteration. The default value is 10. The actual number of returned items is not guaranteed to be exact.

• filter_string: The filter conditions.

  • Supports operators such as +, -, *, /, <, >, !=, (), &&, and ||. The > and < operators do not support string comparisons. To include a string literal in your filter, escape quotation marks with a backslash (\). For example: create_time > 1663637425 && location == \"Hangzhou\".

  • Separate operators from their operands with spaces. For example: "creation_time > 1735".

  • Direct boolean comparisons, such as flag == true, are not supported. Instead, compare the value as a string: flag == \"true\".

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

• max_distance: The maximum distance threshold. This parameter must be used with the vector parameter. When both are specified, the command returns only results whose distance from the query vector is less than max_distance.

Return value

• On success, the command returns an array with two elements:

  • The first element is the cursor for the next iteration. A value of 0 indicates that the scan is complete.

  • The second element is an array of key names for the data records found in the current iteration.

• On failure, the command returns an error message.

Example

Example command:

TVS.SCAN index_name0 0

Example return value:

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

Category

Description

Syntax

TVS.HINCRBY index_name key attribute_key num

Time complexity

O(1)

Command description

Increments the integer value of attribute_key for the specified data record (key) in a vector index by num.

If attribute_key does not exist, the command sets it to 0 before performing the increment. If the value of attribute_key is not an integer, the command returns an error.

Parameters

• index_name: The name of the vector index.

• key: The primary key identifier of the data record.

• attribute_key: The attribute key to increment.

• num: The integer value to add.

Return value

• Integer reply: The new value of attribute_key.

• Otherwise, returns an error message.

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

Increments the value of attribute_key for a given data record (key) by the floating-point number num in a specified vector index.

If the specified attribute_key does not exist, it is created with num as its initial value.

Parameters

• index_name: The name of the vector index.

• key: The primary key identifier of the record.

• attribute_key: The attribute key to increment.

• num: The floating-point value to increment by.

Return value

• On success, the updated value of the attribute key.

• On failure, an error message.

Example

Example command:

TVS.HINCRBYFLOAT index_name0 key0 tv02 9.34

Example output:

"9.34"

Category

Description

Syntax

TVS.HPEXPIREAT index_name key milliseconds-timestamp

Time complexity

O(1)

Command description

Sets the absolute expiration time in milliseconds for a data record, identified by its key, within a specified vector index.

Parameters

• index_name: The name of the vector index.

• key: The primary key of the data record.

• milliseconds-timestamp: A UNIX timestamp specified in milliseconds. If the timestamp is in the past, the key expires immediately.

Return value

• Returns 1 if the timeout is set for an existing key.

• Returns 0 if the key does not exist.

• Otherwise, it returns an exception.

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

Sets a relative expiration time in milliseconds for a specified key in a vector index.

Parameters

• index_name: The name of the vector index.

• key: The primary key identifier of the vector.

• milliseconds-timestamp: The relative expiration time, in milliseconds.

Return value

• 1 if the expiration was set.

• 0 if the key does not exist.

• An error in other cases.

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

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

Options

• index_name: The name of the vector index.

• key: The primary key of the record.

• timestamp: A UNIX timestamp in seconds. If the timestamp is in the past, the key expires immediately.

Return value

• Returns 1 if the timeout is set for the key.

• Returns 0 if the key does not exist.

• Returns an error message otherwise.

Example

Command example:

TVS.HEXPIREAT index_name0 key2 1691466981

Return example:

(integer) 1

Category

Description

Syntax

TVS.HEXPIRE index_name key timestamp

Time complexity

O(1)

Command description

Sets a relative expiration time in seconds for a specified vector (key) in a vector index.

Parameters

• index_name: The name of the vector index.

• key: The primary key identifier of the vector.

• timestamp: The relative expiration time, in seconds.

Output

• If the timeout is successfully set for an existing key: 1.

• If the key does not exist: 0.

• Otherwise, an error message is returned.

Example

Sample command:

TVS.HEXPIRE index_name0 key2 100

Sample output:

(integer) 1

Category

Description

Syntax

TVS.HPTTL index_name key

Time complexity

O(1)

Command description

Returns the TTL, in milliseconds, for a specified data record (key) in a vector index.

Parameters

• index_name: The name of the vector index.

• key: The primary key of the data record.

Return value

• The TTL in milliseconds, if the key exists and has an expiration time set.

• -1 if the key exists but has no expiration time set.

• -2 if the key or index_name does not exist.

• An error message.

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

Retrieves the TTL in seconds for a specified data record (key) in a specified vector index.

Parameters

• index_name: The name of the vector index.

• key: The primary key of the data record.

Return value

• The remaining TTL in seconds, if the key exists and has an expiration time.

• -1, if the key exists but has no expiration time.

• -2, if the key or index_name does not exist.

• An exception message for any other error.

Example

Command example:

TVS.HTTL index_name0 key2

Return example:

(integer) 58

Category

Description

Syntax

TVS.HPEXPIRETIME index_name key

Time complexity

O(1)

Command description

Returns the absolute expiration time of a specified data record (key) in a vector index, as a Unix timestamp in milliseconds.

Parameter

• index_name: The name of the vector index.

• key: The primary key identifier of the data record.

Return value

• If the key exists and has an expiration time set: The absolute expiration time as a Unix timestamp in milliseconds.

• If the key exists but has no expiration time set: -1.

• If the key or index_name does not exist: -2.

• Otherwise: A corresponding error message.

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

Returns the absolute expiration time of a specified data record (key) in a vector index as a Unix timestamp in seconds.

Parameters

• index_name: The name of the vector index.

• key: The primary key identifier of the data record.

Output

• If the key exists and has an expiration time set, the value is the absolute expiration time (Unix timestamp) in seconds.

• The key exists but has no expiration time: -1.

• If the key or index_name does not exist, the command returns -2.

• In other cases, the command returns an error message.

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

Command description

Performs a nearest-neighbor query for a specified vector in a vector index and returns up to topN results.

Parameters

• index_name: The name of the vector index.

• topN: The number of results to return. The value must be in the range [1, 10000].

• vector: The vector value used to perform a nearest neighbor query. If you want to perform only a full-text search on a hybrid index, you can pass "" to this field.

• filter_string: The filter condition.

  • Supports operators such as +-*/<>!=()&&||. String comparisons for greater or less than are not supported. To include a string literal in your filter, you must use an escape character (\) for the quotation marks. For example: "create_time > 1663637425 && location == \"Hangzhou\"".

  • Operators must be separated from their operands by spaces. For example: "creation_time > 1735".

  • Direct boolean comparisons, such as flag == true, are not supported. Instead, compare the value as a string: flag == \"true\".

• param_key and param_value: Operational parameters for the query, specified as key-value pairs. The following parameters are supported:

  • ef_search: The size of the dynamic list for the search. The default value is 100, and the valid range is [1, 1000]. A larger value generally improves search accuracy but increases performance overhead. This parameter is specific to the HNSW algorithm.

    For a hybrid index that uses an HNSW index for sparse vectors, use sparse_ef_search to specify the ef_search parameter for the sparse vector index.

  • MAX_DIST: The maximum distance limit. This must be a float. Filters out keys whose distance to the query vector is greater than this value.

  • TEXT: The query text for a hybrid search, which can be text or a vector. If this parameter is not specified or is set to "", no full-text search is performed and only a vector search is performed.

  • hybrid_ratio: The weight for vector search results in this query. The value must be a float in the range [0, 1]. The default is the hybrid_ratio value set during index creation. The weight for full-text search is calculated as 1-hybrid_ratio.

  • By default, the system uses a PostFilter strategy, which performs k-nearest neighbor (KNN) vector search before applying scalar filtering.

    • vector_filter_count: The maximum number of candidates to filter from the vector search results. Default: 10,000.

      In the PostFilter strategy, the search stops if it filters more than this number of candidates without finding topN results.

    • fulltext_filter_count: The maximum number of candidates to filter from the full-text search results. Default: 10,000.

      In the PostFilter strategy, the search stops if it filters more than this number of candidates without finding topN results.

    • To use a PreFilter strategy, which performs scalar filtering based on the inverted index before the KNN vector search, add the search_policy scalar parameter to your query.

      You can also provide the ivf_filter_count parameter, which specifies the maximum number of records to retrieve from the inverted index during the pre-filtering stage. The default is 10,000. In the PreFilter strategy, if the number of records matching the scalar filter exceeds this value, the system falls back to the PostFilter strategy.

    Note

    In most cases, these default parameters ensure low latency while maintaining high accuracy. You can adjust them for specific requests, but be aware that higher values can increase query latency.

Return value

• A successful execution returns the keys of the nearest neighbors and their distances to the target vector, in order of distance from nearest to farthest.

• If the specified vector index does not exist, the command returns an (empty array).

• In other cases, it returns an error message.

Examples

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"

Example 1:

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

Response 1:

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

Example 2:

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

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

Command description

Searches a vector index for the nearest neighbors of a specified vector. The search logic is identical to TVS.KNNSEARCH, but this command also returns tag attributes.

Parameter

• index_name: The name of the vector index.

• topN: The number of results to return. The value must be in the range of [1, 10000].

• vector: The query vector for the nearest-neighbor search. To perform only a full-text search on a hybrid index, you can pass an empty string ("") for this parameter.

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

• field_name: The names of the tag attributes to return. The number of names must match the value of field_count.

• filter_string: The filter condition. For more information, see TVS.KNNSEARCH.

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

Return value

• On success, this command returns the key, distance from the query vector, and tag attribute key-value pairs for each nearest neighbor. The results are sorted by distance in ascending order.

• If the specified vector index does not exist, it returns (empty array).

• Otherwise, it returns an error message.

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

Command description

Finds the nearest neighbors of a query vector from a specified list of keys within a vector index.

Parameter

• index_name: The name of the vector index.

• vector: The query vector.

• key_count: The number of candidate keys.

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

• TOPN: The maximum number of results to return. The default value is key_count. The value must be in the range [1, key_count].

• FILTER: The filter condition.

  • Supports operators such as +-*/<>!=()&&||. Greater-than and less-than comparisons are not supported for strings. To include a string literal, you must escape the quotation marks with a backslash (\). For example: create_time > 1663637425 && location == \"Hangzhou\".

  • Operators must be separated from their operands by spaces. For example, "creation_time > 1735".

  • Direct boolean comparisons, such as flag == true, are not supported. Instead, compare the value as a string: flag == \"true\".

• MAX_DIST: Filters out keys whose distance from the query vector exceeds this value.

Output

• Returns the matching keys and their distances. By default, results are returned in the same order as the provided keys. If TOPN is specified, the command returns the topN nearest keys and their distances, sorted from nearest to farthest.

• Returns an (empty array) if the vector index does not exist.

• For all other errors, 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 is the number of keys in the vector index.

Command description

Performs a batch nearest neighbor search for multiple vectors in a specified vector index.

Parameters

• index_name: The name of the vector index.

• topN: The number of results to return for each query vector. The value must be in the range [1, 10000].

• vector_count : The number of query vectors.

• vector: One or more vectors for the nearest neighbor search. To perform only a full-text search on a hybrid index, pass "" for this parameter.

• filter_string: The filter condition. For more information, see the description in TVS.KNNSEARCH.

• param_key and param_value: The runtime parameters for the query. For more information, see the description in TVS.KNNSEARCH.

Return value

• On success, the command returns multiple result arrays, one for each query vector. Each array contains the keys of the nearest neighbors and their distances, sorted from nearest to farthest.

• If the vector index does not exist, the command returns an (empty array).

• Otherwise, the command returns an error message.

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

Command description

Searches for the nearest neighbors of a 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 nearest neighbors to return, from 1 to 10,000. The command retrieves the top topN results from each specified index, aggregates them, and returns the overall top topN nearest neighbors from the combined set.

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

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

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

Output

• Returns an array of the nearest neighbor keys and their distances to the query vector, sorted from nearest to farthest.

• Returns an (empty array) if a specified vector index does not exist.

• Otherwise, returns an error message.

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

Performs a nearest neighbor query for a specified vector across multiple vector indexes and optionally returns tags.

Parameters

• index_count: The number of vector indexes.

• index_name: The names of the vector indexes.

• topN: The number of nearest neighbors to return, ranging from 1 to 10,000. The command queries for the topN nearest neighbors in each vector index, aggregates these results, and then returns the overall topN results with the shortest distances.

• vector: The input vector for the nearest neighbor query.

• field_count: The number of tags to return. To return all tags, set field_count to 0.

• field_name: The names of the tags to return. The number of names provided must match the value of field_count.

• filter_string: The filter conditions. For more information, see TVS.KNNSEARCH.

• param_key and param_value: The runtime parameters for the query. For more information, see TVS.KNNSEARCH.

Output

• On success, the command returns the keys of the nearest neighbors, their distances to the query vector, and their corresponding tag key-value pairs. The results are sorted by distance in ascending order.

• If a specified vector index does not exist, the command returns an (empty array).

• Otherwise, the command returns an error message.

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

Command description

Searches multiple vector indexes for the nearest neighbors of multiple vectors.

Parameters

• index_count: The number of vector indexes.

• index_name: The name of a vector index.

• topN: The number of nearest neighbors to return for each query vector. The value must be in the range [1, 10000]. By default, the command retrieves the topN results from each vector index, aggregates them, and returns the overall topN results with the shortest distances.

• vector_count: The number of query vectors.

• vector: A query vector for the nearest-neighbor search.

• filter_string: The filter conditions. For more information, see TVS.KNNSEARCH.

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

Return value

• On success, returns an array of result arrays in the same order as the query vectors. Each result array contains the key and distance for each nearest neighbor, sorted by distance from nearest to farthest.

• If a specified vector index does not exist, returns an (empty array).

• In other cases, returns an error message.

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"