中繼資料篩選器

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 的範圍內
• 中繼資料中的陣列總大小上限為 64 KB
• 巢狀物件會使用句點標記法攤平
• 更新中繼資料時，會取代整個中繼資料物件

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 會正規化為 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
• Chroma
• Cloudflare Vectorize
• libSQL
• MongoDB
• OracleDB
• PgStore
• Pinecone
• Qdrant
• Upstash
• Amazon S3 Vectors