跳到主要内容

Upsert (V2)

This operation inserts new records into the database or updates existing ones.

POST/v2/vectordb/entities/upsert
连接端点

该 API 的 Base URL 格式如下：

https://${CLUSTER_ENDPOINT}

📘说明
  • 你需要填入您的 Zilliz Cloud 集群的 ${CLUSTER_ENDPOINT}。
  • 您可以使用 查看集群详情 V2 来获取集群的 Endpoint.
export CLUSTER_ENDPOINT=""
参数
Authorizationstringheaderrequired

认证令牌，应为具备适当权限的 API 密钥或用冒号分隔的用户名和密码，如 username:password。

示例值：Bearer {{TOKEN}}
请求体application/json
dbNamestring

数据库名称。

collectionNamestring必填项

待插入或更新记录的目标 Collection 名称。

partitionNamestring

The name of a partition in the current collection. If specified, the data is to be inserted into the specified partition.

dataobjectrequired

Entity 对象或 Entity 对象数组。注意，Entity 对象的结构应与 Collection Schema 一致。

partialUpdateboolean

Whether to enable partial updates. When enabled, only the specified fields are updated.

export TOKEN="db_admin:xxxxxxxxxxxxx"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/upsert" \
--header "Authorization: Bearer ${TOKEN}" \
--header "Request-Timeout: 5" \
--header "Content-Type: application/json" \
-d '{
    "data": [
        {
            "id": 0,
            "vector": [
                0.3580376395471989,
                -0.6023495712049978,
                0.18414012509913835,
                -0.26286205330961354,
                0.9029438446296592
            ],
            "color": "pink_8682"
        },
        {
            "id": 1,
            "vector": [
                0.19886812562848388,
                0.06023560599112088,
                0.6976963061752597,
                0.2614474506242501,
                0.838729485096104
            ],
            "color": "red_7025"
        },
        {
            "id": 2,
            "vector": [
                0.43742130801983836,
                -0.5597502546264526,
                0.6457887650909682,
                0.7894058910881185,
                0.20785793220625592
            ],
            "color": "orange_6781"
        },
        {
            "id": 3,
            "vector": [
                0.3172005263489739,
                0.9719044792798428,
                -0.36981146090600725,
                -0.4860894583077995,
                0.95791889146345
            ],
            "color": "pink_9298"
        },
        {
            "id": 4,
            "vector": [
                0.4452349528804562,
                -0.8757026943054742,
                0.8220779437047674,
                0.46406290649483184,
                0.30337481143159106
            ],
            "color": "red_4794"
        },
        {
            "id": 5,
            "vector": [
                0.985825131989184,
                -0.8144651566660419,
                0.6299267002202009,
                0.1206906911183383,
                -0.1446277761879955
            ],
            "color": "yellow_4222"
        },
        {
            "id": 6,
            "vector": [
                0.8371977790571115,
                -0.015764369584852833,
                -0.31062937026679327,
                -0.562666951622192,
                -0.8984947637863987
            ],
            "color": "red_9392"
        },
        {
            "id": 7,
            "vector": [
                -0.33445148015177995,
                -0.2567135004164067,
                0.8987539745369246,
                0.9402995886420709,
                0.5378064918413052
            ],
            "color": "grey_8510"
        },
        {
            "id": 8,
            "vector": [
                0.39524717779832685,
                0.4000257286739164,
                -0.5890507376891594,
                -0.8650502298996872,
                -0.6140360785406336
            ],
            "color": "white_9381"
        },
        {
            "id": 9,
            "vector": [
                0.5718280481994695,
                0.24070317428066512,
                -0.3737913482606834,
                -0.06726932177492717,
                -0.6980531615588608
            ],
            "color": "purple_4976"
        }
    ],
    "collectionName": "quick_setup"
}'
响应200 - application/json
codeinteger

响应码。

costinteger

当前操作的花费。仅用于 Free 和 Serverless 集群，表示当前操作消耗的 vCU。

dataobject

响应载荷，包含了 upsert 操作的结果。

upsertCountinteger

插入或更新的 Entity 数量。

示例值：4
upsertIdsarray

插入或更新的 Entity ID 列表。注意：除非请求包含头 Accept-Type-Allow-Int64: true，否则 ID 以字符串形式返回。

[]upsertIdsstring

一个插入或更新的 Entity ID。

scanned_remote_bytesinteger

当部署使用 Tiered Storage 且已启用用量跟踪，并且操作从远程/磁盘存储读取数据时返回。当所有数据均从本地缓存提供时，此字段将被省略。

scanned_total_bytesinteger

当部署使用 Tiered Storage 且已启用用量跟踪，并且操作从远程/磁盘存储读取数据时返回。当所有数据均从本地缓存提供时，此字段将被省略。

cache_hit_rationumber

当部署使用 Tiered Storage 且已启用用量跟踪，并且操作从远程/磁盘存储读取数据时返回。当所有数据均从本地缓存提供时，此字段将被省略。

返回错误消息。

codeinteger

响应码。

messagestring

错误描述。

{
    "code": 0,
    "data": {
        "upsertCount": 10,
        "upsertIds": [
            0,
            1,
            2,
            3,
            4,
            5,
            6,
            7,
            8,
            9
        ]
    }
}