Hologres:HGraph インデックスユーザーガイド (推奨)

インデックスの作成

構文：テーブル作成時にベクターインデックスを作成します。

説明：Hologres では、ベクターは `float4` 配列として表現されます。ベクターの次元は、このドキュメントで `array_length` と呼ばれる 1 次元配列の長さに対応します。

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` キーは 1 つだけ許可されます。

• `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` を使用します。単一シャードの場合、データ量を 500 万行未満に保ちます。

• 遅延の影響を受けにくいワークロードまたは大容量データ：メモリとディスクのハイブリッドインデックスを使用します。インデックスの量子化には、`rabitq` を使用します。単一シャードの場合、データ量を 3,000 万から 5,000 万行未満に保ちます。

• 注：複数の列にベクターインデックスを設定するには、シャードあたりの推奨データ量を比例して減らしてください。ベクターの次元サイズもこの推奨に影響します。

例：

-- ハイブリッドインデックスの完全な例
CREATE TABLE feature_tb (
    id bigint not null,
    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 not null,
    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。

適切なシャード数の設定

シャード数が多いとマニフェストファイルの数が増え、近似ベクタークエリのスループットが低下します。したがって、アプリケーションに適したシャード数を選択してください。通常、以下のガイドラインに従います。

1. ベクターデータ量に基づいて適切な計算リソース仕様を選択します。例として、768 次元のベクターについては、以下のガイドラインに従ってください。他の次元に固有の推奨事項については、「ベクターコンピューティングに推奨されるインスタンスタイプ」をご参照ください。

   1. 完全なインメモリインデックス：ワーカーあたり 500 万ベクター。

   2. メモリとディスクのハイブリッドインデックス：ワーカーあたり 1 億ベクター。

2. 計算リソースの仕様に基づいてシャード数を決定します。通常、シャード数はワーカーの数と同じに設定します。例えば、64 CU のインスタンスの場合、`shard_count` を 4 に設定します。

   SQL 設定の例：

   -- ベクターテーブルを作成し、Shard Count = 4 のテーブルグループに配置します
   CALL HG_CREATE_TABLE_GROUP ('test_tg_shard_4', 4);
   
   CREATE TABLE feature_tb (
       id bigint not null,
       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` を分散キーとして設定します。これにより、同一のフィルター済みデータが同じシャードに配置されるため、単一のクエリは 1 つのシャードにしかアクセスしません。

• `UUID` をクラスタリングキーとして設定します。データはクラスタリングキーに従ってファイル内でソートされます。

クエリシナリオ 2：フィルター条件としての時間フィールド

以下はクエリの例です。ベクターデータを時間でフィルターすることがよくあります。`time_field` をセグメントキーとして設定すると、関連するデータファイルを迅速に見つけることができます。

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 ;

-- 対応する列に対して JSON 形式データの列指向ストレージを有効化
ALTER TABLE <table_new> ALTER COLUMN <column_name> SET (enable_columnar_type = ON);
-- 対応する列にフルテキストインデックスを作成
CREATE INDEX <idx_name> ON <table_new> USING FULLTEXT (column_name);

-- 一時テーブルにデータを挿入し、サーバーレスリソースを使用して実行し、インデックス構築を同期的に完了
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 ;