類別

說明

語法

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