Tair (Redis® OSS-Compatible)：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）演算法，適用於全文檢索索引

        • 後續 TVS.HSET 寫入時，attribute_key 為 TEXT 關鍵字(必須大寫)，對應的 attribute_value 會自動建全文索引。

        • 您可傳入原始文本，由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會自動、均衡地將資料索引建立在不同的分區中，並且自動命名。資料索引的中繼資料資訊與全域索引相同，並且與全域索引存在關聯關係，同時，資料索引也隔離儲存區 (Isolated Storage)在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：過濾條件。

  • 支援+-*/<>!=()&&||等操作符，暫不支援比較字串之間的大小。如需輸入字串，請輸入逸出字元（\），例如"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"

命令樣本：

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