> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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 的範圍內
- 中繼資料中的陣列總大小上限為 64 KB
- 巢狀物件會使用句點標記法攤平
- 更新中繼資料時，會取代整個中繼資料物件

### 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 會正規化為 epoch 毫秒）。
- `$in`/`$nin` 要求使用**非空的基本型別陣列**；允許 Date 元素，且會正規化為 epoch 毫秒。不支援**陣列相等比較**。
- 隱含 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/zh-TW/reference/vectors/astra)
- [Chroma](https://mastra.zisheng.pro/zh-TW/reference/vectors/chroma)
- [Cloudflare Vectorize](https://mastra.zisheng.pro/zh-TW/reference/vectors/vectorize)
- [libSQL](https://mastra.zisheng.pro/zh-TW/reference/vectors/libsql)
- [MongoDB](https://mastra.zisheng.pro/zh-TW/reference/vectors/mongodb)
- [OracleDB](https://mastra.zisheng.pro/zh-TW/reference/vectors/oracledb)
- [PgStore](https://mastra.zisheng.pro/zh-TW/reference/vectors/pg)
- [Pinecone](https://mastra.zisheng.pro/zh-TW/reference/vectors/pinecone)
- [Qdrant](https://mastra.zisheng.pro/zh-TW/reference/vectors/qdrant)
- [Upstash](https://mastra.zisheng.pro/zh-TW/reference/vectors/upstash)
- [Amazon S3 Vectors](https://mastra.zisheng.pro/zh-TW/reference/vectors/s3vectors)