Vector全局索引

类别

说明

语法

TVS.CREATEINDEXGLOBAL global_index dims algorithm distance_method [algo_param_key alog_param_value] ...

时间复杂度

O(1)

命令描述

创建一个全局索引，同时指定构建索引和查询的具体算法，以及距离函数。

该对象仅能通过TVS.DELINDEXGLOBAL命令删除。

选项

• global_index：全局索引名称。

• dims：向量维度，插入该索引的向量需具有相同的向量维度，取值范围为[1, 32768]。

• algorithm：构建、查询索引的算法，取值如下：

  • FLAT：不单独构建索引，采用暴力搜索的方式执行查询，适合1万条以下的小规模数据集。

  • HNSW：采用HNSW图结构构建整个索引，并通过该算法进行查询，适合大规模的数据集。

• distance_method：计算向量距离函数，取值如下：

  • L2：平方欧氏距离。

  • IP：向量内积，距离值为1-向量内积。

  • COSINE：余弦距离，距离值为1-向量余弦值。使用余弦距离会将写入的向量转化为单元向量（L2正则化），因此查询得到的向量结果可能不是原始向量值。

  • JACCARD：Jaccard距离，距离值为1-Jaccard系数，且需指定向量数据类型（data_type）为BINARY。

• algo_param_key和alog_param_value：

  • data_type：向量数据类型，取值说明如下。

    • FLOAT32（默认）：4字节的单精度浮点数。

    • FLOAT16：2字节的半精度浮点数（IEEE 754-2008标准），可节省向量存储空间，但会损失一定的精度，FLOAT16能表示的最大数值范围为[-65519, 65519]。

    • BINARY：二进制向量，仅能包含0或1，仅支持Jaccard距离函数。

  • HNSW索引的特定参数，取值说明如下：

    • ef_construct：使用HNSW算法构建索引时，动态列表的长度。默认为100，取值范围为[1,1000]，该值越大则ANN查询精度越高，同时性能开销越大。

    • M：图索引结构中，每一层的最大出边数量。默认为16，取值范围为[1,100]。该值越大则ANN查询精度越高，同时性能开销越大。

    • auto_gc：自动回收索引空间，取值为false（默认，表示关闭）、true（表示开启），该功能要求实例的小版本为6.2.8.2及以上。HNSW索引的向量删除采用标记删除的方式，开启该功能后，支持索引空间的自动回收，可有效降低内存占用，但该功能会影响该索引近邻查询的性能，推荐对内存占用量敏感的场景使用该功能。

  • HybridIndex（混合索引）的特定参数，取值说明如下：

    • 如需对指定标签字段创建倒排索引，需提前指定字段名称与对应的数据类型。

      语法为inverted_index_<field_name> int|long|float|double|string，对field_name字段建立倒排索引，支持的类型为Int、Long、Float、Double和String，field_name字段和数据类型关键字需小写。

      例如希望对productname字段（String类型）创建倒排索引的示例为inverted_index_productname string。

    • lexical_algorithm：全文检索算法。

      • bm25：BM25（Okapi BM25）算法，您可传入原始文本，由Tair向量服务构建索引。

      • vector：Vector算法，您需要对原始文本进行编码（Embedding），传入稀疏向量。数据格式为"[[2,0.221],[42,09688],...]"，其中Key为Indices，类型为uint32_t，Value为该Index的词频概览，类型为Float。

    • 若lexical_algorithm设置为bm25，您还可以设置analyzer与k1、b的权重。

      • analyzer：分词器，当前支持jieba（默认）、ik_smart。

      • k1：BM25算法中控制词频饱和度，默认为1.2，取值范围需大于0。

      • b：BM25算法中控制文档长度的影响，默认为0.75，取值范围为[0,1]。

    • hybrid_ratio：该索引在查询时向量检索的默认权重，默认为0.5，取值范围为[0,1]，Float类型，全量检索的权重为1-hybrid_ratio。

返回值

• 执行成功：返回OK。

• 其他情况返回相应的异常信息。

示例

命令示例：

# 创建向量存储结构：向量维度为2、索引类型为HNSW、距离函数为Jaccard、向量数据类型为BINARY。
TVS.CREATEINDEXGLOBAL index_name0 2 HNSW JACCARD data_type BINARY

# 创建向量存储结构：向量维度为2、索引类型为HNSW、距离函数为L2、向量数据类型为FLOAT32。
TVS.CREATEINDEXGLOBAL index_name1 2 HNSW L2 

# 创建向量存储结构：向量维度为2、索引类型为FLAT、距离函数为IP、向量数据类型为FLOAT32。
TVS.CREATEINDEXGLOBAL index_name2 2 FLAT IP 

# 创建向量存储结构：向量维度为2、索引类型为FLAT、距离函数为Jaccard、向量数据类型为BINARY。
TVS.CREATEINDEXGLOBAL index_name3 2 FLAT JACCARD data_type BINARY

# 创建向量存储结构：向量维度为2、索引类型为HNSW、距离函数为IP、向量数据类型为FLOAT32、全文检索算法为BM25，指定productname字段（String类型）为倒排索引。
TVS.CREATEINDEXGLOBAL index_name4 2 HNSW IP lexical_algorithm bm25 inverted_index_productname string

返回示例均为如下：

OK

类别

说明

语法

TVS.EXPANDINDEXGLOBAL global_index num

时间复杂度

O(1)

命令描述

在全局索引中创建数据索引。

当您在本接口指定新建的数量时，Tair会自动、均衡地将数据索引创建在不同的分片中，并且自动命名。数据索引的元数据信息与全局索引相同，并且与全局索引存在关联关系，同时，数据索引也独立存储在Tair中。

选项

• global_index：全局索引名称。

• num：新增数据索引的数量。

返回值

• 执行成功：返回OK。

• 其他情况返回相应的异常信息。

示例

命令示例：

TVS.EXPANDINDEXGLOBAL index_name0 3

返回示例均为如下：

OK

类别

说明

语法

TVS.IMPORTINDEXGLOBAL global_index sub_index

时间复杂度

O(1)

命令描述

绑定存量数据索引至全局索引中，存量数据索引的元数据信息需与全局索引一致。

选项

• global_index：全局索引名称。

• sub_index：数据索引名称。

返回值

• 执行成功：返回OK。

• 若数据索引与全局索引不一致：返回(error)ERR tow indices are not suitable。

• 其他情况返回相应的异常信息。

示例

命令示例：

TVS.IMPORTINDEXGLOBAL index_name0 testvector

返回示例均为如下：

OK

类别

说明

语法

TVS.LISTINDEXGLOBAL num [global_index] [global_index] ...

时间复杂度

O(1)

命令描述

查询全局索引信息。

选项

• num：查询的数量，当该参数为0时，将返回所有全量索引信息。

• global_index：全局索引名称。

返回值

• 执行成功：返回OK。

• 其他情况返回相应的异常信息。

示例

命令示例：

TVS.LISTINDEXGLOBAL 2 index_name0 index_name4

返回示例均为如下：

1) "{\"dimension\":\"2\",\"algorithm\":\"HNSW\",\"distance_method\":\"JACCARD\",\"parameters\":[\"data_type\",\"BINARY\"],\"sub_index_list\":[\"index_name0_sub_1719912517_2\",\"index_name0_sub_1719912517_3\",\"index_name0_sub_1719912517_4\"]}"
2) "{\"dimension\":\"2\",\"algorithm\":\"HNSW\",\"distance_method\":\"IP\",\"parameters\":[\"lexical_algorithm\",\"bm25\",\"inverted_index_productname\",\"string\"],\"sub_index_list\":[\"index_name4_sub_1719986971_2\",\"index_name4_sub_1719986971_0\",\"index_name4_sub_1719986971_1\"]}"

类别

说明

语法

TVS.DELINDEXGLOBAL global_index [sub_index] ...

时间复杂度

O(1)

命令描述

解绑全量索引与数据索引的关系。若不指定数据索引，则直接删除该全量索引，同时解除所有相关的数据索引的关联关系。

选项

• global_index：全局索引名称。

• sub_index：数据索引名称。

返回值

• 执行成功：

  • 若解除全量索引与数据索引的关系，返回0。

  • 若删除全量索引，返回1。

• 其他情况返回相应的异常信息。

示例

命令示例：

TVS.DELINDEXGLOBAL index_name0 index_name0_sub_1720000607_0 index_name0_sub_1720000607_1

返回示例均为如下：

(integer) 0

类别

说明

语法

TVS.HSETGLOBAL global_index key attribute_key attribute_value [attribute_key attribute_value] ...

时间复杂度

若本次插入、更新数据无需创建或更新向量值，则时间复杂度为O(1)；否则时间复杂度为O(log(N))，N为该向量索引中Key的数量。

命令描述

往全局索引中插入数据记录（Key），Tair会自动把Key写到合适的数据索引中，实现数据均衡。

若该记录已存在则更新并覆盖原记录。

选项

• global_index：全局索引名称。

• key：该记录的主键标识，该对象可通过TVS.DELGLOBAL命令删除。

• attribute_key和attribute_value：该条记录的数值，为Key-value格式。

  • 插入向量数据：需要将attribute_key设置为VECTOR关键字（必须大写），对应的attribute_value则需要为该向量索引指定维度（dims）的向量数据字符串，例如VECTOR [1,2]。一个Key仅支持写入一个VECTOR数据，若重复写入会更新并覆盖原数据。

  • 插入文本数据：在创建索引时已制定HybridIndex相关参数，需要将attribute_key设置为TEXT关键字（必须大写），对应的attribute_value可以是文本格式（Text），例如"TairVector是Tair自研的向量数据库服务"，也可以是向量化（Embedding）后的数据，例如"[[2,0.221],[42,09688],...]"。

  • 插入其他属性：可以自定义额外属性或信息，例如create_time 1663637425（创建时间）、location Hangzhou（地点）等。

返回值

• 执行成功：返回新增的数据记录数量，若更新已有的字段则返回0。

• 其他情况返回相应的异常信息。

示例

命令示例：

TVS.HSETGLOBAL my_index key0 VECTOR [5,6] creation_time 1750 productname "Aliyun"

返回示例：

(integer) 3

类别

说明

语法

TVS.HGETALLGLOBAL global_index key

时间复杂度

O(1)*M，M为数据索引的数量。

命令描述

查询全局索引中key对应的所有数据记录。

选项

• global_index：全局索引名称。

• key：该记录的主键标识。

返回值

• 执行成功：返回该key的所有数据记录。

• 若指定的向量索引或key不存在，返回(empty array)。

• 其他情况返回相应的异常信息。

示例

命令示例：

TVS.HGETALLGLOBAL my_index key0

返回示例：

1) "VECTOR"
2) "[5,6]"
3) "productname"
4) "Aliyun"
5) "creation_time"
6) "1750"

类别

说明

语法

TVS.HMGETGLOBAL global_index key attribute_key [attribute_key ...]

时间复杂度

O(1)*M，M为数据索引的数量。

命令描述

查询指定向量索引的key中对应的attribute_key所对应的数值。

选项

• global_index：全局索引名称。

• key：该记录的主键标识。

• attribute_key：待操作的属性Key，支持指定多个。若需查询向量数据，需传入VECTOR关键字（必须大写）。若需查询全文索引中原生文本数据，需传入TEXT关键字（必须大写）。

返回值

• 执行成功：返回attribute_key对应的数值。

• 其他情况返回相应的异常信息。

示例

命令示例：

TVS.HMGETGLOBAL index_name0 key0 create_time VECTOR

返回示例：

1) "1800"
2) "[7,8]"

类别

说明

语法

TVS.DELGLOBAL global_index key [key ...]

时间复杂度

O(1)

命令描述

在全量索引中，删除指定数据记录（key）。

选项

• global_index：全局索引名称。

• key：该记录的主键标识，支持指定多个。

返回值

• 执行成功：删除指定数据记录（key），并返回删除key的数量。

• 若指定索引不存在，返回0。

• 其他情况返回相应的异常信息。

示例

命令示例：

TVS.DELGLOBAL my_index key0 key1

返回示例：

 (integer) 2

类别

说明

语法

TVS.HDELGLOBAL global_index key attribute_key [attribute_key ...]

时间复杂度

O(1)

命令描述

在全量索引的数据记录（key）中，删除指定的attribute_key与其数值。

选项

• global_index：全局索引名称。

• key：该记录的主键标识，支持指定多个。

• attribute_key：待操作的属性Key，支持指定多个。若需删除向量数据，需传入VECTOR关键字（必须大写）。若需删除全量索引数据，需传入TEXT关键字（必须大写）。

返回值

• 执行成功：删除指定数据，并返回删除attribute_key的数量。

• 若指定索引不存在，返回0。

• 其他情况返回相应的异常信息。

示例

命令示例：

TVS.HDELGLOBAL index_name0 keyc VECTOR

返回示例：

 (integer) 1

类别

说明

语法

TVS.SCANGLOBAL global_index cursor [MATCH pattern] [COUNT count] [FILTER filter_string] [VECTOR vector] [MAX_DIST max_distance]

时间复杂度

O(N)，N为数据索引中Key的数量。

命令描述

在全局索引中，扫描符合条件的数据记录（key）。

Tair单次扫描仅会返回单个数据分片的结果。

选项

• global_index：全局索引名称。

• cursor：指定本次扫描的游标，从0开始。

• pattern：模式匹配。

• count：指定本次扫描的数量，默认为10，但无法保证每次迭代都返回精准的元素数量。

• filter_string：过滤条件。

  • 支持+-*/<>!=()&&||等操作符，暂不支持比较字符串之间的大小。如需输入字符串，请输入转义字符（\），例如create_time > 1663637425 && location == \"Hangzhou\"。

  • 操作符两侧必须用空格隔开，例如"creation_time > 1735"。

  • 不支持flag == true类型的比较，即不支持true、false布尔类型，可以替换为flag == \"true\"，当成字符串传递即可。

• vector：查询向量，需要配合max_distance参数使用。

• max_distance：最大距离限制，必须配合vector参数使用。填写这两个参数后，返回结果与vector参数的距离将小于max_distance参数。

返回值

• 执行成功，返回一个数组：

  • 第一个元素：下次查询的游标，若已扫描完成，则返回0。

  • 第二个元素：本次查询的数据记录（key）名称。

• 其他情况返回相应的异常信息。

示例

命令示例：

TVS.SCANGLOBAL index_name0 0

返回示例：

1) "72057594037927936"
2) 1) "key2"
   2) "key1"

类别

说明

语法

TVS.KNNSEARCHGLOBAL global_index topN vector [filter_string] [param_key param_value]

时间复杂度

• HNSW算法：O(log(N))*M

• FLAT算法：O(N)*M

N为数据索引中Key的数量，M为数据索引的数量。

命令描述

在全局索引中，对指定的向量（VECTOR）进行近邻查询，最多可返回topN条。

例如您希望查询topN条结果时，Tair会先从各个数据索引中分别检索出topN条结果，此时最多可能存在topN * 数据索引数条结果，Tair会再对结果进行聚合、排序，最终返回topN条结果。

选项

• global_index：全局索引名称。

• topN：查询返回的数量，取值范围为[1,10000]。

• vector：执行近邻查询的向量值。若您仅希望执行全文检索（索引为混合索引），可在该字段传入""。

• filter_string：过滤条件。

  • 支持+-*/<>!=()&&||等操作符，暂不支持比较字符串之间的大小。如需输入字符串，请输入转义字符（\），例如"create_time > 1663637425 && location == \"Hangzhou\""。

  • 操作符两侧必须用空格隔开，例如"creation_time > 1735"。

  • 不支持flag == true类型的比较，即不支持true、false布尔类型，可以替换为flag == \"true\"，当成字符串传递即可。

• param_key和param_value：查询的运行参数，取值如下。

  • ef_search：查询索引的时候，动态列表的长度，默认为100，取值范围为[1,1000]，该值越大则查询精度越高，同时性能开销越大。该参数为HNSW算法的特定参数。

  • MAX_DIST：最大距离限制，Float类型，若某Key与待查询向量的距离大于该值，则会过滤，不会返回。

  • TEXT：执行查询的文本（混合检索），可传入文本类型或向量类型，若不传入该字段或在该字段传入""，表示不进行全文检索，仅执行向量检索。

  • hybrid_ratio：本次查询时向量检索的权重，默认为TVS.CREATEINDEX设置的hybrid_ratio值，取值范围为[0,1]，Float类型，全量检索的权重为1-hybrid_ratio。

  • 默认情况下，系统使用先执行KNN向量检索、再执行标量检索的后置过滤（PostFilter）策略。

    • vector_filter_count：向量检索过滤的最大数量，默认为10000。

      在PostFilter策略中，当向量检索结果过滤超过vector_filter_count条记录，但仍未到达足够返回的数据量时，系统会终止向量检索遍历。

    • fulltext_filter_count：全文检索过滤的最大数量，默认为10000。

      在PostFilter策略中，当全文检索结果过滤超过fulltext_filter_count条记录，但仍未到达足够返回的数据量时，系统会终止全文检索遍历。

    • 若您希望系统先执行倒排索引的标量检索，再执行KNN向量检索的前置过滤（PreFilter）策略，您可以在查询中增加search_policy scala参数。

      同时提供ivf_filter_count参数，即倒排索引过滤的最大数量，默认为10000。在PreFilter策略中，当倒排索引过滤的结果超过ivf_filter_count条记录时，系统会自动退化为PostFilter策略。

    说明

    在绝大多数情况下，上述默认参数可以在确保准确性的前提下保证系统的延迟。您可以在特定请求中调整上述参数，但上述参数越大，请求延迟也可能越大。

返回值

• 执行成功：按距离近到远的顺序返回近邻的key及与该目标向量的距离。

• 若指定的向量索引不存在，返回(empty array)。

• 其他情况返回相应的异常信息。

示例

TVS.CREATEINDEXGLOBAL my_global_index 2 HNSW L2 inverted_index_productname string
TVS.EXPANDINDEXGLOBAL my_global_index 3
TVS.HSETGLOBAL my_global_index key0 VECTOR [1,2] creation_time 1730 productname "Aliyun"
TVS.HSETGLOBAL my_global_index key1 VECTOR [3,4] creation_time 1740 productname "other"
TVS.HSETGLOBAL my_global_index key2 VECTOR [5,6] creation_time 1750 productname "Aliyun"

命令示例1：

TVS.KNNSEARCHGLOBAL my_global_index 2 [3,3.1] "creation_time > 1735"

返回示例1：

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

命令示例2：

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

返回示例2：

1) "key2"
2) "12.410000801086426"

类别

说明

语法

TVS.KNNSEARCHFIELDGLOBAL global_index topN vector field_count field_name [field_name ...] [filter_string] [param_key param_value]

时间复杂度

• HNSW算法：O(log(N))*M

• FLAT算法：O(N)*M

N为数据索引中Key的数量，M为数据索引的数量。

命令描述

在全局索引中，对指定的向量（VECTOR）进行近邻查询，检索逻辑与TVS.KNNSEARCHGLOBAL相同，额外支持返回标签属性。

选项

• global_index：全局索引名称。

• topN：查询返回的数量，取值范围为[1,10000]。

• vector：执行近邻查询的向量值。若您仅希望执行全文检索（索引为混合索引），可在该字段传入""。

• field_count：返回结果中标签属性的数量，若希望返回所有标签，可以设置field_count为0。

• field_name：标签名称，数量需要与field_count保持一致。

• filter_string：过滤条件，更多信息请参见TVS.KNNSEARCHGLOBAL中的说明。

• param_key和param_value：查询的运行参数，更多信息请参见TVS.KNNSEARCHGLOBAL中的说明。

返回值

• 执行成功：按距离近到远的顺序返回近邻的key及与该目标向量的距离，以及对应的标签属性键值对。

• 若指定的向量索引不存在，返回(empty array)。

• 其他情况返回相应的异常信息。

示例

TVS.CREATEINDEXGLOBAL my_global_index 2 HNSW L2 inverted_index_productname string
TVS.EXPANDINDEXGLOBAL my_global_index 3
TVS.HSETGLOBAL my_global_index key0 VECTOR [1,2] creation_time 1730 productname "Aliyun"
TVS.HSETGLOBAL my_global_index key1 VECTOR [3,4] creation_time 1740 productname "other"
TVS.HSETGLOBAL my_global_index key2 VECTOR [5,6] creation_time 1750 productname "Aliyun"

命令示例：

TVS.KNNSEARCHFIELDGLOBAL my_global_index 2 [3,3.1] 1 VECTOR "creation_time > 1735"

返回示例：

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