Back to blog
Architecture

Qdrant multitenancy: is_tenant payload partitioning vs a collection per tenant

Qdrant multitenancy works best as one collection with an is_tenant keyword index, per-tenant HNSW via payload_m, and shard keys for the few large tenants. Tested on Qdrant 1.20.0, including what JWT can and cannot scope.

Abhilash B10 min read
#qdrant#multi-tenancy#vector search#rag#architecture

For Qdrant multitenancy, put every tenant in one collection, give each point a tenant_id payload field, and index that field as a keyword with "is_tenant": true. Add "payload_m": 16, "m": 0 to the HNSW config so Qdrant builds a graph per tenant and skips the global one, and filter every query on tenant_id. When a few tenants grow large, move them to dedicated shards with tiered multitenancy (1.16+) instead of splitting them out into their own collections.

That is the opposite of what we recommend for turbopuffer, where our turbopuffer namespace design post argues for one namespace per tenant. Both recommendations follow from how each engine stores data, and the second section explains why. Everything below ran on qdrant/qdrant:v1.20.0 in Docker on 31 October 2026, the current release at the time, using plain HTTP calls against 4-dimensional toy vectors. The vectors only show behaviour, so the scores are not a benchmark. Every config was checked against the Qdrant multitenancy docs.

Qdrant multitenancy options in 1.20

The docs list three layouts inside one collection and treat a collection per tenant as the exception. In their words, a collection per tenant "is rarely the most efficient approach", because "each collection carries its own resource overhead". Qdrant Cloud caps a cluster at 1,000 collections, and the cluster configuration page adds that "larger numbers of collections lead to performance degradation".

LayoutSinceIsolation boundaryFitsMain limit
Collection per tenantanyCollectionA handful of tenants that need strict isolationPer-collection overhead; 1,000 per Cloud cluster
Payload partitioning (is_tenant)1.11.0A filter in every queryMany small, similar tenantsA missing filter returns every tenant's data
User-defined sharding (shard_key)1.7.0ShardA modest number of large tenantsEach shard has its own storage and indexes
Tiered multitenancy (fallback shard)1.16.0Shard for big tenants, filter for the restSkewed tenant sizesFallback shard must fit on one node; under 1,000 dedicated shards per cluster

Why Qdrant and turbopuffer disagree on tenancy

In turbopuffer, a namespace is a prefix in an object storage bucket. An idle namespace costs only its storage, the docs list namespaces as unlimited, and a query is billed on the size of the namespace it searches. Splitting tenants into namespaces costs nothing and makes every query cheaper, so per-tenant namespaces win.

In Qdrant, a collection is a set of live structures on a node: segments, a write-ahead log, HNSW graphs, payload indexes and optimizer work. The GET /collections/docs response from our run shows some of that per-collection state, including a 32 MB wal_capacity_mb and its own indexing_threshold. Qdrant does not publish a per-collection memory figure, so we can't give you an exact multiplier. What the docs do say is that the overhead adds up, and that Cloud stops you at 1,000. Querying a filtered subset is cheap, since filtering is built into the HNSW search itself, and is_tenant lays each tenant's points out together so a filtered query reads them in one sequential pass.

So the costs point in opposite directions. turbopuffer charges per namespace searched, which makes small namespaces cheap. Qdrant pays per collection that exists, which makes many collections expensive and a filter on one collection cheap.

flowchart LR
  subgraph A["Collection per tenant"]
    direction TB
    A1["docs_acme<br/>WAL, segments, HNSW"]
    A2["docs_globex<br/>WAL, segments, HNSW"]
    A3["docs_tenant_n<br/>WAL, segments, HNSW"]
  end
  subgraph B["One collection, is_tenant"]
    direction TB
    B0["docs: one WAL, shared segments"]
    B0 --> B1["acme points stored together<br/>payload_m graph"]
    B0 --> B2["globex points stored together<br/>payload_m graph"]
    B0 --> B3["tenant_n points stored together<br/>payload_m graph"]
  end
  Q(["Query + tenant_id filter"]) --> B0
  Q2(["Query to docs_TENANT"]) --> A1

Payload partitioning with is_tenant

Create the collection with the global graph disabled and per-tenant graphs enabled. The docs give the exact order of operations: set payload_m first, because "if you leave payload_m unset, Qdrant uses the value of m", and m: 0 would then disable the payload-aware links too.

PUT /collections/docs
{"vectors":{"size":4,"distance":"Cosine"},"hnsw_config":{"payload_m":16,"m":0}}

{"result":true,"status":"ok","time":0.037444292}
PUT /collections/docs/index
{"field_name":"tenant_id","field_schema":{"type":"keyword","is_tenant":true}}

{"result":{"operation_id":2,"status":"acknowledged"},"status":"ok","time":0.001988917}

We created the tenant index before loading any points. The indexing docs describe the tenant index as a storage layout hint, and the multitenancy page says the payload-aware links are built for indexed payload fields, so the index is what gives each tenant its graph. We then upserted four points, two for acme and two for globex, each with a tenant_id and a title. The collection info confirms the config took:

{
  "hnsw_config": {"m": 0, "ef_construct": 100, "full_scan_threshold": 10000,
                  "max_indexing_threads": 0, "on_disk": false, "payload_m": 16},
  "payload_schema": {"tenant_id": {"data_type": "keyword",
                     "params": {"type": "keyword", "is_tenant": true}, "points": 4}}
}

Two documented caveats come with this config. "Setting m to 0 isn't the same as exact search": Qdrant still builds approximate graphs per tenant. And global queries without the tenant filter get slower, because there is no global graph to walk.

A filtered tenant query

POST /collections/docs/points/query
{"query":[0.9,0.1,0.1,0.1],
 "filter":{"must":[{"key":"tenant_id","match":{"value":"acme"}}]},
 "limit":3,"with_payload":["tenant_id","title"]}

{"result":{"points":[
  {"id":1,"version":3,"score":1.0,"payload":{"tenant_id":"acme","title":"Acme refund policy"}},
  {"id":2,"version":3,"score":0.99111706,"payload":{"tenant_id":"acme","title":"Acme SSO setup"}}]},
 "status":"ok","time":0.001383583}

Only Acme's points come back, and fewer than limit when the tenant has fewer matches.

The same query without the filter

POST /collections/docs/points/query
{"query":[0.9,0.1,0.1,0.1],"limit":3,"with_payload":["tenant_id","title"]}

{"result":{"points":[
  {"id":1,"version":3,"score":1.0,"payload":{"tenant_id":"acme","title":"Acme refund policy"}},
  {"id":3,"version":3,"score":0.999766,"payload":{"tenant_id":"globex","title":"Globex refund policy"}},
  {"id":2,"version":3,"score":0.99111706,"payload":{"tenant_id":"acme","title":"Acme SSO setup"}}]},
 "status":"ok","time":0.0012055}

HTTP 200, no warning, and Globex's refund policy lands in second place for an Acme user. With m: 0, Qdrant still accepts an unfiltered query and searches every tenant. In a RAG product, that document goes straight into the model's context and possibly into a cited answer. The filter is the only thing between two customers, and Qdrant gives you no collection setting that makes it mandatory.

Keyword matching is also exact. The same query filtered on "Acme" returned {"points":[]}. That fails closed, which is the safe direction, but it means tenant IDs need one canonical form, ideally an opaque UUID that never passes through user input.

BM25 and IDF statistics per tenant

If you run hybrid search with BM25 on a full-text index, or sparse vectors with the IDF modifier, payload partitioning does not separate the scoring statistics. By default every tenant shares shard-wide document counts and term frequencies, so one tenant's vocabulary shifts another tenant's BM25 scores. Since 1.19.0 the idf search parameter takes a corpus filter:

"params": {"idf": {"corpus": {"must": [{"key": "tenant_id", "match": {"value": "acme"}}]}}}

The docs add that if the corpus filter matches nothing, ranking drops to plain term frequency with no rarity signal, and Qdrant does not fall back to shard-wide statistics. Our Qdrant hybrid search post covers the prefetch and fusion side of that query.

Tiered multitenancy for large tenants

Shard keys need distributed mode. On a plain single-node container, PUT /collections/tiered/shards returned {"status":{"error":"Qdrant is running in standalone mode"}} with HTTP 405. We restarted with QDRANT__CLUSTER__ENABLED=true and ./qdrant --uri http://qq-b12-tiered:6335, a one-node cluster. The container also needs --hostname set to that name. Without it, the shard transfer failed with Failed to connect to http://qq-b12-tiered:6335/ and the new shard went to state Dead.

The setup follows the docs: a collection with "shard_number": 1, "sharding_method": "custom", a fallback shard {"shard_key":"default","shards_number":1}, and the same is_tenant index. Writes and queries send a shard key selector with both a target and a fallback:

POST /collections/tiered/points/query
{"query":[0.9,0.1,0.1,0.1],
 "filter":{"must":[{"key":"tenant_id","match":{"value":"acme"}}]},
 "shard_key":{"fallback":"default","target":"acme"},"limit":3}

{"result":{"points":[{"id":1,"version":3,"score":1.0,"shard_key":"default"},
                     {"id":2,"version":3,"score":0.99111706,"shard_key":"default"}]},"status":"ok"}

The acme shard did not exist yet, so the request routed to default. Promotion is two calls: create the tenant's shard in Partial state, then copy its points.

PUT /collections/tiered/shards
{"shard_key":"acme","shards_number":1,"replication_factor":1,"initial_state":"Partial"}

POST /collections/tiered/cluster
{"replicate_points":{"filter":{"must":{"key":"tenant_id","match":{"value":"acme"}}},
 "from_shard_key":"default","to_shard_key":"acme"}}

Within a few seconds GET /collections/tiered/cluster reported {"shard_key":"acme","points_count":2,"state":"Active"}, and the identical query came back with "shard_key":"acme" on both points. The application code did not change. The copy leaves the originals in place, so we deleted them with a filter and "shard_key":"default", which took the fallback from 3 points to 1.

sequenceDiagram
  participant App as Your backend
  participant Q as Qdrant
  App->>Q: query, shard_key target acme, fallback default
  Q-->>App: points from shard default
  App->>Q: PUT shards: acme, initial_state Partial
  App->>Q: POST cluster: replicate_points, filter tenant_id acme
  Note over Q: stream_records transfer<br/>acme shard becomes Active
  App->>Q: same query, unchanged
  Q-->>App: points from shard acme
  App->>Q: delete tenant_id acme on shard default

The constraints are worth knowing before you design around this. The fallback and dedicated shards must have shards_number 1, so every small tenant together must fit on a single node. The docs suggest promoting at about 20,000 points and creating no more than 1,000 dedicated shards per cluster. A query that omits shard_key searches all shards: in our run it returned points from acme and default together. So the tenant filter is still required on every request in this layout too.

Enforcing the tenant filter: what JWT can do

Qdrant's security docs describe granular access keys (1.9.0+), which are HS256 JWTs signed with the admin api_key. You enable them on open source with QDRANT__SERVICE__API_KEY plus QDRANT__SERVICE__JWT_RBAC=true. The access claim scopes a token to collections with r or rw. We signed tokens with Python's hmac module and tested them on 1.20.0:

Token claimsRequestResult
access: [{collection: docs, access: r}]query docs with no filterHTTP 200, points from both tenants
sameupsert into docsHTTP 403 Write access to collection docs is required
samecreate collection otherHTTP 403 Global access is required
access: [{collection: docs_acme, access: rw}]query docsHTTP 403 Access to collection docs is required
sameGET /collectionsHTTP 200, lists only docs_acme
access: [{collection: docs, access: r, payload: {tenant_id: acme}}]query docsHTTP 401 access[0].payload: The 'payload' constraint is deprecated and should not be used

The last row is the important one. Older guides show a payload constraint inside the access claim that pinned a token to a payload value. Qdrant 1.20.0 rejects that token outright, and the current docs no longer list the constraint. JWTs in 1.20 scope collections and read or write access. They cannot scope a tenant inside a shared collection.

That leaves the tenant filter in your backend, which is the same position as row-level permissions in any search engine (our Elasticsearch security post covers the equivalent there). Keep one function that builds the filter from the authenticated session and ANDs it onto anything else, and make it the only code that holds the Qdrant client:

from qdrant_client import QdrantClient, models

client = QdrantClient(url="https://qdrant.internal:6333", api_key=QDRANT_KEY)

def tenant_query(tenant_id: str, vector: list[float], extra: models.Filter | None = None,
                 limit: int = 10):
    """tenant_id comes from the verified session, never from the request body."""
    scope = models.FieldCondition(key="tenant_id", match=models.MatchValue(value=tenant_id))
    flt = models.Filter(must=[scope] + ([extra] if extra else []))
    return client.query_points("docs", query=vector, query_filter=flt, limit=limit).points

A collection-scoped JWT still earns its place. Give the search service an r token for docs only, with a sub claim naming the service, so a leaked token cannot write or touch other collections. With audit logging on (1.17+), each entry records method, collection, auth_type and the JWT subject, which lets you alert on reads of docs from any subject except your search service. Add a unit test that fails if any module other than the one holding tenant_query imports the Qdrant client.

Choosing a layout

flowchart TD
  S(["New multi-tenant corpus"]) --> A{"Contract or regulator requires<br/>physically separate data?"}
  A -- yes --> C["Collection per tenant<br/>keep the count well under 1,000"]
  A -- no --> B{"Do a few tenants hold<br/>most of the points?"}
  B -- no --> P["One collection<br/>is_tenant index, payload_m 16, m 0"]
  B -- yes --> T["Tiered multitenancy<br/>fallback shard + promoted tenants"]
  P --> F["Tenant filter added server side<br/>on every query"]
  T --> F
SituationLayout
B2B SaaS with many small tenantsOne collection, is_tenant, payload_m: 16, m: 0
A few tenants past roughly 20,000 points, the rest smallTiered multitenancy, promote with replicate_points
Tenants on different embedding models or dimensionsGroup tenants per model into one collection each
A handful of tenants with contractual isolationCollection per tenant plus a collection-scoped JWT
Analytics or admin search across all tenantsKeep the global graph (m above 0), or use a separate copy
Hybrid BM25 per tenantAdd params.idf.corpus with the tenant filter (1.19+)

Our recommendation: start with one collection and the is_tenant index, disable the global graph unless you really need cross-tenant search, and route every read and delete through one function that adds the tenant filter. Add a fallback shard from day one if you expect skew. We sent PATCH /collections/c with "sharding_method": "custom" on 1.20.0 and got HTTP 200, but the collection stayed on automatic sharding, so plan for it at creation. The vector sizing calculator helps you check whether all small tenants fit on one fallback shard, and the Elasticsearch vs Qdrant comparison covers how the two engines model this more broadly. Retrieval leaks between tenants are one of the failure modes in how RAG fails in production, and the unfiltered query above is how they happen.

Where we can help

We design Qdrant collection layouts, shard plans and tenant isolation around your tenant size distribution, then test them on your data before launch. See our Qdrant consulting service.

Advisor, Query Quotient

Abhilash B is an advisor at Query Quotient and an information retrieval and AI expert who holds patents in the field. Abhilash brings that retrieval depth to the search, RAG and agent systems Query Quotient builds for clients.

Keep reading

Building something similar?

Tell us what you are working on. In a free 30-minute call we will give you an honest view of the approach, the effort and how to measure success.