条件过滤
条件过滤允许你根据标量字段的特定条件检索 Document — 类似于 SQL 中的 WHERE 子句。
性能注意事项
- 已索引的标量字段：可以被高效搜索。
- 未索引的标量字段：仍然可以搜索，但性能会显著降低。
为了获得最佳性能，请确保常用的过滤字段已建立索引。
更多详情请参阅倒排索引。
前提条件
本指南假设你已经打开了一个包含标量字段的 Collection。
执行条件过滤
通过将 filter 表达式传递给 query() 方法来应用条件过滤。
该表达式使用类 SQL 语法来定义搜索条件。
topk 参数指定返回的最大匹配 Document 数量。
如果满足过滤条件的 Document 数量超过指定的 topk，则只返回前 topk 个结果。
结果不保证有特定顺序（通常按内部存储顺序返回）。
import zvec
# 1. 检索最多 10 个 2000 年出版的 Document
results = collection.query(filter="publish_year = 2000", topk=10)
# 2. 检索最多 50 个 1999 年之前出版的 Document
results = collection.query(filter="publish_year < 1999", topk=50)
# 3. 检索所有有库存的项目（假设 Collection 有 ≤100 个 Document）
results = collection.query(filter="in_stock = true", topk=100)
# 4. 浪漫或悬疑类书籍（最多 20 个匹配）
results = collection.query(filter="category CONTAIN_ANY('romance', 'mystery')", topk=20)
# 5. 同时属于科学和哲学类别的书籍
results = collection.query(filter="category CONTAIN_ALL('science', 'philosophy')", topk=10)
# 6. 2015 年及之后的有库存浪漫类书籍
results = collection.query(
filter="publish_year >= 2015 AND in_stock = true AND category CONTAIN_ANY('romance')",
topk=30,
output_fields=["summary"], # 仅返回 'summary' 字段
)带 filter 的 query() 方法返回匹配的 Doc 对象列表。
每个 Doc 对象包括：
id：Document 标识符。vectors：向量字段名称到对应 Embedding 值的映射。
仅在查询中传入include_vector=True时才会填充。fields：标量字段名称到存储值的映射。
默认返回所有标量字段；可通过output_fields参数限制返回的字段。
支持的过滤语法
比较运算符
| 运算符 | 描述 | 支持的数据类型 | 示例表达式 |
|---|---|---|---|
< | 小于 | 整数, 浮点数, 字符串 | publish_year < 2000 |
<= | 小于或等于 | 整数, 浮点数, 字符串 | • price <= 29.99 • author_name <= 'M' |
= | 等于 | 整数, 浮点数, 字符串, 布尔值 | • in_stock = true • name = 'Michael' |
!= | 不等于 | 整数, 浮点数, 字符串, 布尔值 | • rating != 5 • status != 'active' |
>= | 大于或等于 | 整数, 浮点数, 字符串 | score >= 85.5 |
> | 大于 | 整数, 浮点数, 字符串 | age > 12 |
is null | 检查字段是否没有值 | 所有数据类型 | email is null |
is not null | 检查字段是否有值 | 所有数据类型 | email is not null |
- 字符串比较使用字典序：
'apple' < 'banana'的结果为true - 字符串字面量必须用单引号（
'）或双引号（"）括起来：'hello world' - 布尔比较使用关键字
true和false（不区分大小写） - 范围查询：当
enable_range_optimization设置为true时，范围查询运行效率更高。如果为false，它们仍然有效 — 但可能会显著变慢。
成员运算符
| 运算符 | 描述 | 支持的数据类型 | 示例表达式 | 说明 |
|---|---|---|---|---|
in | 属于其中之一 | 整数, 浮点数, 字符串 | • error_code in (400, 403, 404) • user_name in ('admin', 'root') | 如果字段值匹配任一列出的值，则为 true。• error_code 是 400、403 或 404 → true • user_name 是 'admin' 或 'root' → true |
not in | 不属于其中任何一个 | 整数, 浮点数, 字符串 | status not in ('deleted', 'archived') | 如果字段值不匹配任何列出的值，则为 true。• status 不是 'deleted' 或 'archived' → true |
contain_all | 数组包含所有列出的值 | 数组类型 | tags contain_all ('urgent', 'bug') | 仅当数组包含列表中的每个值时才为 true。• tags = ['bug', 'urgent', 'ui'] → true • tags = ['bug', 'ui'] → false（缺少 'urgent'） |
contain_any | 数组包含至少一个列出的值 | 数组类型 | permissions contain_any ('execute', 'write') | 如果数组包含至少一个列出的值则为 true。• permissions = ['admin', 'execute'] → true • permissions = ['read', 'forbidden'] → false（既没有 'execute' 也没有 'write'） |
array_length | 数组长度 | 数组类型 | array_length(tags) > 2 | 如果数组的长度满足条件则为 true。• tags = ['bug'] → false（长度为 1） • tags = ['bug', 'urgent', 'fix'] → true（长度为 3） |
- 值列表周围必须使用括号
()。 - 字符串字面量必须用单引号（
'）或双引号（"）括起来：'hello world'
字符串运算符
| 运算符 | 描述 | 支持的数据类型 | 示例表达式 | 说明 |
|---|---|---|---|---|
like | 使用通配符的模式匹配 | 字符串 | • product_name like 'Smart%' • file_name like '%.log' | • 'Smart%'：匹配以 'Smart' 开头的值（例如 'SmartPhone'、'SmartWatch'） • '%.log'：匹配以 '.log' 结尾的值（例如 'app.log'、'debug_2025.log'） |
性能注意事项：
为了获得最佳的 LIKE 查询性能，字段应该已建立索引。
- 未索引的字段仍然支持过滤，但查询可能会显著变慢。
- 对于高效的中缀/后缀模式（
'abc%def'、'%abc'），请配置倒排索引并设置enable_extended_wildcard = true选项。 - 包含多个通配符的模式（例如
'%abc%def%'）本质上开销较大，应谨慎使用。
逻辑运算符
| 运算符 | 描述 | 示例表达式 | 说明 |
|---|---|---|---|
and | 逻辑与 | status = 'active' and score > 90 | 仅当所有条件都为 true 时才为 true。 |
or | 逻辑或 | role = 'admin' or permission = 'write' | 如果至少一个条件为 true 则为 true。 |
提示：使用括号 () 来分组表达式并控制求值顺序，例如 expr1 and (expr2 or expr3)。