You need to enable JavaScript to run this app.
导航
机器学习平台
  • 文档首页
    • /
  • 机器学习平台

upsert_data

最近更新时间：2024.04.16 13:11:48

首次发布时间：2023.11.03 15:00:09

我的收藏

概述

/collection/upsert_data 接口用于在指定的数据集 Collection 内写入数据。指定写入的数据是一个数组，允许单次插入一条数据或者多条数据，单次最多可插入100条数据。

说明

当前不支持更新部分字段，每次写入数据都要更新所有字段。写入数据时，如果 Collection 中已存在相同主键的数据，则会覆盖源数据；如果 Collection 中没有相同主键的数据，则会写入新数据。

请求接口

说明

请求向量数据库 VikingDB 的 OpenAPI 接口时，需要构造签名进行鉴权，详细的 OpenAPI 签名调用方法请参见 API签名调用指南。

URI

/api/collection/upsert_data

统一资源标识符

请求方法

POST

客户端对向量数据库服务器请求的操作类型

请求头

Content-Type: application/json

请求消息类型

Authorization: HMAC-SHA256 ***

鉴权

请求参数

参数名

类型

是否必选

参数说明

collection_name/collection_alias

string

是

指定写入数据的 Collection 名称/别名。

  • 只能使用英文字母、数字、下划线_，并以英文字母开头，不能为空。
  • 长度要求：[1, 128]。
  • Collection 名称/别名不能重复。

fields

array

是

指定写入的数据。

  • 单次写入的数据数目不超过100。
  • 每条数据作为一个 map，key 为字段名，value 为字段值。
  • 数据写入时 fields 长度最大为65535，超过限制时会返回报错 “fields data is too long, should be less than 65535”。
  • 不同字段类型的字段值格式如下：
    • int64：格式是整型数值。
    • float：格式是浮点数值。
    • string：格式是字符串。
    • bool：格式是 true/false。
    • list<string>：格式是字符串数组。
    • list<int64>：格式是整型数组。
    • vector：格式是向量（浮点数数组）。
    • sparse_vector：格式是 json 字典，k 为 string 类型，表示关键词的字面量，v 为 float 类型，表示该关键词的权重数值。
    • text：格式是 string。

ttl

int

否

数据过期时间，单位为秒。

  • 格式：0 和正整数。
  • 默认值：默认为0，表示数据不过期。
  • 当 ttl 设置为86400时，表示1天后数据自动删除。
  • 数据 ttl 删除，不会立刻更新到索引。

响应消息

参数

参数说明

code

状态码

message

返回信息

request_id

标识每个请求的唯一标识符

状态码说明

状态码

http状态码

返回信息

状态码说明

0

200

success

在指定 Collection 中写入数据成功。

1000005

400

collection not exist

Collection 不存在。

1000003

400

invalid request：%s

非法参数：

  • 缺失必选参数。
  • 字段值与字段类型不匹配。

1000001

401

unauthorized

请求头中缺乏鉴权信息。

1000002

403

no permission

权限不足。

完整示例

请求消息

以写入向量数据为例：

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  http://***/api/collection/upsert_data \
  -d '{
    "collection_name": "test_name",
    "ttl": 86400, // 表示数据一天后过期
    "fields": [
        {
            "id": 1000,
            "text": "hello world!",
            "vector_field": [0.10, 0.13.........0.52],
            "sparse_vector_field": {"hello": 0.34, "world": 0.03, "!": 0.11},
            "time": 1690529701,
            "author": "laoshe"
        },
        
        ...                              
    ]
}'

以写入文本数据为例：

curl -i -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: HMAC-SHA256 ***' \
  http://***/api/collection/upsert_data \
  -d '{
        "collection_name": "test_raw_data_collection",
        "fields": [{
                "id": 1001,  
                "gap": 1.1,
                "content": "hello world"
        }]
}'

响应消息

执行成功返回：

HTTP/1.1 200 OK
Content-Length: 43
Content-Type: application/json
 
{"code":0,"msg":"success","request_id":"021695029757920fd001de6666600000000000000000002569b8f"}

执行失败返回：

HTTP/1.1 400 OK
Content-Length: 43
Content-Type: application/json
 
{"code":1000005, "msg":"collection not exist", "request_id":"021695029757920fd001de6666600000000000000000002569b8f"}