> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# Metadata 篩選器

Mastra 以 MongoDB/Sift 查詢語法為基礎，為所有向量儲存庫提供統一的 metadata 篩選語法。每個向量儲存庫都會將這些篩選器轉換成其原生查詢格式。例如，PgVector 使用 PostgreSQL JSONB predicate；OracleDB 則將 metadata 儲存為 Oracle JSON，並以綁定值將篩選器編譯成 `JSON_VALUE`、`JSON_EXISTS`、`REGEXP_LIKE` 及 `LIKE` predicate。

## 基本範例

```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 類型（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 運算子：

   - 必須是 object
   - 不得為空
   - 可用於欄位層級或頂層
   - 有效：`{ "$not": { "field": "value" } }`
   - 有效：`{ "field": { "$not": { "$eq": "value" } } }`

5. 運算子巢狀結構：

   - 邏輯運算子必須包含欄位條件，而非直接包含運算子
   - 有效：`{ "$and": [{ "field": { "$gt": 100 } }] }`
   - 無效：`{ "$and": [{ "$gt": 100 }] }`

## 各儲存庫注意事項

### Astra

- 支援使用句點標記法查詢巢狀欄位
- 陣列欄位必須在 metadata 中明確定義為陣列
- Metadata 值區分大小寫

### ChromaDB

- Where 篩選器只會傳回 metadata 中存在被篩選欄位的結果
- 空白的 metadata 欄位不會包括在篩選結果中
- 進行否定比對時，metadata 欄位必須存在（例如 $ne 不會比對缺少該欄位的文件）

### Cloudflare Vectorize

- 使用篩選功能前，必須明確建立 metadata 索引
- 使用 `createMetadataIndex()` 為要篩選的欄位建立索引
- 每個 Vectorize 索引最多可有 10 個 metadata 索引
- 字串值只會為首 64 bytes 建立索引（在 UTF-8 邊界截斷）
- 數值使用 float64 精度
- 篩選器 JSON 必須少於 2048 bytes
- 欄位名稱不得包含句點 (.) 或以 $ 開首
- 欄位名稱上限為 512 個字元
- 建立新的 metadata 索引後，必須重新 upsert 向量，向量才會包括在篩選結果中
- 對極大型資料集（約一千萬個或以上向量）進行範圍查詢時，準確度可能會降低

### libSQL

- 支援使用句點標記法查詢巢狀物件
- 系統會驗證陣列欄位，以確保其中包含有效的 JSON 陣列
- 數值比較會維持正確的類型處理
- 條件中的空陣列會得到妥善處理
- Metadata 儲存於 JSONB 欄位中，以提高查詢效率

### OracleDB

- Metadata 會以 Oracle JSON 形式與每個 `VECTOR` row 一併儲存
- 純量比較使用 `JSON_VALUE`；陣列、存在性及元素比對檢查則使用 `JSON_EXISTS`
- `$regex` 使用 Oracle `REGEXP_LIKE`；字串 `$contains` 使用不區分大小寫的 `LIKE`
- 支援以句點標記法表示巢狀欄位，並會將其轉換成加上引號的 Oracle JSON path
- 使用者提供的 metadata 值會綁定為參數，而不是插入 SQL

### PgVector

- 完整支援 PostgreSQL 原生 JSON 查詢功能
- 使用原生陣列函數有效處理陣列操作
- 正確處理 number、string 及 boolean 類型
- 巢狀欄位查詢在內部使用 PostgreSQL JSON path 語法
- Metadata 儲存於 JSONB 欄位中，以提高索引效率

### Pinecone

- Metadata 欄位名稱上限為 512 個字元
- 數值必須在 ±1e38 範圍內
- Metadata 中的陣列總大小上限為 64KB
- 巢狀物件會以句點標記法扁平化
- 更新 metadata 時會取代整個 metadata 物件

### Qdrant

- 支援使用巢狀條件進行進階篩選
- 必須明確為 payload（metadata）欄位建立索引，才能進行篩選
- 使用 `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 及空值
- 向量專用篩選功能
- Datetime 值必須採用 RFC 3339 格式

### Upstash

- Metadata 欄位 key 上限為 512 個字元
- 查詢大小有限制（避免使用大型 IN clause）
- 篩選器不支援 null/undefined 值
- 在內部轉換成類似 SQL 的語法
- 字串比較區分大小寫
- Metadata 更新屬於原子操作

### MongoDB

- 完整支援用於 metadata 篩選器的 MongoDB/Sift 查詢語法
- 支援所有標準比較、陣列、邏輯及元素運算子
- 支援 metadata 中的巢狀欄位及陣列
- 可分別使用 `filter` 及 `documentFilter` 選項，篩選 `metadata` 和原始文件內容
- `filter` 套用至 metadata 物件；`documentFilter` 套用至原始文件欄位
- 不會人為限制篩選器的大小或複雜度（仍受 MongoDB 查詢限制約束）
- 建議為 metadata 欄位建立索引，以取得最佳效能

### Couchbase

- 目前不支援 metadata 篩選器。擷取結果後，必須在 client 端進行篩選；較複雜的查詢亦可直接使用 Couchbase SDK 的 Search 功能。

### Amazon S3 Vectors

- 等值必須是 primitive（string/number/boolean）。等值不允許使用 `null`/`undefined`、陣列、物件及 Date。範圍運算子接受 number 或 Date（Date 會標準化為 epoch ms）。
- `$in`/`$nin` 要求使用**非空的 primitive 陣列**；允許 Date 元素，並會將其標準化為 epoch ms。不支援**陣列等值**。
- 隱含 AND 會標準化（`{a:1,b:2}` → `{$and:[{a:1},{b:2}]`）。邏輯運算子必須包含欄位條件，並使用非空陣列。它們只能出現在 root，或位於其他邏輯運算子內（不得置於欄位值內）。
- 建立索引時列於 `nonFilterableMetadataKeys` 的 key 會被儲存，但不能用於篩選。此設定不可變更。
- $exists 要求使用 boolean 值。
- undefined/null/空篩選器會視為沒有篩選器。
- 每個 metadata key 名稱上限為 63 個字元。
- 每個向量的 metadata 總量：最多 40 KB（可篩選 + 不可篩選）
- 每個向量的 metadata key 總數：最多 10 個
- 每個向量的可篩選 metadata：最多 2 KB
- 每個向量索引的不可篩選 metadata key：最多 10 個

## 相關內容

- [Astra](https://mastra.zisheng.pro/zh-HK/reference/vectors/astra)
- [Chroma](https://mastra.zisheng.pro/zh-HK/reference/vectors/chroma)
- [Cloudflare Vectorize](https://mastra.zisheng.pro/zh-HK/reference/vectors/vectorize)
- [libSQL](https://mastra.zisheng.pro/zh-HK/reference/vectors/libsql)
- [MongoDB](https://mastra.zisheng.pro/zh-HK/reference/vectors/mongodb)
- [OracleDB](https://mastra.zisheng.pro/zh-HK/reference/vectors/oracledb)
- [PgStore](https://mastra.zisheng.pro/zh-HK/reference/vectors/pg)
- [Pinecone](https://mastra.zisheng.pro/zh-HK/reference/vectors/pinecone)
- [Qdrant](https://mastra.zisheng.pro/zh-HK/reference/vectors/qdrant)
- [Upstash](https://mastra.zisheng.pro/zh-HK/reference/vectors/upstash)
- [Amazon S3 Vectors](https://mastra.zisheng.pro/zh-HK/reference/vectors/s3vectors)