Hologres：HGraph索引使用指南（推薦）

建立索引

文法：建表時建立向量索引。

說明：向量在Hologres中通過float4數組表示，向量維度通過一維數組的長度表示，即下文的array_length。

CREATE TABLE <TABLE_NAME> (
    <VECTOR_COLUMN_NAME> float4[] CHECK (array_ndims(<VECTOR_COLUMN_NAME>) = 1 AND array_length(<VECTOR_COLUMN_NAME>, 1) = <DIM>)
)
WITH (
    vectors = '{
    "<VECTOR_COLUMN_NAME>": {
        "algorithm": "<ALGORITHM>",
        "distance_method": "<DISTANCE_METHOD>",
        "builder_params": {
            "<BUILDER_PARAMETERS_NAME>": <VALUE>
            [, ...]
        }
    }
    [ , "<VECTOR_COLUMN_NAME_2>": { ... } ]
  }'
);

參數說明：

向量索引參數vectors的取值有如下要求：

• 僅支援JSON格式字串，頂層僅支援一個vector_column_name鍵，用於指定需構建向量索引向量列名。

• vector_column_name鍵的值為JSON對象，用於配置向量索引參數，支援如下鍵。

向量索引構建參數builder_params支援如下參數：

修改索引

文法：

ALTER TABLE <TABLE_NAME>
SET (
    vectors = '{
    "<VECTOR_COLUMN_NAME>": {
        "algorithm": "<ALGORITHM>",
        "distance_method": "<DISTANCE_METHOD>",
        "builder_params": {
            "<BUILDER_PARAMETERS_NAME>": <VALUE>
            [, ...]
        }
    }
  }'
);

刪除索引

-- 刪除表中全部列的向量索引
ALTER TABLE <TABLE_NAME>
SET (
    vectors = '{}'
);

-- 如果表中有col1、col2兩列均構建向量索引，需刪除col2列的索引，則通過ALTER TABLE語句僅保留col1列的索引即可
ALTER TABLE <TABLE_NAME>
SET (
    vectors = '{
    "col1": { ... }
  }'
);

查看索引

Hologres提供hologres.hg_table_properties系統資料表，可查看已建立的向量索引。

SELECT
    *
FROM
    hologres.hg_table_properties
WHERE 
    table_name = '<TABLE_NAME>'
    AND property_key = 'vectors';

向量距離計算函數

Hologres的向量檢索支援近似檢索和精確檢索，僅近似檢索函數可使用已構建的向量索引進行加速查詢（函數需要和向量索引的distance_method距離計算方法對應），精確檢索函數無法使用向量索引。

說明：向量距離計算函數不支援全部常量入參。

向量索引使用驗證

可通過執行計畫查看SQL是否使用了向量索引，若其中出現“Vector Filter”，說明已成功使用，參見EXPLAIN和EXPLAIN ANALYZE。

• 樣本SQL：

  SELECT
      id,
      approx_euclidean_distance (feature, '{0.1,0.2,0.3,0.4}') AS distance
  FROM
      feature_tb
  ORDER BY
      distance
  LIMIT 40;

• 執行計畫：

  Limit  (cost=0.00..182.75 rows=40 width=12)
    ->  Sort  (cost=0.00..182.75 rows=160 width=12)
          Sort Key: (VectorDistanceRef)
          ->  Gather  (cost=0.00..181.95 rows=160 width=12)
                ->  Limit  (cost=0.00..181.94 rows=160 width=12)
                      ->  Sort  (cost=0.00..181.94 rows=40000 width=12)
                            Sort Key: (VectorDistanceRef)
                            ->  Local Gather  (cost=0.00..91.53 rows=40000 width=12)
                                  ->  Limit  (cost=0.00..91.53 rows=40000 width=12)
                                        ->  Sort  (cost=0.00..91.53 rows=40000 width=12)
                                              Sort Key: (VectorDistanceRef)
                                              ->  Project  (cost=0.00..1.12 rows=40000 width=12)
                                                    ->  Index Scan using Clustering_index on feature_tb  (cost=0.00..1.00 rows=40000 width=8)
                                                          Vector Filter: VectorCond => KNN: '40'::bigint distance_method: approx_euclidean_distance search_params: {NULL} args: {feature'{0.100000001,0.200000003,0.300000012,0.400000006}'::real[]}
  Query Queue: init_warehouse.default_queue
  Optimizer: HQO version 4.0.0

合理使用向量索引

當資料量較小（比如幾萬條），或執行個體計算資源較多情況下，建議不設定向量索引，直接暴力計算。當直接計算無法滿足延遲、吞吐等需求時，再使用向量索引，原因如下：

• 向量索引是有損索引，結果準確率（召回率）無法達到100%。

• 向量索引可能出現召回條數不足的情況，如LIMIT 1000卻只返回500條。

當選擇使用向量索引時，配置建議如下（以單表、單列、768維度向量為例）：

• 延時敏感：建議選擇純記憶體索引，索引量化方法建議使用sq8_uniform或rabitq，單Shard建議資料量不超過500萬行。

• 延時不敏感或巨量資料量：建議選擇記憶體+磁碟混合索引，索引量化方法建議使用rabitq，單Shard建議資料量不超過3000~5000萬行。

• 說明：當需對多列設定向量索引時，單Shard建議資料量需要等比縮小。同時，向量維度大小也會影響該建議值。

使用樣本：

-- 混合索引完整例子
CREATE TABLE feature_tb (
    id bigint,
  	feature float4[] CHECK(array_ndims(feature) = 1 AND array_length(feature, 1) = 4)
)
WITH (
    table_group = 'test_tg_shard_4',
    vectors = '{
    "feature": {
        "algorithm": "HGraph",
        "distance_method": "Cosine",
        "builder_params": {
            "base_quantization_type": "rabitq",
            "graph_storage_type": "compressed",
            "max_degree": 64,
            "ef_construction": 400,
            "precise_quantization_type": "fp32",
            "precise_io_type": "reader_io",
            "use_reorder": true,
            "max_total_size_to_merge_mb" : 4096
        }
    }
    }'
);


-- 全記憶體索引完整例子
CREATE TABLE feature_tb (
    id bigint,
  	feature float4[] CHECK(array_ndims(feature) = 1 AND array_length(feature, 1) = 4)
)
WITH (
    table_group = 'test_tg_shard_4',
    vectors = '{
    "feature": {
        "algorithm": "HGraph",
        "distance_method": "Cosine",
        "builder_params": {
            "base_quantization_type": "sq8_uniform",
            "graph_storage_type": "compressed",
            "max_degree": 64,
            "ef_construction": 400,
            "precise_quantization_type": "fp32",
            "use_reorder": true,
            "max_total_size_to_merge_mb" : 4096
        }
    }
    }'
);

提升召回率

本節以 VectorDBBench 資料集為例，說明如何提升召回率。

一般情況下影響召回率的因素有多個，如下索引參數配置下，系統的預設召回率一般可以達到95%以上：

• 索引參數：

  • base_quantization_type為rabitq、sq8_uniform

  • precise_quantization_type為fp32

  • max_degree為64

  • ef_construction為400

• 查詢參數（GUC）：

  • hg_vector_ef_search ：建議使用預設值 80。該參數控制檢索期間候選列表的大小，用以平衡精度和速度。值越大，準確性越高，但資源開銷也會越大。

如需進一步提升召回率至99%以上，可以在保持其餘參數不變的情況下，執行SET hg_vector_ef_search = 400;。但召回率的提升會使得查詢延遲和計算資源使用率相應增加。

如需進一步提升召回率至 99.5% ~ 99.7%，可進一步調整 max_degree、ef_construction、hg_vector_ef_search 三個值，查詢延遲、查詢資源消耗、索引構建時間、索引構建資源消耗均會相應增加，如：

• max_degree = 96。

• ef_construction = 500 或 600。

• hg_vector_ef_search = 500 或 600。

設定合適的Shard Count

Shard Count越多，實際構建索引的檔案數量就越多，導致向量近似查詢的輸送量下降。因此，建議在實際應用中合理設定Shard Count。通常情況下，可以按照以下思路進行設定：

1. 根據向量資料量，選擇合適的計算資源規格。以768維度向量為例，可以按照以下思路進行選擇。其他維度具體選擇請參見向量計算執行個體規格推薦。

   1. 全記憶體索引：500萬向量/Worker。

   2. 記憶體+磁碟混合索引：1億向量/Worker。

2. 根據計算資源規格來確定Shard Count。通常情況下，Shard Count可以設定為與Worker數量相等，例如，對於64CU的執行個體，可以將shard_count設定為4。

   SQL設定樣本如下：

   -- 建立向量表，並且放於Shard Count = 4 的Table Group中
   CALL HG_CREATE_TABLE_GROUP ('test_tg_shard_4', 4);
   
   CREATE TABLE feature_tb (
       id bigint,
     	feature float4[] CHECK(array_ndims(feature) = 1 AND array_length(feature, 1) = 4)
   )
   WITH (
       table_group = 'test_tg_shard_4',
       vectors = '{
       "feature": {
           "algorithm": "HGraph",
           "distance_method": "Cosine",
           "builder_params": {
               "base_quantization_type": "sq8_uniform",
               "graph_storage_type": "compressed",
               "max_degree": 64,
               "ef_construction": 400,
               "precise_quantization_type": "fp32",
               "use_reorder": true,
               "max_total_size_to_merge_mb" : 4096
           }
       }
       }'
   );

向量+標量混合查詢情境

對於帶過濾條件的向量檢索，情況細分為幾種常見的過濾情境，分別如下：

查詢情境1：某個字串列為過濾條件

樣本查詢如下，常見的情境為在某個組織內尋找對應的向量資料，例如尋找班級內的人臉資料。

SELECT(feature, '{1,2,3,4}') AS d FROM feature_tb WHERE uuid = 'x' ORDER BY d LIMIT 10;

建議做以下最佳化：

• 將UUID設定為Distribution Key，這樣相同的過濾資料會儲存在同一個Shard，查詢時一次查詢只會落到一個Shard上。

• 將UUID設定為表的Clustering Key，資料將會在檔案內根據Clustering Key排序。

查詢情境2：某個時間欄位為過濾條件

樣本查詢如下，一般是根據時間欄位過濾出對應的向量資料。建議將時間欄位time_field設定為表的Segment Key，可以快速的定位到資料所在的檔案。

SELECT xx_distance(feature, '{1,2,3,4}') AS d FROM feature_tb WHERE time_field BETWEEN '2020-08-30 00:00:00' AND '2020-08-30 12:00:00' ORDER BY d LIMIT 10;

因此對於帶任何過濾條件的向量檢索而言，其建表語句通常如下：

-- 說明：如果沒有按照時間過濾的話，則time_field相關的索引可以刪除。
CREATE TABLE feature_tb (
    time_field timestamptz NOT NULL,
    uuid text NOT NULL,
    feature float4[] CHECK(array_ndims(feature) = 1 AND array_length(feature, 1) = 4)
)
WITH (
    distribution_key = 'uuid',
    segment_key = 'time_field',
    clustering_key = 'uuid',
    vectors = '{
    "feature": {
        "algorithm": "HGraph",
        "distance_method": "Cosine",
        "builder_params": {
            "base_quantization_type": "sq8_uniform",
            "graph_storage_type": "compressed",
            "max_degree": 64,
            "ef_construction": 400,
            "precise_quantization_type": "fp32",
            "use_reorder": true,
            "max_total_size_to_merge_mb" : 4096
        }
    }
    }'
);

ASYNC REBUILD TABLE <table_name> 
WITH (
    rebuild_guc_hg_computing_resource = 'serverless'
)
SET (
    bitmap_columns = '<col1>,<col2>',
    dictionary_encoding_columns = '<col1>:on,<col2>:off',
    vectors = '{
    "<col_vector>": {
        "algorithm": "HGraph",
        "distance_method": "Cosine",
        "builder_params": {
            "base_quantization_type": "rabitq",
            "graph_storage_type": "compressed",
            "max_degree": 64,
            "ef_construction": 400,
            "precise_quantization_type": "fp32",
            "use_reorder": true,
            "max_total_size_to_merge_mb" : 4096
        }
    }
    }'
);

BEGIN ;
-- 清理潛在的暫存資料表
DROP TABLE IF EXISTS <table_new>;
-- 建立暫存資料表
SET hg_experimental_enable_create_table_like_properties=on;
CALL HG_CREATE_TABLE_LIKE ('<table_new>', 'select * from <table>');
COMMIT ;

-- 對應列開啟列式JSONB
ALTER TABLE <table_new> ALTER COLUMN <column_name> SET (enable_columnar_type = ON);
-- 對應列建立全文索引
CREATE INDEX <idx_name> ON <table_new> USING FULLTEXT (column_name);

-- 向暫存資料表插入資料，使用Serverless資源執行，並同步完成索引構建
SET hg_computing_resource = 'serverless';
INSERT INTO <table_new> SELECT * FROM <table>;
ANALYZE <table_new>;

BEGIN ;
-- 刪除舊錶
DROP TABLE IF EXISTS  <table>;
-- 暫存資料表改名
ALTER TABLE <table_new> RENAME TO <table>;
COMMIT ;