MongoDB Maximum Document Size

MongoDB limits each BSON document to 16 MB. If a record grows beyond that, reduce its encoded size or move some data to other documents; for large files, consider GridFS. The limit applies to each document, not to the total size of a collection or to a file represented by multiple GridFS documents.

MongoDB’s Maximum BSON Document Size

MongoDB stores records in BSON, a binary format for JSON-like documents. BSON supports additional data types such as dates and binary data. The MongoDB limits documentation gives the maximum size of one BSON document as 16 MB and states a maximum nesting depth of 100 levels. Arrays and embedded documents contribute to nesting depth.

The limit is measured on the encoded BSON document, including field names, type markers, lengths, and other structural overhead. The size of a JSON string or the number of values alone therefore does not tell you whether a document will fit. Leave room below the maximum when designing records, and measure representative documents with the BSON tools in your application’s driver before relying on a size estimate.

How GridFS Stores Files Larger Than the Document Limit

GridFS is a MongoDB specification for storing and retrieving files that are larger than the single-document limit. A GridFS implementation divides a file into chunks stored as separate documents. By default, it uses the fs.files collection for file metadata and the fs.chunks collection for chunk data. A file document identifies the file, and each chunk refers back to it through files_id.

This structure allows a large file to be handled in pieces; it does not permit one oversized BSON document. Use the GridFS support provided by your MongoDB driver to upload, retrieve, or stream a file. Chunk size and API details depend on the implementation and configuration, so consult the documentation for the driver you use.

How to Keep a BSON Document Within the Limit

First, inspect which fields account for most of the encoded size. Remove data that can be derived, avoid repeating large values, and choose compact representations where they remain clear and maintainable. Compression of a string in application code is useful only if the application can store and interpret the resulting binary data; it also adds processing and compatibility considerations.

When a field contains a small set of repeated strings, dictionary encoding can store each distinct string once and represent occurrences by an index. The following Python example illustrates that transformation in memory; it does not calculate BSON size or connect to MongoDB.

Run this example:

values = ["pending", "complete", "pending", "pending"]
dictionary = list(dict.fromkeys(values))
indexes = [dictionary.index(value) for value in values]
print(dictionary)
print(indexes)

Dictionary encoding can reduce repeated text, but indexes make records harder to inspect and require the dictionary to remain available and consistent. It may not help when values are mostly unique, and the added structure also has a cost. Measure representative encoded documents rather than assuming a transformation guarantees a fit.

Choose a Storage Strategy When Data Exceeds the Limit

Use a smaller document when the data belongs together and can be represented more compactly without losing needed information. Split data into related documents when parts have their own lifecycle or are read independently; keep a stable identifier or reference so the application can retrieve the related records. This can make queries require additional reads and means related updates may need careful handling.

Use GridFS for large file content such as images, audio, or video when the application needs MongoDB’s file storage and retrieval behavior. Keep searchable or frequently queried attributes in ordinary documents and store a reference to the GridFS file. GridFS is not the default answer for every oversized record: first decide whether the data is a file, related structured data, or simply a document that can be made smaller.