PG ベクターストア

PgVector クラスは、PostgreSQL で pgvector 拡張を導入したベクトル検索を提供します。 既存の PostgreSQL データベース内で信頼性の高いベクトル類似検索を利用できます。

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

connectionString?:

string

PostgreSQL 接続 URL

host?:

string

PostgreSQL サーバーのホスト

port?:

number

PostgreSQL サーバーのポート

database?:

string

PostgreSQL データベース名

user?:

string

PostgreSQL ユーザー

password?:

string

PostgreSQL パスワード

ssl?:

boolean | ConnectionOptions

SSL を有効にするか、カスタム SSL 設定を指定します

schemaName?:

string

ベクターストアで使用するスキーマ名。指定しない場合はデフォルトスキーマを使用します。

max?:

number

プール接続の最大数（デフォルト: 20）

idleTimeoutMillis?:

number

アイドル接続のタイムアウト（ミリ秒、デフォルト: 30000）

pgPoolOptions?:

PoolConfig

追加の pg プール設定オプション

disableInit?:

boolean

= false

true の場合、createIndex 内での自動 DDL（スキーマ、拡張、テーブル、インデックスの作成）を省略します。スキーマとインデックスを別に管理し、ランタイムのデータベースロールに DDL 権限がない CI/CD パイプラインで役立ちます。環境変数 MASTRA_DISABLE_STORAGE_INIT でも有効にできます。

コンストラクターの例

接続文字列

import { PgVector } from '@mastra/pg'

const vectorStore = new PgVector({
  id: 'pg-vector',
  connectionString: 'postgresql://user:password@localhost:5432/mydb',
})

ホスト、ポート、データベースの設定

const vectorStore = new PgVector({
  id: 'pg-vector',
  host: 'localhost',
  port: 5432,
  database: 'mydb',
  user: 'postgres',
  password: 'password',
})

高度な設定

const vectorStore = new PgVector({
  id: 'pg-vector',
  connectionString: 'postgresql://user:password@localhost:5432/mydb',
  schemaName: 'custom_schema',
  max: 30,
  idleTimeoutMillis: 60000,
  pgPoolOptions: {
    connectionTimeoutMillis: 5000,
    allowExitOnIdle: true,
  },
})

メソッド

createIndex()

indexName:

string

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

dimension:

number

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

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

類似検索の距離メトリクス

indexConfig?:

IndexConfig

= { type: 'ivfflat' }

インデックス設定

buildIndex?:

boolean

= true

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

metadataIndexes?:

string[]

btree インデックスを作成するメタデータフィールド名の配列。これらのメタデータフィールドでフィルタリングする際のクエリ性能を向上させます。

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 インデックスの構築には大量の共有メモリが必要です。ベクトルが 10 万件の場合:

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

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

upsert()

indexName:

string

ベクトルを upsert するインデックスの名前

vectors:

number[][]

埋め込みベクトルの配列

metadata?:

Record<string, any>[]

各ベクトルのメタデータ

ids?:

string[]

任意のベクトル ID（指定しない場合は自動生成されます）

query()

indexName:

string

検索するインデックスの名前

queryVector:

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()

ID またはメタデータフィルターで単一のベクトルを更新します。id と filter のどちらか一方だけを指定する必要があります。

indexName:

string

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

id?:

string

更新するベクトルの ID（filter と同時に指定できません）

filter?:

Record<string, any>

更新するベクトルを特定するメタデータフィルター（id と同時に指定できません）

update:

{ vector?: number[]; metadata?: Record<string, any>; }

更新するベクトルやメタデータを含むオブジェクト

ID またはフィルターで既存のベクトルを更新します。update オブジェクトには vector または metadata の少なくとも一方を指定する必要があります。

// Update by ID
await pgVector.updateVector({
  indexName: 'my_vectors',
  id: 'vector123',
  update: {
    vector: [0.1, 0.2, 0.3],
    metadata: { label: 'updated' },
  },
})

// Update by filter
await pgVector.updateVector({
  indexName: 'my_vectors',
  filter: { category: 'product' },
  update: {
    metadata: { status: 'reviewed' },
  },
})

deleteVector()

indexName:

string

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

id:

string

削除するベクトルの ID

指定したインデックスから ID で単一のベクトルを削除します。

await pgVector.deleteVector({ indexName: 'my_vectors', id: 'vector123' })

deleteVectors()

ID またはメタデータフィルターで複数のベクトルを削除します。ids と filter のどちらか一方だけを指定する必要があります。

indexName:

string

削除するベクトルを含むインデックスの名前

ids?:

string[]

削除するベクトル ID の配列（filter と同時に指定できません）

filter?:

Record<string, any>

削除するベクトルを特定するメタデータフィルター（ids と同時に指定できません）

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
  }
}

インデックス設定ガイド

パフォーマンスの最適化

IVFFlat の調整

• lists パラメーター: n をベクトル数として sqrt(n) * 2 に設定します
• リストが多いほど精度は上がりますが、構築時間は長くなります
• リストが少ないほど構築は速くなりますが、精度が下がる可能性があります

HNSW の調整

• m パラメーター:
  • 8〜16: 中程度の精度、少ないメモリ
  • 16〜32: 高精度、中程度のメモリ
  • 32〜64: 非常に高い精度、多くのメモリ
• efConstruction:
  • 32〜64: 高速な構築、良好な品質
  • 64〜128: 低速な構築、より良い品質
  • 128〜256: 最も低速な構築、最高の品質

インデックスの再作成動作

システムは設定変更を自動検出し、必要な場合にのみインデックスを再構築します。

• 同じ設定: インデックスを保持します（再作成なし）
• 設定変更あり: インデックスを削除して再構築します
• これにより、不要なインデックス再作成によるパフォーマンス上の問題を防ぎます

ベストプラクティス

• 最適なパフォーマンスを確保するため、インデックス設定を定期的に評価します。
• データセットのサイズとクエリ要件に基づいて、lists や m などのパラメーターを調整します。
• describeIndex() で使用状況を追跡し、インデックスのパフォーマンスを監視します
• 特にデータが大幅に変更された後は、効率を維持するため定期的にインデックスを再構築します

プールへの直接アクセス

PgVector クラスは、基盤となる PostgreSQL 接続プールをパブリックフィールドとして公開します。

pgVector.pool // instance of pg.Pool

これにより、SQL クエリの直接実行、トランザクション管理、プール状態の監視など、高度な使い方が可能になります。プールへ直接アクセスする場合:

• 使用後のクライアント解放（client.release()）は利用者の責任です。
• disconnect() を呼び出した後もプールへアクセスできますが、新しいクエリは失敗します。
• 直接アクセスすると、PgVector メソッドが提供する検証やトランザクションロジックを迂回します。

この設計は高度なユースケースに対応しますが、利用者による慎重なリソース管理が必要です。

使用例

fastembed を使用したローカル埋め込み

埋め込みは、Memory の semanticRecall がキーワードではなく意味に基づいて関連メッセージを取得するために使用する数値ベクトルです。この設定では @mastra/fastembed でベクトル埋め込みを生成します。

まず fastembed をインストールします。

npm

npm install @mastra/fastembed@latest

pnpm

pnpm add @mastra/fastembed@latest

Yarn

yarn add @mastra/fastembed@latest

Bun

bun add @mastra/fastembed@latest

Agent に次の内容を追加します。

src/mastra/agents/example-pg-agent.ts

import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { PostgresStore, PgVector } from '@mastra/pg'
import { fastembed } from '@mastra/fastembed'

export const pgAgent = new Agent({
  id: 'pg-agent',
  name: 'PG Agent',
  instructions:
    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new PostgresStore({
      id: 'pg-agent-storage',
      connectionString: process.env.DATABASE_URL!,
    }),
    vector: new PgVector({
      id: 'pg-agent-vector',
      connectionString: process.env.DATABASE_URL!,
    }),
    embedder: fastembed,
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
      },
    },
  }),
})

関連情報

• メタデータフィルター