upsert

最近更新时间:2025-02-24 10:35:53

我的收藏

Method 与 URL

给 Collection 中插入向量或文本信息:POST https://{实例访问 IP 地址}:{实例网络端口}/document/upsert
说明:
在插入数据时, Collection 中已经存在相同 ID 的 Document,则会删除源 Document,插入新的 Document 数据。

使用示例

注意:
如下示例 api_key 的值 A5VOgsMpGWJhUI0WmUbY******************** 与 10.0.X.X,需要分别替换为具体实例的 API Key 以及访问地址。
插入向量数据
插入文本数据
写入二进制数据
写入 json 数据
如果您无需使用腾讯云向量数据库(Tencent Cloud VectorDB)的 Embedding 功能做向量化,则可以直接写入向量数据。
curl -i -X POST \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\
http://10.0.X.X:80/document/upsert \\
-d '{
"database": "db-test",
"collection": "book-vector",
"documents": [
{
"id": "0001",
"vector": [
0.2123,
0.23,
0.213
],
"sparse_vector": [[2,0.96],[5,0.53],[100,0.443]],
"author": "罗贯中",
"bookName": "三国演义",
"page": 21
},
{
"id": "0002",
"vector": [
0.2123,
0.22,
0.213
],
"sparse_vector": [[2,0.97],[5,0.54],[100,0.445]],
"author": "吴承恩",
"bookName": "西游记",
"page": 22
},
{
"id": "0003",
"vector": [
0.2123,
0.21,
0.213
],
"sparse_vector": [[2,0.97],[5,0.54],[100,0.445]],
"author": "曹雪芹",
"bookName": "红楼梦",
"page": 23
}
]
}'
如果您使用 Embedding 功能,在 /collection/create 建表时,配置 Embedding 模型相关参数之后,便可以通过 /document/upsert 接口可直接传入原始文本。Embedding 模型会将原始文本转换为向量数据,并将转换后的向量数据以及原始文本一并存入数据库。具体信息,请参见 Embedding 介绍。如下示例,基于 /collection/create 创建的集合 book-emb,写入原始文本。
说明:
创建 Collection 时,已指定 Embedding 模型,则只能插入文本信息,不能插入向量数据。
curl -i -X POST \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\
http://10.0.X.X:80/document/upsert \\
-d '{
"database": "db-test",
"collection": "book-emb",
"buildIndex": true,
"documents": [
{
"id": "0001",
"text": "话说天下大势,分久必合,合久必分。",
"sparse_vector": [[2,0.97],[5,0.54],[100,0.445]],
"author": "罗贯中",
"bookName": "三国演义",
"page": 21
},
{
"id": "0002",
"text": "混沌未分天地乱,茫茫渺渺无人间。",
"author": "吴承恩",
"bookName": "西游记",
"page": 22
},
{
"id": "0003",
"text": "甄士隐梦幻识通灵,贾雨村风尘怀闺秀。",
"author": "曹雪芹",
"bookName": "红楼梦",
"page": 23
}
]
}'
curl -i -X POST \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\
http://10.0.X.X:80/document/upsert \\
-d '{
"database": "db-test",
"collection": "bin-vector",
"documents": [
{
"id": "0001",
"vector": [21, 13],
"page": 21
}
]
}'
以下示例展示了在开启 autoId 功能的情况下,写入 json 类型字段 bookInfo 的操作。
curl -i -X POST \\
-H 'Content-Type: application/json' \\
-H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\
http://10.0.X.X:80/document/upsert \\
-d '{
"database": "db-test",
"collection": "coll-json-test",
"documents": [
{
"vector": [
0.2123,
0.23,
0.213
],
"bookInfo": {
"bookName": "三国演义",
"author": "罗贯中"
}
}
]
}'

请求参数

参数名称
参数含义
子参数
是否必选
配置方法及要求
database
指定要插入的 Database 名称。
-
使用 /database/list 获取集群中的数据库列表,复制需写入数据的集合所属的数据库名。
collection
指定要插入数据的 Collection 名称。
-
使用 /collection/list 获取指定数据库名下的 Collection 列表,复制需写入数据的集合名。
buildIndex
指定是否需要更新索引。
-
取值如下所示:
true:需更新索引。默认值是 true
false:不更新索引。
注意:
如果创建 Collection 选择的索引类型为 IVF 系列:
当第一次写入时,当前集合还没有向量索引,此时 buildIndex 必须为 false。插入原始数据之后,需通过 rebuild 训练数据并重建索引。
当集合已经调用过 rebuild 创建索引后,集合已经存在向量索引,此时:
如果 buildIndex = true,表示新写入的数据会加入到已有的 IVF 索引中,但不会更新索引结构,此时新写入的数据可以被检索到。
如果 buildIndex = false,表示新写入的数据不会加入到已有的 IVF 索引中,此时新写入的数据无法被检索到。
具体应用实践,请参见 应用 IVF 系列索引
documents
指定要插入的 Document 数据,是一个数组,支持单次插入一条或者多条 Document,最大可插入1000条。
id
Document 主键,长度限制为[1,128]。
vector
表示文档的向量值,
集合的向量索引为 FLAT/HNSW/IVF 时,直接传入向量数据,以32位浮点数存储,如[0.2123, 0.9281, ..., 0.6712]。
集合的向量索引为二进制索引时,写入向量时需要以十进制写入,并且维度是创建集合时指定维度的1/8。如创建集合时指定索引为 BIN_FLAT,维度为8维,则 upsert 时可以直接写入[150],其代表的二进制数据为“10010110”。
说明:
如果使用 Embedding 功能做向量化,则无需写入向量数据。
text
该参数为 创建集合 时,Embedding 参数 field 对应指定的文本字段名。写入原始文本。
说明:
写入原始文本数据,系统会自动从该字段中提取原始文本信息,并将其转换为向量数据,并将原始文本以及转化后的向量数据一起存储在数据库中。
输入的文本长度有限制,超过512个 token,约400个字符之后会自动截断。
other_scalar_field
其他标量字段,用于存储文档的其他信息。例如:请求示例中的 bookName、author、page、segment。
说明:
若字段为存储数据过期时间戳的标量字段,需以标准的 Unix 时间戳格式为该字段赋值,且数据类型为 uint64。例如:"expired_at": 1728372822
若时间戳字段为空未指定具体的过期时间,插入的该条数据将不会执行过期删除操作,数据将永久保留。
若时间戳字段传入 Value 的数据类型有误或者不符合 Unix 时间戳规范时,将会报出错误信息,请根据提示信息修改。
若时间戳字段指定的过期时间小于当前插入数据时的时间,则在下一个定时删除操作时,直接删除该条数据。
Json 类型是一种由键值对组成的数据对象,使用花括号{}进行包裹。在 Json 对象中,键(Key)和值(Value)通过冒号(:)连接。例如,Json 类型的对象 a 的写入格式为"a": {"b": "test", "c": 12}。更多信息,请参见 Json 类型
说明:
Json 字段的键(Key)命名规则:仅允许使用字母、数字及下划线(_)组成键名,且键名必须以字母或下划线开头,不得以数字开头。

响应消息

{"code":0,"msg":"Operation success","affectedCount":3,"embeddingExtraInfo":{"tokenUsed":51}}
参数名
参数含义
affectedCount
影响行数,即插入的文档数量。
embeddingExtraInfo
消耗的 Token 的数量。