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

MongoDB supports no more than 100 levels of nesting for BSON documents.

Naming Restrictions

Database Name Case Sensitivity

Since database names are case insensitive in MongoDB, database names cannot differ only by the case of the characters.

Restrictions on Database Names for Windows

For MongoDB deployments running on Windows, database names cannot contain any of the following characters:

copy 
/\. "$*<>:|?

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, database names cannot contain any of the following characters:

copy 
/\. "$

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

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

If your collection name includes special characters, such as the underscore character, or begins with numbers, then to access the collection use the db.getCollection() method in the mongo shell or a similar method for your driver .

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.

Restrictions on Field Names

  • Field names cannot contain the null character.

  • Top-level field names cannot start with the dollar sign ($) character.

    Otherwise, starting in MongoDB 3.6, the server permits storage of field names that contain dots (i.e. .) and dollar signs (i.e. $).

    Important

    The MongoDB Query Language cannot always meaningfully express queries over documents whose field names contain these characters (see SERVER-30575 ).

    Until support is added in the query language, the use of $ and . in field names is not recommended and is not supported by the official MongoDB drivers.

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.

See also

Naming Restrictions

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.

Size of Namespace File

Changed in version 3.0.

For the MMAPv1 storage engine, namespace files can be no larger than 2047 megabytes.

By default namespace files are 16 megabytes. You can configure the size using the nsSize option.

The WiredTiger storage engine is not subject to this limitation.

See also

Naming Restrictions

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 32 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

Multikey indexes cannot cover queries over array field(s).

Geospatial Index

Geospatial indexes cannot cover a query.

Memory Usage in Foreground Index Builds

You can build one or more indexes on a collection with the database command createIndexes. The default limit on memory usage for a createIndexes operation is 500 megabytes. You can override this limit by setting the maxIndexBuildMemoryUsageMegabytes server parameter.

createIndexes uses a combination of memory and temporary files on disk to complete index builds. Once the memory limit is reached, createIndexes uses temporary disk files in a subdirectory named _tmp within the --dbpath directory for additional scratch space. The higher the memory limit is set, the faster the index build can complete, but be careful not to set this limit too high relative to available RAM or your system can run out of free memory.

Foreground index builds may be initiated either by a user command such as Create Index or by an administrative process such as an initial sync. Both are subject to the limit set by maxIndexBuildMemoryUsageMegabytes.

An initial sync operation populates only one collection at a time and has no risk of exceeding the memory limit. However, it is possible for a user to start foreground index builds on multiple collections in multiple databases simultaneously and potentially consume an amount of memory greater than the limit set in maxIndexBuildMemoryUsageMegabytes.

Tip

To minimize the impact of building an index on replica sets and sharded clusters with replica set shards, use a rolling index build procedure as described on Build Indexes on Replica Sets.

Collation and Index Types

The following index types only support simple binary comparison and do not support collation:

Tip

To create a text, a 2d, or a geoHaystack index on a collection that has a non-simple collation, you must explicitly specify {collation: {locale: "simple"} } when creating the index.

Data

Maximum Number of Documents in a Capped Collection

If you specify a maximum number of documents for

首页