Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
branch: v2.4
Fetching contributors…

Cannot retrieve contributors at this time

142 lines (98 sloc) 4.741 kB
.. index:: GridFS
======
GridFS
======
.. default-domain:: mongodb
:term:`GridFS` is a specification for storing and retrieving files
that exceed the :term:`BSON`\-document :ref:`size limit
<limit-bson-document-size>` of 16MB.
Instead of storing a file in a single document, GridFS divides a file
into parts, or chunks, [#chunk-disambiguation]_ and stores each of
those chunks as a separate document. By default GridFS limits chunk
size to 255k.
.. versionchanged:: 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 :ref:`faq-developers-when-to-use-gridfs`.
.. [#chunk-disambiguation] 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.
.. index:: GridFS; initialize
.. _gridfs-implement:
Implement GridFS
----------------
To store and retrieve files using :term:`GridFS`, use either of the following:
- A MongoDB driver. See the :doc:`drivers</applications/drivers>`
documentation for information on using GridFS with your driver.
- The :program:`mongofiles` command-line tool in the :program:`mongo`
shell. See :doc:`/reference/program/mongofiles`.
GridFS Collections
------------------
:term:`GridFS` stores files in two collections:
- ``chunks`` stores the binary chunks. For details, see
:ref:`gridfs-chunks-collection`.
- ``files`` stores the file's metadata. For details, see
:ref:`gridfs-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 :term:`ObjectId` stored in its ``_id`` field.
For descriptions of all fields in the ``chunks`` and ``files``
collections, see :doc:`/reference/gridfs`.
.. index:: GridFS; index
.. _gridfs-index:
GridFS Index
------------
:term:`GridFS` uses a :term:`unique <unique index>`, :term:`compound
<compound index>` 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 :doc:`/reference/gridfs`.
The GridFS index allows efficient retrieval of chunks using the
``files_id`` and ``n`` values, as shown in the following example:
.. code-block:: javascript
cursor = db.fs.chunks.find({files_id: myFileID}).sort({n:1});
See the relevant :doc:`driver </applications/drivers>` documentation
for the specific behavior of your GridFS application. If your driver
does not create this index, issue the following operation using the
:program:`mongo` shell:
.. code-block:: javascript
db.fs.chunks.ensureIndex( { files_id: 1, n: 1 }, { unique: true } );
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
:doc:`driver </applications/drivers>` documentation.
By default, the interface must support the default GridFS bucket, named
``fs``, as in the following:
.. code-block:: java
// returns default GridFS bucket (i.e. "fs" collection)
GridFS myFS = new GridFS(myDatabase);
// saves the file to "fs" GridFS bucket
myFS.createFile(new File("/tmp/largething.mpg"));
Optionally, interfaces may support other additional GridFS buckets as
in the following example:
.. code-block:: java
// returns GridFS bucket named "contracts"
GridFS myContracts = new GridFS(myDatabase, "contracts");
// retrieve GridFS object "smithco"
GridFSDBFile file = myContracts.findOne("smithco");
// saves the GridFS file to the file system
file.writeTo(new File("/tmp/smithco.pdf"));
Jump to Line
Something went wrong with that request. Please try again.