向量数据库 Filter 表达式

条件表达式是一种用于筛选文档的查询条件。它可以根据文档中的字段值来进行筛选。通常，条件表达式由一个或多个条件组成，每个条件包括一个字段名、一个比较运算符和一个值。
说明：
新增 IS NULL 与 IS NOT NULL 语法支持，覆盖所有主要标量索引类型（uint64, string, array, json）。对于 JSON 字段，使用 a.b 的形式进行单层属性路径的空值判断，满足常见的数据筛选需求，允许用户精确筛选出字段值为空 (NULL) 或非空（有具体值）的数据记录。
逻辑运算表达式
腾讯云向量数据库（Tencent Cloud VectorDB）所支持的逻辑运算符包括 and、or、not，如下表所示。
运算符
描述
示例
and
与
game_tag = "Robert" and (video_tag = "dance" or video_tag = "music")
or
或
game_tag = "1000" or video_tag = "dance"
not
非
game_tag = "1000" and not( video_tag = "dance")
字符串类型表达式
字符串类型的值必须要用英文双引号括起来。字符串类型可以用单值或多值匹配。腾讯云向量数据库当前所支持的运算符如下表所示。
运算符
描述
示例
in
匹配任意一个字符串值
game_tag in("Detective","Action Roguelike","Party-Based RPG","1980s")
not in
排除所有字符串值
game_tag not in ("Detective")
=
匹配单个字符串值
game_tag = "Detective"
!=
排除单个字符串值
game_tag != "Detective"
数值类型表达式
腾讯云向量数据库标量索引字段的数值类型当前仅支持 uint64，暂不支持负数和浮点型。如有需求，可以把负数和浮点型转换成整型。所支持的运算符，如下表所示。
运算符
描述
示例
>
大于
exipred_time > 1623388524
>=
大于等于
exipred_time >= 1623388524
=
等于
exipred_time = 1623388524
<
小于
exipred_time < 1623388524
<=
小于等于
exipred_time <= 1623388524
!=
不等于
exipred_time != 1623388524
in
匹配任意一个数值
exipred_time in (1, 2)
not in
排除所有字符串值
exipred_time not in (1, 2)
数组（Array）类型表达式
数据类型目前仅支持数组元素为 string 类型。具体运算符，请参见下表。
运算符
描述
示例
include
包含数组元素之一
name include (\\"Bob\\", \\"Jack\\")
exclude
排除数组元素之一
name exclude (\\"Bob\\", \\"Jack\\")
include all
全包含数组元素
name include all (\\"Bob\\", \\"Jack\\")
JSON 类型表达式
json 类型是一种由键值对组成的数据对象，使用花括号{}进行包裹。在 json 对象中，键（Key）和值（Value）通过冒号（:）连接。例如，json 类型的对象 a 的写入格式为"a": {"b": "test", "c": 12}。若访问 json 对象中的键，使用点（.）符号连接。例如，对象 a 中的字段 b 可以通过 a.b 表示。
说明：
json 字段的键（Key）命名规则：仅允许使用字母、数字及下划线（_）组成键名，且键名必须以字母或下划线开头，不得以数字开头。
json 类型字段在进行 Filter 检索时，支持的条件表达式语法和 json 字段的键值类型保持一致，支持的数据类型包括 string、uint64 和 array。若键值为 string 类型，Filter 表达式仅支持 string 类型的运算符。例如，写入格式为"a": {"b": "test", "c": 12}的文档，字段 a.b 为 string 类型，Filter 表达式仅支持 string 类型所允许的 in、not in、=、!= 操作符，也只能与另一个 string 类型的字符串进行比较。类型 uint64，则仅支持数值类型表达式，也只能与另一个 uint64 类型的整数进行比较。
注意：
向量数据库写入 json 类型时，不支持在 json 字段值中嵌套字典结构，也无法对嵌套结构内部的字段进行单独检索。例如，
“a'：｛b”：｛c1"："test1"，"c2"："test2"｝｝。其中，字段 b 嵌套了一层 Json 结构 ｛c1"："test1"，"c2"： "test2"｝，在写入时将提示错误信息，写入失败。
数据类型
json 示例
Filter 表达式示例
string
{
  "a": {
      "b": "test",
      "c": 12
  }
}
a.b != "demo"
a.b = "test"  
a.b in ("test", "example", "hello")
a.b not in ("error", "invalid", "null")
uint64
{
    "data": {
        "id": 184467,  
        "count": 100
    }
}
data.id = 184467
data.count > 50  
data.count in (100, 200, 300)
array
{
    "user": {
        "name": "Bob",
        "hobbies": ["gaming", "reading"],
    }
}
user.name include (\\"Bob\\", \\"Jack\\")
user.hobbies include all (\\"gaming\\", \\"reading\\")
应用示例
本文给出过滤检索的请求示例，帮助您直观地了解过滤检索的方式。如下示例，使用 /document/search 接口，综合检索满足bookName字段条件表达式（"bookName in (\\"三国演义\\",\\"西游记\\")"），与指定向量"vectors": [[0.3123,0.43,0.213]]最相似的 Top3 的数据。
curl -i -X POST \\
  -H 'Content-Type: application/json' \\
  -H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\
  http://10.0.X.X:80/document/search \\
  -d '{
    "database": "db-test",
    "collection": "book-vector",
    "search": {
        "vectors": [
            [
                0.3123,
                0.43,
                0.213
            ]
        ],
        "params": {
            "ef": 200
        },
        "retrieveVector": true,
        "filter": "bookName in (\\"三国演义\\",\\"西游记\\")",
        "limit": 3
    }
}'
最终返回满足过滤条件最相近的文档数据，结果如下所示：
说明：
每一个查询结果按照相似程度由高到低逐级排列，且均返回 Top K 条相似度计算的结果。其中，K 为 limit 设置的数值。如果检索的数据不足 K 条，则返回实际的 Document 数量。
{
  "code": 0,
  "msg": "Operation success",
  "documents": [
    [
      {
        "id": "0001",
        "vector": [
          0.21230000257492066,
          0.23000000417232514,
          0.21299999952316285
        ],
        "score": 0.97142,
        "bookName": "三国演义",
        "page": 21,
        "author": "罗贯中"
      },
      {
        "id": "0002",
        "vector": [
          0.21230000257492066,
          0.2199999988079071,
          0.21299999952316285
        ],
        "score": 0.96688,
        "bookName": "西游记",
        "author": "吴承恩",
        "page": 22
      }
    ]
  ]
}

运算符	描述	示例
and	与	game_tag = "Robert" and (video_tag = "dance" or video_tag = "music")
or	或	game_tag = "1000" or video_tag = "dance"
not	非	game_tag = "1000" and not( video_tag = "dance")

数据类型	json 示例	Filter 表达式示例
string	{ "a": { "b": "test", "c": 12 } }	a.b != "demo" a.b = "test" a.b in ("test", "example", "hello") a.b not in ("error", "invalid", "null")
uint64	{ "data": { "id": 184467, "count": 100 } }	data.id = 184467 data.count > 50 data.count in (100, 200, 300)
array	{ "user": { "name": "Bob", "hobbies": ["gaming", "reading"], } }	user.name include (\\"Bob\\", \\"Jack\\") user.hobbies include all (\\"gaming\\", \\"reading\\")

Filter 表达式

本页目录：

逻辑运算表达式

字符串类型表达式

数值类型表达式

数组（Array）类型表达式

JSON 类型表达式

应用示例