Insert Points

Learn how to insert and upsert points (vectors with payloads) into Qdrant collections using the REST API and Python client.

Points are the core data structure in Qdrant. Each point consists of an ID, a vector (or multiple vectors), and an optional payload.

API Endpoint

PUT /collections/{collection_name}/points

This endpoint performs an upsert operation: if a point with the given ID already exists, it will be overwritten. Otherwise, a new point will be created.

Point Structure

Each point has the following structure:

id · integer | string · required

Unique identifier for the point. Can be an integer or UUID string.

vector · array | object · required

Vector data. Can be a simple array for single vectors or an object with named vectors.

payload · object

Optional JSON object with additional data associated with the point.

Insert a Single Point

REST API

curl -X PUT http://localhost:6333/collections/my_collection/points \
  -H 'Content-Type: application/json' \
  -d '{
    "points": [
      {
        "id": 1,
        "vector": [0.05, 0.61, 0.76, 0.74],
        "payload": {
          "city": "Berlin",
          "country": "Germany",
          "population": 3645000,
          "year": 2023
        }
      }
    ]
  }'

Insert Multiple Points (Batch)

Batch insertion is more efficient for inserting multiple points at once.

REST API

curl -X PUT http://localhost:6333/collections/my_collection/points \
  -H 'Content-Type: application/json' \
  -d '{
    "points": [
      {
        "id": 1,
        "vector": [0.05, 0.61, 0.76, 0.74],
        "payload": {"city": "Berlin", "country": "Germany"}
      },
      {
        "id": 2,
        "vector": [0.19, 0.81, 0.75, 0.11],
        "payload": {"city": "London", "country": "UK"}
      },
      {
        "id": 3,
        "vector": [0.36, 0.55, 0.47, 0.94],
        "payload": {"city": "Paris", "country": "France"}
      }
    ]
  }'

Insert Points with Named Vectors

For collections with multiple named vectors, specify each vector separately.

REST API

curl -X PUT http://localhost:6333/collections/multi_vector_collection/points \
  -H 'Content-Type: application/json' \
  -d '{
    "points": [
      {
        "id": 1,
        "vector": {
          "text": [0.1, 0.2, 0.3, 0.4],
          "image": [0.5, 0.6, 0.7, 0.8]
        },
        "payload": {
          "title": "Product A",
          "description": "High quality item"
        }
      }
    ]
  }'

Insert Points Using Batch Format

The batch format is more efficient for inserting many points with the same structure.

REST API

curl -X PUT http://localhost:6333/collections/my_collection/points \
  -H 'Content-Type: application/json' \
  -d '{
    "batch": {
      "ids": [1, 2, 3],
      "vectors": [
        [0.05, 0.61, 0.76, 0.74],
        [0.19, 0.81, 0.75, 0.11],
        [0.36, 0.55, 0.47, 0.94]
      ],
      "payloads": [
        {"city": "Berlin"},
        {"city": "London"},
        {"city": "Paris"}
      ]
    }
  }'

Query Parameters

wait · boolean · default: "true"

If true, wait for changes to actually happen. If false, return immediately after the request is accepted.

ordering · string

Define ordering guarantees for the operation:

• weak - No ordering guarantees
• medium - Operations are ordered within a single node
• strong - Operations are ordered across all nodes

timeout · integer

Timeout for the operation in seconds.

Using the Wait Parameter

Wait for completion

curl -X PUT "http://localhost:6333/collections/my_collection/points?wait=true" \
  -H 'Content-Type: application/json' \
  -d '{...}'

The request will return only after the points are fully indexed and available for search.

Return immediately

curl -X PUT "http://localhost:6333/collections/my_collection/points?wait=false" \
  -H 'Content-Type: application/json' \
  -d '{...}'

The request returns immediately after accepting the operation. Points may not be immediately searchable.

Setting wait=false provides lower latency but points may not be immediately available for search.

Response Format

result · object

Result of the upsert operation.

result.operation_id · integer

Sequential number of the operation.

result.status · string

Operation status: completed or acknowledged.

status · string

Overall response status, typically “ok”.

time · number

Time taken to execute the operation in seconds.

Response Example

{
  "result": {
    "operation_id": 0,
    "status": "completed"
  },
  "status": "ok",
  "time": 0.002375
}

Update Modes

Control how points are inserted or updated:

Insert Only (Skip Existing)

curl -X PUT http://localhost:6333/collections/my_collection/points \
  -H 'Content-Type: application/json' \
  -d '{
    "points": [...],
    "update_mode": "insert_only"
  }'

update_mode · string · default: "upsert"

• upsert - Insert new points and update existing ones (default)
• insert_only - Only insert new points, skip existing ones
• update_only - Only update existing points, skip new ones

Vector dimensions must match the collection configuration. Mismatched dimensions will result in an error.

Best Practices

1. Batch Size: Insert points in batches of 100-1000 for optimal performance
2. Wait Parameter: Use wait=false for bulk uploads to improve throughput
3. Payload Size: Keep payloads reasonably sized (< 1MB per point) for best performance
4. IDs: Use sequential integers or UUIDs; avoid very long string IDs