pg_vectorsearch：高性能な近似最近傍検索（ANN）エクステンション

PostgreSQL エキステンション

pg_vectorsearch

⚠️ 状態と注意事項

• α版（アルファ版）：テスト用途のみで、本番環境での利用は推奨されません。
• アップグレード制限：プリリリース間でのアップグレードが不可能な場合があるため、拡張機能とインデックスの削除および再構築を計画してください。
• 既知の不具合：詳細は Changelog をご参照ください。

PRISM インデックスの特徴

PRISM（Partitioned Routing Index for Similarity Matching）は、pgvector の

IVFFlat

主要機能

• アルゴリズム: IVF スタイルの実装で、階層的ルーティングを採用しています。
• クアンタ化: 二段階検索の誤差 bound を持つ RaBitQ クアンタ化を使用します。
• パフォーマンス: SIMD 最適化された距離計算（AVX2, AVX512, NEON）をサポート。
• 動的更新対応: インサート、アップデート、デリートをサポートし、

  prism_rebalance

  を用いたポストインゴストの再分割が可能です。
• pgvector 互換性: 既存のベクトルおよび

  halfvec

  カラムをそのままインデックス化できます（詳細は後述）。

パフォーマンス比較

PGVector の

IVFFlat

• 検索およびインデックス構築の双方で大幅な高速化。
• 1 億ベクトル規模でも同等の再現率（recall）を達成可能。
• グラフベースの HNSW よりも高速でありながら、メモリ使用量は HNSW の四分の一以下。

アーキテクチャ概要

PRISM は階層的セントロイド木を用いてベクトルをクラスター分割し、PostgreSQL バッファキャッシュを活用してメモリ上に温存します。

1. クアンタ化: RaBitQ でエンコードされ、誤差 bound が含まれるため「近傍ではないはずのベクトル」を事前に除外可能です。
2. ページレイアウト: SIMD 距離計算に最適化されたポストインゴスト構造。

クエリフロー

1. セントロイド木の巡回で最も近いクラスター特定（バッファキャッシュ利用）
2. ポストインゴストのスキャンと候補選択（バッファキャッシュ・非同期 I/O 利用）
3. RaBitQ 二段階フィルタリング：推定 → 誤差 bound 判定 → リランク
4. ヒープからの全精度再ランク付け
5. $k$ 個の最近傍 neighbor を返却

詳細なアーキテクチャは

docs/architecture.md

使い方

拡張機能のインストール後、ベクトル格納場所に応じて以下の 2 パスから選択します。両方とも同じ演算子クラス（

<->

<#>

<=>

パス 1：ネイティブ型

新しいプロジェクト向け、または pgvector を使用しない場合です。独自の

vec32

vec16

# リリースビルド
meson setup builddir --buildtype=release
meson install -C builddir

実装例（ネイティブ型）

-- 拡張機能をインストール
CREATE EXTENSION pg_vectorsearch;

-- テーブル定義
-- PLAIN: 内联格納。EXTERNAL（デフォルト）は値が 2kB を超えるとトーストされ、追加のフェッチが発生します。
CREATE TABLE items (
    id serial PRIMARY KEY,
    embedding vec32(3) STORAGE PLAIN
);

-- データロード
INSERT INTO items (embedding)
SELECT ARRAY[i::real, (i % 7)::real, (i % 5)::real]::vec32
FROM generate_series(1, 1000) i;

-- インデックス構築
-- vec32_l2_ops: L2 距離演算子クラス
CREATE INDEX ON items USING prism (embedding vec32_l2_ops);

-- パラメータ設定（再現率向上のため nprobe を上げる、速度向上のため下げる）
SET prism.nprobe = 40;

-- クエリ実行
SELECT * FROM items
ORDER BY embedding <-> '[3,1,2]'
LIMIT 5;

• vec16: ベクトルデータを半分サイズ化したい場合に使用。演算子クラスは

  vec16_*

  に変更してください。

パス 2：既存の pgvector テーブル

vector

halfvec

実装例（pgvector テーブル互換）

-- pgvector 拡張機能（既存の場合、既にインストール済み）
CREATE EXTENSION vector;

-- 既存の HNSW インデックスがあるテーブル
CREATE TABLE documents (
    id        bigserial PRIMARY KEY,
    body      text,
    embedding vector(384)
);
CREATE INDEX documents_embedding_hnsw
    ON documents USING hnsw (embedding vector_l2_ops);

-- pg_vectorsearch を追加インストール
CREATE EXTENSION pg_vectorsearch;

-- 既存のカラムに対し、PRISM インデックスを構築
-- カラム自体は書き換えられません。
CREATE INDEX documents_embedding_prism
    ON documents USING prism (embedding vec32_l2_ops);

-- クエリは変更不要。通常 PRISM は高速なため、プランナーが自動的に優先します。
EXPLAIN (COSTS OFF)
SELECT id, body
FROM documents
ORDER BY embedding <-> (SELECT embedding FROM documents WHERE id = 42)
LIMIT 10;

-- 確認後に不要となった HNSW インデックスを削除
DROP INDEX documents_embedding_hnsw;

演算子クラス

距離尺度とカラムタイプ（

vec32

vector

vec16

halfvec

vec32

vector

vec16

halfvec

<->

vec32_l2_ops

vec16_l2_ops

<#>

vec32_ip_ops

vec16_ip_ops

<=>

vec32_cosine_ops

vec16_cosine_ops

マッピングルール: pgvector の

vector_<metric>_ops

vec32_<metric>_ops

halfvec_<metric>_ops

vec16_<metric>_ops

チューニング

• デフォルト値: 大規模なベンチマークで決定されており、多くの場合

  prism.nprobe

  のみを変更すれば十分です。
• 詳細: 各パラメータ、GUC、トレードオフについては チューニングガイド を参照してください。

保守管理

インサートやアップデートによりリストが成長しても自動分割は行われません。REINDEX の他に、以下の手順で過大化したリストを再分割できます。

• プロシージャ:

  prism_rebalance

  を使用してポストインゴストの分割を行います。
• 詳細: 動作方法と制限については 保守ガイド を参照してください。

ビルド要件

• PostgreSQL: 18 以降（開発ヘッダー付き）
• コンパイラ: GNU C11 (GCC 11 以上 または Clang 14 以上)
• ビルドシステム: Meson
• オプション: CBLAS (RaBitQ エンコーディングの高速化用)

詳細なビルドオプションについては開発ガイドを参照してください。

ドキュメント一覧

• [チューニング]: インデックスパラメータ、GUC、トレードオフ
• [保守]: ポストインゴストの再均衡と分割
• [アーキテクチャ]: 高レベル設計とデータ構造
• [SIMD]: ビルドオプションと距離計算の詳細
• [開発]: ビルド・テスト・CI スクリプト

リンク集 & ライセンス

研究論文

• RaBitQ: 理論的な誤差 bound を持つ二値クアンタ化（SIGMOD 2024）
• SPFresh: インクリメンタル更新のための LIRE プロトコル（SOSP 2023）
• SPANN: バウンダリレプリケーションによる十億規模の ANN（NeurIPS 2021）
• ScaNN for AlloyDB: 階層的クラスタリング（Google）

関連プロジェクト

• pgvector: PostgreSQL のベクトルタイプと演算子
• pgvectorscale: PostgreSQL 用ディスク ANN ベースのベクトルインデックス

ライセンス: PostgreSQL ライセンス