メタデータフィルター

Mastra は、MongoDB/Sift のクエリ構文に基づく統一されたメタデータフィルタリング構文を、すべてのベクトルストアに提供します。各ベクトルストアは、これらのフィルターをネイティブのクエリ形式に変換します。たとえば、PgVector は PostgreSQL の JSONB 述語を使用します。一方、OracleDB はメタデータを Oracle JSON として保存し、フィルターを値がバインドされた JSON_VALUE、JSON_EXISTS、REGEXP_LIKE、LIKE 述語にコンパイルします。

基本的な例

import { PgVector } from '@mastra/pg'

const store = new PgVector({
  id: 'pg-vector',
  connectionString,
})

const results = await store.query({
  indexName: 'my_index',
  queryVector: queryVector,
  topK: 10,
  filter: {
    category: 'electronics', // Simple equality
    price: { $gt: 100 }, // Numeric comparison
    tags: { $in: ['sale', 'new'] }, // Array membership
  },
})

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

基本的な比較

$eq

指定した値と等しい値に一致します

{ age: { $eq: 25 } }

Supported by: Couchbase を除くすべて

$ne

等しくない値に一致します

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

Supported by: Couchbase を除くすべて

$gt

より大きい

{ price: { $gt: 100 } }

Supported by: Couchbase を除くすべて

$gte

以上

{ rating: { $gte: 4.5 } }

Supported by: Couchbase を除くすべて

$lt

より小さい

{ stock: { $lt: 20 } }

Supported by: Couchbase を除くすべて

$lte

以下

{ priority: { $lte: 3 } }

Supported by: Couchbase を除くすべて

配列演算子

$in

配列内のいずれかの値に一致します

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

Supported by: Couchbase を除くすべて

$nin

どの値にも一致しません

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

Supported by: Couchbase を除くすべて

$all

すべての要素を含む配列に一致します

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

Supported by: Astra, Pinecone, Upstash, MongoDB, OracleDB

$elemMatch

条件を満たす配列要素に一致します

{ scores: { $elemMatch: { $gt: 80 } } }

Supported by: libSQL, PgVector, MongoDB, OracleDB

論理演算子

$and

論理 AND

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

Supported by: Vectorize、Couchbase を除くすべて

$or

論理 OR

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

Supported by: Vectorize、Couchbase を除くすべて

$not

論理 NOT

{ price: { $not: { $lt: 100 } } }

Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB

$nor

論理 NOR

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

Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB

要素演算子

$exists

フィールドを持つドキュメントに一致します

{ rating: { $exists: true } }

Supported by: Vectorize、Chroma、Couchbase を除くすべて

カスタム演算子

$contains

テキストに部分文字列が含まれるかを判定します

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

Supported by: Upstash, libSQL, PgVector, OracleDB

$regex

正規表現に一致するかを判定します

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

Supported by: Qdrant, PgVector, Upstash, MongoDB, OracleDB

$size

配列の長さを確認します

{ tags: { $size: 3 } }

Supported by: Astra, libSQL, PgVector, MongoDB, OracleDB

$geo

地理空間クエリ

{ location: { $geo: { type: "radius", ... } } }

Supported by: Qdrant

$datetime

日時範囲クエリ

{ created: { $datetime: { range: { gt: "2024-01-01" } } } }

Supported by: Qdrant

$hasId

ベクトル ID の存在確認

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

Supported by: Qdrant

$hasVector

ベクトルの存在確認

{ $hasVector: true }

Supported by: Qdrant

共通のルールと制約

1. フィールド名には次の制約があります。

   • ネストされたフィールドを参照する場合を除き、ドット（.）を含めることはできません
   • $ で始めることや、null 文字を含めることはできません
   • 空文字列にすることはできません

2. 値は次の要件を満たす必要があります。

   • 有効な JSON 型（文字列、数値、真偽値、オブジェクト、配列）であること
   • undefined でないこと
   • 演算子に適した型であること（例：数値比較には数値）

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

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

Cloudflare Vectorize

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

libSQL

• ドット記法によるネストされたオブジェクトのクエリをサポートします
• 配列フィールドが有効な JSON 配列を含むことを検証します
• 数値比較では型が適切に処理されます
• 条件内の空配列は適切に処理されます
• 効率的にクエリできるよう、メタデータは JSONB 列に保存されます

OracleDB

• メタデータは各 VECTOR 行とともに Oracle JSON として保存されます
• スカラー比較では JSON_VALUE を使用し、配列、存在確認、要素一致のチェックでは JSON_EXISTS を使用します
• $regex では Oracle の REGEXP_LIKE を使用し、文字列の $contains では大文字と小文字を区別しない LIKE を使用します
• ネストされたフィールドはドット記法でサポートされ、引用符で囲まれた Oracle JSON パスに変換されます
• ユーザーが指定したメタデータ値は、SQL に埋め込まれず、パラメーターとしてバインドされます

PgVector

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

Pinecone

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

Qdrant

• ネストされた条件を使用した高度なフィルタリングをサポートします
• フィルタリングする Payload（メタデータ）フィールドは、明示的にインデックス化する必要があります
• フィルター対象にするフィールドのインデックスを作成するには、createPayloadIndex() を使用します。

// Index a field before filtering on it
await store.createPayloadIndex({
  indexName: 'my_index',
  fieldName: 'source',
  fieldSchema: 'keyword', // 'keyword' | 'integer' | 'float' | 'geo' | 'text' | 'bool' | 'datetime' | 'uuid'
})

// Now filtering works
const results = await store.query({
  indexName: 'my_index',
  queryVector: queryVector,
  filter: { source: 'document-a' },
})

• 地理空間クエリを効率的に処理します
• null 値と空の値を特別に処理します
• ベクトル固有のフィルタリング機能を備えています
• 日時の値は RFC 3339 形式である必要があります

Upstash

• メタデータフィールドのキーは 512 文字までです
• クエリサイズには制限があります（大きな IN 句は避けてください）
• フィルター内の null/undefined 値はサポートされません
• 内部的に SQL に似た構文へ変換されます
• 文字列比較では大文字と小文字が区別されます
• メタデータの更新はアトミックです

MongoDB

• メタデータフィルターで MongoDB/Sift クエリ構文を完全にサポートします
• 標準の比較、配列、論理、要素演算子をすべてサポートします
• メタデータ内のネストされたフィールドと配列をサポートします
• filter オプションと documentFilter オプションをそれぞれ使用し、metadata と元のドキュメント内容の両方にフィルタリングを適用できます
• filter はメタデータオブジェクトに適用され、documentFilter は元のドキュメントフィールドに適用されます
• フィルターのサイズや複雑さに人為的な制限はありません（MongoDB のクエリ制限には従います）
• 最適なパフォーマンスを得るには、メタデータフィールドのインデックス化を推奨します

Couchbase

• 現在、メタデータフィルターはサポートされていません。結果の取得後にクライアント側でフィルタリングするか、より複雑なクエリでは Couchbase SDK の Search 機能を直接使用する必要があります。

Amazon S3 Vectors

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

関連項目

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