Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →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.
.claude/skills/github-qdrant-horizontal-scaling/SKILL.md| Test case | Without → With | Effect | Δ tokens | Δ turns |
|---|---|---|---|---|
| case-01 | ✗→✓ | ▲ Improved | -20% | 0% |
| case-02 | ✗→✓ | ▲ Improved | -6% | 0% |
| case-03 | ✗→✓ | ▲ Improved | -52% | 0% |
| case-06 | ✗→✓ | ▲ Improved | -10% | 0% |
| case-07 | ✗→✓ | ▲ Improved | -37% | 0% |
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).
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.
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.
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.
Better alternatives: over-provision shards initially, or spin up new cluster with correct config and migrate data.
shard_number that isn't a multiple of node count (uneven distribution)replication_factor: 1 in production if you need fault tolerance| Case | Status | Duration (ms) | Turns | Tokens | Tool calls | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Without | With | Δ | Without | With | Δ | Without | With | Δ | Without | With | Δ | ||
case-01 | fail→pass | 26,116 | 46,072 | +76% | 1 | 1 | 0% | 4,047 | 3,221 | -20% | 0 | 0 | — |
case-02 | fail→pass | 26,043 | 18,256 | -30% | 1 | 1 | 0% | 3,967 | 3,731 | -6% | 0 | 0 | — |
case-03 | fail→pass | 44,916 | 18,290 | -59% | 1 | 1 | 0% | 8,034 | 3,872 | -52% | 0 | 0 | — |
case-04 | pass→pass | 17,641 | 8,044 | -54% | 1 | 1 | 0% | 2,811 | 1,755 | -38% | 0 | 0 | — |
case-05 | pass→pass | 16,060 | 11,432 | -29% | 1 | 1 | 0% | 2,227 | 2,036 | -9% | 0 | 0 | — |
case-06 | fail→pass | 15,483 | 11,694 | -24% | 1 | 1 | 0% | 2,578 | 2,319 | -10% | 0 | 0 | — |
case-07 | fail→pass | 14,688 | 5,307 | -64% | 1 | 1 | 0% | 2,468 | 1,565 | -37% | 0 | 0 | — |
case-08 | pass→pass | 21,079 | 24,774 | +18% | 1 | 1 | 0% | 2,886 | 2,693 | -7% | 0 | 0 | — |
case-09 | pass→pass | 19,558 | 11,714 | -40% | 1 | 1 | 0% | 2,507 | 2,246 | -10% | 0 | 0 | — |
case-10 | pass→pass | 15,102 | 6,406 | -58% | 1 | 1 | 0% | 1,851 | 1,618 | -13% | 0 | 0 | — |
case-11 | fail→pass | 14,531 | 8,603 | -41% | 1 | 1 | 0% | 2,112 | 1,705 | -19% | 0 | 0 | — |
case-12 | pass→pass | 14,634 | 7,706 | -47% | 1 | 1 | 0% | 2,001 | 1,896 | -5% | 0 | 0 | — |
case-13 | pass→pass | 20,542 | 10,432 | -49% | 1 | 1 | 0% | 2,707 | 2,310 | -15% | 0 | 0 | — |
case-14 | pass→pass | 15,123 | 8,561 | -43% | 1 | 1 | 0% | 1,950 | 1,729 | -11% | 0 | 0 | — |
case-15 | pass→pass | 28,462 | 8,085 | -72% | 1 | 1 | 0% | 2,354 | 1,904 | -19% | 0 | 0 | — |
case-16 | fail→pass | 15,582 | 2,894 | -81% | 1 | 1 | 0% | 2,403 | 947 | -61% | 0 | 0 | — |
case-17 | fail→pass | 16,670 | 7,462 | -55% | 1 | 1 | 0% | 2,525 | 1,573 | -38% | 0 | 0 | — |
case-18 | pass→fail | 15,805 | 12,013 | -24% | 1 | 1 | 0% | 2,507 | 2,364 | -6% | 0 | 0 | — |
case-19 | pass→pass | 17,593 | 3,936 | -78% | 1 | 1 | 0% | 2,253 | 1,091 | -52% | 0 | 0 | — |
case-20 | pass→pass | 14,755 | 10,250 | -31% | 1 | 1 | 0% | 2,512 | 2,375 | -5% | 0 | 0 | — |
case-21 | pass→pass | 7,992 | 4,153 | -48% | 1 | 1 | 0% | 1,420 | 1,251 | -12% | 0 | 0 | — |
case-22 | pass→pass | 11,976 | 5,608 | -53% | 1 | 1 | 0% | 2,236 | 1,590 | -29% | 0 | 0 | — |
DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted. The headline lift of +32 percentage points is the difference between those two pass rates over the 22 comparable cases. 1 case got worse with the skill loaded, and it is included in that figure.
Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.
Other measured skills in the registry, with their headline benchmark lift.