You need to enable JavaScript to run this app.
文档中心
向量数据库VikingDB

向量数据库VikingDB

请输入
  • 文档首页
    • 向量数据库VikingDBVikingDB 向量库向量库历史版本（V1）API V1参考检索(Search)检索过滤能力标量过滤
复制全文
下载 pdf
我的收藏
检索过滤能力
标量过滤
复制全文
下载 pdf
我的收藏
标量过滤

您可通过标量过滤器（Filter）在向量数据库中限定结果范围。
标量过滤是通用检索能力，您可以通过在检索和聚合统计的相关接口中传入filter参数来启用标量过滤能力。

请求接口

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

URI

/api/index/search

统一资源标识符

请求方法

POST

客户端对向量数据库服务器请求的操作类型

请求头

Content-Type: application/json

请求消息类型

Authorization: HMAC-SHA256 ***

鉴权

URI

/api/index/search/agg

统一资源标识符

请求方法

POST

客户端对向量数据库服务器请求的操作类型

请求头

Content-Type: application/json

请求消息类型

Authorization: HMAC-SHA256 ***

鉴权

请求参数

在向量检索和聚合统计请求的基础上，您可以在search请求参数中指定 filter 子参数进行标量过滤。

参数

子参数

类型

是否必选

默认值

参数说明

search

filter

map

是

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

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

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

filter 表达式

算子

算子说明

字段类型

示例

must

针对指定字段名生效，语义为必须在 [...] 之中，即 "must in"。

string、int64、list、list

JSON <br> { <br> "op": "must", <br> "field": "region", <br> "conds": ["cn", "sg"] <br> } <br>

must_not

针对指定字段名生效，语义为必须不在 [...] 之中，即 "must not in"。

string、int64、list、list

JSON <br> { <br> "op": "must_not", <br> "field": "data_type", <br> "conds": [1,2,3] <br> } <br>

range

针对指定字段名生效，语义为必须在指定范围内。
配置使用gte（大于等于）, gt（大于）, lte（小于等于）, lt（小于），用以圈定一维范围。
另外，支持用 center 和 radius 表示二维圆内范围。

int64、float32

JSON <br> // price 在 [100.0, 500.0) <br> { <br> "op": "range", <br> "field": "price", <br> "gte": 100.0, <br> "lt": 500.0 <br> } <br> <br> //price >= 100.0 <br> { <br> "op": "range", <br> "field": "price", <br> "gte": 100.0 <br> } <br> <br> // 以 center 为中心，半径为50的圆内 <br> { <br> "op": "range", <br> "field": ["pos_x", "pos_y"], <br> "center": [100.0, 123.4], <br> "radius": 50.0 <br> } <br>

range_out

针对指定字段名生效，语义为必须在指定范围外。配置使用gte（大于等于）, gt（大于）, lte（小于等于）, lt（小于），用以圈定一维范围。

int64、float32

JSON <br> // 筛选价格低于100或高于500的商品 <br> { <br> "op": "range_out", <br> "field": "price", <br> "gt": 500.0, <br> "lt": 100.0 <br> } <br>

and

逻辑算子，针对逻辑查询需求，对多个条件取交集。

JSON <br> { <br> "op": "and", // 算子名 <br> "conds": [ // 条件列表，支持嵌套逻辑算子和 must/must_not 算子 <br> { <br> "op": "must", <br> "field": "type", <br> "conds": [1] <br> }, <br> { <br> ... // 支持>=1的任意数量的条件进行组合 <br> } <br> ] <br> } <br>

or

逻辑算子，针对逻辑查询需求，对多个条件取并集。

JSON <br> { <br> "op": "or", // 算子名 <br> "conds": [ // 条件列表，支持嵌套逻辑算子和 must/must_not 算子 <br> { <br> "op": "must", <br> "field": "type", <br> "conds": [1] <br> }, <br> { <br> ... // 支持>=1的任意数量的条件进行组合 <br> } <br> ] <br> } <br>

响应消息

参数

参数说明

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}, {"信息": 0.19, "检索": 0.63}]
      },
      "limit": 2,
      "dense_weight": 0.5,
      "filter": {"op": "must", "field": "region", "conds": ["cn", "sg"]},
      "partition": "default"
    }
  }'

响应消息

执行成功返回：

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
 
{
    "code":0,
    "message":"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, "message":"index not exist", "request_id":"021695029757920fd001de6666600000000000000000002569b8f"}

返回说明补充

检索结果结构

返回字段 data 的类型为 array<array<object>>：外层数组与请求中的查询项一一对应；每个内层数组是该查询项的 TopN 结果列表。

字段类型含义
data[][].idstring 或 int64命中数据的主键，类型与 Collection 主键类型一致。
data[][].scorefloat32命中结果的相关性分数。
data[][].fieldsmap<string, any>命中数据的字段集合；键为字段名，值类型与 Collection 字段定义一致。

错误处理补充

常见错误处理建议

错误码处理建议
1000001检查 AK/SK、签名时间和 Authorization 请求头，并按 API 签名调用指南重新生成签名。
1000002检查 IAM 用户是否具有目标项目和 VikingDB 资源权限，缺少权限时由管理员授权。
1000003根据错误消息检查必填参数、类型、枚举值和数值范围。
1000005检查 collection_name 是否拼写正确、是否位于当前项目且尚未删除。
1000008检查 index_name 是否正确、索引是否已创建并处于可用状态。
1000011检查数据主键是否存在于目标 Collection；不存在时先写入数据。

完整触发条件参见向量库 V1 错误码。

最近更新时间：2026.09.08 15:30:03
这个页面对您有帮助吗？
有用
有用
无用
无用