All Products
Search

This Product

    Tair:Vector

    Document Center

    Tair:Vector

    Last Updated:Apr 09, 2024

    TairVector is an extended data structure developed by the Tair team to provide high-performance real-time storage and retrieval of vectors.

    Overview

    TairVector uses a multi-layer hash structure, as shown in the following figure.TairVector数据结构TairVector provides two indexing algorithms: Hierarchical Navigable Small World (HNSW) and Flat Search.

    • HNSW: creates graph-based vector indexes and supports asynchronous memory space reclamation to maintain high query accuracy while still being able to handle real-time updates and changes to the index structure.

    • Flat Search: implements exact match and fast data insertion. This algorithm is suitable for small datasets.

    Additionally, TairVector supports multiple distance formulas, such as Euclidean distance, inner product, Cosine distance, and Jaccard distance. Compared with traditional vector retrieval services, TairVector has the following advantages:

    • Stores all data in memory and supports real-time index updates to reduce read and write latency.

    • Uses an optimized data structure in memory to better utilize storage capacity.

    • Functions as an out-of-the-box data structure in a simple and efficient architecture without complex modules or dependencies.

    • Supports hybrid search that combines vector search and full-text search.

    • Allows you to create inverted indexes for scalar data such as tag attributes, and provides the k-nearest neighbor (KNN) search feature. During retrieval, TairVector first filters the dataset based on the scalar attributes and then applies the KNN algorithm for vector search on the filtered results.

    Release notes

    1. TairVector was released on October 13, 2022 together with Tair DRAM-based instances that are compatible with Redis 6.0.

    2. With the release of Tair 6.2.2.0 on November 22, 2022, two notable additions to TairVector are support for the Jaccard distance formula and enhancement in the TVS.GETINDEX command. This command can provide memory usage statistics for each index by using the index_data_size and attribute_data_size parameters.

    3. With the release of Tair 6.2.3.0 on December 26, 2022, notable additions to TairVector include support for cluster instances in proxy mode, introduction of the FLOAT16 data type, and inclusion of the TVS.MINDEXKNNSEARCH and TVS.MINDEXMKNNSEARCH commands.

    4. With the release of Tair 6.2.8.2 on July 4, 2023, two notable additions to TairVector are support for the Cosine distance formula and automatic memory space reclamation of HNSW indexes.

    5. With the release of Tair 23.8.0.0 on August 3, 2023, TairVector introduces commands such as TVS.HEXPIREAT and TVS.HPEXPIREAT that allow you to set a time-to-live (TTL) for keys in indexes, and introduces the TVS.GETDISTANCE command to support vector nearest-neighbor queries on specified keys. TairVector also enhances its capabilities with respect to full-text search by updating commands such as TVS.CREATEINDEX and TVS.KNNSEARCH. These enhancements allow you to combine vector search and full-text search to perform hybrid search.

    Best practices

    Prerequisites

    The instance is a Tair DRAM-based instance that is compatible with Redis 6.0. For more information, see DRAM-based instances.

    Note

    A DRAM-based instance that runs Redis 5.0 cannot be upgraded to one that runs Redis 6.0. To use a DRAM-based instance that runs Redis 6.0, you must create one.

    Precautions

    • The TairVector data that you want to manage is stored on the Tair instance.

    • Hashtags in Redis cannot be used to control key distribution and slot allocation for TairVector indexes.

    • TairVector does not support features such as MOVE.

    • If your business requires high data persistence, we recommend that you enable the semi-synchronous replication feature by setting the #no_loose_tsync-repl-mode parameter to semisync. For more information, see Modify the values of parameters for an instance.

    Supported commands

    Table 1. TairVector commands

    Type

    Command

    Syntax

    Description

    Operations on vector indexes

    TVS.CREATEINDEX

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

    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.

    TVS.GETINDEX

    TVS.GETINDEX index_name

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

    TVS.DELINDEX

    TVS.DELINDEX index_name

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

    TVS.SCANINDEX

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

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

    Operations on vectors

    TVS.HSET

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

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

    TVS.HGETALL

    TVS.HGETALL index_name key

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

    TVS.HMGET

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

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

    TVS.DEL

    TVS.DEL index_name key [key ...]

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

    TVS.HDEL

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

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

    TVS.SCAN

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

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

    TVS.HINCRBY

    TVS.HINCRBY index_name key attribute_key num

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

    TVS.HINCRBYFLOAT

    TVS.HINCRBYFLOAT index_name key attribute_key num

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

    TVS.HPEXPIREAT

    TVS.HPEXPIREAT index_name key milliseconds-timestamp

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

    TVS.HPEXPIRE

    TVS.HPEXPIRE index_name key milliseconds-timestamp

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

    TVS.HEXPIREAT

    TVS.HEXPIREAT index_name key timestamp

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

    TVS.HEXPIRE

    TVS.HEXPIRE index_name key timestamp

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

    TVS.HPTTL

    TVS.HPTTL index_name key

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

    TVS.HTTL

    TVS.HTTL index_name key

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

    TVS.HPEXPIRETIME

    TVS.HPEXPIRETIME index_name key

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

    TVS.HEXPIRETIME

    TVS.HEXPIRETIME index_name key

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

    Vector nearest-neighbor queries

    TVS.KNNSEARCH

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

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

    TVS.GETDISTANCE

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

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

    TVS.MKNNSEARCH

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

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

    TVS.MINDEXKNNSEARCH

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

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

    TVS.MINDEXMKNNSEARCH

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

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

    Note The following list describes the conventions for the command syntax used in this topic:
    • Uppercase keyword: indicates the command keyword.
    • Italic text: indicates variables.
    • [options]: indicates that the enclosed parameters are optional. Parameters that are not enclosed by brackets must be specified.
    • A|B: indicates that the parameters separated by the vertical bars (|) are mutually exclusive. Only one of the parameters can be specified.
    • ...: indicates that the parameter preceding this symbol can be repeatedly specified.

    TVS.CREATEINDEX

    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 vector data type. 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 more performance overheads.

        • 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 more performance overheads.

        • 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 of 6.2.8.2 or later. An HNSW index uses the marked deletion method to delete vectors. After you enable this feature, the index reclaims memory space automatically, 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 in scenarios where memory usage is a concern, and a decrease in nearest-neighbor query performance can be tolerated.

      • Parameters specific to hybrid indexes:

        • lexical_algorithm: the full-text search algorithm.

          • 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. 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, in which 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 further customize the behavior of the BM25 algorithm by adjusting the following parameters:

          • analyzer: the analyzer that you want to use for text segmentation. Valid values: g 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 document length on the relevance score in the BM25 algorithm. Valid values: 0 to 1. Default value: 0.75.

        • 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 HNSW algorithm and the inner product formula for vectors whose dimension is 2 and data type is FLOAT32. 
TVS.CREATEINDEX index_name2 2 HNSW IP

# Create a vector index that uses the Flat Search algorithm and the Euclidean distance formula for vectors whose dimension is 2 and data type is FLOAT32. 
TVS.CREATEINDEX index_name3 2 FLAT 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_name4 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_name5 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. 
TVS.CREATEINDEX index_name6 2 HNSW IP lexical_algorithm bm25

    Sample output:

    OK

    TVS.GETINDEX

    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) "delete_record_count"  // The number of vectors that are pending deletion to reclaim memory space. 
30) "0"

    TVS.DELINDEX

    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 1 is returned.

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

    • Otherwise, an error message is returned.

    Example

    Sample command:

    TVS.DELINDEX index_name0

    Sample output:

     (integer) 1

    TVS.SCANINDEX

    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 operation is successful, 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"

    TVS.HSET

    Item

    Description

    Syntax

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

    Time complexity

    If no indexes are created in this operation, the time complexity is O(1). Otherwise, the time complexity is O(log(N)), in which 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 vectors that are written to the vector index 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

    TVS.HGETALL

    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"

    TVS.HMGET

    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"

    TVS.DEL

    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 vectors are deleted and the number of deleted vectors is returned.

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

    • Otherwise, an error message is returned.

    Example

    Sample command:

    TVS.DEL index_name0 keyV

    Sample output:

     (integer) 1

    TVS.HDEL

    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, 0 is returned.

    • Otherwise, an error message is returned.

    Example

    Sample command:

    TVS.HDEL index_name0 keyc VECTOR

    Sample output:

     (integer) 1

    TVS.SCAN

    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 a distance of the max_distance value 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 operation is successful, 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"

    TVS.HINCRBY

    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

    TVS.HINCRBYFLOAT

    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"

    TVS.HPEXPIREAT

    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

    TVS.HPEXPIRE

    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

    TVS.HEXPIREAT

    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

    TVS.HEXPIRE

    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

    TVS.HPTTL

    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 a TTL 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

    TVS.HTTL

    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 a TTL 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

    TVS.HPEXPIRETIME

    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

    TVS.HEXPIRETIME

    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

    TVS.KNNSEARCH

    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 more performance overheads. This parameter is available only if you use the HNSW indexing algorithm.

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

    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 indexes do not exist, (empty array) is returned.

    • Otherwise, an error message is returned.

    Example

    Run the following commands in advance:

    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.KNNSEARCH my_index_k 2 [3,3.1] "creation_time > 1735"

    Sample output:

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

    TVS.GETDISTANCE

    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 vectors 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 indexes do not exist, (empty array) is returned.

    • Otherwise, an error message is returned.

    Example

    Run the following commands in advance:

    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"

    TVS.MKNNSEARCH

    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 vectors 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 more performance overheads and slower queries. This parameter is available only if you use the HNSW indexing algorithm.

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

    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 indexes do not exist, (empty array) is returned.

    • Otherwise, an error message is returned.

    Example

    Run the following commands in advance:

    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"

    TVS.MINDEXKNNSEARCH

    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.

      • 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 more performance overheads and slower queries. This parameter is available only if you use the HNSW indexing algorithm.

    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 indexes do not exist, (empty array) is returned.

    • Otherwise, an error message is returned.

    Example

    Run the following commands in advance:

    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"

    TVS.MINDEXMKNNSEARCH

    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.

      • 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 more performance overheads and slower queries. This parameter is available only if you use the HNSW indexing algorithm.

    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 indexes do not exist, (empty array) is returned.

    • Otherwise, an error message is returned.

    Example

    Run the following commands in advance:

    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"