功能介绍
/document/update 接口用于对通过主键(Document ID)与 Filter 表达式过滤检索 Document ,对 Document 的部分字段进行更新。同时,支持新增字段。
说明:
新增字段,在创建 Collection 时没有为这些字段指定索引方式,那么新增这些字段时,系统不会自动为其创建索引。
接口约束
注意:
不能变更 Document ID 字段,不要求事务完整性。
请求示例
注意:
如下示例可直接复制,在 CVM 运行之前,您需在文本编辑器将 api_key=A5VOgsMpGWJhUI0WmUbY******************** 与 10.0.X.X 依据实际情况进行替换。
集合未配置 Embedding 参数,则直接更新向量数据。如下示例,在集合 book-vector 中,基于/document/upsert 插入的向量数据,通过 documentIds 与 filter 表达式,过滤出 Document ID 为 0001 的数据,更新其 vectors 字段的向量数据,并更新 page 字段值为 30,新增字段 test_new_field。
curl -i -X POST \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\http://10.0.X.X:80/document/update\\-d '{"database": "db-test","collection": "book-vector","query": {"documentIds": ["0001","0003"],"filter": "bookName in (\\"三国演义\\",\\"西游记\\")"},"update": {"vector": [0.2123,0.28,0.213],"page": 30,"test_new_field": "new field value"}}'
执行成功之后,返回如下信息。
{"code": 0,"msg": "operation success","affectedCount": 1}
通过 /document/query 查询 Document ID 为 0001 的数据,请求消息如下所示,确认更新的字段是否生效。返回如下信息,可看到 vectors 字段与 page 字段值已更新,新增字段 test_new_field 也已生效。
{"code": 0,"msg": "operation success","count": 1,"documents": [{"id": "0001","vector": [0.21230000257492066,0.2800000011920929,0.21299999952316285],"bookName": "三国演义","author": "罗贯中","test_new_field": "new field value","page": 30}]}
实例在创建 Collection 时,已配置 Embedding 模型,通过/document/upsert 写入原始文本,则可输入文本信息,通过 Embedding 将数据向量化更新向量数据。如下示例,基于/document/upsert 插入的原始文本,使用 /document/update 接口,通过 documentIds 与 filter 表达式过滤 Document ID 为 0001 的数据,更新其 text 字段的文本信息,更新 page 字段值为 30,并新增字段 test_new_field。
curl -i -X POST \\-H 'Content-Type: application/json' \\-H 'Authorization: Bearer account=root&api_key=A5VOgsMpGWJhUI0WmUbY********************' \\http://10.0.X.X:80/document/update \\-d '{"database": "db-test","collection": "book-emb","query": {"documentIds": ["0001","0003"],"filter": "bookName in (\\"三国演义\\",\\"西游记\\")"},"update": {"text": "合久必分,分久必合","page": 30,"test_new_field": "new field value"}}'
执行成功之后,返回如下信息。
{"code": 0,"msg": "operation success","affectedCount": 1,"embeddingExtralnfo": {"tokenUsed":9}}
通过 /document/query 查询 Document ID 为 0001 的数据,确认更新的字段是否生效。返回如下信息,可看到 text 字段与 page 字段值已更新,新增字段 test_new_field 也已生效。
{"code": 0,"msg": "operation success","count": 1,"documents": [{"id": "0001","author": "罗贯中","test_new_field": "new field value","bookName": "三国演义","page": 30,"text": "合久必分,分久必合"}]}
请求参数
参数名称 | 参数含义 | 子参数 | 是否必选 | 配置方法及要求 |
database | 指定要更文档的 Database 名称。 | - | 是 | |
collection | 指定要更新文档的 Collection 名称。 | - | 是 | |
query | 设置查询条件检索需更新的文档 | documentIds | 是 | 表示要更新的文档的所有 ID,支持批量查询,数组元素范围[1,20]。 |
| | filter | 否 | 使用创建 Collection 指定的 Filter 索引的字段设置查询过滤表达式。Filter 的表达式格式为 '<field_name><operator><value>',多个表达式之间支持 and(与)、or(或)、not(非)关系。具体信息,请参见 Filter 条件表达式。其中 <field_name>:表示要过滤的字段名。 <operator>:表示要使用的运算符。 string :匹配单个字符串值(=)、排除单个字符串值(!=)、匹配任意一个字符串值(in)、排除所有字符串值(not in)。其对应的 Value 必须使用英文双引号括起来。 unit64:大于(>)、大于等于(>=)、等于(==)、小于(<)、小于等于(<=)。例如:expired_time > 1623388524。 array:数组类型,包含数组元素之一(include)、排除数组元素之一(exclude)、全包含数组元素(include all)。例如,name include (\\"Bob\\", \\"Jack\\")。 <value>:表示要匹配的值。 示例: Filter('author="jerry"').And('page>20')。 |
update | 设置需更新的字段 | vector | 否 | 更新 vector 字段的向量数据。 说明: 如果 Collection 在创建时,未配置 Embedding 参数,或者该实例并未开通 Embedding 功能,则只能配置该参数,输入向量数据,更新数据。 |
| | text | 否 | Embedding 模型输入文本的字段名。该字段在创建 Collection 时定义。本示例为 text 。 string:字符型。 float:浮点型数据。 说明: 如果 Collection 在创建时,已配置 Embedding 参数,则只能配置该参数,依据输入的文本信息更新向量数据,并将文本字段与向量数据更新存于数据库。 |
| | old_field | 否 | 当前已存在的字段,更新字段对应的数据。 类型:string。 字符长度要求:[1,256]。 |
| | new_field | 否 | 新增字段,并给新字段赋值。 类型:string。 字符长度要求:[1,256]。 |
响应消息
HTTP 响应消息体是服务器返回给客户端的数据,通常包含了请求的结果或者所请求的资源。/document/update 接口返回的状态码以及相关信息,如下所示。
状态码 | 含义 | 响应消息 |
200 | 更新数据成功 |
|
400 | 更新数据失败 |
|
返回消息参数
参数名 | 参数含义 |
affectedCount | 更新的文档数量。如果该参数返回的值为 0,说明更新无效。 |