DOCS-656 - GridFS faq

source/faq/developers.txt

@@ -151,6 +151,46 @@ flag to modify the file preallocation strategy.
 
 .. seealso:: This wiki page that address :wiki:`MongoDB disk use <Excessive+Disk+Space>`.
 
+.. _faq-developers-when-to-use-gridfs:
+
+When should I use GridFS?
+-------------------------
+
+For documents in a MongoDB collection, you should always use
+:term:`GridFS` for storing files larger than 16 MB.
+
+For files on your file system, storing the files in a MongoDB database
+through GridFS provides advantages in a number of situations:
+
+- If your file system limits the number of files in a directory, you can
+  use GridFS to store as many files as needed.
+
+- When you want to store file metadata (such as description, download
+  count, and MD5 hash) together with the file itself. Storing the file
+  data and metadata is important in many scenarios and supported by
+  GridFS.
+
+- When you want to keep your files and metadata automatically synced.
+  If you set up replication, MongoDB replicates both the files and their
+  metadata so things won't get out of sync.
+
+- When you want to access information from random sections of large
+  files without having to load whole files into memory. GridFS lets you
+  access sections of files without having to read the entire file.
+
+Do not use GridFS if a file is under the 16 MB limit and you need to
+update the file atomically. Instead, consider either:
+
+- Storing the file manually within a single document. This can be
+  accomplished using the BSON BinData datatype. For details on using
+  BinData, see the :doc:`drivers </applications/drivers>` documentation
+  for your driver.
+
+- Storing multiple versions and specifying which version is current.
+  This can be changed atomically after the new file is uploaded.
+
+For more information on GridFS, see :doc:`/applications/gridfs`.
+
 How does MongoDB address SQL or Query injection?
 ------------------------------------------------
 

source/reference/glossary.txt

@@ -245,6 +245,9 @@ Glossary
       of the official MongoDB drivers support this convention, as
       does the ``mongofiles`` program.
 
+      .. todo When source/applications/gridfs.txt goes live,
+         add a link here.
+
       .. seealso:: :doc:`/reference/mongofiles`.
 
    md5