跳到主要内容

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.
shell
export CLUSTER_ENDPOINT=""
参数
Authorizationstringheader必填项

认证令牌，应为具备适当权限的 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.

dataobject必填项

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

partialUpdateboolean

是否启用部分更新。启用后，仅更新指定字段。可通过 fieldOps 为各字段指定替换或数组更新行为。

fieldOpsarray

部分更新时应用的字段级操作。每一项指定目标字段及其值的更新方式。

[]fieldOpsobject
fieldNamestring必填项

待更新字段的名称。

opstring必填项

更新操作。REPLACE 替换字段值，ARRAY_APPEND 追加数组元素，ARRAY_REMOVE 删除匹配的数组元素。

bash
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"
}'
bash
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 '{
    "collectionName": "product_catalog",
    "data": [
        {
            "id": 1,
            "tags": [
                "featured"
            ]
        }
    ],
    "partialUpdate": true,
    "fieldOps": [
        {
            "fieldName": "tags",
            "op": "ARRAY_APPEND"
        }
    ]
}'
响应200 OK - application/json

返回一个 MutationResult 对象。

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

错误描述。

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