向量数据库 upsert-SDK 参考-文档中心-腾讯云

Method 与 URL
给 Collection 中插入向量或文本信息：POST https://{实例访问 IP 地址}:{实例网络端口}/document/upsert。
说明：
在插入数据时， Collection 中已经存在相同 ID 的 Document，则会删除源 Document，插入新的 Document 数据。
使用示例
注意：
如下示例 api_key 的值 A5VOgsMpGWJhUI0WmUbY******************** 与 10.0.X.X，需要分别替换为具体实例的 API Key 以及访问地址。
插入向量数据
插入文本数据
如果您无需使用腾讯云向量数据库（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
        }
    ]
}'
请求参数
参数名称
参数含义
子参数
是否必选
配置方法及要求
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
否
表示文档的向量值，请务必使用32位浮点数存储向量数据。
说明：
如果业务无需使用腾讯云向量数据库（Tencent Cloud VectorDB）的 Embedding 功能做向量化，则配置该参数，写入向量数据，而无需配置 Embedding 参数 text （创建 Collection 时，Embedding 参数 field 对应指定的文本字段名，示例中为 text）。
﻿
﻿
text
否
该参数为 创建集合 时，Embedding 参数 field 对应指定的文本字段名。写入原始文本。
说明：
写入原始文本数据，系统会自动从该字段中提取原始文本信息，并将其转换为向量数据，并将原始文本以及转化后的向量数据一起存储在数据库中。
输入的文本长度有限制，超过512个 token，约400个字符之后会自动截断。
﻿
﻿
other_scalar_field
否
其他标量字段，用于存储文档的其他信息。例如：请求示例中的 bookName、author、page、segment。
说明：
若字段为存储数据过期时间戳的标量字段，需以标准的 Unix 时间戳格式为该字段赋值，且数据类型为 uint64。例如："expired_at": 1728372822。
若时间戳字段为空未指定具体的过期时间，插入的该条数据将不会执行过期删除操作，数据将永久保留。
若时间戳字段传入 Value 的数据类型有误或者不符合 Unix 时间戳规范时，将会报出错误信息，请根据提示信息修改。
若时间戳字段指定的过期时间小于当前插入数据时的时间，则在下一个定时删除操作时，直接删除该条数据。
响应消息
{
    "code": 0,
    "msg": "operation success",
    "affectedCount": 3
}
﻿
{"code":0,"msg":"Operation success","affectedCount":3,"embeddingExtraInfo":{"tokenUsed":51}}
参数名
参数含义
affectedCount
影响行数，即插入的文档数量。
embeddingExtraInfo
消耗的 Token 的数量。
﻿

参数名称	参数含义	子参数	是否必选	配置方法及要求
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	否	表示文档的向量值，请务必使用32位浮点数存储向量数据。说明：如果业务无需使用腾讯云向量数据库（Tencent Cloud VectorDB）的 Embedding 功能做向量化，则配置该参数，写入向量数据，而无需配置 Embedding 参数 text （创建 Collection 时，Embedding 参数 field 对应指定的文本字段名，示例中为 text）。
				text	否	该参数为创建集合时，Embedding 参数 field 对应指定的文本字段名。写入原始文本。说明：写入原始文本数据，系统会自动从该字段中提取原始文本信息，并将其转换为向量数据，并将原始文本以及转化后的向量数据一起存储在数据库中。输入的文本长度有限制，超过512个 token，约400个字符之后会自动截断。
				other_scalar_field	否	其他标量字段，用于存储文档的其他信息。例如：请求示例中的 bookName、author、page、segment。说明：若字段为存储数据过期时间戳的标量字段，需以标准的 Unix 时间戳格式为该字段赋值，且数据类型为 uint64。例如：`"expired_at": 1728372822`。若时间戳字段为空未指定具体的过期时间，插入的该条数据将不会执行过期删除操作，数据将永久保留。若时间戳字段传入 Value 的数据类型有误或者不符合 Unix 时间戳规范时，将会报出错误信息，请根据提示信息修改。若时间戳字段指定的过期时间小于当前插入数据时的时间，则在下一个定时删除操作时，直接删除该条数据。

参数名	参数含义
affectedCount	影响行数，即插入的文档数量。
embeddingExtraInfo	消耗的 Token 的数量。

upsert

本页目录：

Method 与 URL

使用示例

请求参数

响应消息