What is the Maximum Size of a MongoDB Document?

MongoDB is a NoSQL database which can store JSON like documents in containers known as collections. There is no technical limit as to how many documents can be stored in a MongoDB collection. However, current versions of MongoDB has a limit on the maximum size of a single document stored in a collection. Since 1.7.4 version of MongoDB, single document size limit is 16MB (Originally it was 4MB). MongoDB stores JSON like documents in a binary representation known as the BSON document. The size limit of 16MB applies to the BSON form, not to the JSON representation.

For example, if you try to insert a single document with more than 16MB into MongoDB using Pymongo library for python, you will get the following error,

DocumentTooLarge: BSON document too large

There are two options to solve the size limit issue. You need to either redesign the schema or use GridFS.

If you need to store documents larger than 16MB in MongoDB, you can use the GridFS specification available in MongoDB. GridFS splits the large document in smaller chunks of size 255KB and stores them in a collection. The metadata for the document itself is stored in a separate collection. Hence each entity in GridFS needs two collections for data storage.

Please be aware that the 16MB limit is for pure MongoDB implementations. Other database platforms that provide MongoDB API compatibility may have a different maximum document size. For example, Azure CosmosDB for MongoDB API has a per document size limit of 2MB for JSON representation. This limit requires careful design decisions when collections are designed for CosmosDB database since a future requirement or rare data instances may cause failure of data storage. In such cases, refactoring of collections may be needed. For example, you may be storing all product IDs under a category in a product category collection until a super category appears with a large number of products causing the document size to hit the 2MB limit. One solution in this case is to model each product to category association as a separate document!

The limit of 16MB is needed to ensure that excessive RAM or network transfers are not caused by very large documents. If you face issues with 16MB limit, it usually means you need to redesign your MongoDB schema or use GridFS specification. Also note that when it comes to complex documents, MongoDB has a limit of 100 levels of nesting.

Here are some tips to analyse/refactor your MongoDB schema if you hit 16MB limit,

  • Is it possible to logically split the collection containing the document into multiple collections? If needed it is possible to combine data from multiple collections using the $lookup operator in MongoDB.
  • Can you model the schema such that nested elements or arrays can be modelled as individual documents? With indexing, multiple documents matching a criteria can be easily retrieved. It is always better to have lot of small documents than a few large documents.