qdrant-multitenancy

Qdrant Multitenancy

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 .
• 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.
• 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.

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.
• 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.
• 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 you have a limited number of tenants that need strict isolation, or when tenants' 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 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.