How to insert or update a doc in a collection by using the HTTP API-DashVector(DashVector)-阿里云帮助中心

Insert new documents or overwrite existing documents in a collection through the HTTP API.

If a document with the specified ID already exists, the operation updates the document. If no document with the specified ID exists, the operation inserts a new document.

Prerequisites

Before you begin, make sure that you have:

A DashVector cluster
An API key
The latest version of the DashVector SDK

Request

POST https://{Endpoint}/v1/collections/{CollectionName}/docs/upsert

Request parameters

Parameter	Location	Type	Required	Description
{Endpoint}	Path	str	Yes	The cluster endpoint. Find this on the cluster details page in the console.
{CollectionName}	Path	str	Yes	The collection name.
dashvector-auth-token	Header	str	Yes	The API key.
docs	Body	array	Yes	An array of documents to upsert.
partition	Body	str	No	The partition name.

Response parameters

Parameter	Type	Description	Example
code	int	Status code. `0` indicates success. See Status codes for details.	0
message	str	A human-readable status message.	Success
request_id	str	A unique identifier for the request, useful for troubleshooting.	19215409-ea66-4db9-8764-26ce2eb5bb99
usage	map	For a doc insert or update request to a collection of a serverless (pay-as-you-go) instance, this parameter indicates the number of write request units (WRUs) consumed after the request is successful.	`{ Usage: { write_units: 4 } }`

Examples

The following examples use a collection named quickstart. Create this collection first by following the steps in Create a collection.

Replace the placeholders with your actual values:

Placeholder	Description
`<your-api-key>`	Your DashVector API key
`<your-cluster-endpoint>`	Your cluster endpoint URL

Upsert a single document

The simplest upsert call sends one document with an ID and a vector:

curl -XPOST \
  -H 'dashvector-auth-token: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "docs": [{"id": "1", "vector": [0.1, 0.2, 0.3, 0.4]}]
  }' https://<your-cluster-endpoint>/v1/collections/quickstart/docs/upsert

Sample response:

{
  "request_id": "3fc2acfa-48cb-4924-8ef7-f94388ecb07d",
  "code": 0,
  "message": "Success"
}

Upsert a document with fields

Attach metadata as key-value pairs in the fields object. Supported value types include strings, integers, floats, and booleans.

curl -XPOST \
  -H 'dashvector-auth-token: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "docs": [
      {
        "id": "2",
        "vector": [0.2, 0.3, 0.4, 0.5],
        "fields": {
          "age": 70,
          "name": "zhangshan",
          "anykey1": "str-value",
          "anykey2": 1,
          "anykey3": true,
          "anykey4": 3.1415926
        }
      }
    ]
   }' https://<your-cluster-endpoint>/v1/collections/quickstart/docs/upsert

Sample response:

{
  "request_id": "4abd0c5e-78a6-488b-976f-16f0d2e628c5",
  "code": 0,
  "message": "Success"
}

Upsert multiple documents in a batch

Pass multiple document objects in the docs array to upsert them in a single request. Each document can independently include or omit fields.

curl -XPOST \
  -H 'dashvector-auth-token: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "docs": [
      {"id": "3", "vector": [0.3, 0.4, 0.5, 0.6]},
      {"id": "4", "vector": [0.4, 0.5, 0.6, 0.7], "fields": {"age": 20, "name": "zhangsan"}},
      {"id": "5", "vector": [0.5, 0.6, 0.7, 0.8], "fields": {"anykey": "anyvalue"}}
    ]
   }' https://<your-cluster-endpoint>/v1/collections/quickstart/docs/upsert

Sample response:

{
  "request_id": "19215409-ea66-4db9-8764-26ce2eb5bb99",
  "code": 0,
  "message": ""
}

Upsert a document with a sparse vector

A sparse vector stores only the non-zero elements as index-value pairs. This format is efficient for high-dimensional data where most values are zero. For example, the sparse vector {"1": 0.4, "10000": 0.6, "222222": 0.8} represents three non-zero values at indices 1, 10000, and 222222, with all other positions implicitly zero.

Include the sparse_vector field alongside the dense vector:

curl -XPOST \
  -H 'dashvector-auth-token: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "docs": [
      {
        "id": "6",
        "vector": [0.1, 0.2, 0.3, 0.4],
        "sparse_vector": {"1": 0.4, "10000": 0.6, "222222": 0.8}
      }
    ]
   }' https://<your-cluster-endpoint>/v1/collections/quickstart/docs/upsert

Sample response:

{
  "request_id": "4fefe855-ae39-48b3-9aa8-f45a77a3cd29",
  "code": 0,
  "message": "Success"
}