文档中心

向量数据库VikingDB

请输入

数据(Data)

数据更新-UpdateData

概述

接口用于为已存在数据的部分字段进行更新。支持 text、标量字段、vector 字段的更新。

接口升级说明

对应的V1接口为：https://www.volcengine.com/docs/84313/1400258
使用区别：

	V2接口	V1接口
写入数据对应的参数	data	fields
返回模型消耗token量	自动返回	需手动设置
单次写入的数据量限制	如果数据集带 vectorize，不超过 1 条，时延更低；不带 vectorize，不超过 100 条。	不超过 100 条。

注：QPS限流是以数据条数计算，V1与V2接口的限流行为完全相同。

请求接口

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

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

请求体参数

参数名	类型	必选	默认值	备注
resource_id	string	至少填写一个		资源 ID；与 `collection_name` 至少传入一个，同时传入时优先使用 `resource_id`。资源 ID 可通过相应资源的创建接口返回结果获取，也可在资源详情中查看。
collection_name	string	至少填写一个		Collection 名称；未传 `resource_id` 时必填。
data	array	是		单次写入的数据数目：如果数据集带 vectorize，不超过 1 条；不带 vectorize，不超过 100 条。每条数据作为一个 Map，其中 key 为字段名，value 为字段值，不同字段类型的字段值格式见下表。注意：不允许写入不存在的字段名。如果缺失某字段，则该字段保持不变（不更新）。若请求参数非法（4xx 类型），则会全部失败。
ttl	int32	否	保持原值	更新后的数据生存时间，单位为秒，取值范围 `[0, 2147483647]`。不传时保持原 TTL，传 0 表示数据不过期。数据过期时间，单位为秒。设置为86400，则1天后数据自动删除。数据ttl删除，不会立刻更新到索引。
注意：数据更新时主键不能为 0

data 可以只包括部分字段（但必须包含主键）
暂不支持异步写入

响应体参数

公共响应体参数部分见数据面API调用流程。

参数名	类型	说明
result	map	更新结果。
result.token_usage	map	本次更新消耗的 token 统计；具体计量项随使用的向量化模型返回。

请求模板

"""
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_schema("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="https://{}{}".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/update"
    req_body = {
        "collection_name": "test_coll_with_vectorize",  # 替换为您的collection名
        "data": [
            {
                "f_id": "000135",
                "f_city": "北京",
                "f_text": "这是一件历史悠久的文物，具有1300年的历史",
                "f_image": "tos://my_bucket/good_000135.jpg",
            }
        ],
    }
    result = client.do_req(
        req_method=req_method, req_path=req_path, req_params=req_params, req_body=req_body
    )
    print("req status code: ", result.status_code)
    print("req result: \n", result.text)

参数说明补充

请求数据中的主键键名不是固定的 id，而是创建 Collection 时在 Fields 中设置 IsPrimaryKey=true 的字段名。主键值类型必须与该字段的 FieldType 一致；每条更新数据均需携带该主键。

错误处理补充

错误码

本接口的业务错误码、触发条件和处理建议统一参见向量库 V2 错误码。排查时请同时记录响应中的 request_id，以便定位具体请求。

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

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

参数说明补充 #

错误处理补充 #

错误码 #

参数说明补充

错误处理补充

错误码