> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt # メタデータフィルター Mastra は、MongoDB/Sift のクエリ構文に基づく統一されたメタデータフィルタリング構文を、すべてのベクトルストアに提供します。各ベクトルストアは、これらのフィルターをネイティブのクエリ形式に変換します。たとえば、PgVector は PostgreSQL の JSONB 述語を使用します。一方、OracleDB はメタデータを Oracle JSON として保存し、フィルターを値がバインドされた `JSON_VALUE`、`JSON_EXISTS`、`REGEXP_LIKE`、`LIKE` 述語にコンパイルします。 ## 基本的な例 ```typescript 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()` を使用します。 ```typescript // 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](https://mastra.zisheng.pro/ja/reference/vectors/astra) - [Chroma](https://mastra.zisheng.pro/ja/reference/vectors/chroma) - [Cloudflare Vectorize](https://mastra.zisheng.pro/ja/reference/vectors/vectorize) - [libSQL](https://mastra.zisheng.pro/ja/reference/vectors/libsql) - [MongoDB](https://mastra.zisheng.pro/ja/reference/vectors/mongodb) - [OracleDB](https://mastra.zisheng.pro/ja/reference/vectors/oracledb) - [PgStore](https://mastra.zisheng.pro/ja/reference/vectors/pg) - [Pinecone](https://mastra.zisheng.pro/ja/reference/vectors/pinecone) - [Qdrant](https://mastra.zisheng.pro/ja/reference/vectors/qdrant) - [Upstash](https://mastra.zisheng.pro/ja/reference/vectors/upstash) - [Amazon S3 Vectors](https://mastra.zisheng.pro/ja/reference/vectors/s3vectors)