From 9a10f8549addca4725862b83ecc7103787d0499e Mon Sep 17 00:00:00 2001 From: kay Date: Wed, 3 Oct 2012 17:52:30 -0400 Subject: [PATCH] DOCS-64 document rename behavior when old name does not exist --- source/reference/command/findAndModify.txt | 155 +++++++++++----- .../method/db.collection.findAndModify.txt | 158 ++++++++++------ source/reference/operator/rename.txt | 171 +++++++++++++++++- 3 files changed, 378 insertions(+), 106 deletions(-) diff --git a/source/reference/command/findAndModify.txt b/source/reference/command/findAndModify.txt index 8547682f0c5..da8bd889c13 100644 --- a/source/reference/command/findAndModify.txt +++ b/source/reference/command/findAndModify.txt @@ -7,68 +7,133 @@ findAndModify .. dbcommand:: findAndModify The :dbcommand:`findAndModify` command atomically modifies and - returns a single document. The shell and many :term:`drivers - ` provide a :method:`findAndModify()` helper method. The - command has the following prototype form: + returns a single document. By default, the returned document does + not include the modifications made on the update. To return the + document with the modifications made on the update, use the ``new`` + option. + + The command has the following syntax: .. code-block:: javascript - { findAndModify: "collection", } + { findAndModify: , } + + The :dbcommand:`findAndModify` command takes the following are + sub-document ``options``: + + :field document query: + + Optional. Specifies the selection criteria for the + modification. The ``query`` field employs the same + :ref:`query selectors ` as used in the + :method:`db.collection.find()` method. Although the query may + match multiple documents, only one document will be selected + for the modification. + + The ``query`` field has the following syntax: + + .. code-block:: javascript + + query: { } + + :field document sort: + + Optional. Determines which document will be modified if the + query selects multiple documents. The first document as + determined by the ``sort`` will be the one modified. + + The ``sort`` field has the following syntax: + + .. code-block:: javascript + + sort: { field1: value1, field2: value2, ... } + + :field boolean remove: + + Optional if ``update`` field exists. When ``true``, removes + the selected document. The default is ``false``. + + The ``remove`` field has the following syntax: + + .. code-block:: javascript + + remove: - Replace, ``collection`` with the name of the collection - containing the document that you want to modify, and specify - options, as a sub-document that specifies the following: + :field document update: - :field query: A query object. This statement might resemble the - :term:`document` passed to :method:`db.collection.find()`, and - should return *one* document from the database. + Optional if ``remove`` field exists. Performs an update of + the selected document. The ``update`` field employs the same + :ref:`update operators ` or ``key:value`` + specifications to modify the selected document. - :field sort: Optional. If the query selects multiple documents, the - first document given by this sort clause will be the - one modified. + .. code-block:: javascript - :field remove: When ``true``, :dbcommand:`findAndModify` removes - the selected document. + update: { } - :field update: an :ref:`update operator ` to - modify the selected document. + :field boolean new: - :field new: when ``true``, returns the modified document rather - than the original. :dbcommand:`findAndModify` ignores - the ``new`` option for ``remove`` operations. + Optional. When ``true``, returns the modified document rather + than the original. The :dbcommand:`findAndModify` method + ignores the ``new`` option for ``remove`` operations. The + default is ``false``. - :field fields: a subset of fields to return. See ":ref:`projection - operators `" for more - information. + .. code-block:: javascript - :field upsert: when ``true``, creates a new document if the - specified ``query`` returns no documents. The - default is ``false``. The return value for these - operations is ``null`` in version 2.2 + new: - .. versionchanged:: 2.2 - Previously, ``upsert`` operations returned a an empty document - (e.g. ``{ }``,) see :ref:`the 2.2 release notes - <2.2-findandmodify-returns-null>` for more information. + :field document fields: + + Optional. A subset of fields to return. + + .. code-block:: javascript - For example: + fields: { field1: , field2: ... } + + :field boolean upsert: + + Optional. Used in conjunction with the ``update`` field. When + ``true``, the :dbcommand:`findAndModify` command creates a + new document if the ``query`` returns no documents. The + default is ``false``. In version 2.2, the + :dbcommand:`findAndModify` command returns ``null`` when + ``upsert`` is ``true``. + + .. code-block:: javascript + + upsert: + + .. versionchanged:: 2.2 + Previously, ``upsert`` operations returned a an empty + document (e.g. ``{ }``,) see :ref:`the 2.2 release notes + <2.2-findandmodify-returns-null>` for more information. + + Consider the following example: .. code-block:: javascript { findAndModify: "people", - { query: { name: "Tom", state: "active", rating: { $gt: 10 } }, - sort: { rating: 1 }, - update: { $inc: { score: 1 } } - } - } - - This operation, finds a document in the ``people`` collection - where the ``name`` field has the value ``Tom``, the - ``active`` value in the ``state`` field and a value in the - ``rating`` field :operator:`greater than <$gt>` 10. If there is - more than one result for this query, MongoDB sorts the results of - the query in descending order, and :operator:`increments <$inc>` - the value of the ``score`` field by 1. Using the shell helper, + query: { name: "Tom", state: "active", rating: { $gt: 10 } }, + sort: { rating: 1 }, + update: { $inc: { score: 1 } } + } + + This command performs the following actions: + + #. The ``query`` finds a document in the ``people`` collection where the + ``name`` field has the value ``Tom``, the ``state`` field has the + value ``active`` and the ``rating`` field has a value + :operator:`greater than <$gt>` 10. + + #. The ``sort`` orders the results of the query in ascending order. + + #. The update :operator:`increments <$inc>` the value of the + ``score`` field by 1. + + #. The command returns the original (pre-modification) document + selected for this update. + + The shell and many :term:`drivers ` provide a + :method:`findAndModify()` helper method. Using the shell helper, this same operation can take the following form: .. code-block:: javascript diff --git a/source/reference/method/db.collection.findAndModify.txt b/source/reference/method/db.collection.findAndModify.txt index e02266ebe81..ae5e1b83f5f 100644 --- a/source/reference/method/db.collection.findAndModify.txt +++ b/source/reference/method/db.collection.findAndModify.txt @@ -4,50 +4,98 @@ db.collection.findAndModify() .. default-domain:: mongodb -.. method:: db.collection.findAndModify() - - The :method:`db.collection.findAndModify()` method atomically modifies and - returns a single document. Always call :method:`db.collection.findAndModify()` - on a collection object, using the following form: - - .. code-block:: javascript - - db.collection.findAndModify(); - - Replace, ``collection`` with the name of the collection - containing the document that you want to modify, and specify - options, as a sub-document that specifies the following: - - :field document query: A query object. This statement might - resemble the :term:`document` passed to - :method:`db.collection.find()`, and should return *one* - document from the database. - - :field sort: Optional. If the query selects multiple documents, the - first document given by this sort clause will be the - one modified. - - :field remove: Optional. When ``true``, :dbcommand:`findAndModify` - removes the selected document. The default is - ``false`` - - :field update: An :ref:`update operator ` to - modify the selected document. - - :field new: Optional. When ``true``, returns the modified document - rather than the original. :dbcommand:`findAndModify` - ignores the ``new`` option for ``remove`` - operations. The default is ``false``. - - :field fields: Optional. A subset of fields to return. See - ":ref:`projection operators `" - for more information. - - :field upsert: Optional. When ``true``, :dbcommand:`findAndModify` - creates a new document if the specified ``query`` - returns no documents. The default is ``false``. - - For example: +.. method:: db.collection.findAndModify + + The :method:`db.collection.findAndModify()` method atomically + modifies and returns a single document. By default, the returned + document does not include the modifications made on the update. To + return the document with the modifications made on the update, use + the ``new`` option. + + The :method:`db.collection.findAndModify()` method takes a document + parameter with the following subdocument fields: + + :field document query: + + Optional. Specifies the selection criteria for the + modification. The ``query`` field employs the same + :ref:`query selectors ` as used in the + :method:`db.collection.find()` method. Although the query may + match multiple documents, only one document will be selected + for the modification. + + The ``query`` field has the following syntax: + + .. code-block:: javascript + + query: { } + + :field document sort: + + Optional. Determines which document will be modified if the + query selects multiple documents. The first document as + determined by the ``sort`` will be the one modified. + + The ``sort`` field has the following syntax: + + .. code-block:: javascript + + sort: { field1: value1, field2: value2, ... } + + :field boolean remove: + + Optional if ``update`` field exists. When ``true``, removes + the selected document. The default is ``false``. + + The ``remove`` field has the following syntax: + + .. code-block:: javascript + + remove: + + :field document update: + + Optional if ``remove`` field exists. Performs an update of + the selected document. The ``update`` field employs the same + :ref:`update operators ` or ``key:value`` + specifications to modify the selected document. + + .. code-block:: javascript + + update: { } + + :field boolean new: + + Optional. When ``true``, returns the modified document rather + than the original. The :dbcommand:`findAndModify` method + ignores the ``new`` option for ``remove`` operations. The + default is ``false``. + + .. code-block:: javascript + + new: + + :field document fields: + + Optional. A subset of fields to return. + + .. code-block:: javascript + + fields: { field1: , field2: ... } + + :field boolean upsert: + + Optional. Used in conjunction with the ``update`` field. When + ``true``, :dbcommand:`findAndModify` creates a new document + if the ``query`` returns no documents. The default is + ``false``. In version 2.2, the :dbcommand:`findAndModify` + command returns ``null`` when ``upsert`` is ``true``. + + .. code-block:: javascript + + upsert: + + Consider the following example: .. code-block:: javascript @@ -57,14 +105,20 @@ db.collection.findAndModify() update: { $inc: { score: 1 } } } ); - This operation finds a document in the ``people`` collection - where the ``name`` field has the value ``Tom``, the - ``active`` value in the ``state`` field and a value in the - ``rating`` field :operator:`greater than <$gt>` 10, and - :operator:`increments <$inc>` the value of the ``score`` field by - 1. If there is more than one result for this query, MongoDB sorts - the results of the query in ascending order, and updates and - returns the first matching document found. + This command performs the following actions: + + #. The ``query`` finds a document in the ``people`` collection where + the ``name`` field has the value ``Tom``, the ``state`` field has + the value ``active`` and the ``rating`` field has a value + : operator:`greater than <$gt>` 10. + + #. The ``sort`` orders the results of the query in ascending order. + + #. The update :operator:`increments <$inc>` the value of the + ``score`` field by 1. + + #. The command returns the original (pre-modification) document + selected for this update. .. warning:: diff --git a/source/reference/operator/rename.txt b/source/reference/operator/rename.txt index a57e65b87fe..52f337d41d3 100644 --- a/source/reference/operator/rename.txt +++ b/source/reference/operator/rename.txt @@ -6,19 +6,172 @@ $rename .. operator:: $rename - The :operator:`$rename` operator changes the name of a field. Consider the - following example: + *Syntax*: ``{$rename: { : , : , ... } }`` + + The :operator:`$rename` operator updates the name of a field. The + ``new name`` must differ from the ``old name``. + + Consider the following example: .. code-block:: javascript - db.collection.update( { field: value }, { $rename: { old_field: new_field } } ); + db.students.update( { _id: 1 }, { $rename: { 'nickname': 'alias', 'cell': 'mobile' } } ) - Here, the :operator:`$rename` operator changes the name of the ``old_field`` - field to ``new_field``, in the document that matches the query ``{ - field: value }`` in ``collection``. + The query renames the field ``nickname`` to the new name ``alias``, + and the field ``cell`` to ``mobile``. + If a field with the ``new name`` already exists in the document, the + :operator:`$rename` operator renames the field with the ``old name`` + to the ``new name`` and the field previously named ``old name`` no + longer exists. + The :operator:`$rename` operator will expand arrays and - sub-documents to find a match for field names (e.g. ``old_field`` - in the example above.) + sub-documents to find a match for field names. When renaming a field + in a sub-document to another sub-document or to a regular field, the + sub-document itself remains. + + Consider the following examples involving the sub-document of the + following document: + + .. code-block:: javascript + + { "_id": 1, + "alias": [ "The American Cincinnatus", "The American Fabius" ], + "mobile": "555-555-5555", + "nmae": { "first" : "george", "last" : "washington" } + } + + - To rename a sub-document, call the :operator:`$rename` operator + with the name of the sub-document as you would any other field: + + .. code-block:: javascript + + db.students.update( { _id: 1 }, { $rename: { "nmae": "name" } } ) + + The query renames the sub-document ``nmae`` to ``name``: + + .. code-block:: javascript + + { "_id": 1, + "alias": [ "The American Cincinnatus", "The American Fabius" ], + "mobile": "555-555-5555", + "name": { "first" : "george", "last" : "washington" } + } + + - To rename a field within a sub-document, call the + :operator:`$rename` operator using the :wiki:`dot notation + ` to refer to the field. + Include the name of the sub-document in the ``new name`` to ensure + the field remains in the sub-document: + + .. code-block:: javascript + + db.students.update( { _id: 1 }, { $rename: { "name.first": "name.fname" } } ) + + The query renames the sub-document field ``first`` to ``fname``: + + .. code-block:: javascript + + { "_id" : 1, + "alias" : [ "The American Cincinnatus", "The American Fabius" ], + "mobile" : "555-555-5555", + "name" : { "fname" : "george", "last" : "washington" } + } + + - To rename a field within a sub-document and move it to another + sub-document, call the :operator:`$rename` operator using the + :wiki:`dot notation ` to + refer to the field. Include the name of the new sub-document in + the ``new name``: + + .. code-block:: javascript + + db.students.update( { _id: 1 }, { $rename: { "name.last": "contact.lname" } } ) + + The query renames the sub-document field ``last`` to ``lname`` and + moves it to the sub-document ``contact``: + + .. code-block:: javascript + + { "_id" : 1, + "alias" : [ "The American Cincinnatus", "The American Fabius" ], + "contact" : { "lname" : "washington" }, + "mobile" : "555-555-5555", + "name" : { "fname" : "george" } + } + + If the ``new name`` does not include a sub-document name, the + field moves out of the subdocument and becomes a regular document + field. + + Consider the following behavior when the ``old name`` does not exist: + + - When renaming a single field and the ``old name`` refers to a + non-existing field, the :operator:`$rename` operator does nothing, + as in the following: + + .. code-block:: javascript + + db.students.update( { _id: 1 }, { $rename: { 'wife': 'spouse' } } ) + + The above query performs no action since the field with the name + ``wife`` does not exist. + + - When renaming multiple fields and **all** the ``old names`` refer to + non-existing fields, the :operator:`$rename` operator does + nothing, as in the following: + + .. code-block:: javascript + + db.students.update( { _id: 1 }, { $rename: { 'wife': 'spouse', 'vice': 'vp', 'office': 'term' } } ) + + The above query performs no action since fields with the name + ``wife``, ``vice``, and ``office`` do not exist. + + - When renaming multiple fields and **some** but not all ``old names`` + refer to non-existing fields, the :operator:`$rename` operator + performs the following operations: + + - Renames those existing fields to their respective ``new names``. + + - In version 2.2, ignores the non-existing fields. + + - In versions 2.0.3, 2.0.4, 2.0.7, **if** no field already exists + with the ``new names``, ignores the non-existing fields. + Otherwise, **if** fields already exist with the ``new names``, + drops these pre-existing fields. + + Consider the following query that renames both an existing field + ``mobile`` and a non-existing field ``wife``. The non-existing + field ``wife`` is being set to a name that already exists + ``alias``. + + .. code-block:: javascript + + db.students.update( { _id: 1 }, { $rename: { 'wife': 'alias', 'mobile': 'cell' } } ) - .. versionadded:: 1.7.2 + In version 2.2, the existing field ``mobile`` is renamed to + ``cell``. No other action occurs. + + .. code-block:: javascript + + { "_id" : 1, + "alias" : [ "The American Cincinnatus", "The American Fabius" ], + "cell" : "555-555-5555", + "name" : { "lname" : "washington" }, + "places" : { "d" : "Mt Vernon", "b" : "Colonial Beach" } + } + + In versions 2.0.3, 2.0.4, 2.0.7, the existing field ``mobile`` is + renamed to ``cell``. The field currently named ``alias`` is + dropped even though the field ``wife`` does not exist: + + .. code-block:: javascript + + { "_id" : 1, + "cell" : "555-555-5555", + "name" : { "lname" : "washington" }, + "places" : { "d" : "Mt Vernon", "b" : "Colonial Beach" } + } + + .. versionadded:: 1.7.2