元数据过滤器

🌐 Metadata Filters

Mastra 提供了一种统一的元数据过滤语法，适用于所有向量存储，基于 MongoDB/Sift 查询语法。每个向量存储将这些过滤器转换为其原生格式。

🌐 Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into their native format.

基本示例

🌐 Basic Example

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
  },
});

支持的运算符

🌐 Supported Operators

基本比较

$eq

Matches values equal to specified value

{ age: { $eq: 25 } }

Supported by: All except Couchbase

$ne

Matches values not equal

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

Supported by: All except Couchbase

$gt

Greater than

{ price: { $gt: 100 } }

Supported by: All except Couchbase

$gte

Greater than or equal

{ rating: { $gte: 4.5 } }

Supported by: All except Couchbase

$lt

Less than

{ stock: { $lt: 20 } }

Supported by: All except Couchbase

$lte

Less than or equal

{ priority: { $lte: 3 } }

Supported by: All except Couchbase

数组运算符

$in

Matches any value in array

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

Supported by: All except Couchbase

$nin

Matches none of the values

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

Supported by: All except Couchbase

$all

Matches arrays containing all elements

{ tags: { $all: ["urgent", "high"] } }

Supported by: Astra, Pinecone, Upstash, MongoDB

$elemMatch

Matches array elements meeting criteria

{ scores: { $elemMatch: { $gt: 80 } } }

Supported by: libSQL, PgVector, MongoDB

逻辑运算符

$and

Logical AND

{ $and: [{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }

Supported by: All except Vectorize, Couchbase

$or

Logical OR

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

Supported by: All except Vectorize, Couchbase

$not

Logical NOT

{ price: { $not: { $lt: 100 } } }

Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB

$nor

Logical NOR

{ $nor: [{ status: "deleted" }, { archived: true }] }

Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB

元素运算符

$exists

Matches documents with field

{ rating: { $exists: true } }

Supported by: All except Vectorize, Chroma, Couchbase

自定义运算符

$contains

Text contains substring

{ description: { $contains: "sale" } }

Supported by: Upstash, libSQL, PgVector

$regex

Regular expression match

{ name: { $regex: "^test" } }

Supported by: Qdrant, PgVector, Upstash, MongoDB

$size

Array length check

{ tags: { $size: { $gt: 2 } } }

Supported by: Astra, libSQL, PgVector, MongoDB

$geo

Geospatial query

{ location: { $geo: { type: "radius", ... } } }

Supported by: Qdrant

$datetime

Datetime range query

{ created: { $datetime: { range: { gt: "2024-01-01" } } } }

Supported by: Qdrant

$hasId

Vector ID existence check

{ $hasId: ["id1", "id2"] }

Supported by: Qdrant

$hasVector

Vector existence check

{ $hasVector: true }

Supported by: Qdrant

常规规则和限制

🌐 Common Rules and Restrictions

1. 字段名称不能：
   • 包含点（.），除非指的是嵌套字段
   • 以 $ 开头或包含空字符
   • 为空字符串
2. 值必须为：
   • 有效的 JSON 类型（字符串、数字、布尔值、对象、数组）
   • 非未定义
   • 为操作符正确输入类型（例如，数字用于数字比较）
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 }] }

存储专用说明

🌐 Store-Specific Notes

阿斯特拉

🌐 Astra

• 使用点符号支持嵌套字段查询
• 数组字段必须在元数据中明确定义为数组
• 元数据值区分大小写

ChromaDB

• 只有当被筛选的字段存在于元数据中时，筛选器才会返回结果
• 空的元数据字段不会包含在筛选结果中
• 对于负匹配，元数据字段必须存在（例如，$ne 不会匹配缺少该字段的文档）

Cloudflare 向量化

🌐 Cloudflare Vectorize

• 在使用过滤功能之前需要明确的元数据索引
• 使用 createMetadataIndex() 来索引你想要筛选的字段
• 每个 Vectorize 索引最多 10 个元数据索引
• 字符串值会被索引到前64个字节（在UTF-8边界处截断）
• 数字值使用 float64 精度
• 过滤 JSON 必须小于 2048 字节
• 字段名称不能包含点（.）或以 $ 开头
• 字段名称限制为512个字符
• 在创建新的元数据索引后，向量必须重新更新，以便包含在筛选结果中
• 在非常大型的数据集（约1000万以上向量）中，范围查询的准确性可能降低

libSQL

• 支持使用点符号的嵌套对象查询
• 数组字段会被验证以确保它们包含有效的 JSON 数组
• 数值比较保持正确的类型处理
• 条件中的空数组会被优雅处理
• 元数据存储在 JSONB 列中以实现高效查询

PgVector

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

Pinecone

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

Qdrant

• 支持带有嵌套条件的高级过滤
• 有效载荷（元数据）字段必须明确编入索引以进行过滤
• 使用 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" },
});

• 高效处理地理空间查询
• 对空值和空字符串的特殊处理
• 矢量特定的过滤功能
• 日期时间值必须符合 RFC 3339 格式

Upstash

• 元数据字段键的上限为512个字符
• 查询大小有限（避免使用大的 IN 子句）
• 过滤器不支持 null/undefined 值
• 内部转换为类似 SQL 的语法
• 区分大小写的字符串比较
• 元数据更新是原子的

MongoDB

• 完全支持用于元数据筛选的 MongoDB/Sift 查询语法
• 支持所有标准的比较、数组、逻辑和元素运算符
• 支持元数据中的嵌套字段和数组
• 过滤可以分别使用 filter 和 documentFilter 选项应用于 metadata 和原始文档内容
• filter 适用于元数据对象；documentFilter 适用于原始文档字段
• 过滤器的大小或复杂性没有人工限制（受MongoDB查询限制约束）
• 建议对元数据字段进行索引以获得最佳性能

Couchbase

• 当前不支持元数据过滤。过滤必须在获取结果后由客户端进行，或通过直接使用 Couchbase SDK 的搜索功能来处理更复杂的查询。

亚马逊 S3 向量

🌐 Amazon S3 Vectors

• 等值必须是原始类型（字符串/数字/布尔值）。不允许使用 null/undefined、数组、对象和日期作为等值。范围操作符接受数字或日期（日期会被标准化为纪元毫秒）。
• $in/$nin 需要 非空的原始类型数组；允许使用日期元素，并会被标准化为纪元毫秒。不支持数组相等。
• 隐式 AND 已规范化（{a:1,b:2} → {$and:[{a:1},{b:2}]}）。逻辑运算符必须包含字段条件，使用非空数组，并且只能出现在根节点或其他逻辑运算符内（不能出现在字段值内部）。
• 在创建索引时列在 nonFilterableMetadataKeys 中的键会被存储，但无法用于过滤；此设置不可更改。
• $exists 需要一个布尔值。
• 未定义/空值/空过滤器将被视为无过滤器。
• 每个元数据键名最多限制为63个字符。
• 每个向量的总元数据：最高 40 KB（可过滤 + 不可过滤）
• 每个向量的元数据键总数：最多 10 个
• 每个向量的可筛选元数据：最多 2 KB
• 每个向量索引的不支持过滤的元数据键：最多 10 个

相关

🌐 Related

• Astra
• Chroma
• Cloudflare 向量化
• libSQL
• MongoDB
• PgStore
• Pinecone
• Qdrant
• Upstash
• Amazon S3 向量