- Data Models >
- Data Modeling Concepts >
- GridFS
GridFS¶
On this page
GridFS is a specification for storing and retrieving files that exceed the BSON-document size limit of 16MB.
Instead of storing a file in a single document, GridFS divides a file into parts, or chunks, [1] and stores each of those chunks as a separate document. By default GridFS limits chunk size to 255k.
Changed in version 2.4.10: The default chunk size changed from 256k to 255k.
GridFS uses two collections to store files. One collection stores the file chunks, and the other stores file metadata.
When you query a GridFS store for a file, the driver or client will reassemble the chunks as needed. You can perform range queries on files stored through GridFS. You also can access information from arbitrary sections of files, which allows you to “skip” into the middle of a video or audio file.
GridFS is useful not only for storing files that exceed 16MB but also for storing any files for which you want access without having to load the entire file into memory. For more information on the indications of GridFS, see When should I use GridFS?.
[1] | 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. |
Implement 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 in themongo
shell. See mongofiles.
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
names prefixed by fs
bucket:
fs.files
fs.chunks
You can choose a different bucket name than fs
, and create
multiple buckets in a single database.
Each document in the chunks
collection represents a distinct chunk
of a file as represented in the GridFS store. Each chunk is identified
by its unique ObjectId stored in its _id
field.
For descriptions of all fields in the chunks
and files
collections, see GridFS Reference.
GridFS Index¶
GridFS uses a unique, compound index on the chunks
collection for the
files_id
and n
fields. The files_id
field contains the
_id
of the chunk’s “parent” document. The n
field contains the
sequence number of the chunk. GridFS numbers all chunks, starting with
0. For descriptions of the documents and fields in the chunks
collection, see GridFS Reference.
The GridFS index allows efficient retrieval of chunks using the
files_id
and n
values, as shown in the following example:
See the relevant driver documentation
for the specific behavior of your GridFS application. If your driver
does not create this index, issue the following operation using the
mongo
shell:
Example Interface¶
The following is an example of the GridFS interface in Java. The example is for demonstration purposes only. For API specifics, see the relevant driver documentation.
By default, the interface must support the default GridFS bucket, named
fs
, as in the following:
Optionally, interfaces may support other additional GridFS buckets as in the following example: