Insert (V2)

This operation inserts data into a specific collection.

POST/v2/vectordb/entities/insert

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 target database.

collectionNamestringrequired

The name of an existing collection.

dataoneOfrequired

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

Option 1

A single entity, whose structure should match the schema of the target collection.

Option 2

A list of entities, each of which should match the schema of the target collection.

partitionNamestring

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

partialUpdateboolean

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

fieldOpsarray

Field-level operations to apply to the entities being written. Each entry selects a field and specifies how its value is updated.

[]fieldOpsobject

A single field-level operation that selects a field and specifies how its value is updated.

fieldNamestring

The name of the field to which the operation applies.

opstring

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

pathstringPublic Preview

The path prefix within the volume that the field operation targets. This is required when type is EXTERNAL.

Examplebash

export TOKEN="db_admin:xxxxxxxxxxxxx"

curl --request POST \
--url "${CLUSTER_ENDPOINT}/v2/vectordb/entities/insert" \
--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"
}'

Responses200 OK - application/json

A dictionary contains information about the number of inserted entities.

Success

A response payload variant returned by the insert operation.

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 results of this operation.

insertCountinteger

The number of inserted entities.

Example Value: 4

insertIdsarray

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

[]insertIdsoneOf

The ID of an inserted entity.

Option 1

integer

(To be added soon)

Option 2

string

(To be added soon)

Failure

Returns an error message.

codeinteger

Response code.

messagestring

Error message.

Successjson

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