diff --git a/draft/applications/delete.txt b/draft/applications/delete.txt index e6c9ddfeb49..3c22c5476ec 100644 --- a/draft/applications/delete.txt +++ b/draft/applications/delete.txt @@ -5,14 +5,18 @@ Delete .. default-domain:: mongodb Of the four basic database operations (i.e. CRUD), *delete* operations -are those that remove documents from a :term:`collection` in -MongoDB. The :ref:`remove() ` method in the -:program:`mongo` shell provides this operation, as do corresponding -methods in the :doc:`drivers `. +are those that remove documents from a :term:`collection` in MongoDB. -For more information about document removal and other write operations -see :ref:`/core/write-operations`, for documentation of other basic -database operations see the :doc:`/crud` page. +For general information about write operations and the factors that affect +their performance, see :ref:`/core/write-operations`; for documentation +of other CRUD operations, see the :doc:`/crud` page. + +Overview +-------- + +The :ref:`remove() ` method in the :program:`mongo` +shell provides this operation, as do corresponding methods in the +:doc:`drivers `. .. note:: @@ -31,22 +35,21 @@ the following prototype operation: db.collection.delete( , ) -In the :method:`remove() ` consider the -following rough analogies to SQL: +.. admonition:: Corresponding operation in SQL -- :method:`remove() ` has the same function as - the ``DELETE`` statement, + The :method:`remove() ` method is analogous to + the ``DELETE`` statement, and: -- the ```` argument corresponds to the ``WHERE`` statement, and + - the ```` argument corresponds to the ``WHERE`` statement, and -- the ```` argument has the same affect as ``LIMIT 1``. + - the ```` argument has the same affect as ``LIMIT 1``. Consider the following examples that illustrate the use of the :method:`remove() `: -- If there is a query argument, the :method:`remove() +- If there is a ```` argument, the :method:`remove() ` method deletes from the collection all - documents that match the query. + documents that match the argument. The following operation deletes all documents from the ``csbios`` collection where the ``first`` field in the subdocument ``name`` @@ -56,7 +59,7 @@ Consider the following examples that illustrate the use of the db.csbios.remove( { 'name.first' : /^G/ } ) -- If there is a query argument and you specify the ``justOne`` +- If there is a ```` argument and you specify the ```` argument, :method:`remove() ` only deletes a single documents from the collection that matches the query. @@ -67,7 +70,7 @@ Consider the following examples that illustrate the use of the db.csbios.remove( { turing: true }, 1 ) -- If there is no ``query`` argument, the :method:`remove() +- If there is no ```` argument, the :method:`remove() ` method deletes all documents from a collection. The following operation deletes all documents from the ``csbios`` collection: @@ -94,15 +97,15 @@ Capped Collection Isolation ~~~~~~~~~ -If the query argument to the :method:`remove() +If the ```` argument to the :method:`remove() ` method matches multiple documents in the collection, the delete operation may interleave with other write operations to that collection. For an unsharded collection, you have the option to override this behavior with the :operator:`$atomic` isolation operator, effectively isolating the delete operation and -blocking all other operations during the delete operation. To isolate the operation, -include ``$atomic: 1`` in the ``query`` parameter as in the following -example: +blocking all other operations during the delete operation. To isolate +the operation, include ``$atomic: 1`` in the ```` parameter as in +the following example: .. code-block:: javascript diff --git a/draft/applications/update.txt b/draft/applications/update.txt index 294bf6acd01..f6ec5df3e6b 100644 --- a/draft/applications/update.txt +++ b/draft/applications/update.txt @@ -6,10 +6,13 @@ Update Of the four basic database operations (i.e. CRUD), *update* operations are those that modify existing records or :term:`documents ` -in a MongoDB :term:`collection`. For more information about document -modification and other write operations see :ref:`/core/write-operations`, -for documentation of other basic database operations see the -:doc:`/crud` page. +in a MongoDB :term:`collection`. For general information about write +operations and the factors that affect their performance, see +:ref:`/core/write-operations`; for documentation of other CRUD +operations, see the :doc:`/crud` page. + +Overview +-------- Update operation modifies an existing :term:`document ` or documents in a :term:`collection`. MongoDB provides the following @@ -47,12 +50,18 @@ syntax: db.collection.update( , , ) -The :method:`update() ` method corresponds to -the ``UPDATE`` operation in SQL, while ```` argument -corresponds to the ``WHERE`` statement and ```` corresponds to -the ``SET ...`` statement. However, :method:`update() -` is more flexible and offers more control -than the SQL equivalents. +.. admonition:: Corresponding operation in SQL + + The :method:`update() ` method corresponds + to the ``UPDATE`` operation in SQL, and: + + - the ```` argument corresponds to the ``WHERE`` statement, + and + + - the ```` corresponds to the ``SET ...`` statement. + + However, :method:`update() ` is more + flexible and offers more control than its SQL equivalents. Consider the following examples that illustrate the use of the :method:`update() ` method: @@ -76,7 +85,7 @@ Consider the following examples that illustrate the use of the by: 'IBM' } } } ) -- If the update argument contains :operator:`$unset` operator, the +- If the ```` argument contains :operator:`$unset` operator, the :method:`update() ` method removes the field from the document. @@ -112,7 +121,7 @@ Consider the following examples that illustrate the use of the The following operation queries the ``csbios`` collection for the first document that has a ``name`` field equal to ``{ first: 'John', last: 'McCarthy' }`` and replaces all but the ``_id`` field in the - document with the fields in the ``update`` argument: + document with the fields in the ```` argument: .. code-block:: javascript @@ -186,7 +195,7 @@ Consider the following examples that illustrate the use of the db.csbios.update( { _id: 6, 'awards.by': 'ACM' } , { $set: { 'awards.$.by': 'Association for Computing Machinery' } } ) -- If the ``options`` argument contains the ``multi`` option set to +- If the ```` argument contains the ``multi`` option set to ``true`` or ``1``, the :method:`update() ` method updates all documents that match the query. @@ -201,7 +210,7 @@ Consider the following examples that illustrate the use of the { $set: { turing: true } }, { multi: true } ) -- If you set the ``upsert`` option in the ``options`` argument, to +- If you set the ``upsert`` option in the ```` argument to ``true`` or ``1`` and no existing document match the ```` argument, the :method:`update() ` method can insert a new document into the collection: @@ -209,11 +218,12 @@ Consider the following examples that illustrate the use of the The following operation queries the ``csbios`` collection for a document with the ``_id`` field equal to ``11`` and the ``name`` field equal to ``{ first: 'James', last: 'Gosling'}``. If the query - selects a document, the operation performs an update operation. If a document - is not found, :method:`update() ` performs an insert operation of a new - document with the fields and values in the ``update`` argument and - the ```` argument since the ``update`` argument contains only - :ref:`update operators ` expressions. + selects a document, the operation performs an update operation. If a + document is not found, :method:`update() ` + performs an insert operation of a new document with the fields and + values in the ```` argument and the ```` argument + since the ```` argument contains only :ref:`update operators + ` expressions. .. code-block::javascript @@ -247,7 +257,7 @@ The :method:`save() ` method updates an existing document or inserts a document depending on the ``_id`` field of the document. The :method:`save() ` method is analogous to the :method:`update() ` method -with the ``upsert`` option and a ``query`` argument on the ``_id`` +with the ``upsert`` option and a ```` argument on the ``_id`` field. The :method:`save() ` method has the @@ -260,15 +270,15 @@ following syntax: Consider the following examples of the :method:`save() ` method: -- If the ``document`` argument contains the ``_id`` field that exists +- If the ```` argument contains the ``_id`` field that exists in the collection, the :method:`save() ` method performs an update that replaces the existing document with the - document argument. + ```` argument. The following operation queries the ``csbios`` collection for a document where the ``_id`` equals ``ObjectId("507c4e138fada716c89d0014")`` and replaces the document - with the ``document`` argument: + with the ```` argument: .. code-block:: javascript diff --git a/draft/core/documents.txt b/draft/core/documents.txt index 8082f0a31b6..fe8c8b61d8b 100644 --- a/draft/core/documents.txt +++ b/draft/core/documents.txt @@ -12,7 +12,7 @@ The document structure in MongoDB refer to the data structure of: - the :ref:`query selectors ` that determine which records to select for read, update, and delete operations -- the :ref:`update actions ` that specifies +- the :ref:`update actions ` that specify the particular field updates to perform during an update operation - the :ref:`index ` on a collection @@ -41,7 +41,7 @@ structure: } Having support for the full range of :term:`BSON types`, MongoDB -documents may contain ``field:value`` pairs where the value can be +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``. @@ -99,7 +99,8 @@ Document as query selectors Query selector documents may contain any or all of the following: -- Simple ``field:value`` pair(s) to specify the equality condition. +- Simple ``field`` and ``value`` pair(s) to specify the equality + condition. - :doc:`Query operator ` expressions to specify other conditions. @@ -191,7 +192,7 @@ When passed as an argument to the :method:`update() Document as index ----------------- -The index documents contain ``field:value`` pairs where: +The index documents contain ``field`` and ``value`` pairs where: - the ``field`` is the field to index on @@ -218,7 +219,7 @@ the index to create: Document as sort order ---------------------- -The sort order documents contain ``field:value`` pairs where: +The sort order documents contain ``field`` and ``value`` pairs where: - the ``field`` is the field to sort diff --git a/source/includes/fact-document-max-size.rst b/source/includes/fact-document-max-size.rst index 81730bb32d5..40fdea090a7 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 document size helps ensure that a single document cannot -use neither an excessive amount of RAM nor excessive amount of -bandwidth to transmit. To store larger objects, MongoDB provides the +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.