- Reference >
- MongoDB Limits and Thresholds
MongoDB Limits and Thresholds¶
On this page
This document provides a collection of hard and soft limitations of the MongoDB system.
BSON Documents¶
- BSON Document Size¶
The maximum BSON document size is 16 megabytes.
The maximum document size helps ensure that a single document cannot use excessive amount of RAM or, during transmission, excessive amount of bandwidth. To store documents larger than the maximum size, MongoDB provides the GridFS API. See mongofiles and the documentation for your driver for more information about GridFS.
- Nested Depth for BSON Documents¶
Changed in version 2.2.
MongoDB supports no more than 100 levels of nesting for BSON documents.
Namespaces¶
- Namespace Length¶
The maximum length of the collection namespace, which includes the database name, the dot (.) separator, and the collection name (i.e. <database>.<collection>), is 120 bytes.
- Number of Namespaces¶
Changed in version 3.0.
For the MMAPv1 the number of namespaces is limited to the size of the namespace file divided by 628.
A 16 megabyte namespace file can support approximately 24,000 namespaces. Each collection and index is a namespace.
The WiredTiger storage engine is not subject to this limitation.
Indexes¶
- Index Key Limit¶
The total size of an index entry, which can include structural overhead depending on the BSON type, must be less than 1024 bytes.
Changed in version 2.6: MongoDB versions 2.6 and greater implement a stronger enforcement of the limit on index key:
MongoDB will not create an index on a collection if the index entry for an existing document exceeds the index key limit. Previous versions of MongoDB would create the index but not index such documents.
Reindexing operations will error if the index entry for an indexed field exceeds the index key limit. Reindexing operations occur as part of compact and repairDatabase commands as well as the db.collection.reIndex() method.
Because these operations drop all the indexes from a collection and then recreate them sequentially, the error from the index key limit prevents these operations from rebuilding any remaining indexes for the collection and, in the case of the repairDatabase command, from continuing with the remainder of the process.
MongoDB will not insert into an indexed collection any document with an indexed field whose corresponding index entry would exceed the index key limit, and instead, will return an error. Previous versions of MongoDB would insert but not index such documents.
Updates to the indexed field will error if the updated value causes the index entry to exceed the index key limit.
If an existing document contains an indexed field whose index entry exceeds the limit, any update that results in the relocation of that document on disk will error.
mongorestore and mongoimport will not insert documents that contain an indexed field whose corresponding index entry would exceed the index key limit.
In MongoDB 2.6, secondary members of replica sets will continue to replicate documents with an indexed field whose corresponding index entry exceeds the index key limit on initial sync but will print warnings in the logs.
Secondary members also allow index build and rebuild operations on a collection that contains an indexed field whose corresponding index entry exceeds the index key limit but with warnings in the logs.
With mixed version replica sets where the secondaries are version 2.6 and the primary is version 2.4, secondaries will replicate documents inserted or updated on the 2.4 primary, but will print error messages in the log if the documents contain an indexed field whose corresponding index entry exceeds the index key limit.
For existing sharded collections, chunk migration will fail if the chunk has a document that contains an indexed field whose index entry exceeds the index key limit.
- Number of Indexes per Collection¶
A single collection can have no more than 64 indexes.
- Index Name Length¶
Fully qualified index names, which includes the namespace and the dot separators (i.e. <database name>.<collection name>.$<index name>), cannot be longer than 128 characters.
By default, <index name> is the concatenation of the field names and index type. You can explicitly specify the <index name> to the createIndex() method to ensure that the fully qualified index name does not exceed the limit.
- Number of Indexed Fields in a Compound Index¶
There can be no more than 31 fields in a compound index.
- Queries cannot use both text and Geospatial Indexes¶
You cannot combine the $text query, which requires a special text index, with a query operator that requires a different type of special index. For example you cannot combine $text query with the $near operator.
- Fields with 2dsphere Indexes can only hold Geometries¶
Fields with 2dsphere indexes must hold geometry data in the form of coordinate pairs or GeoJSON data. If you attempt to insert a document with non-geometry data in a 2dsphere indexed field, or build a 2dsphere index on a collection where the indexed field has non-geometry data, the operation will fail.
See also
The unique indexes limit in Sharding Operational Restrictions.
- NaN values returned from Covered Queries by the WiredTiger Storage Engine are always of type double¶
If the value of a field returned from a query that is covered by an index is NaN, the type of that NaN value is always double.
- Multikey Index¶
A multikey index cannot support a covered query.
Data¶
- Maximum Number of Documents in a Capped Collection¶
Changed in version 2.4.
If you specify a maximum number of documents for a capped collection using the max parameter to create, the limit must be less than 232 documents. If you do not specify a maximum number of documents when creating a capped collection, there is no limit on the number of documents.
- Database Size¶
The MMAPv1 storage engine limits each database to no more than 16000 data files. This means that a single MMAPv1 database has a maximum size of 32TB. Setting the storage.mmapv1.smallFiles option reduces this limit to 8TB.
- Data Size¶
Changed in version 3.0.
Using the MMAPv1 storage engine, a single mongod instance cannot manage a data set that exceeds maximum virtual memory address space provided by the underlying operating system.
Virtual Memory Limitations Operating System Journaled Not Journaled Linux 64 terabytes 128 terabytes Windows Server 2012 R2 and Windows 8.1 64 terabytes 128 terabytes Windows (otherwise) 4 terabytes 8 terabytes The WiredTiger storage engine is not subject to this limitation.
- Number of Collections in a Database¶
Changed in version 3.0.
For the MMAPv1 storage engine, the maximum number of collections in a database is a function of the size of the namespace file and the number of indexes of collections in the database.
The WiredTiger storage engine is not subject to this limitation.
See Number of Namespaces for more information.
Replica Sets¶
- Number of Members of a Replica Set¶
Changed in version 3.0.0.
Replica sets can have up to 50 members. See Increased Number of Replica Set Members for more information about specific driver compatibility with large replica sets.
- Number of Voting Members of a Replica Set¶
Replica sets can have up to 7 voting members. For replica sets with more than 7 total members, see Non-Voting Members.
- Maximum Size of Auto-Created Oplog¶
Changed in version 2.6.
If you do not explicitly specify an oplog size (i.e. with oplogSizeMB or --oplogSize) MongoDB will create an oplog that is no larger than 50 gigabytes.
Sharded Clusters¶
Sharded clusters have the restrictions and thresholds described here.
Sharding Operational Restrictions¶
The group does not work with sharding. Use mapReduce or aggregate instead.
db.eval() is incompatible with sharded collections. You may use db.eval() with un-sharded collections in a shard cluster.
$where does not permit references to the db object from the $where function. This is uncommon in un-sharded collections.
The $isolated update modifier does not work in sharded environments.
$snapshot queries do not work in sharded environments.
The geoSearch command is not supported in sharded environments.
- Covered Queries in Sharded Clusters¶
An index cannot cover a query on a sharded collection when run against a mongos if the index does not contain the shard key, with the following exception for the _id index: If a query on a sharded collection only specifies a condition on the _id field and returns only the _id field, the _id index can cover the query when run against a mongos even if the _id field is not the shard key.
- Sharding Existing Collection Data Size¶
For existing collections that hold documents, MongoDB supports enabling sharding on any collections that contains less than 256 gigabytes of data. MongoDB may be able to shard collections with as many as 400 gigabytes depending on the distribution of document sizes. The precise size of the limitation is a function of the chunk size and the data size. Consider the following table:
Shard Key Size 512 bytes 200 bytes Number of Splits 31,558 85,196 Max Collection Size (1 MB Chunk Size) 31 GB 83 GB Max Collection Size (64 MB Chunk Size) 1.9 TB 5.3 TB Max Collection Size (256 MB Chunk Size) 7.6 TB 21.2 TB Max Collection Size (512 MB Chunk Size) 15.2 TB 42.4 TB The data in this chart reflects documents with no data other than the shard key values and therefore represents the smallest possible data size that could reach this limit.
Important
Sharded collections may have any size, after successfully enabling sharding.
- Single Document Modification Operations in Sharded Collections¶
All update() and remove() operations for a sharded collection that specify the justOne or multi: false option must include the shard key or the _id field in the query specification. update() and remove() operations specifying justOne or multi: false in a sharded collection without the shard key or the _id field return an error.
- Unique Indexes in Sharded Collections¶
MongoDB does not support unique indexes across shards, except when the unique index contains the full shard key as a prefix of the index. In these situations MongoDB will enforce uniqueness across the full key, not a single field.
See
Enforce Unique Keys for Sharded Collections for an alternate approach.
- Maximum Number of Documents Per Chunk to Migrate¶
MongoDB cannot move a chunk if the number of documents in the chunk exceeds either 250000 documents or 1.3 times the number of average sized documents that the maximum chunk size can hold.
Shard Key Limitations¶
- Shard Key Size¶
A shard key cannot exceed 512 bytes.
- Shard Key Index Type¶
A shard key index can be an ascending index on the shard key, a compound index that start with the shard key and specify ascending order for the shard key, or a hashed index.
A shard key index cannot be an index that specifies a multikey index, a text index or a geospatial index on the shard key fields.
- Shard Key is Immutable¶
You cannot change a shard key after sharding the collection. If you must change a shard key:
- Dump all data from MongoDB into an external format.
- Drop the original sharded collection.
- Configure sharding using the new shard key.
- Pre-split the shard key range to ensure initial even distribution.
- Restore the dumped data into MongoDB.
- Shard Key Value in a Document is Immutable¶
After you insert a document into a sharded collection, you cannot change the document’s value for the field or fields that comprise the shard key. The update() operation will not modify the value of a shard key in an existing document.
- Monotonically Increasing Shard Keys Can Limit Insert Throughput¶
For clusters with high insert volumes, a shard keys with monotonically increasing and decreasing keys can affect insert throughput. If your shard key is the _id field, be aware that the default values of the _id fields are ObjectIds which have generally increasing values.
When inserting documents with monotonically increasing shard keys, all inserts belong to the same chunk on a single shard. The system will eventually divide the chunk range that receives all write operations and migrate its contents to distribute data more evenly. However, at any moment the cluster can direct insert operations only to a single shard, which creates an insert throughput bottleneck.
If the operations on the cluster are predominately read operations and updates, this limitation may not affect the cluster.
To avoid this constraint, use a hashed shard key or select a field that does not increase or decrease monotonically.
Changed in version 2.4: Hashed shard keys and hashed indexes store hashes of keys with ascending values.
Operations¶
- Sort Operations¶
If MongoDB cannot use an index to get documents in the requested sort order, the combined size of all documents in the sort operation, plus a small overhead, must be less than 32 megabytes.
- Aggregation Pipeline Operation¶
Changed in version 2.6.
Pipeline stages have a limit of 100 megabytes of RAM. If a stage exceeds this limit, MongoDB will produce an error. To allow for the handling of large datasets, use the allowDiskUse option to enable aggregation pipeline stages to write data to temporary files.
See also
$sort and Memory Restrictions and $group Operator and Memory.
- 2d Geospatial queries cannot use the $or operator¶
See
$or and 2d Index Internals.
- Area of GeoJSON Polygons¶
For $geoIntersects or $geoWithin, if you specify a single-ringed polygon that has an area greater than a single hemisphere, include the custom MongoDB coordinate reference system in the $geometry expression; otherwise, $geoIntersects or $geoWithin queries for the complementary geometry. For all other GeoJSON polygons with areas greater than a hemisphere, $geoIntersects or $geoWithin queries for the complementary geometry.
- Write Command Operation Limit Size¶
Write commands can accept no more than 1000 operations. The Bulk() operations in the mongo shell and comparable methods in the drivers do not have this limit.
Naming Restrictions¶
- Database Name Case Sensitivity¶
MongoDB does not permit database names that differ only by the case of the characters.
- Restrictions on Database Names for Windows¶
Changed in version 2.2: Restrictions on Database Names for Windows.
For MongoDB deployments running on Windows, MongoDB will not permit database names that include any of the following characters:
/\. "$*<>:|?
Also, database names cannot contain the null character.
- Restrictions on Database Names for Unix and Linux Systems¶
For MongoDB deployments running on Unix and Linux systems, MongoDB will not permit database names that include any of the following characters:
/\. "$
Also, database names cannot contain the null character.
- Length of Database Names¶
Database names cannot be empty and must have fewer than 64 characters.
- Restriction on Collection Names¶
New in version 2.2.
Collection names should begin with an underscore or a letter character, and cannot:
- contain the $.
- be an empty string (e.g. "").
- contain the null character.
- begin with the system. prefix. (Reserved for internal use.)
In the mongo shell, use db.getCollection() to specify collection names that might interact with the shell or are not valid JavaScript.
- Restrictions on Field Names¶
Field names cannot contain dots (i.e. .) or null characters, and they must not start with a dollar sign (i.e. $). See Dollar Sign Operator Escaping for an alternate approach.
Thank you for your feedback!
We're sorry! You can Report a Problem to help us improve this page.