Skip to main content
skill CX Codex

qdrant-multitenancy — Claude Code skill: tenant isolation

qdrant-multitenancy — a skill for Claude Code, Codex, and Cursor. Guides tenant isolation architecture across users in Qdrant vector databases.

Apache-2.0 298 installs ★ 271 updated 2026-11-11

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add qdrant/skills --skill qdrant-multitenancy -a claude-code
Open on GitHub

What qdrant-multitenancy does

Runs across Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. It guides your assistant on selecting between payload-based partitioning, tiered custom sharding, and separate collections based on tenant count and size distribution.

The guidance covers indexing payload fields with is_tenant=true, isolating HNSW graphs using payload_m, tuning text relevance with per-tenant idf scoring on Qdrant 1.19+, and moving tenants past roughly 20,000 points to dedicated shards.

An auto-sharded collection cannot switch to custom sharding in place, making upfront collection design mandatory if large tenants might need dedicated shards later.

What it helps with

  • choose a tenant isolation model for Qdrant deployments
  • solve noisy-neighbor bottlenecks caused by oversized tenants
  • isolate BM25 and IDF scoring statistics per customer
  • pin customer vectors to specific geographic regions

Example prompts for the agent

  • How should I partition customer data in Qdrant for 1,000 small tenants?
  • One tenant grew past 25,000 vectors and slows down queries, how do I move it to a dedicated shard?
  • Show how to pin German customer records to specific nodes using custom sharding.

How to install qdrant-multitenancy

1Skills CLI (Vercel)

npx skills add qdrant/skills --skill qdrant-multitenancy -a claude-code

2Manually: put the files in place

~/.claude/skills/qdrant-multitenancy/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/qdrant-multitenancy/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about qdrant-multitenancy

How to install qdrant-multitenancy in Claude Code?

Run npx skills add qdrant/skills --skill qdrant-multitenancy -a claude-code in your terminal.

What does qdrant-multitenancy do?

It equips the coding agent with architectural patterns for multitenancy in Qdrant, covering payload filtering, tiered sharding, and residency constraints.

Can I convert an auto-sharded collection to custom sharding later?

No, sharding choices are immutable after collection creation, so custom sharding with a fallback shard must be configured on day one.

Source text

SKILL.md · Apache-2.0
---
name: qdrant-multitenancy
description: "Guides tenant isolation architecture in Qdrant for multi-tenant or multi-user applications. Use when someone asks 'how to isolate customer data', 'how to build multi-tenant search/RAG', 'how many collections should I create', 'how to partition tenants by payload', 'a customer's data legally has to stay in a certain country or region'. Also use when they describe a symptom: one customer's data is way bigger than the rest and slowing everyone down, or one tenant is hogging resources."
---

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

### How It Works

- Create a keyword payload index on the tenant field with `is_tenant=true` (v1.11+), so each tenant's points are stored together and read sequentially [Partition by payload](https://skills.qdrant.tech/md/documentation/manage-data/multitenancy/?s=partition-by-payload).
- Filter every query with a `must` condition on the tenant field. Without it, a query searches every tenant's data.
- Text relevance (BM25 or sparse vectors with the IDF modifier) is scored with statistics computed over the whole shard, so tenants with different vocabularies distort each other's scores. On Qdrant 1.19 or newer, pass the `idf` search parameter with the tenant filter and index the tenant field; on 1.20 or newer this covers BM25 `text` queries on a full-text index too [Per-tenant scoring statistics](https://skills.qdrant.tech/md/documentation/manage-data/multitenancy/?s=per-tenant-scoring-statistics).
- Every tenant indexes into the same collection, so indexing can become a bottleneck at scale. Build per-tenant HNSW graphs instead of a global one: set `payload_m` to a non-zero value explicitly (it defaults to `m`), then set `m=0`. Queries without a tenant filter get slower, 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.

Small tenants share a fallback shard and large tenants get dedicated shards, all in one collection. A tenant that outgrows the fallback shard can be promoted to a dedicated shard later with no downtime.

### How It Works

- Create the collection with custom sharding and `shard_number: 1`, add a fallback shard for the small tenants, and keep the `is_tenant` payload index from payload partitioning [Configure tiered multitenancy](https://skills.qdrant.tech/md/documentation/manage-data/multitenancy/?s=configure-tiered-multitenancy).
- Promote a tenant to a dedicated shard once it approaches the indexing threshold, about 20,000 points. Qdrant moves its data with a shard transfer and keeps serving reads and writes [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 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](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.

© qdrant · Apache-2.0 · qdrant/skills

Similar skills

All skills for Data and databases →

From the same set12

The whole set →
qdrant-version-upgrade The qdrant-version-upgrade Claude Code skill guides Qdrant server and SDK upgrades with version compatibility in mind. It covers upgrade sequencing, multi-version jumps, and behavior changes after a release. CX Codex +1 1,400installs qdrant-performance-optimization qdrant-performance-optimization — a routing skill for Qdrant tuning: it matches your symptom to the right sub-skill for search speed, indexing or memory. CX Codex +1 1,700installs qdrant-advisor qdrant-advisor fetches official troubleshooting guidance live from skills.qdrant.tech to diagnose vector search latency, memory spikes, and sharding issues. CX Codex +1 782installs qdrant-edge This Claude Code skill guides development with Qdrant Edge. It covers local shard sync, BM25 search, and index maintenance. CX Codex +1 328installs qdrant-sizing qdrant-sizing calculates RAM, disk space, CPU cores, and node count for a Qdrant deployment before hardware or cloud instances are provisioned. CX Codex +1 222installs qdrant-migration-tool The qdrant-migration-tool skill facilitates migrating vector data and metadata from various databases into Qdrant. It orchestrates the migration process, handles data streaming, and manages resume capabilities. CX Codex +1 137installs qdrant-hybrid-cloud-setup The qdrant-hybrid-cloud-setup Claude Code skill guides Qdrant Hybrid Cloud deployment on a self-managed Kubernetes cluster. It activates for agent and operator setup, storage and backups, or cluster access configuration. CX Codex +1 121installs qdrant-skills This plugin gives the agent Qdrant guidance for scaling, search quality, SDK work, deployments, monitoring, and model changes. ★ 271repo stars

Project sponsors

Companies that keep this analytics open