How do I install the Qdrant Horizontal Scaling skill?

Run npx skillmds@latest add pyfagorass/qdrant-horizontal-scaling in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Qdrant Horizontal Scaling safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Qdrant Horizontal Scaling?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Qdrant Horizontal Scaling free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Qdrant Horizontal Scaling?

pyfagorass (@pyfagorass) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Qdrant Horizontal Scaling by pyfagorass

Name: Qdrant Horizontal Scaling
Author: pyfagorass

Qdrant Horizontal Scaling

Diagnoses and guides Qdrant horizontal scaling decisions. Use when someone asks 'vertical or horizontal?', 'how many nodes?', 'how many shards?', 'how to add nodes', 'resharding', 'data doesn't fit', or 'need more capacity'. Also use when data growth outpaces current deployment.

pyfagorass 4633a4c 2.9 KB Updated Sep 17, 2026

File contents

What to Do When Qdrant Needs More Capacity

Vertical first: simpler operations, no network overhead, good up to ~100M vectors per node depending on 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

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 each shard has 1 replica, so you have 2 copies of data. This allows for zero-downtime scaling and maintenance. 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.

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
Resharding is not available for self-hosted deployments.

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

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)
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 causes days-long latency incidents)
Do not hit the collection limit by using one collection per tenant (use payload partitioning)

---name: qdrant-horizontal-scalingdescription: Diagnoses and guides Qdrant horizontal scaling decisions. Use when someone asks 'vertical or horizontal?', 'how many nodes?', 'how many shards?', 'how to add nodes', 'resharding', 'data doesn't fit', or 'need more capacity'. Also use when data growth outpaces current deployment.---# What to Do When Qdrant Needs More CapacityVertical first: simpler operations, no network overhead, good up to ~100M vectors per node depending on 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 scalingMinimum 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 each shard has 1 replica, so you have 2 copies of data. This allows for zero-downtime scaling and maintenance. With `replication_factor: 1`, zero-downtime is not guaranteed even for point-level operations, and cluster maintenance requires downtime.## Choosing number of shardsShards 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. ## Changing number of shardsUse 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](https://skills.qdrant.tech/md/documentation/distributed_deployment/?s=resharding)- Resharding is not available for self-hosted deployments.Better alternatives: over-provision shards initially, or spin up new cluster with correct config and migrate data.## 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)- 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 causes days-long latency incidents)- Do not hit the collection limit by using one collection per tenant (use payload partitioning)

Frequently asked questions