You need to enable JavaScript to run this app.
导航

upsert_data

最近更新时间2024.01.22 19:38:14

首次发布时间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

string

指定写入数据的 Collection 名称。

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

fields

array<map>

指定写入的数据。

  • 单次写入的数据数目不超过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:格式是向量(浮点数数组)。
    • text:格式是 map<string, string>,当前支持 text 。
      • text:以 string 形式写入文本原始数据, 如 {"text": "hello world"}。

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],
            "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": {
                        "text": "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"}