pgvector

pgvector

PostgreSQL でベクトルを保存し、SQL で厳密な最近傍検索および近似最近傍検索を実行するための拡張機能です。

クイックナビゲーション

• インストール：references/installation.md
• コア概念と SQL レシピ：references/core.md
• インデックス作成（HNSW / IVFFlat）とチューニング：references/indexing.md
• フィルタリング、反復スキャン、パフォーマンス：references/performance-and-filtering.md
• 型と関数のリファレンス（vector/halfvec/bit/sparsevec）：references/types-and-functions.md
• トラブルシューティング：references/troubleshooting.md
• クライアントライブラリ（優先順）：
  • Python：references/python.md
  • Go：references/go.md
  • Node（JS/TS）：references/node.md
  • Java：references/java.md
  • Swift：references/swift.md

使用する場面

• Postgres 内でベクトル類似検索を行う必要がある場合（ベクトルをリレーショナルデータと一緒に保持できます）。
• 調整可能な再現率と速度を備えた、SQL ネイティブの ANN インデックス（HNSW または IVFFlat）を使用したい場合。
• 複数のアプリケーション言語で、埋め込みを保存・検索する一貫したパターンを使用したい場合。

クイックスタート（インストール済みの場合）

前提条件：Postgres サーバーに pgvector がインストールされている必要があります。詳しくは references/installation.md を参照してください。

データベースごとに有効化し、最初のクエリを実行します。

CREATE EXTENSION vector;

CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(3));
INSERT INTO items (embedding) VALUES ('[1,2,3]'), ('[4,5,6]');

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

距離演算子の選択

• L2（ユークリッド距離）：<-> を使用します
• 内積：<#> を使用します（注：負の内積を返します）
• コサイン距離：<=> を使用します
• L1：<+> を使用します
• バイナリベクトル：ハミング距離 <~> / ジャカード距離 <%>

インデックス作成の目安

• 厳密検索：pgvector インデックスは不要です。大きなテーブルでは並列スキャンが使用される場合があります。
• ANN 検索：
  • 速度と再現率を優先する場合は HNSW を推奨します。構築時間とメモリ使用量は増加します。
  • 構築を速くし、メモリ使用量を抑えたい場合は IVFFlat を使用します。
• 使用する距離関数／演算子クラスごとに、インデックスを 1 つ作成してください。

重要な禁止事項／注意点

• 近似インデックスを使用すると、結果が変わる可能性があります（再現率と速度のトレードオフ）。
• インデックスを使用するには、通常 ORDER BY <distance-op> ... LIMIT ... が必要です。
• <#> は負の内積を返します。実際の値を得るには -1 を掛けてください。
• NULL ベクトルはインデックスに登録されません。コサイン距離の場合、ゼロベクトルも登録されません。

リンク

• ドキュメント／リポジトリ：https://github.com/pgvector/pgvector
• クライアントライブラリ：
  • Python：https://github.com/pgvector/pgvector-python
  • Go：https://github.com/pgvector/pgvector-go
  • Node：https://github.com/pgvector/pgvector-node
  • Java：https://github.com/pgvector/pgvector-java
  • Swift：https://github.com/pgvector/pgvector-swift
• リリース／タグ：https://github.com/pgvector/pgvector/tags