Shard Key Design for Multi-Tenancy

Parent: MongoDB Multi-Tenancy · Published reference · snapshot 2026-10-23 · skill mongodb-cohort-18121faaf93a

Source-anchored research for Shard Key Design for Multi-Tenancy. Run status: COMPLETED.

These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.

Structure and components

Evaluate candidate keys against distinct-value cardinality, value frequency and tenant skew, insert monotonicity, and common query shapes. High cardinality alone does not guarantee balanced load. Queries that omit the shard key or the prefix of a compound shard key require scatter-gather across the shards that may contain matching data. (high confidence) [source]

How it works

Choose the key and query shapes together. Queries that include relevant shard-key fields can target shard ranges, while queries without the shard key are broadcast across shards. A tenant-first key or prefix is useful when tenant filtering is common; adding a suffix can let a large tenant's data occupy ranges on multiple shards. (medium confidence) [source]
For a shared-collection multi-tenant design, store tenantId on every document and include it in every query. When tenant-scoped reads and writes dominate, including tenantId in the shard key aligns routing with the application’s tenant boundary; the boundary remains logical and must be enforced in application code. (medium confidence) [source]
When tenant sizes vary widely, a compound key with tenantId as a prefix and a varied suffix, such as {tenantId: 1, userId: 1} or {tenant_id: 1, _id: "hashed"}, adds split points within a tenant. Queries using the tenantId prefix can target the shard or shards holding that tenant’s ranges; a large tenant can span multiple shards, so tenant-only queries may reach more than one shard. (medium confidence) [source]

Problems, failure modes and limitations

With a range shard key consisting only of tenantId, all documents for a tenant share one shard-key value. MongoDB can place each unique shard-key value in only one chunk, so a very large or active tenant cannot be split by tenantId alone and can concentrate storage or workload on one shard. This favors per-tenant locality when tenant sizes and activity are reasonably balanced, but risks a hotspot or indivisible chunk when they are skewed. (high confidence) [source]
Hashing tenantId can distribute different tenant values across shards and reduce hotspots from sequentially assigned tenant IDs, but range queries on the hashed field are less efficient. Hashing tenantId alone still gives each tenant one shard-key value, so it cannot split an unusually large tenant by itself. To preserve tenant-based targeting while allowing a large tenant to span ranges, one option is a compound key with tenantId as a prefix and a suffix that varies within the tenant (which may be hashed). A different high-cardinality shard key, such as hashed _id, can also distribute data, but tenant-only queries that omit that key are broadcast across shards. (high confidence) [source]

Facts and statements

Evaluate a shard-key candidate by cardinality, frequency of each value, monotonicity, and the common query patterns. High cardinality alone does not guarantee even distribution. (high confidence) [source]
A compound key such as {tenantId: 1, _id: 1} adds split points within each tenant's key range. This can make a high-frequency tenant value splittable across chunks while retaining tenantId as the key prefix. Yorkie's MongoDB design documents the same pattern with project_id and a hashed _id suffix after limited project_id values concentrated data on a few chunks. (high confidence) [source]
For insert-heavy workloads with monotonic suffix values, a compound hashed key such as {tenantId: 1, _id: "hashed"} can distribute inserts more evenly within the tenant-prefixed key space. Hashed shard keys trade range locality on the hashed field for more even distribution; MongoDB supports one hashed field in a compound hashed key. (high confidence) (verified as of 2026-10-19) [source]
In shared collections, tenantId is logical segmentation: queries must filter by tenantId and the application tier must enforce tenant access controls. MongoDB's Vector Search guidance also uses tenant_id as a prefilter for tenant-scoped searches. (high confidence) [source]
Zones can associate shard-key value ranges with selected shards, supporting placement policies such as grouping tenant-ID ranges. Zones control where ranges reside; they do not create split points for repeated tenantId values in a tenant-only key. (high confidence) [source]
A non-MongoDB outlier-handling example is Datadog Husky: it assigns a variable shard count per tenant from observed traffic and changes future placements as load changes. This illustrates an application-managed placement strategy, not behavior provided by MongoDB's native shard key. (low confidence) [source]
MongoDB zones can constrain shard-key ranges to designated shards for deliberate placement. For tenant placement, the range boundaries must use fields in the shard key; if the key field is hashed, zone ranges refer to hashed values and do not map predictably to the original tenantId values. Zones control placement, while shared-collection tenant access remains an application-level security responsibility. (medium confidence) [source]
Before committing to a shard key, MongoDB’s analyzeShardKey can use sampled queries to report key cardinality, frequency, monotonicity, query targeting, and read/write distribution. MongoDB documents this capability as available starting in version 7.0. (medium confidence) (verified as of 2026-10-19) [source]

Children

Zone sharding for tenant placement (frontier)
Resharding and shard-key refinement (frontier)

Frontier under this node: Resharding and shard-key refinement, Zone sharding for tenant placement

← the whole tree · 3D view· how to read this page