文档中心

向量数据库VikingDB

请输入

检索(Search)

标量排序检索-SearchByScalar

概述

接口适用于含有int64/float32类型标量索引字段的索引。向量数据库中的标量检索指的是基于标量值的检索方法。在向量数据库中，每条数据都有一个或多个标量值，标量检索可以基于这些标量值进行检索，找到与查询相关的数据。例如文档检索中的作者特征检索。

请求接口

请求向量数据库 VikingDB 的 OpenAPI 接口时，可以使用 API Key（推荐）或者 AK、SK 构造签名 进行鉴权。请参见数据面API调用流程，复制调用示例并填入必要信息。

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

请求体参数

仅列出本接口特有的参数。更多信息请参见检索公共参数。

参数名	必选	类型	备注
field	是	string	字段名。前提条件：1.字段必须为 int64 或 float32。2.必须为此字段建立标量索引。
order	否	string	asc/desc。默认 desc 为降序排列，asc 为升序排列。

请求响应示例

请求参数

req_path = "/api/vikingdb/data/search/scalar"
req_body = {
    "collection_name": "test_coll",
    "index_name": "idx_1",
    "limit": 2,
    "field": "f_price",
    "order": "desc"
}

响应参数

{
    "code": "Success",
    "message": "The API call was executed successfully.",
    "request_id": "02175438839168500000000000000000000ffff0a003ee4fc3499",
    "result": {
        "data": [
            {
                "id": "uid_001",
                "fields": {
                    "f_good_id": "uid_001", "f_price": 999000
                },
                "score": 999000
            },
            {
                "id": "uid_002",
                "fields": {
                    "f_good_id": "uid_002", "f_price": 309000
                },
                "score": 309000
            }
        ],
        "total_return_count": 2
    }
}

请求模版

"""
pip3 install volcengine
"""

from volcengine.base.Request import Request
import requests, json


class ClientForDataApi:
    def __init__(self, api_key=None, host=None):
        """
        初始化ClientForDataApi类
        :param api_key: VikingDB的API Key
        :param host: VikingDB的API Host
        """
        if not api_key or not host:
            raise ValueError("api_key and host are required")
        self.api_key = api_key
        self.host = host

    def prepare_request(self, method, path, params=None, data=None):
        r = Request()
        r.set_shema("https")
        r.set_method(method)
        r.set_connection_timeout(10)
        r.set_socket_timeout(10)
        mheaders = {
            "Accept": "application/json",
            "Content-Type": "application/json",
            "Host": self.host,
            "Authorization": f"Bearer {self.api_key}",
        }
        r.set_headers(mheaders)
        if params:
            r.set_query(params)
        r.set_host(self.host)
        r.set_path(path)
        if data is not None:
            r.set_body(json.dumps(data))
        return r

    def do_req(self, req_method, req_path, req_params, req_body):
        req = self.prepare_request(
            method=req_method, path=req_path, params=req_params, data=req_body
        )
        return requests.request(
            method=req.method,
            url="http://{}{}".format(self.host, req.path),
            headers=req.headers,
            data=req.body,
            timeout=10000,
        )


if __name__ == "__main__":
    import os
    client = ClientForDataApi(
        api_key=os.environ.get("VIKINGDB_API_KEY", "***"), # 从环境变量中获取API Key，若未设置则使用默认值
        host="api-vikingdb.vikingdb.cn-beijing.volces.com",  # 替换为您所在的域名
    )
    req_method = "POST"
    req_params = None
    req_path = "/api/vikingdb/data/search/scalar"
    req_body = {
        "collection_name": "test_coll",
        "index_name": "idx_1",
        "limit": 2,
        "field": "f_price",
        "order": "desc",
    }
    result = client.do_req(
        req_method=req_method, req_path=req_path, req_params=req_params, req_body=req_body
    )
    print("req http status code: ", result.status_code)
    print("req result: \n", result.text)

返回说明补充

返回参数

字段	类型	含义
`code`	int	业务状态码；成功时为 0。
`message`	string	状态说明或错误信息。
`request_id`	string	请求唯一标识，用于问题排查。
`result`	object	检索结果对象。
`result.data`	array	命中的 TopN 数据列表。
`result.total_return_count`	int	本次返回的结果数量。
`result.token_usage`	object	可选。实际调用向量化模型并返回用量信息时出现。

检索结果结构

返回字段 result.data 的类型为 array<object>，每个元素是一条命中结果。

字段	类型	含义
`result.data[].id`	string 或 int64	命中数据的主键，类型与 Collection 主键类型一致。
`result.data[].score`	float64	最终相关性分数。
`result.data[].ann_score`	float64	可选。向量召回阶段的原始分数。
`result.data[].fields`	map<string, any>	命中数据的字段集合；键为字段名，值类型与 Collection 字段定义一致。

最近更新时间：2026.09.08 12:02:49

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

返回说明补充 #

返回参数 #

检索结果结构 #

返回说明补充

返回参数

检索结果结构