标量过滤--向量数据库VikingDB-火山引擎

文档中心

立即注册

导航

标量过滤

最近更新时间：2025.01.10 19:13:06首次发布时间：2025.01.10 19:13:06

您可通过标量过滤器（Filter）在向量数据库中限定结果范围。

说明

标量过滤是通用检索能力，您可以将其应用在向量近邻检索、稠密稀疏混合近邻检索等检索方式中。

请求接口

说明

请求向量数据库 VikingDB 的 OpenAPI 接口时，需要构造签名进行鉴权，详细的 OpenAPI 签名调用方法请参见 API签名调用指南。

URI	/api/index/search	统一资源标识符
请求方法	POST	客户端对向量数据库服务器请求的操作类型
请求头	Content-Type: application/json	请求消息类型
请求头	Authorization: HMAC-SHA256 ***	鉴权

请求参数

在向量检索接口的基础上，您可以使用 filter 子参数进行过滤。

参数	子参数	类型	是否必选	默认值	参数说明
search	filter	map	是		过滤条件，详见 filter 表达式说明。默认为空，不做过滤。过滤条件包含 must、must_not、range、range_out四类查询算子，包含 and 和 or 两种对查询算子的组合。注意 filter的前提条件是：相应字段开启了标量索引。

参数

子参数

类型

是否必选

默认值

参数说明

filter

map

是

过滤条件，详见 filter 表达式说明。

默认为空，不做过滤。
过滤条件包含 must、must_not、range、range_out四类查询算子，包含 and 和 or 两种对查询算子的组合。

注意

filter的前提条件是：相应字段开启了标量索引。

filter 表达式

算子	算子说明	示例
must	针对指定字段名生效，语义为必须在 [...] 之中，即 "must in"。	`{ "op": "must", "field": "region", "conds": ["cn", "sg"] }`
must_not	针对指定字段名生效，语义为必须不在 [...] 之中，即 "must not in"。	`{ "op": "must_not", "field": "data_type", "conds": [1,2,3] }`
range	针对指定字段名生效，语义为必须在指定范围内。配置使用`gte`（大于等于）, `gt`（大于）, `lte`（小于等于）, `lt`（小于），用以圈定一维范围。另外，支持用 `center` 和 `radius` 表示二维圆内范围。	`// price 在 [100.0, 500.0) { "op": "range", "field": "price", "gte": 100.0, "lt": 500.0 } //price >= 100.0 { "op": "range", "field": "price", "gte": 100.0 } // 以 center 为中心，半径为50的圆内 { "op": "range", "field": ["pos_x", "pos_y"], "center": [100.0, 123.4], "radius": 50.0 }`
range_out	针对指定字段名生效，语义为必须在指定范围外。配置使用`gte`（大于等于）, `gt`（大于）, `lte`（小于等于）, `lt`（小于），用以圈定一维范围。	`// 筛选价格低于100或高于500的商品 { "op": "range_out", "field": "price", "gt": 500.0, "lt": 100.0 }`
and	逻辑算子，针对逻辑查询需求，对多个条件取交集。	`{ "op": "and", // 算子名 "conds": [ // 条件列表，支持嵌套逻辑算子和 must/must_not 算子 { "op": "must", "field": "type", "conds": [1] }, { ... // 支持>=1的任意数量的条件进行组合 } ] }`
or	逻辑算子，针对逻辑查询需求，对多个条件取并集。	`{ "op": "or", // 算子名 "conds": [ // 条件列表，支持嵌套逻辑算子和 must/must_not 算子 { "op": "must", "field": "type", "conds": [1] }, { ... // 支持>=1的任意数量的条件进行组合 } ] }`

响应消息

参数	参数说明
code	状态码
message	返回信息
request_id	标识每个请求的唯一标识符
data	检索结果，标量过滤检索会返回检索到的主键、score、fields。

状态码说明

状态码	http状态码	返回信息	状态码说明
0	200	drop index success	Index 检索成功。
1000008	400	index not exist	指定的 Index 不存在。
1000003	400	invalid request	非法参数：缺失必选参数。缺乏检索输入。不满足约束条件。
1000001	401	unauthorized	请求头中缺乏鉴权信息。
1000002	403	no permission	权限不足。
1000016	400	invalid vectors for index_recall	输入的向量格式不合法。
1000029	429	请求已达上限, 请调整CPU核数	需要调大 cpu_quota

完整示例

请求消息

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/index/search \
  -d '{
    "collection_name": "test_name",
    "index_name": "index_test",
    "search": {
        "order_by_vector": {
            "vectors": [
                [0.1, 0.2, 0.3......0.9], 
                [0.01, 0.02, 0.03......0.09],
            ],
            "sparse_vectors": [
                {"什么": 0.34, "是": 0.03, "B": 0.11, "M":0.32, "25": 0.03}, 
                {"一": 0.08, "种": 0.14, " 信息": 0.19, " 检索": 0.63, " 算法":0.97} 
            ]            
        }, 
        "limit": 2,   
        "dense_weight": 0.5,  
        "filter": {     // 过滤条件，限制查询结果
          "op": "must",    //过滤操作类型，这里表示结果必须符合条件
          "field": "region",     //过滤的字段名称
          "conds": ["cn", "sg"]    // 过滤值，必须匹配 "cn" 或 "sg"
        }
        "partition": "default"     //子索引名称，对应 field 的值
    }
}'

响应消息

执行成功返回：

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
 
{
    "code":0,
    "msg":"search success",
    "request_id":"021695029757920fd001de6666600000000000000000002569b8f",
    "data": [
        [
            {
                "id": 1,
                "score": 0.99,
                "fields": {
                    "time": 1690529704,
                    "author": "zhangsan"
                } 
            },
            {
                "id": 2,
                "score": 0.98,
                "fields": {
                    "time": 1690529701,
                    "author": "lisi"
                } 
            }
        ],
        [
            {
                "id": 9,
                "score": 0.95,
                "fields": {
                    "time": 1690529708,
                    "author": "wangwu"
                } 
            },
            {
                "id": 8,
                "score": 0.84,
                "fields": {
                    "time": 1690529710,
                    "author": "zhaoliu"
                } 
            }            
        ]
    ]
}

执行失败返回：

HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
 
{"code":1000008, "msg":"index not exist", "request_id":"021695029757920fd001de6666600000000000000000002569b8f"}