Filter过滤条件表达式语法

更新时间：2025-01-15

什么是Filter过滤条件表达式

在向量检索中，VectorDB支持指定一个表达式形式的Filter参数，用来确保后端数据库在执行检索时，仅检索满足Filter表达式条件的数据记录。通过支持带Filter过滤条件，VectorDB能够实现精细的标量/向量混合检索，支持各类业务的多样性检索需求。

在VectorDB的HTTP API中，Filter过滤条件表达式表示为如下类似形式："filter": "FieldA == 'Aa'"；在Python SDK中，Filter过滤条件表达式作为一个检索参数存在，参数取值表示为如下类似形式：filter = "FieldA == 'Aa'"。

Filter过滤条件表达式的基础语法

Filter过滤条件表达式的语法遵循SQL的WHERE子句表达式语法，是其语法的子集，非常直观易懂。

Filter过滤条件表达式基础语法包含2种形式：

<$field_name><$operator><$value>：简单标量字段的表达式；
<$array_field_name[idx]><$operator><$value>：数组字段的表达式。

也支持表达式的组合，多个子表达式之间支持通过AND（与）、OR（或）以及NOT（非）进行组合来构建更加复杂的表达式。。

表达各个部分的语法说明如下：

<$field_name>：表示常规标量字段的名称。
<$array_field_name[idx]>：其中array_field_name表示数组字段的名称，idx表示该数组字段的第idx个元素，从0开始编号。
<$operator>：表示表达式运算符，支持相等（=、==）、不等于（!=、<>）、大于（>）、大于等于（>=）、小于（<），小于等于（<=）和IN操作符。
<$value>：表示目标字段的取值。根据字段类型的不同，值的表示方法也有所不同：
- 整型值：常规表示，例如100、-123
- 字符串类型：头尾使用英文单引号括起来，例如'HelloWord'
- 日期/时间：同字符串类型，例如'2024-03-20T16:30:00Z'
- 布尔值：也表示为字符串，但是仅支持'True'、'true'、'False'、'false'四种形式，其中'True'等价于'true'，'False'等价于'false'
- 二进制类型：同字符串类型，但是必须采用base64编码

IN操作符语法说明如下：

语法：<$field_name> IN ($value1, $value2, ...)，表示该字段取值只要是后面数组中的任意一个值即可。

组合操作符的语法说明如下：

AND：与操作，例如<$expr1> AND <$expr2>，表示同时满足expr1和expr2的条件。
OR：或操作，例如<$expr1> OR <$expr2>，表示expr1和expr2这两个条件只需满足其一即可。
NOT：非操作，例如NOT <$expr1>，表示将expr1的结果进行取反，要求满足取反之后的条件。

通过合理使用括号，可以支持带运算符优先级的复杂表达式，例如：

FieldA == 'Aa' AND FieldB >= 100
(FieldA == 'Aa' OR FieldC == 'Cc') AND FieldB != 0
((FieldA == 'Aa' OR FieldC != 'Cc') AND FieldX == 'true')) OR FieldY >= '2024-01-01T00:00:00Z'
fieldA IN ('男', '女') AND fieldB > 35
('arrayField[0] == 'AAA') OR ('arrayField[1] == 'aaa')

Filter过滤条件表达式的数组算子语法

Filter过滤条件表达式中的数组类型算子语法形式为<$operator>(<$field_name>, [$element1, $element2, ...])，表达式各个部分的语法说明如下：

<$operator>：算子名称
<$field_name>：数组字段的名称
[$element1, $element2, ...]：条件数组，包含一个或多个元素

数组类型支持如下3类算子：

array_contains_any：条件数组中的元素，只要有任意一个出现在目标字段的数组中，即认为满足条件，否则认为不满足条件，例如：array_contains_any(arrayField1, [123, 456, 789])；
array_contains_all：条件数组中的元素，要求所有元素都出现在目标字段的数组中，才认为满足条件，否则认为不满足条件，例如：array_contains_all(arrayField2, ['A', 'a']);
array_contains：该算子是上述算子的特例，条件数组只能填1个元素，该元素若出现在目标字段的数组中时，则认为满足条件，否则认为不满足条件，例如：array_contains(arrayField3, 'Hello VectorDB')。

Filter过滤条件表达式的使用限制

Filter过滤条件表达式在使用中仍然存在一些限制，说明如下：

IN操作符右侧的值数组不可以为空：若值数组为空，则意味着目标字段不能取任何值，说明这是一个无意义的条件，VectorDB会直接报错。
数组字段及其过滤表达式仅在>=2.1版本中支持：若您的实例不支持数组及相应的表达式语法，请联系我们进行升级。

带标量过滤条件的向量检索

向量索引

向量数据库 VectorDB