upsertData--向量数据库VikingDB-火山引擎

文档中心

向量数据库VikingDB

数据(Data)

upsertData

概述

接口用于在指定的数据集 Collection 内写入数据。指定写入的数据是一个 Map，允许单次插入一条或多条数据，单次最多可插入 100 条数据。如提供的主键已存在，则更新对应的数据；否则，插入新的数据。

说明

对 V2 版本的 UpsertData 接口进行了调整（仅影响含 vectorize 配置的需要向量化数据集，已带 vector 类型字段的数据集不受影响），核心信息如下：

含 vectorize 配置的数据集写入，embedding 计算将从实时同步转为后台异步执行，数据生效会有一定滞后；
写入失败错误信息，可前往向量数据库控制台“日志管理”页查看；
响应体参数不再返回 token_usage 字段。

方法定义

public DataApiResponse<UpsertDataResult> upsertData(UpsertDataRequest request)
        throws ApiClientException, VectorApiException

请求体参数

名称	类型	描述	必选
collectionName	String	数据集的名称。	二选一
resourceId	String	数据集的 ID。	二选一
data	List[Map[String, Object]]	要写入的数据列表。列表中的每个 Map 代表一条数据，必须包含主键字段。	是
ttl	integer	数据的生存时间（Time-To-Live），单位为秒。超过该时间后数据将被自动删除。	否
async	Boolean	对于“需要向量化”的数据集：本参数仅区分是否流式更新。 async=false，异步写入生效后触发索引流式更新 async=true，异步写入生效后仍不触发索引流式更新对于“已有向量数据”的数据集：异步写入开关。异步写入限流阈值为同步写入的 10 倍异步写入的数据不会实时同步写入 collection，滞后时间为分钟级别。可通过接口 `FetchDataInCollection` 来确认数据是否已经写入 collection 异步写入的数据不会触发索引的流式更新，索引同步时间为小时级别。可通过接口 `FetchDataInIndex` 接口确认数据是否同步至 index	否

data参数字段值格式

说明

注意：数据插入时主键不能为 0

字段类型	格式	说明
int64	整型数值	整数
float32	浮点数值	浮点数
string	字符串	字符串。内容限制 256 byte
bool	true/false	布尔类型
list[string]	字符串数组	字符串数组
list[int64]	整型数组	整数数组
vector	向量（浮点数数组） float32/float64 压缩为 bytes 后的 base64 编码	稠密向量
sparse_vector	输入格式 <token_id, token_weight> 的字典列表，用于表征稀疏向量的非零位下标及其对应的值，其中 token_id 为 string 类型，token_weight 为 float 类型	稀疏向量
text	字符串	若为向量化字段，则值不能为空。（若否，可以为空）
image	Object	若为向量化字段，则值不能为空。（若否，可以为空）图片tos链接 `tos://{bucket}/{object}` http/https格式链接
video	Object	{ "value": `tos://{bucket}/{object}`，http/https 格式 URL 链接，该字段必填 "fps": 0.2（取值 0.2-5，选填） }
dateTime	string	分钟级别： `yyyy-MM-ddTHH:mmZ`或`yyyy-MM-ddTHH:mm±HH:mm` 秒级别： `yyyy-MM-ddTHH:mm:ssZ`或`yyyy-MM-ddTHH:mm:ss±HH:mm` 毫秒级别： `yyyy-MM-ddTHH:mm:ss.SSSZ`或`yyyy-MM-ddTHH:mm:ss.SSS±HH:mm` 例如："2025-08-12T11:33:56+08:00"
geoPoint	string	地理坐标`longitude,latitude`，其中`longitude`取值(-180,180)，`latitude`取值(-90,90) 例如："116.408108,39.915023"

时间类型字段（date_time）

只能填写以下格式的其中一种，全部遵循 RFC 3339 标准（https://datatracker.ietf.org/doc/html/rfc3339）
例如："2025-08-12T12:34:56+08:00"

	格式(string)	示例	说明
分钟级别	`yyyy-MM-ddTHH:mmZ`（UTC 时间）或 `yyyy-MM-ddTHH:mm±HH:mm`（指定时区）	`2025-08-12T04:34Z` `2025-08-12T12:34+08:00`	左侧示例都会解析为北京时间`2025-08-12`的`12:34:00`。
秒级别	`yyyy-MM-ddTHH:mm:ssZ`（UTC 时间）或 `yyyy-MM-ddTHH:mm:ss±HH:mm`（指定时区）	`2025-08-12T04:34:56Z` `2025-08-12T12:34:56+08:00`	左侧示例都会解析为北京时间`2025-08-12`的`12:34:56`。
毫秒级别	`yyyy-MM-ddTHH:mm:ss.SSSZ`（UTC 时间）或 `yyyy-MM-ddTHH:mm:ss.SSS±HH:mm`（带时区）	`2025-08-12T04:34:56.147Z` `2025-08-12T12:34:56.147+08:00`	左侧示例都会解析为北京时间`2025-08-12`的`12:34:56.147`。

返回参数

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

请求示例代码

import com.volcengine.vikingdb.runtime.Util;
import com.volcengine.vikingdb.runtime.core.auth.AuthWithAkSk;
import com.volcengine.vikingdb.runtime.core.ClientConfig;
import com.volcengine.vikingdb.runtime.enums.Scheme;
import com.volcengine.vikingdb.runtime.vector.model.request.UpsertDataRequest;
import com.volcengine.vikingdb.runtime.vector.model.response.DataApiResponse;
import com.volcengine.vikingdb.runtime.vector.model.response.UpsertDataResult;
import com.volcengine.vikingdb.runtime.vector.service.VectorService;

import java.util.Arrays;
import java.util.HashMap;

public class UpsertDataExample {

    public static void main(String[] args) {
        // 1. 初始化客户端 (请替换为您的配置)
        VectorService vectorService = null;
        try {
            vectorService = new VectorService(
                    Scheme.HTTPS,
                    "api-vikingdb.vikingdb.cn-beijing.volces.com",
                    "cn-beijing",
                    new AuthWithAkSk("your-access-key", "your-secret-key"),
                    ClientConfig.builder().build()
            );
        } catch (Exception e) {
            System.err.println("Client initialization failed: " + e.getMessage());
            e.printStackTrace();
            return;
        }

        // 2. 准备请求
        UpsertDataRequest request = UpsertDataRequest.builder()
                .collectionName("your_collection_name") // 替换为您的集合名称
                .data(Arrays.asList(
                        new HashMap<String, Object>() {{ put("id", 1); put("field1", "value1"); put("vector", Util.generateRandomVector(128)); }},
                        new HashMap<String, Object>() {{ put("id", 2); put("field1", "value2"); put("vector", Util.generateRandomVector(128)); }},
                        new HashMap<String, Object>() {{ put("id", 3); put("field1", "value3"); put("vector", Util.generateRandomVector(128)); }}
                ))
                .build();

        // 3. 发起请求
        try {
            DataApiResponse<UpsertDataResult> response = vectorService.upsertData(request);
            System.out.println("Upsert data successfully:");
            System.out.println(response);
        } catch (Exception e) {
            System.err.println("Failed to upsert data: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

最近更新时间：2026.04.16 20:05:41

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

时间类型字段（date_time） #

时间类型字段（date_time）