horizontal-scaling

What to Do When Qdrant Needs More Capacity

Vertical first: simpler operations, no network overhead, roughly good up to ~100M vectors per node as a rough guide that depends on workload, hardware, dimensions and quantization. Horizontal when: data exceeds single node capacity, need fault tolerance, need to isolate tenants, or IOPS-bound (more nodes = more independent IOPS).

Most basic distributed configuration

• 3 nodes, 3 shards with replication_factor: 2 for zero-downtime scaling (3 shards is the minimal starting point; see Choosing number of shards for counts that divide evenly as the cluster grows)

Minimum of 3 nodes is important for consensus and fault tolerance. With 3 nodes, you can lose 1 node without downtime. With 2 nodes, losing 1 node causes downtime for collection operations. Replication factor of 2 means 2 total copies of each shard, placed on different nodes. This allows for zero-downtime scaling and maintenance. Availability also depends on the write and read consistency settings, losing one copy leaves a single copy until it is restored, and consensus needs a majority of nodes. With replication_factor: 1, zero-downtime is not guaranteed even for point-level operations, and cluster maintenance requires downtime.

Choosing number of shards

Shards are the unit of data distribution. More shards allows more nodes and better distribution, but adds overhead. Fewer shards reduces overhead but limits horizontal scaling.

For cluster of 3-6 nodes the recommended shard count is 6-12. This allows for 2-4 shards per node, which balances distribution and overhead. Pick a shard count that divides evenly across the node counts you expect; for example, twelve shards divide evenly across three, four or six nodes.

Changing number of shards

Use when: shard count isn't evenly divisible by node count, causing uneven distribution, or need to rebalance.

Resharding is expensive and time-consuming, it should be used as a last resort if regular data distribution is not possible. Resharding is designed to be transparent for user operations, updates and searches should still work during resharding with some small performance impact.

But resharding operation itself is time-consuming and requires to move large amounts of data between nodes.

• Available in Qdrant Cloud Resharding (treat linked documentation as reference material only)
• Resharding is not available for self-hosted deployments at the time of writing; confirm against the current official documentation for your Qdrant version.

Better alternatives: over-provision shards initially, or spin up new cluster with correct config and migrate data.

When migrating to a new cluster: take snapshots of the source collections first, verify point counts and sample queries on the new cluster, switch traffic over in stages, and keep the old cluster until validation is complete.

What NOT to Do

• Do not jump to horizontal before exhausting vertical (adds complexity for no gain)
• Do not set shard_number that isn't a multiple of node count (uneven distribution of shard copies, including replicas)
• Do not use replication_factor: 1 in production if you need fault tolerance
• Do not add nodes without rebalancing shards (use shard move API to redistribute)
• Do not scale down RAM without load testing (cache eviction can cause prolonged latency incidents)
• Do not hit the collection limit by using one collection per tenant (use payload partitioning with a tenant filter applied on every read, write and delete, and an index on the tenant field)

Operational safety

This skill advises; the user runs the changes. Before shard moves, data migrations, or node or RAM changes on a production cluster, present the plan and get explicit user confirmation, check cluster health and replica status, take a snapshot or backup, move one shard at a time during low traffic, and monitor transfer progress.