diff --git a/draft/core/documents.txt b/draft/core/document.txt similarity index 60% rename from draft/core/documents.txt rename to draft/core/document.txt index 2659841c3d7..135737aeb55 100644 --- a/draft/core/documents.txt +++ b/draft/core/document.txt @@ -1,10 +1,14 @@ -========= -Documents -========= +============== +BSON Documents +============== .. default-domain:: mongodb -The document structure in MongoDB refer to the data structure of: +MongoDB is a document-based database system, and as a result, all +records, or data, in MongoDB are documents. Documents are the default +representation of most user accessible data structures in the +database. Documents provide structure for data in the following +MongoDB contexts: - the :ref:`records ` stored in :term:`collections ` @@ -22,13 +26,23 @@ The document structure in MongoDB refer to the data structure of: - :ref:`sort order ` for the :method:`sort() ` method. + - :ref:`index specification ` for the + :method:`hint() ` method. + +- the various outputs from commands and operations, such as: + + - the output of :dbcommand:`collStats` command + + - the output of :doc:`db.serverStatus + ` command + Structure --------- -The document structure in MongoDB are :term:`BSON` objects with support -for the full range of :term:`BSON types`; however, conceptually, -documents may be viewed as :term:`JSON` objects with the following -structure: +The document structure in MongoDB are :term:`BSON` objects with +support for the full range of :term:`BSON types`; however, BSON +documents are conceptually, similar to :term:`JSON` objects, and have +the following structure: .. code-block:: javascript @@ -45,13 +59,48 @@ documents may contain field and value pairs where the value can be another document, an array, an array of documents as well as the basic types such as ``Double``, ``String``, or ``Date``. +Consider the following document that contains values of varying +types: + +.. code-block:: javascript + + { + _id: ObjectId("5099803df3f4948bd2f98391"), + name: { first: "Alan", last: "Turing" }, + birth: new Date('Jun 23, 1912'), + death: new Date('Jun 07, 1954'), + contribs: [ "Turing machine", "Turing test", "Turingery" ], + views : NumberLong(1250000), + update : Timestamp(1352237167000, 1) + } + +The document contains the following fields: + +- field ``_id`` whose value is an *ObjectId* + +- field ``name`` whose value is another *Document* that contains the + fields ``first`` and ``last`` + +- fields ``birth`` and ``death`` whose value is a *Date* + +- field ``contribs`` whose value is an *array of Strings* + +- field ``views`` whose value is a *NumberLong* + +- field ``update`` whose value is a *Timestamp* + +Types +----- + .. _documents-records: -Document as records -------------------- +Record Documents +~~~~~~~~~~~~~~~~ -For documents that specify records to be stored in a collection, the -following restrictions apply: +Most documents in MongoDB are records in :term:`collections` which +store data from users' applications. + +These documents have the following limitations: - .. include:: /includes/fact-document-max-size.rst @@ -92,18 +141,20 @@ The document contains the following fields: - field ``awards`` whose value is an *array of Documents* -.. _documents-query-selectors: - -Document as query selectors ---------------------------- +.. not sure about the capitalization of Documents/Date/String here. -Query selector documents may contain any or all of the following: +.. _documents-query-selectors: -- Simple field and value pair(s) to specify the equality - condition. +Query Specification Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- :doc:`Query operator ` expressions to specify - other conditions. +Query selector documents specify the conditions that determine which +records to select for read, update, and delete operations. You can use +field and value expressions to specify the equality condition and +:doc:`query operator ` expressions to specify +additional conditions. Refer to :doc:`read `, +:doc:`update `, and :doc:`delete +` pages for more examples. Consider the following examples of query selector documents: @@ -140,8 +191,8 @@ Consider the following examples of query selector documents: When passed as an argument to methods such as the :method:`find() ` method, the :method:`remove() ` method, or the :method:`update() -` method, the query selector document -determines which records are returned, removed, or updated: +` method, the query document selects documents +for MongoDB to return, remove, or update, as in the following: .. code-block:: javascript @@ -152,11 +203,15 @@ determines which records are returned, removed, or updated: .. _documents-update-actions: -Document as update actions --------------------------- +Update Specification Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The update actions documents contain :ref:`update operators -` expressions. +The update action documents specify the data modifications to perform +during an :method:`update() ` operation to +modify existing records in a collection. You can use :ref:`update +operators ` to specify the exact actions to perform +on the document fields. See the :ref:`update operators +` page for the available update operators and syntax. Consider the following example of an update actions document: @@ -189,8 +244,13 @@ When passed as an argument to the :method:`update() .. _documents-index: -Document as index ------------------ +Index Specifier Documents +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Indexes improve the efficiency of :doc:`read ` +operations. Index documents specify the fields to index on during the +:method:`index creation ` operation. See +:doc:`indexes ` for an overview of indexes. The index documents contain field and value pairs where: @@ -216,8 +276,14 @@ the index to create: .. _documents-sort-order: -Document as sort order ----------------------- +Sort Order Specification Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The sort order documents specify the order of documents that a +:method:`query() ` returns. The sort order +document is passed as an argument to the :method:`sort() +` method. See the :method:`sort() ` page +for more information on sorting. The sort order documents contain field and value pairs where: @@ -226,7 +292,7 @@ The sort order documents contain field and value pairs where: - the ``value`` is either 1 for ascending or -1 for descending. The following document specifies the sort order using the fields from a -subdocument ``name``: first sort by the ``last`` field ascending, then +subdocument ``name`` first sort by the ``last`` field ascending, then by the ``first`` field also ascending: .. code-block:: javascript diff --git a/source/includes/fact-document-max-size.rst b/source/includes/fact-document-max-size.rst index 40fdea090a7..1f9a8381019 100644 --- a/source/includes/fact-document-max-size.rst +++ b/source/includes/fact-document-max-size.rst @@ -1,7 +1,7 @@ -Documents have a 16 megabytes size limit. +The maximum BSON document size is 16 megabytes. The maximum document size helps ensure that a single document cannot use excessive amount of RAM or, during transmission, excessive amount -of bandwidth. To store larger objects, MongoDB provides the -GridFS API to handle documents larger than the maximum size. See your -specific driver documentation for GridFS. +of bandwidth. To store larger objects, MongoDB provides the GridFS API +to handle documents larger than the maximum size. See your specific +driver documentation for GridFS. diff --git a/source/reference/limits.txt b/source/reference/limits.txt index 5224972a1c3..2e24139dff9 100644 --- a/source/reference/limits.txt +++ b/source/reference/limits.txt @@ -19,7 +19,7 @@ BSON Documents .. _limit-bson-document-size: .. limit:: BSON Document Size - The maximum BSON document size is 16 megabytes. + .. include:: /includes/fact-document-max-size.rst .. _limit-nested-depth: .. limit:: Nested Depth for BSON Documents