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

Update one or more documents in a DashVector collection through the HTTP API.

Note

If the ID of a document to be updated does not exist, the update operation is invalid for the document.
If you update only some fields, the rest of the fields are set to null by default.

Prerequisites

Before you begin, make sure you have:

A DashVector cluster
An API key
The latest DashVector SDK

Method and URL

HTTP

PUT https://{Endpoint}/v1/collections/{CollectionName}/docs

Examples

The following examples use the quickstart collection. Create it by following the example in Create a collection.

Replace these placeholders with your actual values:

Placeholder	Description
`YOUR_API_KEY`	Your DashVector API key
`YOUR_CLUSTER_ENDPOINT`	Your cluster endpoint

Update a single document

The following request updates only the vector for document 1:

Shell

curl -XPUT \
  -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

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

Update a document with fields

The following request updates the vector and custom fields for document 2. All six fields (age, name, anykey1 through anykey4) are included because omitted fields are reset to null:

Shell

curl -XPUT \
  -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

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

Update multiple documents in a batch

Pass multiple documents in the docs array. Each document can have a different combination of vector and fields:

Shell

curl -XPUT \
  -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

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

Update a document with a sparse vector

Include a sparse_vector object alongside the dense vector:

Shell

curl -XPUT \
  -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

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

Request parameters

Parameter	Location	Type	Required	Description
`{Endpoint}`	Path	str	Yes	The cluster endpoint. Find it 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	A list of documents to update.
`partition`	Body	str	No	The partition name.

Response parameters

Parameter	Type	Description	Example
`code`	int	Status code. `0` indicates success. For details, see Status codes.	0
`message`	str	Response message.	success
`request_id`	str	Unique request identifier.	19215409-ea66-4db9-8764-26ce2eb5bb99
usage	map	For serverless (pay-as-you-go) instances, this parameter returns the number of write units consumed by a successful doc update request.	`{ Usage: { write_units: 5 } }`