filter 传入过滤器，即可按元数据匹配文档。
{ "team": "support", "year": { "$gte": 2024 } }
运算符
| 运算符 | 匹配 |
|---|---|
{ "key": value }、$eq | 等于该值；对于数组，包含该值 |
$in | 等于列表中的任一值 |
$ne、$nin | 不等于该值，或不等于列表中的任何值（仅限搜索） |
$gt、$gte、$lt、$lte | 大于、大于等于、小于、小于等于 |
$and、$or | 满足过滤器列表中的全部或任一条件 |
示例
| 过滤器 | 匹配 |
|---|---|
{ "tags": "billing" } | tags 数组包含 billing 的文档 |
{ "lang": { "$in": ["en", "de"] } } | 英语或德语文档 |
{ "$or": [{ "team": "support" }, { "year": { "$in": [2024, 2025] } }] } | 支持团队的文档，或 2024 年、2025 年的任意文档 |
{ "published_at": { "$gte": "2025-06-01" } } | 2025 年 6 月 1 日或之后发布的文档 |
{ "file_id": "report.pdf" } | 某个已上传文件 |
{ "file_id": "report.pdf", "page": 3 } | 该文件的第 3 页 |
规则
| 规则 | |
|---|---|
| 相等 | 按文本比较：3、3.0 和 "3" 彼此匹配 |
| 范围 | 数字与数字、字符串与字符串逐字节比较；日期请使用统一格式的 ISO 8601（2025-06-01 或 2025-06-01T10:00:00Z） |
| 不参与范围比较 | 布尔值、数组元素和超过 222 字节的字符串 |
| 缺失的键 | 不含该键的文档会匹配 $ne 和 $nin |
| 否定条件 | 排除大多数文档的否定条件可能返回少于 top_k 的结果 |
| 大小 | 最多 256 个条件，最多嵌套 8 层；每个 $and、$or 和多值 $in 计为一个 |
| 列表 | $in 和 $nin 最多接受 255 个值 |
| 未知的键 | 不做检查：拼错的键不会匹配任何内容 |
| 错误 | 无效的过滤器返回 400 invalid_filter |