Skip to Content
リファレンスRAGPgVector

PG Vector Store

PgVectorクラスは、PostgreSQL とpgvector 拡張機能を使用したベクトル検索を提供します。 既存のPostgreSQLデータベース内で堅牢なベクトル類似性検索機能を実現します。

コンストラクタオプション

connectionString:

string
PostgreSQL接続URL

schemaName?:

string
ベクトルストアが使用するスキーマの名前。提供されない場合はデフォルトのスキーマを使用します。

コンストラクタの例

PgVectorを2つの方法でインスタンス化できます：

import { PgVector } from "@mastra/pg";
 
// 接続文字列を使用する方法（文字列形式）
const vectorStore1 = new PgVector(
  "postgresql://user:password@localhost:5432/mydb",
);
 
// 設定オブジェクトを使用する方法（オプションのschemaNameを含む）
const vectorStore2 = new PgVector({
  connectionString: "postgresql://user:password@localhost:5432/mydb",
  schemaName: "custom_schema", // オプション
});

メソッド

createIndex()

indexName:

string
作成するインデックスの名前

dimension:

number
ベクトルの次元数（埋め込みモデルと一致する必要があります）

metric?:

'cosine' | 'euclidean' | 'dotproduct'
= cosine
類似検索に使用する距離メトリック

indexConfig?:

IndexConfig
= { type: 'ivfflat' }
インデックスの設定

buildIndex?:

boolean
= true
インデックスを構築するかどうか

IndexConfig

type:

'flat' | 'hnsw' | 'ivfflat'
= ivfflat
インデックスタイプ
string

flat:

flat
全探索を行うシーケンシャルスキャン（インデックスなし）。

ivfflat:

ivfflat
ベクトルをリストにクラスタリングし、近似検索を行います。

hnsw:

hnsw
高速な検索と高いリコールを実現するグラフベースのインデックス。

ivf?:

IVFConfig
IVFの設定
object

lists?:

number
リスト数。指定しない場合はデータセットサイズに基づき自動計算されます。（最小100、最大4000）

hnsw?:

HNSWConfig
HNSWの設定
object

m?:

number
ノードごとの最大接続数（デフォルト: 8）

efConstruction?:

number
構築時の複雑度（デフォルト: 32）

メモリ要件

HNSWインデックスの構築時には多くの共有メモリが必要です。100Kベクトルの場合：

  • 小さい次元（64d）：デフォルト設定で約60MB
  • 中程度の次元（256d）：デフォルト設定で約180MB
  • 大きい次元（384d以上）：デフォルト設定で約250MB以上

M値やefConstruction値を大きくすると、必要なメモリも大幅に増加します。必要に応じてシステムの共有メモリ上限を調整してください。

upsert()

indexName:

string
ベクトルをアップサートするインデックスの名前

vectors:

number[][]
埋め込みベクトルの配列

metadata?:

Record<string, any>[]
各ベクトルのメタデータ

ids?:

string[]
オプションのベクトルID（指定しない場合は自動生成）

query()

indexName:

string
クエリを実行するインデックスの名前

vector:

number[]
クエリベクトル

topK?:

number
= 10
返す結果の数

filter?:

Record<string, any>
メタデータフィルター

includeVector?:

boolean
= false
結果にベクトルを含めるかどうか

minScore?:

number
= 0
最小類似度スコアのしきい値

options?:

{ ef?: number; probes?: number }
HNSWおよびIVFインデックスの追加オプション
object

ef?:

number
HNSW検索パラメータ

probes?:

number
IVF検索パラメータ

listIndexes()

インデックス名の文字列配列を返します。

describeIndex()

indexName:

string
説明するインデックスの名前

戻り値：

interface PGIndexStats {
  dimension: number;
  count: number;
  metric: "cosine" | "euclidean" | "dotproduct";
  type: "flat" | "hnsw" | "ivfflat";
  config: {
    m?: number;
    efConstruction?: number;
    lists?: number;
    probes?: number;
  };
}

deleteIndex()

indexName:

string
削除するインデックスの名前

updateVector()

indexName:

string
ベクトルを含むインデックスの名前

id:

string
更新するベクトルのID

update:

object
更新パラメータ
object

vector?:

number[]
新しいベクトル値

metadata?:

Record<string, any>
新しいメタデータ値

IDによって既存のベクトルを更新します。ベクトルまたはメタデータの少なくとも一方を提供する必要があります。

// ベクトルのみを更新
await pgVector.updateVector("my_vectors", "vector123", {
  vector: [0.1, 0.2, 0.3],
});
 
// メタデータのみを更新
await pgVector.updateVector("my_vectors", "vector123", {
  metadata: { label: "updated" },
});
 
// ベクトルとメタデータの両方を更新
await pgVector.updateVector("my_vectors", "vector123", {
  vector: [0.1, 0.2, 0.3],
  metadata: { label: "updated" },
});

deleteVector()

indexName:

string
ベクトルを含むインデックスの名前

id:

string
削除するベクトルのID

指定されたインデックスからIDによって単一のベクトルを削除します。

await pgVector.deleteVector("my_vectors", "vector123");

disconnect()

データベース接続プールを閉じます。ストアの使用が終了したら呼び出す必要があります。

buildIndex()

indexName:

string
定義するインデックスの名前

metric?:

'cosine' | 'euclidean' | 'dotproduct'
= cosine
類似検索に使用する距離メトリック

indexConfig:

IndexConfig
インデックスタイプおよびパラメータの設定

指定したメトリックと設定でインデックスを作成または再作成します。新しいインデックスを作成する前に、既存のインデックスは削除されます。

// Define HNSW index
await pgVector.buildIndex("my_vectors", "cosine", {
  type: "hnsw",
  hnsw: {
    m: 8,
    efConstruction: 32,
  },
});
 
// Define IVF index
await pgVector.buildIndex("my_vectors", "cosine", {
  type: "ivfflat",
  ivf: {
    lists: 100,
  },
});
 
// Define flat index
await pgVector.buildIndex("my_vectors", "cosine", {
  type: "flat",
});

レスポンスタイプ

クエリ結果は次の形式で返されます：

interface QueryResult {
  id: string;
  score: number;
  metadata: Record<string, any>;
  vector?: number[]; // Only included if includeVector is true
}

エラー処理

このストアは型付きエラーをスローし、キャッチすることができます。

try {
  await store.query({
    indexName: "index_name",
    queryVector: queryVector,
  });
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code); // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details); // Additional error context
  }
}

ベストプラクティス

  • 最適なパフォーマンスを確保するために、インデックス設定を定期的に評価してください。
  • データセットのサイズやクエリ要件に応じて、lists や m などのパラメータを調整しましょう。
  • 特に大きなデータ変更の後は、効率を維持するためにインデックスを定期的に再構築してください。

関連

CloudflareVectorLibSQLVector