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

インデックスの作成

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

説明：Hologres では、ベクターは float4 配列で表されます。ベクターディメンションは、1 次元配列の長さで表され、次の構文では `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` キーが 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,
  	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 万ベクター。

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

2. インスタンスの仕様に基づいて Shard Count を決定します。通常、Shard Count はワーカーの数と同じに設定できます。たとえば、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,
     	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` を分散キーとして設定します。これにより、同じフィルター条件を持つデータが同じシャードに保存されることが保証されます。クエリは単一のシャードにのみアクセスします。

• `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;

したがって、フィルター条件付きのベクター取得では、`CREATE TABLE` 文は通常次のようになります：

-- 注：時間でフィルタリングしない場合は、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);

-- 一時テーブルにデータを挿入し、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 ;