Snapshots - Qdrant

Qdrant provides a comprehensive snapshot system for backing up and restoring data at multiple levels of granularity.

Collection Snapshots

Collection snapshots capture the complete state of a collection including vectors, payloads, indexes, and configuration.

Creating Collection Snapshots

REST API
Python
gRPC

POST /collections/{collection_name}/snapshots

Example:

curl -X POST http://localhost:6333/collections/my_collection/snapshots

from qdrant_client import QdrantClient

client = QdrantClient("localhost", port=6333)

snapshot_info = client.create_snapshot(
    collection_name="my_collection"
)

print(f"Snapshot created: {snapshot_info.name}")

import grpc
from qdrant_client import QdrantClient

client = QdrantClient("localhost", port=6334, prefer_grpc=True)
snapshot_info = client.create_snapshot(collection_name="my_collection")

Synchronous vs Asynchronous

By default, snapshot creation is synchronous. For large collections, use async mode:

curl -X POST "http://localhost:6333/collections/my_collection/snapshots?wait=false"

Listing Snapshots

GET /collections/{collection_name}/snapshots

Example:

curl http://localhost:6333/collections/my_collection/snapshots

Response:

{
  "result": [
    {
      "name": "my_collection-2024-03-04-12-00-00.snapshot",
      "creation_time": "2024-03-04T12:00:00Z",
      "size": 524288000
    }
  ],
  "status": "ok",
  "time": 0.001
}

Downloading Snapshots

GET /collections/{collection_name}/snapshots/{snapshot_name}

Example:

curl http://localhost:6333/collections/my_collection/snapshots/snapshot-2024.snapshot \
  --output my_collection_backup.snapshot

Deleting Snapshots

DELETE /collections/{collection_name}/snapshots/{snapshot_name}

Example:

curl -X DELETE \
  http://localhost:6333/collections/my_collection/snapshots/snapshot-2024.snapshot

Snapshot Recovery

Upload and Recover

Upload a snapshot file and automatically recover the collection:

POST /collections/{collection_name}/snapshots/upload

Example:

curl -X POST \
  -F "snapshot=@my_collection_backup.snapshot" \
  http://localhost:6333/collections/my_collection/snapshots/upload

With checksum verification:

curl -X POST \
  -F "snapshot=@backup.snapshot" \
  "http://localhost:6333/collections/my_collection/snapshots/upload?checksum=b3a8..."

Recover from URL

Recover from a remote snapshot location:

PUT /collections/{collection_name}/snapshots/recover

Example with HTTP URL:

curl -X PUT http://localhost:6333/collections/my_collection/snapshots/recover \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "http://example.com/backup.snapshot"
  }'

Example with file path:

curl -X PUT http://localhost:6333/collections/my_collection/snapshots/recover \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "file:///backup/snapshot.snapshot"
  }'

Recovery with Priority

Control recovery behavior:

{
  "location": "http://example.com/backup.snapshot",
  "priority": "snapshot"
}

Priority options:

snapshot - Prioritize snapshot data, prefer using the snapshot for recovery
replica - Prioritize existing replicas, use snapshot only if replicas unavailable
no_sync - Skip post-recovery synchronization

Shard Snapshots

For distributed deployments, you can create snapshots at the shard level.

Creating Shard Snapshots

POST /collections/{collection_name}/shards/{shard_id}/snapshots

Example:

curl -X POST \
  http://localhost:6333/collections/my_collection/shards/0/snapshots

Listing Shard Snapshots

GET /collections/{collection_name}/shards/{shard_id}/snapshots

Downloading Shard Snapshots

GET /collections/{collection_name}/shards/{shard_id}/snapshots/{snapshot_name}

Direct Shard Snapshot Streaming

Stream a shard snapshot directly:

GET /collections/{collection_name}/shards/{shard_id}/snapshot

This creates and streams the snapshot in one operation.

Shard Snapshot Recovery

Upload and recover a shard:

POST /collections/{collection_name}/shards/{shard_id}/snapshots/upload

Example:

curl -X POST \
  -F "snapshot=@shard-backup.snapshot" \
  "http://localhost:6333/collections/my_collection/shards/0/snapshots/upload"

Recover from URL:

PUT /collections/{collection_name}/shards/{shard_id}/snapshots/recover

curl -X PUT \
  http://localhost:6333/collections/my_collection/shards/0/snapshots/recover \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "http://example.com/shard-backup.snapshot",
    "priority": "snapshot"
  }'

Partial Snapshots

Partial snapshots enable incremental backups and recoveries, transferring only changed data.

Creating Partial Snapshots

POST /collections/{collection_name}/shards/{shard_id}/snapshot/partial/create

With manifest:

curl -X POST \
  http://localhost:6333/collections/my_collection/shards/0/snapshot/partial/create \
  -H 'Content-Type: application/json' \
  -d '{
    "files": [
      {"path": "segment_1.dat", "hash": "abc123"},
      {"path": "segment_2.dat", "hash": "def456"}
    ]
  }'

The server compares the manifest with its current state and returns only changed files.

Recovering from Partial Snapshots

POST /collections/{collection_name}/shards/{shard_id}/snapshot/partial/recover

Upload partial snapshot:

curl -X POST \
  -F "snapshot=@partial-backup.snapshot" \
  http://localhost:6333/collections/my_collection/shards/0/snapshot/partial/recover

Recover from Peer

Recover using partial snapshot from another peer:

POST /collections/{collection_name}/shards/{shard_id}/snapshot/partial/recover_from

Example:

curl -X POST \
  http://localhost:6333/collections/my_collection/shards/0/snapshot/partial/recover_from \
  -H 'Content-Type: application/json' \
  -d '{
    "peer_url": "http://peer-node:6333",
    "api_key": "your-api-key"
  }'

This:

Gets the partial snapshot manifest from the local shard
Requests a partial snapshot from the peer with the manifest
Receives only the differences
Applies changes to the local shard

Partial Snapshot Manifest

Get the current partial snapshot manifest:

GET /collections/{collection_name}/shards/{shard_id}/snapshot/partial/manifest

S3 Integration

Qdrant supports storing snapshots directly in S3.

Configuring S3 Storage

config/config.yaml

storage:
  snapshots_config:
    snapshots_storage: s3
    s3_config:
      bucket: "my-qdrant-snapshots"
      region: "us-east-1"
      access_key: "AKIAIOSFODNN7EXAMPLE"
      secret_key: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"

Store S3 credentials securely using environment variables or secret management systems.

Recovering from S3

curl -X PUT http://localhost:6333/collections/my_collection/snapshots/recover \
  -H 'Content-Type: application/json' \
  -d '{
    "location": "s3://my-qdrant-snapshots/backup.snapshot",
    "api_key": "AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
  }'

Storage Snapshots

Full storage snapshots capture the entire Qdrant instance.

Creating Full Snapshots

POST /snapshots

Example:

curl -X POST http://localhost:6333/snapshots

Listing Full Snapshots

GET /snapshots

Downloading Full Snapshots

GET /snapshots/{snapshot_name}

Deleting Full Snapshots

DELETE /snapshots/{snapshot_name}

Snapshot Monitoring

Monitor snapshot operations via metrics:

snapshot_creation_running - Number of active snapshot creations
snapshot_recovery_running - Number of active recoveries
snapshot_created_total - Total snapshots created

curl http://localhost:6333/metrics | grep snapshot

Best Practices

Use Checksums

Always verify snapshot integrity with SHA-256 checksums during uploads and recovery.

Async for Large Collections

Use wait=false for collections with millions of vectors to avoid timeouts.

Partial for Incremental

Use partial snapshots for frequent backups to reduce transfer size and time.

S3 for Durability

Store production snapshots in S3 or similar object storage for durability and disaster recovery.

Configuration

Snapshot Paths

config/config.yaml

storage:
  snapshots_path: ./snapshots
  temp_path: null  # Uses storage/snapshots_temp/ if null

Storage Backend

config/config.yaml

storage:
  snapshots_config:
    snapshots_storage: local  # or "s3"

Troubleshooting

Snapshot Creation Hangs

Use async mode: ?wait=false
Check disk space in snapshots_path
Verify no ongoing optimization tasks blocking resources

Recovery Fails

Verify checksum matches
Check Qdrant version compatibility
Ensure sufficient disk space in storage_path
Review logs for detailed error messages

Checksum Mismatch

{
  "status": "error",
  "error": "Checksum mismatch: expected b3a8..., got c4d9..."
}

The snapshot file is corrupted or modified. Re-download or use a different snapshot.

Empty Partial Snapshot

When recovering from a peer, if the response is NOT_MODIFIED (304), the replica is already up to date.

Advanced Usage

Custom Snapshot Names

Snapshots are automatically named with timestamps:

{collection_name}-{timestamp}.snapshot

Cross-Version Recovery

Snapshots are forward-compatible within major versions. For major version upgrades, consult migration documentation.

Concurrent Operations

Multiple snapshot operations can run concurrently:

Different collections can snapshot simultaneously
Snapshot creation doesn’t block searches or updates
Recovery operations are serialized per collection

Getting Started

Core Concepts

Working with Data

Advanced Features

Deployment

Operations

​Collection Snapshots

​Creating Collection Snapshots

​Synchronous vs Asynchronous

​Listing Snapshots

​Downloading Snapshots

​Deleting Snapshots

​Snapshot Recovery

​Upload and Recover

​Recover from URL

​Recovery with Priority

​Shard Snapshots

​Creating Shard Snapshots

​Listing Shard Snapshots

​Downloading Shard Snapshots

​Direct Shard Snapshot Streaming

​Shard Snapshot Recovery

​Partial Snapshots

​Creating Partial Snapshots

​Recovering from Partial Snapshots

​Recover from Peer

​Partial Snapshot Manifest

​S3 Integration

​Configuring S3 Storage

​Recovering from S3

​Storage Snapshots

​Creating Full Snapshots

​Listing Full Snapshots

​Downloading Full Snapshots

​Deleting Full Snapshots

​Snapshot Monitoring

​Best Practices

Use Checksums

Async for Large Collections

Partial for Incremental

S3 for Durability

​Configuration

​Snapshot Paths

​Storage Backend

​Troubleshooting

​Snapshot Creation Hangs

​Recovery Fails

​Checksum Mismatch

​Empty Partial Snapshot

​Advanced Usage

​Custom Snapshot Names

​Cross-Version Recovery

​Concurrent Operations

Collection Snapshots

Creating Collection Snapshots

Synchronous vs Asynchronous

Listing Snapshots

Downloading Snapshots

Deleting Snapshots

Snapshot Recovery

Upload and Recover

Recover from URL

Recovery with Priority

Shard Snapshots

Creating Shard Snapshots

Listing Shard Snapshots

Downloading Shard Snapshots

Direct Shard Snapshot Streaming

Shard Snapshot Recovery

Partial Snapshots

Creating Partial Snapshots

Recovering from Partial Snapshots

Recover from Peer

Partial Snapshot Manifest

S3 Integration

Configuring S3 Storage

Recovering from S3

Storage Snapshots

Creating Full Snapshots

Listing Full Snapshots

Downloading Full Snapshots

Deleting Full Snapshots

Snapshot Monitoring

Best Practices

Configuration

Snapshot Paths

Storage Backend

Troubleshooting

Snapshot Creation Hangs

Recovery Fails

Checksum Mismatch

Empty Partial Snapshot

Advanced Usage

Custom Snapshot Names

Cross-Version Recovery

Concurrent Operations