文档中心

向量数据库VikingDB

请输入

检索过滤能力

主键过滤

您可以通过主键过滤能力在向量数据库中通过主键限定结果范围。
主键值来自 Collection 的主键字段：使用自定义主键时，填写写入数据时该主键字段的值；未指定主键时系统使用自动生成的 AUTO_ID，可从控制台数据预览或检索/点查返回结果的 id 字段取得。传入值的类型必须与主键字段类型一致。
主键过滤是通用检索能力，您可以将其应用在基本向量检索、稠密稀疏混合检索中。

请求接口

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

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

请求参数

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

参数	子参数	类型	是否必选	默认值	参数说明
search	primary_key_in	list或list	否		设定此参数，会限定仅在主键列表范围内进行检索。传入空列表和不传此参数效果相同。
	primary_key_not_in（不传时等同于空列表，不排除任何主键）	list或list	否		设定此参数，将把主键列表范围内的数据从检索结果中排除。

响应消息

参数	参数说明
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], 
            ], 
        }, 
        "limit": 2,   
        "primary_key_in":[1,2,3,4,5,6], //限定仅在该主键列表范围内检索
        "primary_key_not_in":[7,8]，  //限定不在该主键列表范围内检索
        "partition": "default"     //子索引名称，对应 field 的值
    }
}'

响应消息

执行成功返回：

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"
                } 
            }
        ]
    ]
}

执行失败返回：

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[][].id`	string 或 int64	命中数据的主键，类型与 Collection 主键类型一致。
`data[][].score`	float32	命中结果的相关性分数。
`data[][].fields`	map<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

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

状态码说明 #

请求消息 #

响应消息 #

返回说明补充 #

检索结果结构 #

错误处理补充 #