ANN インデックス管理

概要

Apache Doris の Approximate Nearest Neighbor (ANN) インデックスは、高次元データに対する効率的なベクトル類似度検索を可能にします。Doris 4.x以降、汎用的なインデックス操作構文がANNインデックスにも拡張されました。この記事では、ANNインデックス関連操作の具体的なSQL構文を紹介し、詳細なパラメータ説明を提供します。

ANNインデックスはベクトル列（通常は ARRAY<FLOAT> NOT NULL 型）に構築され、サポートされる距離メトリクスにはL2距離と内積が含まれます。

ANNインデックスの作成

ANNインデックスは USING ANN を使用した CREATE INDEX 文で作成できます。主に2つのアプローチがあります：

テーブル作成時にインデックスを定義: データがロードされる際にインデックスが同期的に構築されます。

構文

CREATE TABLE [IF NOT EXISTS] <table_name> (
  <columns_definition>
  INDEX <index_name> (<vector_column) USING ANN PROPERTIES (
    "<key>" = "<value>" [, ...]
  )
)
...

インデックスを別途作成する: 最初にインデックスを定義し、次にBUILD INDEXを使用して既存データ上にインデックスを構築します。

構文

CREATE INDEX [IF NOT EXISTS] <index_name>
             ON <table_name> (<column_name>)
             USING ANN
             PROPERTIES ("<key>" = "<value>" [, ...])
             [COMMENT '<index_comment>']

-- or
ALTER TABLE <table_name> ADD INDEX <index_name>(<column_name>)
             USING ANN
             [PROPERTIES("<key>" = "<value>" [, ...])]
             [COMMENT '<index_comment>']

一般的なプロパティ

index_type: ANNインデックスのタイプ。サポートされる値: "ivf"、"ivf_on_disk"、または "hnsw"。
metric_type: 距離メトリック。サポートされる値: "l2_distance"、"inner_product"。
dim: ベクトル列の次元。
quantizer: quantizerタイプ。サポートされる値: flat、sq4、sq8、pq。指定されない場合のデフォルトは flat。

インデックス固有のプロパティ

IVF / IVF On-Diskインデックスプロパティ

nlist: クラスター数（転置リスト）。デフォルト: 1024。ivfとivf_on_diskの両方で必要。値が大きいほど再現率が向上しますが、構築時間とリソース使用量が増加します。

HNSWインデックスプロパティ

max_degree: ノードあたりの最大接続数。デフォルト: 32。再現率とクエリパフォーマンスに影響します。
ef_construction: インデックス構築時の候補キューのサイズ。デフォルト: 40。値が大きいほどグラフの品質が向上しますが、構築時間が増加します。

量子化固有のプロパティ

quantizerプロパティ用:

sq4: Scalar Quantization (SQ)、ベクトルの各次元値を格納するために、一般的な32ビット浮動小数点数の代わりに4ビット整数を使用します。
sq8: Scalar Quantization (SQ)、ベクトルの各次元値を格納するために、一般的な32ビット浮動小数点数の代わりに8ビット整数を使用します。
pq: Product Quantization (PQ)、2つの追加パラメータpq_mとpq_nbitsがプロパティに必要です。

Product Quantizationプロパティ

pq_m: 使用するサブベクトルの数を指定します（ベクトル次元dimはpq_mで割り切れる必要があります）。
pq_nbits: 各サブベクトルを表現するために使用するビット数。faissでは一般的にpq_nbitsは24以下である必要があります。

例

ANNインデックスを使用したテーブルの作成

CREATE TABLE tbl_ann (
    id int NOT NULL,
    embedding array<float> NOT NULL,
    INDEX ann_index (embedding) USING ANN PROPERTIES(
        "index_type"="hnsw",
        "metric_type"="l2_distance",
        "dim"="128"
    )
) ENGINE=OLAP
DUPLICATE KEY(id)
DISTRIBUTED BY HASH(id) BUCKETS 1
PROPERTIES ("replication_num" = "1");

IVF Index

CREATE INDEX ann_ivf_index ON tbl_ivf (`embedding`) USING ANN PROPERTIES(
    "index_type"="ivf",
    "metric_type"="l2_distance",
    "dim"="128",
    "nlist"="1024"
);

HNSW インデックス

CREATE INDEX ann_hnsw_index ON tbl_hnsw (`embedding`) USING ANN PROPERTIES(
    "index_type"="hnsw",
    "metric_type"="l2_distance",
    "dim"="128",
    "max_degree"="32",
    "ef_construction"="40"
);

SQ を使用した HNSW インデックス

CREATE INDEX ann_hnsw_sq ON tbl_hnsw (`embedding`) USING ANN PROPERTIES(
    "index_type"="hnsw",
    "metric_type"="l2_distance",
    "dim"="128",
    "max_degree"="32",
    "ef_construction"="40",
    "quantizer"="sq8"
);

PQ付きHNSWインデックス

CREATE INDEX ann_hnsw_pq ON tbl_hnsw (`embedding`) USING ANN PROPERTIES(
    "index_type"="hnsw",
    "metric_type"="l2_distance",
    "dim"="128",
    "max_degree"="32",
    "ef_construction"="40",
    "quantizer"="pq",
    "pq_m"="8",
    "pq_nbits"="8"
);

SQを使用したIVFインデックス

CREATE INDEX ann_ivf_sq ON tbl_ivf (`embedding`) USING ANN PROPERTIES(
    "index_type"="ivf",
    "metric_type"="l2_distance",
    "dim"="128",
    "nlist"="1024",
    "quantizer"="sq8"
);

PQを使用したIVFインデックス

CREATE INDEX ann_ivf_pq ON tbl_ivf (`embedding`) USING ANN PROPERTIES(
    "index_type"="ivf",
    "metric_type"="l2_distance",
    "dim"="128",
    "nlist"="1024",
    "quantizer"="pq",
    "pq_m"="8",
    "pq_nbits"="8"
);

ANN インデックスの構築

別途作成されたインデックス（テーブル作成時ではない）については、BUILD INDEX を使用して既存データ上にインデックスを構築します。この操作は非同期です。

構文

BUILD INDEX <index_name> ON <table_name> [PARTITION (<partition_name> [, ...])]

ビルド進行状況の監視

SHOW BUILD INDEXを使用してインデックスビルドジョブのステータスを確認します。

-- view all the progress of BUILD INDEX tasks [for a specific database]
SHOW BUILD INDEX [FROM db_name];

-- view the progress of BUILD INDEX tasks for a specific table
SHOW BUILD INDEX WHERE TableName = "<table_name>";

出力には、JobId、TableName、State（例：FINISHED、RUNNING）、Progressなどの列が含まれます。例えば：

mysql> show build index where TableName = "sift_1M";
+---------------+-----------+---------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------+-------------------------+---------------+----------+------+----------+
| JobId         | TableName | PartitionName | AlterInvertedIndexes                                                                                                                                | CreateTime              | FinishTime              | TransactionId | State    | Msg  | Progress |
+---------------+-----------+---------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------+-------------------------+---------------+----------+------+----------+
| 1764579876673 | sift_1M   | sift_1M       | [ADD INDEX idx_test_ann (`embedding`) USING ANN PROPERTIES("dim" = "128", "index_type" = "ivf", "metric_type" = "l2_distance", "nlist" = "1024")],  | 2025-12-01 17:59:54.277 | 2025-12-01 17:59:56.987 | 82            | FINISHED |      | NULL     |
+---------------+-----------+---------------+-----------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------+-------------------------+---------------+----------+------+----------+
1 row in set (0.00 sec)

インデックス構築のキャンセル

進行中のインデックス構築をキャンセルするには:

CANCEL BUILD INDEX ON <table_name> [(<job_id> [, ...])]

ANN インデックスの削除

DROP INDEX を使用して ANN インデックスを削除します。

構文

DROP INDEX [IF EXISTS] <index_name> ON [<db_name>.]<table_name>

-- or
ALTER TABLE [<db_name>.]<table_name> DROP INDEX <index_name>

ANN インデックスの表示

SHOW INDEX または SHOW CREATE TABLE を使用してテーブルのインデックスに関する情報を表示します。

構文

SHOW INDEX[ES] FROM [<db_name>.]<table_name> [FROM <db_name>]

-- or
SHOW CREATE TABLE [<db_name>.]<table_name>

出力例

mysql> SHOW INDEX FROM sift_1M;
+---------+------------+--------------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+----------------------------------------------------------------------------------------+
| Table   | Non_unique | Key_name     | Seq_in_index | Column_name | Collation | Cardinality | Sub_part | Packed | Null | Index_type | Comment | Properties                                                                             |
+---------+------------+--------------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+----------------------------------------------------------------------------------------+
| sift_1M |            | idx_test_ann |              | embedding   |           |             |          |        |      | ANN        |         | ("dim" = "128", "index_type" = "ivf", "metric_type" = "l2_distance", "nlist" = "1024") |
+---------+------------+--------------+--------------+-------------+-----------+-------------+----------+--------+------+------------+---------+----------------------------------------------------------------------------------------+
1 row in set (0.01 sec)

出力には、Table、Key_name、Index_type（ANNインデックスの場合はANNを表示）、Properties（インデックス設定を含む）などの列が含まれます。

概要​

ANNインデックスの作成​

構文​

構文​

一般的なプロパティ​

インデックス固有のプロパティ​

IVF / IVF On-Diskインデックスプロパティ​

HNSWインデックスプロパティ​

量子化固有のプロパティ​

Product Quantizationプロパティ​

例​

ANNインデックスを使用したテーブルの作成​

IVF Index​

HNSW インデックス​

SQ を使用した HNSW インデックス​

PQ付きHNSWインデックス​

SQを使用したIVFインデックス​

PQを使用したIVFインデックス​

ANN インデックスの構築​

構文​

ビルド進行状況の監視​

インデックス構築のキャンセル​

ANN インデックスの削除​

構文​

ANN インデックスの表示​

構文​

出力例​

概要