文档中心

向量数据库VikingDB

请输入

数据(Data)

fetch_data(collection)

概述

/collection/fetch_data 接口用于根据主键在指定的 Collection 中查询单条或多条数据，单次最多可查询100条数据。
Collection 数据写入/删除后，可以实时查询数据。

请求接口

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

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

请求参数

参数	类型	是否必选	参数说明
collection_name/collection_alias	string	是	指定查询数据的 Collection 名称/别名。只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。长度要求：[1, 128]。 Collection 名称/别名不能重复。
resource_id	string	否	资源ID；资源 ID 可通过相应资源的创建接口返回结果获取，也可在资源详情中查看。
primary_keys	int64、 array、 string、 array、	是	指定主键字段值，单次最多查询100条数据。primary_keys设置为不同类型时，数据查询逻辑如下： int64类型、string类型：单条数据查询，也支持主键对应的多个文本切片数据查询。 array、array：多条数据查询，数据条数为外层 array 长度，最大100条。

参数

类型

是否必选

参数说明

collection_name/collection_alias

string

是

指定查询数据的 Collection 名称/别名。

只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。
长度要求：[1, 128]。
Collection 名称/别名不能重复。

resource_id

string

否

资源ID；资源 ID 可通过相应资源的创建接口返回结果获取，也可在资源详情中查看。

primary_keys

int64、
array、
string、
array、

是

指定主键字段值，单次最多查询100条数据。primary_keys设置为不同类型时，数据查询逻辑如下：

int64类型、string类型：单条数据查询，也支持主键对应的多个文本切片数据查询。
array、array：多条数据查询，数据条数为外层 array 长度，最大100条。

响应消息

参数	参数说明
code	状态码
message	返回信息
request_id	标识每个请求的唯一标识符
data	返回查询的数据。如果查询单条数据，则类型是 map；如果批量查询多条数据，则类型是 array；如果某条数据查不到，则只返回主键值和提示信息。每条数据作为一个 map，key 为字段名，value 为字段值。

状态码说明

状态码	http状态码	返回信息	状态码说明
0	200	success	指定的 Collection 查询数据成功。
1000005	400	collection not exist	Collection 不存在。
1000003	400	invalid request：%s	非法参数缺失必选参数。
1000001	401	unauthorized	请求头中缺乏鉴权信息。
1000002	403	no permission	权限不足。

完整示例

请求消息

curl -i -X GET \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  https://api-vikingdb.volces.com/api/collection/fetch_data \
  -d '{
    "collection": "test_name",
    "primary_keys": [123,124]                              
}'

响应消息

执行成功返回：

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
 
{
    "code":0,
    "message":"fetch data success",
    "request_id":"021695029748777fd001de6666600000000000000000002887b8d",
    "data": [
        {
            "id": "123",
            "text": "hello world!",
            "vector_field": [0.10, 0.13.........0.52],
            "sparse_vector_field": {"hello": 0.34, "world": 0.03, "!": 0.11},
            "time": "1690529701",
            "author": "zhangsan"
        },
        {
        "id": "124",
          // 查不到，则没有vector, 并返回提示信息
            "message": "no data found"
        }  
    ]
}

执行失败返回：

HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
 
{"code": 1000005, "message": "collection not exist", "request_id":"021695029748777fd001de6666600000000000000000002887b8d"}

使用说明修正

请求 JSON 中使用 collection（string）指定 Collection 名称或别名；参数表中的旧写法 collection_name 应按此 Key 构造请求。

返回说明补充

响应字段类型补充

字段	类型	含义
`code`	int	业务状态码；成功时为 0。
`message`	string	状态说明或错误信息。
`request_id`	string	请求唯一标识，用于问题排查。
`data`	object / array	接口业务数据；没有业务数据时可为空。

错误处理补充

常见错误处理建议

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

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

最近更新时间：2026.09.08 15:30:02

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

状态码说明 #

请求消息 #

响应消息 #

使用说明修正 #

返回说明补充 #

响应字段类型补充 #

错误处理补充 #

常见错误处理建议 #