什么是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, ...)，表示该字段取值只要是后面数组中的任意一个值即可。

LIKE操作符语法说明如下：

• 语法：<$field_name> [NOT] LIKE $expression
• $expression 为字符串表达式，支持 % 匹配0至多个任意字符，_ 匹配1个任意字符。

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

• 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')。

JSON 类型数据过滤表达式

版本支持说明

JSON 数据类型及其过滤表达式功能自 2.2 版本起提供完整支持。

数据示例

在介绍过滤表达式时，以如下的 JSON 文档作为数据示例：

1{
2    "header": "Viewer",
3    "items": [
4        {"id": "Open"},
5        null,
6        {"id": "ZoomIn", "width": 300},
7        {"id": "Search", "ignore case": true}
8    ],
9    "keys": {
10        "C-.": "Jump"
11    },
12    "files": ["a", "b", "c"]
13}

支持的表达式类型

元素访问操作

提供两种等效的路径访问方式：

1. 下标表示法

1字段名[路径组件]

示例：

• json_field['header'] → "Viewer"
• json_field['items'][0]['id'] → "Open"
• json_field['items'][1] → null

2. 函数表示法

1json_extract_value(字段名, 路径表达式)

示例：

• json_extract_value(json_field, '$.header') → "Viewer"
• json_extract_value(json_field, '$.items[0].id') → "Open"
• json_extract_value(json_field, '$.items[1]') → null

元素存在性判断

1json_path_exists(字段名, 路径表达式)

若 JSON 路径存在，返回 true，否则返回 false。

示例：

• json_path_exists(json_field, '$.items') → true
• json_path_exists(json_field, '$.items[1]') → true
• json_path_exists(json_field, '$.items[4]') → false

比较操作符

支持通过路径访问 JSON 中的特定元素，并构建布尔表达式。支持的运算符：

示例：

• json_field['header'] = 'Viewer' → true
• json_field['items'][2]['width'] > 200 → true
• json_field['items'][3]['ignore case'] = true → true
• json_field['items'][1] IS NULL → true
• json_field['items'][1] IS NOT NULL → false

注意事项：

1. 如果路径不存在，比较操作将返回 false，例如：

   • json_field['items'][4] = 0 → false
   • json_field['items'][4] != 0 → false

2. 禁止将 JSON 元素与 null 直接进行比较，应该使用 IS NULL 或 IS NOT NULL。以下为非法表达式：

   • json_field['items'] = NULL
   • json_field['items'][1] = NULL

3. 表达式 json_field['items'][1] IS NOT NULL 只有在以下条件全部满足时才返回 true：

   • json_field['items'][1] 存在
   • json_field['items'][1] 的值不是 null

否则，IS NOT NULL 返回 false。

组合操作符

支持使用 AND、OR、NOT 和括号，合成复杂表达式，例如：

• arr_field[0] == 'AAA' OR (json_path_exists(json_field, '$.items[1]') AND json_field['items'][1] IS NOT NULL)

数组算子

支持对 JSON 中的数组元素进行过滤。支持如下算子：

• json_array_contains(字段名，路径表达式，元素)：元素若出现在目标数组中，则认为满足条件，否则认为不满足条件。
• json_array_contains_any(字段名，路径表达式，[元素1, 元素 2, ...])：若列表中的任意元素出现在目标数组中，则认为满足条件，否则认为不满足条件。
• json_array_contains_all(字段名，路径表达式，[元素1, 元素 2, ...])：若列表中的每个元素都出现在目标数组中，则认为满足条件，否则认为不满足条件。

示例：

• json_array_contains(json_field, '$.header', 'a') → false (如果路径指向的元素不是数组，则返回 false)
• json_array_contains(json_field, '$.files', 'a') → true
• json_array_contains(json_field, '$.files', 'd') → false
• json_array_contains_any(json_field, '$.files', ['a', 'd']) → true
• json_array_contains_all(json_field, '$.files', ['a', 'd']) → false

路径表达式语法

基础语法

路径表达式包含以下符号：

要求路径表达式必须以 "$" 开始，例如 $.items[0].id。

特殊字符处理

如果路径表达式的键名包含特殊字符如 $、.、[、]，需要为其加上双引号，例如 $.keys."C-."。

普通的键名也可以加上双引号，例如上面的例子也可以写为 $."keys"."C-."。

双引号中的反斜杠 \ 作为转义字符。转义规则与 JSON 相同（请参阅 RFC 8259）。以下是支持的转义字符：

反斜杠后跟其他任何字符（除了上表列出的）都是不合法的路径表达式。

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

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

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