功能介绍
/document/upsert 接口用于给 Collection 中插入向量数据。如果 Collection 在创建时,已配置 Embedding 参数,则仅需要插入文本信息,Embedding 服务会自动将文本信息转换为向量数据,存入数据库。
接口约束
在插入数据时, Collection 中已经存在相同 ID 的 Document,则会删除源 Document,插入新的 Document 数据。
请求示例
注意:
如下示例可直接复制,在 CVM 运行之前,您需在文本编辑器将 api_key=A5VOgsMpGWJhUI0WmUbY******************** 与 10.0.X.X 依据实际情况进行替换。
如果您无需使用腾讯云向量数据库(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],"author": "罗贯中","bookName": "三国演义","page": 21},{"id": "0002","vector": [0.2123,0.22,0.213],"author": "吴承恩","bookName": "西游记","page": 22},{"id": "0003","vector": [0.2123,0.21,0.213],"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": "话说天下大势,分久必合,合久必分。","author": "罗贯中","bookName": "三国演义","page": 21},{"id": "0002","text": "混沌未分天地乱,茫茫渺渺无人间。","author": "吴承恩","bookName": "西游记","page": 22},{"id": "0003","text": "甄士隐梦幻识通灵,贾雨村风尘怀闺秀。","author": "曹雪芹","bookName": "红楼梦","page": 23}]}'
?
请求参数
参数名称 | 参数含义 | 子参数 | 是否必选 | 配置方法及要求 |
database | 指定要插入的 Database 名称。 | - | 是 | |
collection | 指定要插入数据的Collection 名称。 | - | 是 | |
buildIndex
| 指定是否需要更新索引。 | - | 否 | 取值如下所示: true:需更新索引。默认值是 true。 false:不更新索引。 注意: 如果创建 Collection 选择的索引类型为 IVF 系列: 当第一次写入时,当前集合还没有向量索引,此时
buildIndex 必须为 false。插入原始数据之后,需通过
rebuild训练数据并重建索引。 当集合已经调用过 rebuild 创建索引后,集合已经存在向量索引,此时: 如果 buildIndex = true,表示新写入的数据会加入到已有的 IVF 索引中,但不会更新索引结构,此时新写入的数据可以被检索到。 如果 buildIndex = false,表示新写入的数据不会加入到已有的 IVF 索引中,此时新写入的数据无法被检索到。 ? |
documents | 指定要插入的 Document数据,是一个数组,支持单次插入一条或者多条 Document,最大可插入 1000 条。 | id | 是 | Document 主键,长度限制为[1,128]。 |
? | ? | vector | 否 | 表示文档的向量值,请务必使用32位浮点数存储向量数据。 说明: 如果业务无需使用腾讯云向量数据库(Tencent?Cloud?VectorDB)的 Embedding 功能做向量化,则配置该参数,写入向量数据,而无需配置 Embedding 参数 text (创建 Collection 时,Embedding 参数 field 对应指定的文本字段名,示例中为 text)。 ? |
? | ? | text | 否 | 说明: 写入原始文本数据,系统会自动从该字段中提取原始文本信息,并将其转换为向量数据,并将原始文本以及转化后的向量数据一起存储在数据库中。 输入的文本长度有限制,超过512个token,约400个字符之后会自动截断。 ? |
? | ? | other_scalar_field | 否 | 其他标量字段,用于存储文档的其他信息。例如:请求示例中的 bookName、author、page、segment。 ? |
响应消息
HTTP 响应消息体是服务器返回给客户端的数据,通常包含了请求的结果或者所请求的资源。/document/upsert 接口返回的状态码以及相关信息,如下所示。
状态码 | 含义 | 响应消息 |
200 | 插入数据成功 |
|
400 | 插入数据失败 |
|
?
返回参数
参数名 | 参数含义 |
affectedCount | 影响行数,即插入的文档数量。 |
?