How to insert a document into a collection by using the HTTP API-DashVector(DashVector)-阿里云帮助中心

Insert one or more documents into a DashVector collection. Each document consists of an ID, a dense vector, and optional fields or sparse vectors.

Note

If a document with the same ID already exists in the collection, the insert operation skips that document without overwriting it. If you omit the id field, DashVector automatically generates an ID and returns it in the response.

Prerequisites

Before you begin, make sure that you have:

A DashVector cluster. See Create a cluster
An API key. See Manage API keys
The latest version of the DashVector SDK. See Install DashVector SDK

Request syntax

HTTP

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

Examples

All examples use curl to send requests to the insert endpoint. Replace YOUR_API_KEY with your API key and YOUR_CLUSTER_ENDPOINT with the endpoint of your cluster.

The examples use a collection named quickstart with a vector dimension of 4. To create this collection, see the "Example" section of Create a collection.

Insert a single document

Insert a document with a 4-dimensional vector:

Shell

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

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

Insert a document with fields

Attach custom key-value pairs to a document through the fields object. Supported value types: string, integer, float, and boolean.

Shell

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",
            "weight": 70.0,
            "id": 1234567890,
            "anykey1": "str-value",
            "anykey2": 1,
            "anykey3": true,
            "anykey4": 3.1415926
          }
      }
    ]
   }' https://YOUR_CLUSTER_ENDPOINT/v1/collections/quickstart/docs

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

Insert multiple documents in a batch

Pass multiple document objects in the docs array. Documents in the same batch do not need to share the same fields.

Shell

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

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

Insert a document with a sparse vector

Include a sparse_vector object alongside the dense vector.

Shell

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

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

Request parameters

Parameter	Location	Type	Required	Description
`{Endpoint}`	Path	str	Yes	Cluster endpoint. Find this on the cluster details page in the console.
`{CollectionName}`	Path	str	Yes	Name of the target collection.
`dashvector-auth-token`	Header	str	Yes	API key for authentication.
`docs`	Body	array	Yes	Array of document objects to insert.
`partition`	Body	str	No	Target partition name.

Response parameters

Parameter	Type	Description	Example
`code`	int	Status code. `0` indicates success. For non-zero codes, see Status codes.	`0`
`message`	str	Human-readable status message.	`Success`
`request_id`	str	Unique request identifier for troubleshooting.	`19215409-ea66-4db9-8764-26ce2eb5bb99`
usage	map	For successful doc insertion requests to a serverless (pay-as-you-go) collection, this parameter returns the number of consumed write request units (WRUs).	`{ Usage: { write_units: 3 } }`