元数据过滤器

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: All except Couchbase

$ne

匹配不相等的值

{ status: { $ne: 'inactive' } }

Supported by: All except Couchbase

$gt

大于

{ price: { $gt: 100 } }

Supported by: All except Couchbase

$gte

大于或等于

{ rating: { $gte: 4.5 } }

Supported by: All except Couchbase

$lt

小于

{ stock: { $lt: 20 } }

Supported by: All except Couchbase

$lte

小于或等于

{ priority: { $lte: 3 } }

Supported by: All except Couchbase

数组运算符

$in

匹配数组中的任意值

{ category: { $in: ["A", "B"] } }

Supported by: All except Couchbase

$nin

不匹配其中任何值

{ status: { $nin: ["deleted", "archived"] } }

Supported by: All except 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: All except Vectorize, Couchbase

$or

逻辑 OR

{ $or: [{ status: "active" }, { priority: "high" }] }

Supported by: All except 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: All except 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. 字段名不能：

   • 包含点号 (.)，除非用于引用嵌套字段
   • 以 $ 开头或包含空字符
   • 为空字符串

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 运算符：

   • 必须为对象
   • 不能为空
   • 可在字段层级或顶层使用
   • 有效：{ "$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 向量，才能将其包含在过滤结果中
• 数据集非常大时（~1000 万以上向量），范围查询的准确度可能降低

libSQL

• 支持使用点表示法查询嵌套对象
• 会验证数组字段是否包含有效 JSON 数组
• 数值比较会保持正确的类型处理
• 可妥善处理条件中的空数组
• 元数据存储在 JSONB 列中，以实现高效查询

OracleDB

• 元数据以 Oracle JSON 形式与每个 VECTOR 行一同存储
• 标量比较使用 JSON_VALUE，数组、存在性和元素匹配检查使用 JSON_EXISTS
• $regex 使用 Oracle REGEXP_LIKE；字符串 $contains 使用不区分大小写的 LIKE
• 支持使用点表示法的嵌套字段，并会转换为带引号的 Oracle JSON 路径
• 用户提供的元数据值会作为参数绑定，而非插入 SQL 中

PgVector

• 完整支持 PostgreSQL 原生 JSON 查询功能
• 使用原生数组函数高效处理数组操作
• 正确处理 number、string 和 boolean 类型
• 在内部使用 PostgreSQL JSON 路径语法查询嵌套字段
• 元数据存储在 JSONB 列中，以实现高效索引

Pinecone

• 元数据字段名最多 512 个字符
• 数值必须在 ±1e38 范围内
• 元数据中的数组总大小限制为 64KB
• 嵌套对象会通过点表示法扁平化
• 更新元数据会替换整个元数据对象

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

• 完整支持用于 metadata filter 的 MongoDB/Sift 查询语法
• 支持所有标准比较、数组、逻辑和元素 operator
• 支持 metadata 中的嵌套字段和数组
• 可以分别使用 filter 和 documentFilter 选项对 metadata 和原始文档内容应用过滤
• filter 应用于 metadata 对象；documentFilter 应用于原始文档字段
• 不人为限制 filter 的大小或复杂度（仍受 MongoDB 查询限制）
• 建议为 metadata 字段创建索引，以获得最佳性能

Couchbase

• 目前不支持 metadata filter。必须在检索结果后由 client 端完成过滤；对于更复杂的查询，也可以直接使用 Couchbase SDK 的 Search 功能。

Amazon S3 Vectors

• 等值必须为基本类型（string/number/boolean）。等值比较不允许使用 null/undefined、数组、对象和 Date。范围 operator 接受数字或 Date（Date 会归一化为 epoch 毫秒）。
• $in/$nin 要求使用非空的基本类型数组；允许 Date 元素，并会归一化为 epoch 毫秒。不支持数组等值比较。
• 隐式 AND 会被规范化（{a:1,b:2} → {$and:[{a:1},{b:2}]）。逻辑 operator 必须包含字段条件并使用非空数组。它们只能出现在根级别或其他逻辑 operator 内部，不能出现在字段值内部。
• 创建索引时列入 nonFilterableMetadataKeys 的键会被存储，但不可用于过滤。该设置不可变更。
• $exists 要求 boolean 值。
• undefined/null/空 filter 会被视为未设置 filter。
• 每个 metadata key 名称最多 63 个字符。
• 每个 vector 的 metadata 总量：最多 40 KB（可过滤与不可过滤部分合计）
• 每个 vector 的 metadata key 总数：最多 10 个
• 每个 vector 的可过滤 metadata：最多 2 KB
• 每个 vector index 的不可过滤 metadata key：最多 10 个

相关内容

• Astra
• Chroma
• Cloudflare Vectorize
• libSQL
• MongoDB
• OracleDB
• PgStore
• Pinecone
• Qdrant
• Upstash
• Amazon S3 Vectors