Metadata 篩選器

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

基本範例

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() 為要篩選的欄位建立索引：

// 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
• Chroma
• Cloudflare Vectorize
• libSQL
• MongoDB
• OracleDB
• PgStore
• Pinecone
• Qdrant
• Upstash
• Amazon S3 Vectors