You can implement multi-tenancy with MongoDB Search so that a single instance of an application serves multiple tenants. This page describes design recommendations that apply specifically to MongoDB Search for structuring data and MongoDB Search indexes to scale safely while maintaining tenant isolation.
Important
This guidance assumes that you can colocate tenants within a single VPC. If strict network isolation is required, you must maintain separate projects for each tenant.
Choosing a Strategy
Select a strategy based on your isolation needs, scaling goals, and write-load requirements. The most common strategies are:
A single collection for all tenants - This strategy is recommended for most workloads.
One Database per tenant - This strategy offers high isolation but increases index count.
One Collection per tenant - This strategy is not recommended for MongoDB Search workloads.
A Single Collection for All Tenants (Recommended)
We recommend applying the one collection for all tenants strategy. In this architecture, you store all tenant data in a single collection within a single database. You can distinguish between tenants by including a tenant_id field within each document. This field can be any unique identifier for the tenant, such as a UUID or a tenant name.
This centralized approach offers the following benefits:
Reduces the number of indexes
Since all tenant data is stored in one collection, you need only a single index that serves documents for all tenants. You avoid hitting the cluster resource limits. For example, you can include the
tenant_idand other shared or tenant-specific fields in a single index.Simplifies maintenance operations
With only a single collection storing all data, you don't have to maintain multiple collections or scale resources across multiple databases. You also simplify backup, sharding, and replication operations as you need to target only a single collection in a single database.
Processes query efficiently
You provide the
tenant_idfield in your queries as a filter using the equals operator within the$search.compound.filterclause.Note
Your query results will only include documents from the matching tenant, preventing data from leaking across tenants.
If the tenants you colocate share similar access patterns and resource sizes, this strategy also keeps the Lucene index field count low.
Important
When every tenant has a high write load, colocating all tenants into a single collection might create write contention. In that scenario, consider splitting tenants with the most writes into separate collections so that you can distribute the write load across more underlying resources.
If you have large tenants with unique resourcing or indexing requirements, use a View:
Index separately. Create a MongoDB Search index on the View.
This allows you to customize the index definition for the large tenant without impacting the shared index used by others. All other tenants can use a single index.
A high index count generates significant load on the base cluster and might disrupt your workload. The number of indexes your cluster can support depends on your cluster tier and workload. Smaller cluster tiers like
M10can experience performance degradation or out-of-memory errors as index count increases. Start with a small number of indexes and monitor your cluster's resource usage as you scale.
If you currently apply the one collection per tenant strategy, we recommend scaling up the base tier to prevent increased replication lag or OOM errors due to resource contention from a high number of indexes. We also recommend migrating to the one collection for all tenants strategy.
Handling High-Write Tenants
If specific tenants have massive write loads, they might cause contention in a shared collection. We recommend that you move only the highest-volume tenants to separate collections to distribute the I/O load.
Handling Unique Requirements (Views)
If a tenant requires unique indexing or is significantly larger than others, use a MongoDB View:
One Database Per Tenant
In a database-per-tenant setup, each tenant contains its own database. This setup isolates tenant data, but it also multiplies the number of indexes in the cluster. As the number of tenant databases grows, the index count can exceed what your cluster tier and workload can support.
Warning
A high index count generates significant load on the base cluster and might disrupt your workload. The number of indexes your cluster can support depends on your cluster tier and workload. Smaller cluster tiers like M10 can experience performance degradation or out-of-memory errors as index count increases. Start with a small number of indexes and monitor your cluster's resource usage as you scale.
One Collection Per Tenant (Not Recommended)
The collection-per-tenant strategy maps each tenant to its own collection within a shared database. The overhead of maintaining an index per collection might cause:
Increased replication lag
OOM errors due to resource contention
Instability in the base tier
We do not recommend this strategy for MongoDB Search unless tenants have very predictable, lightweight workloads. If you currently use this strategy, migrate toward the one collection for all tenants strategy.
Managing Indexed Fields
Consider the following recommendations to manage indexed fields: