メタデータフィルター

Mastra は、MongoDB/Sift のクエリ構文に基づき、すべてのベクトルストアで統一的なメタデータフィルタリング構文を提供します。各ベクトルストアは、これらのフィルターをそれぞれのネイティブ形式に変換します。

基本例

import { PgVector } from "@mastra/pg";
 
const store = new PgVector({ connectionString });
 
const results = await store.query({
  indexName: "my_index",
  queryVector: queryVector,
  topK: 10,
  filter: {
    category: "electronics", // 単純な等価比較
    price: { $gt: 100 }, // 数値比較
    tags: { $in: ["sale", "new"] }, // 配列内の要素一致
  },
});

サポートされている演算子

{
  age: {
    $eq: 25
  }
}

{
  status: {
    $ne: 'inactive'
  }
}

{
  price: {
    $gt: 100
  }
}

{
  rating: {
    $gte: 4.5
  }
}

{
  stock: {
    $lt: 20
  }
}

{
  priority: {
    $lte: 3
  }
}

{
  category: {
    $in: ["A", "B"]
  }
}

{
  status: {
    $nin: ["deleted", "archived"]
  }
}

{
  tags: {
    $all: ["urgent", "high"]
  }
}

{
  scores: {
    $elemMatch
  }
}

{
  $and: [
    { price: { $gt: 100 } },
    { stock: { $gt: 0 } } }
  ]
}

{
  $or: [
    { status: "active" },
    { priority: "high" } }
  ]
}

{
  price: {
    $not
  }
}

{
  $nor: [
    { status: "deleted" },
    { archived: true } }
  ]
}

{
  rating: {
    $exists: true
  }
}

{
  description: {
    $contains: "sale"
  }
}

{
  name: {
    $regex: "^test"
  }
}

{
  tags: {
    $size
  }
}

{
  location: {
    $geo
  }
}

{
  created: {
    $datetime
  }
}

{
  $hasId: [
    { "id1", "id2" }
  ]
}

{
  $hasVector: true
}

共通ルールと制限

1. フィールド名についての禁止事項:

   • ネストされたフィールドを参照する場合を除き、ドット (.) を含めない
   • $ で始めない、または null 文字を含めない
   • 空文字列にしない

2. 値の要件:

   • 有効な JSON 型であること（string、number、boolean、object、array）
   • undefined でないこと
   • 使用する演算子に対して適切な型であること（例: 数値比較には number）

3. 論理演算子:

   • 有効な条件を含めること
   • 空にしないこと
   • 適切にネストされていること
   • トップレベル、または他の論理演算子内にネストしてのみ使用できる
   • フィールドレベルで、またはフィールド内にネストして使用してはならない
   • 他の演算子の内部で使用してはならない
   • 有効: { "$and": [{ "field": { "$gt": 100 } }] }
   • 有効: { "$or": [{ "$and": [{ "field": { "$gt": 100 } }] }] }
   • 無効: { "field": { "$and": [{ "$gt": 100 }] } }
   • 無効: { "field": { "$gt": { "$and": [{...}] } } }

4. $not 演算子:

   • オブジェクトでなければならない
   • 空にしてはならない
   • フィールドレベルまたはトップレベルで使用できる
   • 有効: { "$not": { "field": "value" } }
   • 有効: { "field": { "$not": { "$eq": "value" } } }

5. 演算子のネスト:

   • 論理演算子は、演算子そのものではなくフィールド条件を含めなければならない
   • 有効: { "$and": [{ "field": { "$gt": 100 } }] }
   • 無効: { "$and": [{ "$gt": 100 }] }

ストア別の注意事項

Astra

• ネストされたフィールドのクエリはドット記法でサポートされています
• 配列フィールドはメタデータで明示的に配列として定義する必要があります
• メタデータの値は大文字・小文字を区別します

ChromaDB

• フィルタは、メタデータ内に対象フィールドが存在する結果のみを返します
• 空のメタデータフィールドはフィルタ結果に含まれません
• 否定条件での一致には当該メタデータフィールドが存在している必要があります（例：$ne はそのフィールドが欠落しているドキュメントには一致しません）

Cloudflare Vectorize

• フィルタリングを使う前に、メタデータの明示的なインデックス作成が必要
• フィルタ対象のフィールドをインデックスするには createMetadataIndex() を使用
• Vectorize のインデックスあたり最大 10 個のメタデータインデックス
• 文字列値は先頭 64 バイトまでをインデックス化（UTF-8 の境界で切り詰め）
• 数値は float64 精度を使用
• フィルター用 JSON は 2048 バイト未満である必要がある
• フィールド名にドット (.) を含めたり、$ で始めることはできない
• フィールド名は最大 512 文字まで
• 新しいメタデータインデックスを作成した後、フィルタ結果に反映させるにはベクトルを再アップサートする必要がある
• 非常に大規模なデータセット（約 1,000 万件以上のベクトル）では、範囲クエリの精度が低下する場合がある

LibSQL

• ドット記法でネストされたオブジェクトのクエリをサポート
• 配列フィールドは、有効な JSON 配列であることを確認するために検証されます
• 数値比較では適切な型処理を維持
• 条件での空配列は適切に処理されます
• メタデータは効率的なクエリのために JSONB カラムに格納されます

PgVector

• PostgreSQL のネイティブな JSON クエリ機能を完全にサポート
• ネイティブの配列関数による配列操作の効率的な処理
• 数値、文字列、ブール値の適切な型処理
• ネストされたフィールドのクエリは内部的に PostgreSQL の JSON パス構文を使用
• メタデータは効率的なインデックス作成のために JSONB 列に保存

Pinecone

• メタデータのフィールド名は512文字までです
• 数値は±1e38の範囲内である必要があります
• メタデータ内の配列は合計サイズが64KBまでです
• ネストされたオブジェクトはドット記法でフラット化されます
• メタデータの更新はメタデータオブジェクト全体を置き換えます

Qdrant

• ネストされた条件による高度なフィルタリングをサポート
• フィルタリングには Payload（メタデータ）フィールドを明示的にインデックス化する必要がある
• 位置情報（ジオ空間）クエリを効率的に処理
• null および空値を特別に処理
• ベクター固有のフィルタリング機能
• 日時値は RFC 3339 形式である必要がある

Upstash

• メタデータフィールドのキーは512文字まで
• クエリのサイズに制限あり（大きな IN 句は避ける）
• フィルターでの null/undefined 値は非対応
• 内部的に SQL 風の構文へ変換
• 文字列比較は大文字・小文字を区別
• メタデータの更新はアトミックに実行

MongoDB

• メタデータ用フィルタに対する MongoDB/Sift クエリ構文を完全サポート
• 標準的な比較・配列・論理・要素オペレーターをすべてサポート
• メタデータ内のネストされたフィールドや配列に対応
• filter と documentFilter オプションを使用して、metadata と元のドキュメント内容の両方にフィルタリングを適用可能
• filter はメタデータオブジェクトに、documentFilter は元のドキュメントのフィールドに適用
• フィルタのサイズや複雑さに人工的な制限はなし（MongoDB のクエリ制限に準拠）
• 最適なパフォーマンスのため、メタデータフィールドのインデックス化を推奨

Couchbase

• 現在、メタデータフィルターには対応していません。フィルタリングは結果取得後にクライアント側で行うか、より複雑なクエリの場合は Couchbase SDK の Search 機能を直接使用してください。

Amazon S3 ベクター

• 等価比較の値はプリミティブ（string/number/boolean）でなければなりません。null/undefined、配列、オブジェクト、Date は等価比較には使用できません。範囲演算子は number または Date を受け付けます（Date はエポック ms に正規化されます）。
• $in/$nin は空でないプリミティブの配列が必要です。Date 要素は許可され、エポック ms に正規化されます。配列の等価比較はサポートされません。
• 暗黙の AND は正規化されます（{a:1,b:2} → {$and:[{a:1},{b:2}]}）。論理演算子はフィールド条件を含み、空でない配列を使用し、ルートまたは他の論理演算子内にのみ記述できます（フィールド値の内部は不可）。
• インデックス作成時に nonFilterableMetadataKeys に指定したキーは保存されますが、フィルターには使用できません。この設定は変更できません。
• $exists には boolean 値が必要です。
• undefined/null/空のフィルターは、フィルターなしとして扱われます。
• 各メタデータキー名は最大 63 文字。
• ベクターあたりのメタデータ合計：最大 40 KB（フィルタ可能 + フィルタ不可）
• ベクターあたりのメタデータキー数合計：最大 10
• ベクターあたりのフィルタ可能メタデータ：最大 2 KB
• ベクターインデックスあたりのフィルタ不可メタデータキー数：最大 10

関連項目

• Astra
• Chroma
• Cloudflare Vectorize
• LibSQL
• MongoDB
• PgStore
• Pinecone
• Qdrant
• Upstash
• Amazon S3 Vectors