- Storage >
- GridFS
GridFS¶
On this page
GridFS is a specification for storing and retrieving files that exceed the BSON-document size limit of 16 MB.
Instead of storing a file in a single document, GridFS divides the file into parts, or chunks [1], and stores each chunk as a separate document. By default, GridFS uses a chunk size of 255 kB; that is, GridFS divides a file into chunks of 255 kB with the exception of the last chunk. The last chunk is only as large as necessary. Similarly, files that are no larger than the chunk size only have a final chunk, using only as much space as needed plus some additional metadata.
GridFS uses two collections to store files. One collection stores the file chunks, and the other stores file metadata. The section GridFS Collections describes each collection in detail.
When you query GridFS for a file, the driver will reassemble the chunks as needed. You can perform range queries on files stored through GridFS. You can also access information from arbitrary sections of files, such as to “skip” to the middle of a video or audio file.
GridFS is useful not only for storing files that exceed 16 MB but also for storing any files for which you want access without having to load the entire file into memory. See also When should I use GridFS?.
Changed in version 2.4.10: The default chunk size changed from 256 kB to 255 kB.
Use GridFS¶
To store and retrieve files using GridFS, use either of the following:
- A MongoDB driver. See the drivers documentation for information on using GridFS with your driver.
- The mongofiles command-line tool. See the mongofiles reference for documentation.
GridFS Collections¶
GridFS stores files in two collections:
- chunks stores the binary chunks. For details, see The chunks Collection.
- files stores the file’s metadata. For details, see The files Collection.
GridFS places the collections in a common bucket by prefixing each with the bucket name. By default, GridFS uses two collections with a bucket named fs:
- fs.files
- fs.chunks
You can choose a different bucket name, as well as create multiple buckets in a single database. The full collection name, which includes the bucket name, is subject to the namespace length limit.
The chunks Collection¶
Each document in the chunks [1] collection represents a distinct chunk of a file as represented in GridFS. Documents in this collection have the following form:
{
"_id" : <ObjectId>,
"files_id" : <ObjectId>,
"n" : <num>,
"data" : <binary>
}
A document from the chunks collection contains the following fields:
- chunks.files_id¶
The _id of the “parent” document, as specified in the files collection.
- chunks.n¶
The sequence number of the chunk. GridFS numbers all chunks, starting with 0.
The files Collection¶
Each document in the files collection represents a file in GridFS. Consider a document in the files collection, which has the following form:
{
"_id" : <ObjectId>,
"length" : <num>,
"chunkSize" : <num>,
"uploadDate" : <timestamp>,
"md5" : <hash>,
"filename" : <string>,
"contentType" : <string>,
"aliases" : <string array>,
"metadata" : <dataObject>,
}
Documents in the files collection contain some or all of the following fields. Applications may create additional arbitrary fields:
- files._id¶
The unique identifier for this document. The _id is of the data type you chose for the original document. The default type for MongoDB documents is BSON ObjectId.
- files.length¶
The size of the document in bytes.
- files.chunkSize¶
The size of each chunk in bytes. GridFS divides the document into chunks of size chunkSize, except for the last, which is only as large as needed. The default size is 255 kilobytes (kB).
Changed in version 2.4.10: The default chunk size changed from 256 kB to 255 kB.
- files.uploadDate¶
The date the document was first stored by GridFS. This value has the Date type.
- files.md5¶
An MD5 hash of the complete file returned by the filemd5 command. This value has the String type.
- files.filename¶
Optional. A human-readable name for the GridFS file.
- files.contentType¶
Optional. A valid MIME type for the GridFS file.
- files.aliases¶
Optional. An array of alias strings.
- files.metadata¶
Optional. Any additional information you want to store.
GridFS Indexes¶
GridFS uses indexes on each of the chunks and files collections for efficiency. Drivers that conform to the GridFS specification automatically create these indexes for convenience. You can also create any additional indexes as desired to suit your application’s needs.
The chunks Index¶
GridFS uses a unique, compound index on the chunks collection using the files_id and n fields. This allows for efficient retrieval of chunks, as demonstrated in the following example:
db.fs.chunks.find( { files_id: myFileID } ).sort( { n: 1 } )
Drivers that conform to the GridFS specification will automatically ensure that this index exists before read and write operations. See the relevant driver documentation for the specific behavior of your GridFS application.
If this index does not exist, you can issue the following operation to create it using the mongo shell:
db.fs.chunks.createIndex( { files_id: 1, n: 1 }, { unique: true } );
The files Index¶
GridFS uses an index on the files collection using the filename and uploadDate fields. This index allows for efficient retrieval of files, as shown in this example:
db.fs.files.find( { filename: myFileName } ).sort( { uploadDate: 1 } )
Drivers that conform to the GridFS specification will automatically ensure that this index exists before read and write operations. See the relevant driver documentation for the specific behavior of your GridFS application.
If this index does not exist, you can issue the following operation to create it using the mongo shell:
db.fs.files.createIndex( { filename: 1, uploadDate: 1 } );
| [1] | (1, 2) The use of the term chunks in the context of GridFS is not related to the use of the term chunks in the context of sharding. |
Thank you for your feedback!
We're sorry! You can Report a Problem to help us improve this page.