> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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: 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()` 为要过滤的字段创建索引：

```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

- 完整支持用于 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](https://mastra.zisheng.pro/reference/vectors/astra)
- [Chroma](https://mastra.zisheng.pro/reference/vectors/chroma)
- [Cloudflare Vectorize](https://mastra.zisheng.pro/reference/vectors/vectorize)
- [libSQL](https://mastra.zisheng.pro/reference/vectors/libsql)
- [MongoDB](https://mastra.zisheng.pro/reference/vectors/mongodb)
- [OracleDB](https://mastra.zisheng.pro/reference/vectors/oracledb)
- [PgStore](https://mastra.zisheng.pro/reference/vectors/pg)
- [Pinecone](https://mastra.zisheng.pro/reference/vectors/pinecone)
- [Qdrant](https://mastra.zisheng.pro/reference/vectors/qdrant)
- [Upstash](https://mastra.zisheng.pro/reference/vectors/upstash)
- [Amazon S3 Vectors](https://mastra.zisheng.pro/reference/vectors/s3vectors)