From ee4db930c3455c2d874926836696ec8e2a5e930d Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Fri, 2 Nov 2012 15:58:43 -0400 Subject: [PATCH 1/3] DOCS-656 GridFS FAQ --- source/faq/developers.txt | 38 +++++++++++++++++++++++++++++++++++ source/reference/glossary.txt | 3 +++ 2 files changed, 41 insertions(+) diff --git a/source/faq/developers.txt b/source/faq/developers.txt index 35db80d4345..38d61922d5c 100644 --- a/source/faq/developers.txt +++ b/source/faq/developers.txt @@ -151,6 +151,44 @@ flag to modify the file preallocation strategy. .. seealso:: This wiki page that address :wiki:`MongoDB disk use `. +When should and shouldn't I use GridFS? +--------------------------------------- + +:term:`GridFS` is a specification for storing and retrieving files +that exceed the :term:`BSON`-document :ref:`size limit +` of 16MB. You should always use GridFS +for storing files larger than 16MB. + +Additionally, GridFS storage has advantages in the following other +situations as well: + +- When you have many thousands of files, GridFS tends to handle the + large numbers better than many file systems. + +- When users frequently upload files. When users upload files you tend + to have a lot of files, all of which are also usually replicated and + backed up. GridFS lets you manage them the same way you that you + manage your data. You can query the files, for example by user or + upload date, directly in the file store, without a layer of + indirection. + +- When files often change. If you have certain files that change a lot, + consider storing them in GridFS, which then allows you to modify them + in one place. Also, all clients get the updates. If you instead store + in source tree, you must deploy an application to update files. + +There are some situations where you should not use GridFS: + +- When you have only a few small and static files, such as js, css, and + images on a web site. + +.. todo Verify that this info from the wiki can be deleted: + Note that if you need to update a binary object atomically, and the + object is under the document size limit for your version of MongoDB + (16MB for 1.8), then you might consider storing the object manually + within a single document. This can be accomplished using the BSON + bindata type. Check your driver's docs for details on using this type + How does MongoDB address SQL or Query injection? ------------------------------------------------ diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index 419bc1d3e00..3bae3c01f27 100644 --- a/source/reference/glossary.txt +++ b/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 From 52a09f7a043707330e080283a1c0b609b9069552 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Wed, 21 Nov 2012 10:17:29 -0500 Subject: [PATCH 2/3] DOCS-656 GridFS FAQ review edits --- source/faq/developers.txt | 60 ++++++++++++++++++++------------------- 1 file changed, 31 insertions(+), 29 deletions(-) diff --git a/source/faq/developers.txt b/source/faq/developers.txt index 38d61922d5c..b9223493869 100644 --- a/source/faq/developers.txt +++ b/source/faq/developers.txt @@ -151,43 +151,45 @@ flag to modify the file preallocation strategy. .. seealso:: This wiki page that address :wiki:`MongoDB disk use `. -When should and shouldn't I use GridFS? ---------------------------------------- +.. _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: -:term:`GridFS` is a specification for storing and retrieving files -that exceed the :term:`BSON`-document :ref:`size limit -` of 16MB. You should always use GridFS -for storing files larger than 16MB. +- If your file system limits the number of files in a directory, you can + use GridFS to store as many files as needed in a directory. -Additionally, GridFS storage has advantages in the following other -situations as well: +- When you want to store file metadata (such as description, download + count, and MD5 hash) together with the file itself. GridFS stores file + metadata in the same bucket as the file's content. -- When you have many thousands of files, GridFS tends to handle the - large numbers better than many file systems. +- When you want to keep your files and metadata automatically backed up. + If you set up replication, MongoDB makes automatic backups of your + files and metadata. -- When users frequently upload files. When users upload files you tend - to have a lot of files, all of which are also usually replicated and - backed up. GridFS lets you manage them the same way you that you - manage your data. You can query the files, for example by user or - upload date, directly in the file store, without a layer of - indirection. +- 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, for + example skipping into the middle of a video. -- When files often change. If you have certain files that change a lot, - consider storing them in GridFS, which then allows you to modify them - in one place. Also, all clients get the updates. If you instead store - in source tree, you must deploy an application to update files. +Do not use GridFS if a file is under the 16 MB limit and you need to +update the file atomically. Instead, consider either: -There are some situations where you should not use GridFS: +- 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 ` documentation + for your driver. -- When you have only a few small and static files, such as js, css, and - images on a web site. +- Storing multiple versions and specifying which version is current. + This can be changed atomically after the new file is uploaded. -.. todo Verify that this info from the wiki can be deleted: - Note that if you need to update a binary object atomically, and the - object is under the document size limit for your version of MongoDB - (16MB for 1.8), then you might consider storing the object manually - within a single document. This can be accomplished using the BSON - bindata type. Check your driver's docs for details on using this type +For more information on GridFS, see :doc:`/applications/gridfs`. How does MongoDB address SQL or Query injection? ------------------------------------------------ From ea749d45ceb58647432d8102b9f6ea545465eb69 Mon Sep 17 00:00:00 2001 From: Bob Grabar Date: Mon, 3 Dec 2012 14:03:13 -0500 Subject: [PATCH 3/3] DOCS-656 review edits --- source/faq/developers.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/faq/developers.txt b/source/faq/developers.txt index b9223493869..e9ccc702e67 100644 --- a/source/faq/developers.txt +++ b/source/faq/developers.txt @@ -163,20 +163,20 @@ 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 in a directory. + 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. GridFS stores file - metadata in the same bucket as the file's content. + 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 backed up. - If you set up replication, MongoDB makes automatic backups of your - files and metadata. +- 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, for - example skipping into the middle of a video. + 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: