HGraph は、近似最近傍 (ANN) 検索用の Hologres のベクトルインデックスアルゴリズムです。これを使用して、既存の Hologres テーブルを基盤に、類似性検索、画像リトリーバル、シーン認識のアプリケーションを構築できます。
近似検索関数は、ベクターインデックスを使用してクエリを高速化しますが、厳密な検索とは異なる結果が返される場合があります。再現率は 100% に達しないため、 LIMIT 1000 を指定したクエリでも、1,000 件未満の結果しか返されないことがあります。
注意事項
-
HGraph は Hologres V4.0 以降でサポートされています。
-
ベクターインデックスは、列指向テーブルとハイブリッド行列表テーブルでのみサポートされています。行指向テーブルではベクターインデックスはサポートされていません。
-
ベクターインデックス付きのテーブルを削除または再構築する予定がある場合 (例:
INSERT OVERWRITEを使用する場合)、ごみ箱機能を有効にしないでください。ごみ箱内のテーブルは引き続きメモリを消費します。 -
ベクターインデックスを作成した後、データインポート後のコンパクション中にインデックスマニフェストが構築されます。
-
MemTable 内のデータにはベクターインデックスがありません。MemTable データに対する検索リクエストは、ブルートフォース計算を使用します。
-
大規模なデータインポートの場合は、サーバーレスコンピューティングリソースを使用してください。サーバーレスリソースは、インポート中にコンパクションとインデックス構築を同時に実行します。詳細については、サーバーレスコンピューティングを使用した読み取りおよび書き込みタスクの実行 および サーバーレスリソースへのコンパクションのオフロード をご参照ください。
-
サーバーレスリソースを使用していない場合は、バッチデータインポート後またはインデックス変更後に手動でコンパクションをトリガーしてください。
SELECT hologres.hg_full_compact_table('<SCHEMA_NAME>.<TABLE_NAME>', 'max_file_size_mb=4096'); -
サーバーレスコンピューティングリソースは、ベクター検索クエリをサポートしています。
ベクターインデックスの管理
インデックスの作成
テーブルを作成するときにベクターインデックスを作成します。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 つだけ使用できます。そのキーの値は、次のフィールドを含む JSON オブジェクトです:
|
キー |
説明 |
|
|
必須。インデックスアルゴリズムです。サポートされているのは |
|
|
必須。距離計算方法です。サポートされている値: |
|
|
インデックス構築パラメータを JSON 形式で記述した文字列です。詳細は、次の表を参照してください。 |
距離計算方法と必須のソート順
|
メソッド |
ソート順 |
例 |
|
|
昇順のみ |
|
|
|
降順のみ |
|
|
|
降順のみ |
|
ビルダーパラメータ
|
パラメータ |
デフォルト |
説明 |
|
|
— |
必須。低精度インデックスの量子化方法です。サポートされている値: |
|
|
64 |
インデックス構築中に各頂点が接続する近傍の最大数です。値を大きくすると検索精度が向上しますが、グラフの構築時間とストレージ使用量が増加します。96 を超えないように設定してください。 |
|
|
400 |
インデックス構築中の候補リストのサイズです。値を大きくするとインデックスの精度が向上しますが、構築時間が増加します。600 を超えないように設定してください。 |
|
|
|
再ランキングのために高精度インデックスレイヤーを有効にするかどうかを指定します。 |
|
|
|
高精度インデックスの量子化方法です。 |
|
|
|
ハイブリッドインデックスのストレージ媒体です。 |
|
|
|
メモリ内のグラフインデックスの圧縮を制御します。サポートされている値: |
|
|
— |
ベクターテーブルをクエリせずに値を取得できるよう、列の値をインデックスにアタッチします。サポートされている列の型: |
|
|
4 |
書き込み中にインデックスを構築するためのスレッド数です。ほとんどのシナリオでは変更しないでください。この値を増やすと、CPU 使用率が高くなる可能性があります。このパラメータを変更しても、インデックスの再構築はトリガーされません。 |
インデックスの変更
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.hg_table_properties システムテーブルにクエリを実行します。
SELECT
*
FROM
hologres.hg_table_properties
WHERE
table_name = '<TABLE_NAME>'
AND property_key = 'vectors';
ベクトル検索クエリの実行
近似検索と完全一致検索
Hologres は、近似検索と完全一致検索の両方のベクトル検索をサポートしています。近似検索関数のみが、ベクトルインデックスを使用してクエリを高速化できます。クエリで使用される近似関数は、インデックスの distance_method と一致し、必要なソート順序を満たす必要があります。そうでない場合、インデックスは使用されません。
ベクトル距離関数
|
関数 |
検索タイプ |
入力 |
戻り値 |
備考 |
|
|
近似 |
|
|
ベクトルインデックスを使用します。 |
|
|
近似 |
|
|
ベクトルインデックスを使用します。 |
|
|
近似 |
|
|
ベクトルインデックスを使用します。 |
|
|
完全一致 |
|
|
ベクトルインデックスを使用しません。 ベクトルインデックスを使用しない ベクトルインデックスを使用しません |
|
|
完全一致 |
|
|
|
|
|
完全一致 |
|
|
距離関数は、すべてのパラメーターが定数である入力をサポートしていません。
インデックス使用の確認
クエリに対して EXPLAIN または EXPLAIN ANALYZE を実行して、実行計画がベクトルインデックスを使用しているかどうかを確認します。プランに Vector Filter が含まれている場合、インデックスが使用されています。
クエリ例:
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
エンドツーエンドの例
次の例では、ベクトルインデックス付きのテーブルを作成し、サーバーレスコンピューティングを使用してデータをインポートした後、近似検索と正確な検索の両方のクエリを実行します。
ステップ 1: テーブルの作成
-- シャード数が 4 のテーブルグループを作成します
CALL HG_CREATE_TABLE_GROUP ('test_tg_shard_4', 4);
-- HGraphベクトルインデックス付きのテーブルを作成します
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",
"use_reorder": true,
"extra_columns": "id",
"max_total_size_to_merge_mb": 4096
}
}
}'
);
ステップ 2: データのインポート
-- 大規模なデータインポートにはサーバーレスコンピューティングを使用します。
-- これにより、インポート中にコンパクションとインデックス構築が並行して実行されます。
SET hg_computing_resource = 'serverless';
SET hg_serverless_computing_run_compaction_before_commit_bulk_load = on;
INSERT INTO feature_tb
SELECT i, array[random(), random(), random(), random()]::float4[]
FROM generate_series(1, 100000) i;
-- インポート後にリセットし、後続のクエリで不要にサーバーレスリソースが使用されないようにします。
RESET hg_computing_resource;
ステップ 3: 近似検索の実行
-- コサイン距離の降順で上位 40 件の結果を返します
SELECT
id,
approx_cosine_distance(feature, '{0.1,0.2,0.3,0.4}') AS distance
FROM
feature_tb
ORDER BY
distance DESC
LIMIT 40;
このテーブルでは"extra_columns": "id"を使用しているため、クエリはベーステーブルの列を読み取らずに、ベクトルインデックスからidの値を直接取得します。EXPLAIN ANALYZEの出力にあるvector_index_extra_columns_usedフィールドを確認すると、extra_columnsを介して値が提供されたマニフェストファイルの数を確認できます。
ステップ 4: 正確な検索の実行
-- 正確な検索ではベクトルインデックスは使用されません。
-- 距離関数は、インデックスの distance_method と一致する必要はありません。
SELECT
id,
cosine_distance(feature, '{0.1,0.2,0.3,0.4}') AS distance
FROM
feature_tb
ORDER BY
distance DESC
LIMIT 40;
パフォーマンスチューニング
ベクトルインデックスを使用する場合
データ量が少ない場合 (例:数万件のレコード)、またはインスタンスに十分なコンピューティングリソースがある場合は、ベクトルインデックスをスキップし、ブルートフォース (厳密な) 計算を使用してください。厳密な検索がレイテンシ、スループット、またはスケーラビリティの要件を満たせない場合にのみ、ベクトルインデックスを追加してください。
ベクトルインデックスは本質的に近似的である点にご留意ください。
-
再現率は 100% に達することはありません。
-
LIMIT 1000を指定したクエリでも、1,000 件未満の結果が返される場合があります。
量子化方法の選択
base_quantization_type は、メモリ使用量、クエリ速度、再現精度のトレードオフを制御します。サポートされる値は sq8、sq8_uniform、fp16、fp32、rabitq です。高精度の量子化タイプはより多くのメモリを使用しますが、再現精度が高くなります。低精度のタイプはメモリ使用量が少なく、クエリ速度が向上しますが、精度が若干犠牲になります。
フルインメモリインデックスを使用するレイテンシが重視されるワークロードの場合は、sq8_uniform または rabitq を使用してください。ハイブリッドメモリディスクインデックスを使用する大規模データセットの場合は、rabitq を使用してください。rabitq を使用する場合、use_reorder: true を precise_quantization_type: fp32 と組み合わせて有効にすると、再現精度を向上させることができます。
ワークロードに応じたインデックス構成の選択
単一テーブル、単一列、768 次元のベクトルインデックスの場合、以下の構成を出発点として使用してください。
|
ワークロード |
インデックスタイプ |
量子化 |
シャードあたりの最大行数 |
|
レイテンシが重視される |
フルインメモリ |
|
500 万 |
|
大量データまたはレイテンシが重視されない |
ハイブリッドメモリディスク |
|
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": "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
}
}
}'
);
ハイブリッドメモリディスクインデックスの例
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
}
}
}'
);
再現率のチューニング
以下のインデックスパラメータは、VectorDBBench データセットで 95% を超えるデフォルトの再現率を達成します。
-
base_quantization_type:rabitqまたはsq8_uniform -
precise_quantization_type:fp32 -
max_degree: 64 -
ef_construction: 400
クエリ時には、Grand Unified Configuration (GUC) パラメータ hg_vector_ef_search が検索時の候補リストサイズを制御します。デフォルト値は 80 で、精度とリソース使用量のバランスを取ります。
再現率を 99% 以上に引き上げるには、インデックスパラメータを変更せずに hg_vector_ef_search を増やしてください。
SET hg_vector_ef_search = 400;
99.5%〜99.7% の再現率を達成するには、インデックス構築パラメータとクエリパラメータの両方を調整してください。これにより、クエリのレイテンシ、クエリのリソース使用量、インデックス構築時間、およびインデックス構築のリソース使用量が増加します。
-
max_degree: 96 -
ef_construction: 500 または 600 -
hg_vector_ef_search: 500 または 600
適切なシャード数の設定
シャード数が多いほど、マニフェストファイルが多くなり、近似クエリのスループットが低下します。以下のガイドラインに従ってください。
-
データに応じてコンピューティングリソースのサイズを設定してください。 768 次元のベクトルの場合、他のベクトル次元については、ベクトル検索インスタンスの仕様をご参照ください。
-
フルインメモリインデックス:ワーカーあたり最大 500 万ベクトル。
-
ハイブリッドメモリディスクインデックス:ワーカーあたり最大 5,000 万ベクトル。
-
-
シャード数をワーカー数と同じに設定してください。 64 CU インスタンスの場合、
shard_countを 4 に設定します。
-- シャード数 = 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
}
}
}'
);
ベクトルとスカラーのハイブリッドクエリ
ベクトル検索とスカラーフィルター条件を組み合わせたクエリの典型的なパターンは次のとおりです。
文字列列でフィルタリングする (例:組織またはグループ ID)
一般的なユースケースは、特定のグループ内のベクトルを取得することです。たとえば、特定のクラスの生徒の顔認識データなどです。
SELECT <distance_function>(feature, '{1,2,3,4}') AS d
FROM feature_tb
WHERE uuid = 'x'
ORDER BY d
LIMIT 10;
最適化するには、以下の方法があります。
-
uuidをディストリビューションキーとして設定します。これにより、同じフィルター値のすべてのデータが同じシャードに配置されるため、クエリは 1 つのシャードにのみアクセスします。 -
uuidをクラスタリングキーとして設定します。これにより、ファイル内のデータがuuidでソートされ、スキャン範囲が減少します。
時間フィールドでフィルタリングする
SELECT <distance_function>(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 をセグメントキーとして設定します。これにより、Hologres は時間範囲で関連するデータファイルを迅速に特定できます。
ハイブリッドクエリに推奨されるテーブル構造
-- 時間でフィルタリングしない場合は、time_field とその segment_key を削除してください。
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
}
}
}'
);
サーバーレスリソースを使用したインデックスの再構築
一部のプロパティ変更は、コンパクションとインデックスの再構築をトリガーし、CPU 使用率が急増する可能性があります。これらの変更は次のように処理してください。
bitmap_columns、dictionary_encoding_columns、またはベクトルインデックスの変更
ALTER TABLE ... SET の代わりに、サーバーレスコンピューティングリソースを使用して REBUILD 構文を使用してください。詳細については、「REBUILD」をご参照ください。
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
}
}
}'
);
JSON データまたはフルテキストインデックス列のカラムナストレージの変更
これらの変更については、REBUILD 構文はまだサポートされていません。代わりに一時テーブルを使用してください。
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;
-- 一時テーブルに新しい列プロパティを適用する
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;
その他のプロパティ変更 (例:distribution_key、clustering_key、segment_key、ストレージ形式)
サーバーレスコンピューティングリソースを使用して REBUILD 構文を使用してください。