Batch operations allow you to perform multiple operations in a single request, significantly improving throughput and reducing network overhead.
Batch Insert/Upsert
Insert or update multiple points in a single request.
API Endpoint
PUT /collections/{collection_name}/points
curl -X PUT http://localhost:6333/collections/my_collection/points \
-H 'Content-Type: application/json' \
-d '{
"points": [
{"id": 1, "vector": [0.1, 0.2, 0.3], "payload": {"city": "Berlin"}},
{"id": 2, "vector": [0.2, 0.3, 0.4], "payload": {"city": "London"}},
{"id": 3, "vector": [0.3, 0.4, 0.5], "payload": {"city": "Paris"}},
{"id": 4, "vector": [0.4, 0.5, 0.6], "payload": {"city": "Madrid"}},
{"id": 5, "vector": [0.5, 0.6, 0.7], "payload": {"city": "Rome"}}
]
}'
The batch format is more efficient for large uploads as it avoids repeating field names.
Batch Update Operations
Perform multiple update operations (upsert, delete, update payload, etc.) in a single request.
API Endpoint
POST /collections/{collection_name}/points/batch
curl -X POST http://localhost:6333/collections/my_collection/points/batch \
-H 'Content-Type: application/json' \
-d '{
"operations": [
{
"upsert": {
"points": [
{"id": 1, "vector": [0.1, 0.2, 0.3], "payload": {"city": "Berlin"}},
{"id": 2, "vector": [0.2, 0.3, 0.4], "payload": {"city": "London"}}
]
}
},
{
"update_vectors": {
"points": [
{"id": 3, "vector": [0.3, 0.4, 0.5]}
]
}
},
{
"set_payload": {
"payload": {"status": "active"},
"points": [1, 2, 3]
}
},
{
"delete": {
"points": [10, 11, 12]
}
}
]
}'
Supported Operations
Delete points by IDs or filter.
Set or merge payload for specified points.
operations[].overwrite_payload
Replace entire payload for specified points.
operations[].delete_payload
Delete specific payload fields.
operations[].clear_payload
Remove all payload from specified points.
operations[].update_vectors
Update vectors for existing points.
operations[].delete_vectors
Delete specific named vectors.
Batch Delete
Delete multiple points at once.
API Endpoint
POST /collections/{collection_name}/points/delete
Delete by IDs
curl -X POST http://localhost:6333/collections/my_collection/points/delete \
-H 'Content-Type: application/json' \
-d '{
"points": [1, 2, 3, 5, 8, 13, 21]
}'
Delete by Filter
Delete all points matching a filter condition.
curl -X POST http://localhost:6333/collections/my_collection/points/delete \
-H 'Content-Type: application/json' \
-d '{
"filter": {
"must": [
{
"key": "status",
"match": {"value": "inactive"}
}
]
}
}'
Deleting by filter can affect many points. Use with caution in production environments.
API Endpoint
POST /collections/{collection_name}/points/scroll
curl -X POST http://localhost:6333/collections/my_collection/points/scroll \
-H 'Content-Type: application/json' \
-d '{
"limit": 100,
"with_payload": true,
"with_vector": false
}'
Start scrolling from this offset. Use the next_page_offset from the previous response.
Maximum number of points to return per request.
with_payload
boolean | array
default:"true"
Include payload in results. Can be true, false, or array of specific fields.
with_vector
boolean | array
default:"false"
Include vectors in results.
Filter conditions to apply during scrolling.
Paginate Through All Points
from qdrant_client import QdrantClient
client = QdrantClient(url="http://localhost:6333")
all_points = []
offset = None
while True:
result, offset = client.scroll(
collection_name="my_collection",
limit=100,
offset=offset,
with_payload=True,
with_vectors=False
)
all_points.extend(result)
if offset is None:
break # No more points
print(f"Total points retrieved: {len(all_points)}")
curl -X POST http://localhost:6333/collections/my_collection/points/scroll \
-H 'Content-Type: application/json' \
-d '{
"limit": 50,
"filter": {
"must": [
{
"key": "country",
"match": {"value": "Germany"}
}
]
},
"with_payload": ["city", "population"],
"with_vector": false
}'
Batch Upsert Response
{
"result": {
"operation_id": 123,
"status": "completed"
},
"status": "ok",
"time": 0.045
}
Batch Update Response
{
"result": [
{
"operation_id": 124,
"status": "completed"
},
{
"operation_id": 125,
"status": "completed"
},
{
"operation_id": 126,
"status": "completed"
}
],
"status": "ok",
"time": 0.067
}
{
"result": {
"points": [
{
"id": 1,
"payload": {"city": "Berlin"},
"vector": null
},
{
"id": 2,
"payload": {"city": "London"},
"vector": null
}
],
"next_page_offset": 100
},
"status": "ok",
"time": 0.003
}
Array of retrieved points.
Offset for the next page. null means no more points.
Query Parameters
Wait for the operation to complete before returning.
Ordering guarantees: weak, medium, or strong.
Operation timeout in seconds.
Best Practices
- Batch Size: Use batch sizes of 100-1000 points for optimal performance
- Wait Parameter: Set
wait=false for bulk operations to improve throughput
- Scroll Limit: Keep scroll limit reasonable (100-1000) to balance memory and network
- Error Handling: Implement retry logic for failed batch operations
- Memory Management: Process scroll results in chunks to avoid memory issues
- Parallel Processing: For very large datasets, consider parallel scroll operations with filters
Batch operations are atomic - either all operations succeed or all fail.
