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.
git clone --depth 1 https://github.com/qdrant/skills /tmp/qdrant-horizontal-scaling && cp -r /tmp/qdrant-horizontal-scaling/skills/qdrant-scaling/scaling-data-volume/horizontal-scaling ~/.claude/skills/qdrant-horizontal-scalingSKILL.md
# 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](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)
Qdrant provides client SDKs for various programming languages, allowing easy integration with Qdrant deployments.
Guides Qdrant deployment selection. Use when someone asks 'how to deploy Qdrant', 'Docker vs Cloud', 'local mode', 'embedded Qdrant', 'Qdrant EDGE', 'which deployment option', 'self-hosted vs cloud', or 'need lowest latency deployment'. Also use when choosing between deployment types for a new project.
Guides embedding model migration in Qdrant without downtime. Use when someone asks 'how to switch embedding models', 'how to migrate vectors', 'how to update to a new model', 'zero-downtime model change', 'how to re-embed my data', or 'can I use two models at once'. Also use when upgrading model dimensions, switching providers, or A/B testing models.
Guides Qdrant monitoring and observability setup. Use when someone asks 'how to monitor Qdrant', 'what metrics to track', 'is Qdrant healthy', 'optimizer stuck', 'why is memory growing', 'requests are slow', or needs to set up Prometheus, Grafana, or health checks. Also use when debugging production issues that require metric analysis.
Diagnoses Qdrant production issues using metrics and observability tools. Use when someone reports 'optimizer stuck', 'indexing too slow', 'memory too high', 'OOM crash', 'queries are slow', 'latency spike', or 'search was fast now it's slow'. Also use when performance degrades without obvious config changes.
Guides Qdrant monitoring setup including Prometheus scraping, health probes, Hybrid Cloud metrics, alerting, and log centralization. Use when someone asks 'how to set up monitoring', 'Prometheus config', 'Grafana dashboard', 'health check endpoints', 'how to scrape Hybrid Cloud', 'what alerts to set', 'how to centralize logs', or 'audit logging'.
Different techniques to optimize the performance of Qdrant, including indexing strategies, query optimization, and hardware considerations. Use when you want to improve the speed and efficiency of your Qdrant deployment.
Diagnoses and fixes slow Qdrant indexing and data ingestion. Use when someone reports 'uploads are slow', 'indexing takes forever', 'optimizer is stuck', 'HNSW build time too long', or 'data uploaded but search is bad'. Also use when optimizer status shows errors, segments won't merge, or indexing threshold questions arise.