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

文档中心

向量数据库VikingDB

数据（Data）

upsertData

概述

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

说明

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

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

请求体参数

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

Data 参数字段值格式

说明

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

字段类型	格式	说明
int64	整型数值	整数
float32	浮点数值	浮点数
string	字符串	字符串。内容限制 256 byte
bool	true/false	布尔类型
list	字符串数组	字符串数组
list	整型数组	整数数组
vector	向量（浮点数数组） float32/float64压缩为bytes后的base64编码	稠密向量
sparse_vector	输入格式<token_id ,token_weight>的字典列表，用来表征稀疏向量的非零位下标及其对应的值，其中 token_id 为 string 类型，token_weight 为 float 类型	稀疏向量
text	string	若为向量化字段，则值不能为空。（若否，可以为空）
image	interface{}	若为向量化字段，则值不能为空。（若否，可以为空）图片tos链接 `tos://{bucket}/{object}` http/https格式链接
video	interface{}	{ "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)

只能填写以下格式的其中一种，全部遵循 RFC3339 标准（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`。

返回参数

响应体包含公共参数（见下方“响应体公共参数介绍”）。

响应体公共参数介绍

参数名	类型	说明
RequestID	string	请求 ID。
Code	string	操作状态码。成功为`Success`，否则为错误码短语。
Message	string	执行信息。成功则为 `The API call was executed successfully.`，否则为错误信息。
Result	map[string]interface{}	操作结果。若无需返回数据，则 `result = null`。

请求示例代码

package main

import (
    "context"
    "fmt"
    "github.com/volcengine/vikingdb-go-sdk/vector"
    "github.com/volcengine/vikingdb-go-sdk/vector/model"
    "os"
    "time"
)

func main() {
    var (
       accessKey = os.Getenv("VIKINGDB_AK")
       secretKey = os.Getenv("VIKINGDB_SK")
       endpoint  = "https://api-vikingdb.vikingdb.cn-beijing.volces.com"
       region    = "cn-beijing"
    )

    client, err := vector.New(
       vector.AuthIAM(accessKey, secretKey), // IAM auth
       // vector.AuthAPIKey(apiKey),            // APIKey auth
       vector.WithEndpoint(endpoint),
       vector.WithRegion(region),
       vector.WithTimeout(time.Second*30),
       vector.WithMaxRetries(3),
    )
    if err != nil {
       fmt.Println("New client failed, err: ", err)
       panic(err)
    }
    ctx := context.Background()

    resp, err := client.Collection(model.CollectionLocator{
       CollectionName: "Your Collection Name",
    }).Upsert(ctx, model.UpsertDataRequest{
       WriteDataBase: model.WriteDataBase{
          Data: []model.MapStr{
             {
                "id":      1,
                "type":    "type1",
                "name":    "vikingdb data",
                "content": "vikingdb is a vector database",
             },
          },
       },
    })
    if err != nil {
       fmt.Println("Upsert failed, err: ", err)
       panic(err)
    }

    fmt.Println(resp.Message)
}

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

这个页面对您有帮助吗？

有用

无用

向量数据库VikingDB

创建时间类型字段(date_time) #

响应体公共参数介绍 #

创建时间类型字段(date_time)

响应体公共参数介绍