From aa74fd31ba7f62f73d145307bf9dc28f13e98c71 Mon Sep 17 00:00:00 2001 From: Sam Kleinman Date: Tue, 6 Nov 2012 15:44:46 -0500 Subject: [PATCH 1/2] DOCS-652: comments on document page inline --- draft/core/documents.txt | 84 +++++++++++++++++++++++++++++----------- 1 file changed, 62 insertions(+), 22 deletions(-) diff --git a/draft/core/documents.txt b/draft/core/documents.txt index 2659841c3d7..e2000e9b125 100644 --- a/draft/core/documents.txt +++ b/draft/core/documents.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. Document's provide structure for data in the following +MongoDB contexts: - the :ref:`records ` stored in :term:`collections ` @@ -22,13 +26,18 @@ The document structure in MongoDB refer to the data structure of: - :ref:`sort order ` for the :method:`sort() ` method. + - index specification for the :method:`hint() ` + method. + +.. status output, link to examples of server stats/coll stats/etc. (?) + 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,18 +54,34 @@ 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``. +.. give more examples of: + + - special bson types NumberLong(), Timestamp, etc. + + - nested document. + + - with arrays + +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 - .. include:: /includes/fact-document-field-name-restrictions.rst +.. these should be links to the limit page or include those links. We + should make these things centrally referenced to limit the number + of places these data points exist *if* any of them ever change. + .. include:: /includes/note-insert-id-field.rst The following document specifies a record in a collection: @@ -92,16 +117,24 @@ The document contains the following fields: - field ``awards`` whose value is an *array of Documents* +.. not sure about the capitalization of Documents/Date/String here. + .. _documents-query-selectors: -Document as query selectors ---------------------------- +Query Specification Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. this section should have a better lead in. I think we should be + able to avoid the bulleted list here, which affects flow... Query selector documents may contain any or all of the following: - Simple field and value pair(s) to specify the equality condition. +.. we should attempt to avoid issuing qualitative judgements about + complexity or simplicity. + - :doc:`Query operator ` expressions to specify other conditions. @@ -140,8 +173,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,8 +185,10 @@ determines which records are returned, removed, or updated: .. _documents-update-actions: -Document as update actions --------------------------- +Update Specification Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. when are they used, links to cross reference material to provide context The update actions documents contain :ref:`update operators ` expressions. @@ -189,8 +224,11 @@ When passed as an argument to the :method:`update() .. _documents-index: -Document as index ------------------ +Index Specifier Documents +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. what are index documents? when are they used? cross reference links + would provide a lot of the required documentation. The index documents contain field and value pairs where: @@ -216,8 +254,10 @@ the index to create: .. _documents-sort-order: -Document as sort order ----------------------- +Sort Order Specification Documents +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. where? context? The sort order documents contain field and value pairs where: From c6644a4d893d7161b05a6369ef0c879e8329a9dd Mon Sep 17 00:00:00 2001 From: kay Date: Tue, 6 Nov 2012 19:02:43 -0500 Subject: [PATCH 2/2] DOCS-617 merge and edit the bson doc --- draft/core/{documents.txt => document.txt} | 100 +++++++++++++-------- source/includes/fact-document-max-size.rst | 8 +- source/reference/limits.txt | 2 +- 3 files changed, 68 insertions(+), 42 deletions(-) rename draft/core/{documents.txt => document.txt} (70%) diff --git a/draft/core/documents.txt b/draft/core/document.txt similarity index 70% rename from draft/core/documents.txt rename to draft/core/document.txt index e2000e9b125..135737aeb55 100644 --- a/draft/core/documents.txt +++ b/draft/core/document.txt @@ -4,10 +4,10 @@ BSON Documents .. default-domain:: mongodb -MongoDB is a document-based database system, and as a result all -records, or data in MongoDB are documents. Documents are the default +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. Document's provide structure for data in the following +database. Documents provide structure for data in the following MongoDB contexts: - the :ref:`records ` stored in :term:`collections @@ -26,10 +26,15 @@ MongoDB contexts: - :ref:`sort order ` for the :method:`sort() ` method. - - index specification for the :method:`hint() ` - method. + - :ref:`index specification ` for the + :method:`hint() ` method. -.. status output, link to examples of server stats/coll stats/etc. (?) +- the various outputs from commands and operations, such as: + + - the output of :dbcommand:`collStats` command + + - the output of :doc:`db.serverStatus + ` command Structure --------- @@ -54,13 +59,35 @@ 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``. -.. give more examples of: +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* - - special bson types NumberLong(), Timestamp, etc. +- field ``contribs`` whose value is an *array of Strings* - - nested document. +- field ``views`` whose value is a *NumberLong* - - with arrays +- field ``update`` whose value is a *Timestamp* Types ----- @@ -71,17 +98,14 @@ Record Documents ~~~~~~~~~~~~~~~~ Most documents in MongoDB are records in :term:`collections` which -store data from users' applications. These documents have the -following limitations: +store data from users' applications. + +These documents have the following limitations: - .. include:: /includes/fact-document-max-size.rst - .. include:: /includes/fact-document-field-name-restrictions.rst -.. these should be links to the limit page or include those links. We - should make these things centrally referenced to limit the number - of places these data points exist *if* any of them ever change. - .. include:: /includes/note-insert-id-field.rst The following document specifies a record in a collection: @@ -124,19 +148,13 @@ The document contains the following fields: Query Specification Documents ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. this section should have a better lead in. I think we should be - able to avoid the bulleted list here, which affects flow... - -Query selector documents may contain any or all of the following: - -- Simple field and value pair(s) to specify the equality - condition. - -.. we should attempt to avoid issuing qualitative judgements about - complexity or simplicity. - -- :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: @@ -188,10 +206,12 @@ for MongoDB to return, remove, or update, as in the following: Update Specification Documents ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. when are they used, links to cross reference material to provide context - -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: @@ -227,8 +247,10 @@ When passed as an argument to the :method:`update() Index Specifier Documents ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. what are index documents? when are they used? cross reference links - would provide a lot of the required documentation. +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: @@ -257,7 +279,11 @@ the index to create: Sort Order Specification Documents ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. where? context? +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: @@ -266,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