--- name: qdrant/qdrant-multitenancy source: https://app.decimal.ai/s/qdrant-qdrant-multitenancy@1/SKILL.md source_sha256: 2c0d48a2d5e0 --- # Qdrant Multitenancy [Multitenancy](https://skills.qdrant.tech/md/documentation/manage-data/multitenancy/) is how you isolate data across multiple users or tenants within a single Qdrant deployment. - The question to ask is: **how many tenants, and how unevenly sized are they?** That answer picks the isolation strategy. - Understand the three isolation levels before choosing: payload-based, shard-based and collection-based. - For almost everyone the right default is a single collection partitioned by payload, NOT a collection per tenant. ## Many Small Tenants (Default: Payload Partitioning) Use when: you have many tenants of roughly similar, modest size. This is the recommended default for most users. One collection holds every tenant. A payload field marks ownership, and a filter on that field at query time is what isolates each tenant's results. ### How It Works - Create a keyword payload index on the tenant field with `is_tenant=true` (the flag requires v1.11+). `is_tenant` tells Qdrant the field identifies tenants, so each tenant's vectors are stored together and served by sequential reads. Check [](https://api.qdrant.tech/api-reference/indexes/create-field-index). - At query time, isolate each tenant with a `must` filter on the tenant field. Without it, a query searches every tenant's data. Check [Payload-based multitenancy](https://skills.qdrant.tech/md/documentation/manage-data/multitenancy/?s=partition-by-payload). - With this strategy, the indexing speed might become a bottleneck at scale because every tenant indexes into the same collection. To avoid this, you can disable the global HNSW creation (for the entire collection) and only build per-tenant indexes: set `m=0` and `payload_m` to a non-zero value. Although this accelerates the indexing process, keep in mind that requests without a tenant filter will become slower as they must scan all groups. So only make this trade if you hit the bottleneck and cross-tenant search is rare. [Calibrate performance](https://skills.qdrant.tech/md/documentation/manage-data/multitenancy/?s=calibrate-performance). ## A Few Large Tenants Plus a Long Tail (Tiered Multitenancy) Use when: you have a realistic SaaS distribution: a few large customers and many small ones, possibly with small tenants that grow over time. Available in v1.16+. It avoids the noisy-neighbor problem, where one big tenant forces the whole cluster to scale, raising costs and degrading performance for everyone else. Tiered multitenancy keeps small tenants together in a shared fallback shard while isolating large tenants in their own dedicated shards, all in one collection. It layers two isolation levels: payload-based tenancy for logical isolation, and custom sharding for physical/ resource-based isolation of the large tenants. A tenant that outgrows the shared shard can be promoted to a dedicated shard later with no downtime. ### How It Works - Create the collection with custom (user-defined) sharding, and configure payload-based tenancy. A single shared fallback shard holds all the small tenants. If you have large tenants, create dedicated shards (one per tenant). Check [Tiered multitenancy](https://skills.qdrant.tech/md/documentation/manage-data/multitenancy/?s=tiered-multitenancy). - When to promote a tenant? If a tenant becomes large enough to warrant dedicated resources (a reasonable promotion trigger is when a tenant approaches the indexing threshold), promote it to a dedicated shard. Qdrant moves its data into a new shard transparently, serving reads and writes throughout. Check [how to promote tenant to dedicated shard](https://skills.qdrant.tech/md/documentation/manage-data/multitenancy/?s=promote-tenant-to-dedicated-shard). - Keep in mind that re-sharding can be an expensive and time-consuming process, so consider your tenant growth patterns carefully when deciding which tenants should receive dedicated shards. - It's not recommended to exceed ~1000 dedicated shards per cluster (resource overhead). - The fallback shard (small tenants) must fit on a single node. - Sharding method is fixed at collection creation: an auto-sharded collection (default) cannot be converted to custom sharding in place. If there is any realistic chance you will need to isolate a large tenant later, create the collection with custom sharding up front and put every tenant in the fallback shard. ## Few Non-Homogenous Tenants (Collection per Tenant) Use when: you have a limited number of tenants with different per-tenant embedding models or collection schemas. - You should only create multiple collections when your data is not homogenous or if users' vectors are created by different embedding models. ## Data Residency and Geographic Isolation (Custom Sharding) Use when: data must be physically pinned to a location, e.g. regional compliance for healthcare industry (one region's data in Canada, another's in Germany). This is not only a tenant concern, a single tenant may also need to separate its own data by region. - Like tiered multitenancy, this uses custom sharding; the difference is what you shard by. Here the shard key is a region. Each key's data lands on specific shards you can place in specific locations, while everything stays in one collection. Combine it with payload partitioning if you also need per-tenant isolation within a region. Check [User-defined sharding](https://skills.qdrant.tech/md/documentation/scaling/distributed_deployment/?s=user-defined-sharding) for setup. - Geographic residency follows only if your cluster's nodes are actually in the target regions. - Qdrant Cloud deploys a cluster in a single region and has no managed multi-region today. ## What NOT to Do - Treat a payload filter as your whole security model. In Qdrant, (unless you're using per-tenant collections), tenant isolation is payload-based. It is an application-layer responsibility, and the filter is only one small part of it.