Skip to main content

Upsert (V2)

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

POST/v2/vectordb/entities/upsert
Connection Endpoint

The base URL for this API is in the following format:

https://${CLUSTER_ENDPOINT}

📘Notes
  • You need to fill in ${CLUSTER_ENDPOINT} with that of your Zilliz Cloud cluster.
  • To get the endpoint, use the Describe Cluster V2 API to extract the values from the responses.
shell
export CLUSTER_ENDPOINT=""
Parameters
Authorizationstringheaderrequired

The authentication token should be an API key with appropriate privileges or a pair of colon-joined username and password, like username:password.

Example Value: Bearer {{TOKEN}}
Request Bodyapplication/json
dbNamestring

The name of the database.

collectionNamestringrequired

The name of the collection in which to upsert data.

partitionNamestring

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

dataobjectrequired

An entity object or an array of entity objects. Note that the keys in an entity object should match the collection schema

partialUpdateboolean

Whether to enable partial updates. When enabled, only the specified fields are updated. Use fieldOps to select replacement or array-specific update behavior for individual fields.

fieldOpsarray

Field-level operations to apply during a partial update. Each entry selects a field and specifies how its value is updated.

[]fieldOpsobject
fieldNamestringrequired

The name of the field to update.

opstringrequired

The update operation. REPLACE replaces the field value, ARRAY_APPEND appends array elements, and ARRAY_REMOVE removes matching array elements.

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"
        }
    ]
}'
Responses200 OK - application/json

A MutationResult object.

codeinteger

Response code.

costinteger

Cost of this operation. This applies to free and serverless clusters only, indicating the vCU usage of the current request.

dataobject

Response payload which carries the result of the upsert operation.

upsertCountinteger

The number of upserted entities.

Example Value: 4
upsertIdsarray

An array of the IDs of upserted entities. Note: IDs are returned as strings unless the request includes the header Accept-Type-Allow-Int64: true.

[]upsertIdsstring

The ID of an upserted entity.

scanned_remote_bytesinteger

Returned when the deployment uses tiered storage with usage tracking enabled and the operation reads from remote/disk storage. Omitted when all data is served from local cache.

scanned_total_bytesinteger

Returned when the deployment uses tiered storage with usage tracking enabled and the operation reads from remote/disk storage. Omitted when all data is served from local cache.

cache_hit_rationumber

Returned when the deployment uses tiered storage with usage tracking enabled and the operation reads from remote/disk storage. Omitted when all data is served from local cache.

Returns an error message.

codeinteger

Response code.

messagestring

Error message.

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