热门活动
全部活动
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}]}'
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 名称。 | - | 是 | |
collection | 指定要插入数据的 Collection 名称。 | - | 是 | |
buildIndex
| 指定是否需要更新索引。 | - | 否 | 取值如下所示： true：需更新索引。默认值是 true。 false：不更新索引。 |
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 | 否 | 说明： 写入原始文本数据，系统会自动从该字段中提取原始文本信息，并将其转换为向量数据，并将原始文本以及转化后的向量数据一起存储在数据库中。 输入的文本长度有限制，超过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 的数量。 |
