From f5613178de240fb5f8cbd36d6ed2c23109a26dd8 Mon Sep 17 00:00:00 2001 From: kay Date: Fri, 12 Oct 2012 13:54:52 -0400 Subject: [PATCH] DOCS-468 CRUD drafts --- draft/applications/create.txt | 480 +++++++++++++++--- draft/applications/delete.txt | 69 ++- draft/applications/read.txt | 161 +++++- draft/applications/update.txt | 286 +++++++++-- source/includes/note-write-concerns.rst | 6 + .../reference/method/db.collection.find.txt | 15 +- .../reference/method/db.collection.update.txt | 7 +- 7 files changed, 876 insertions(+), 148 deletions(-) create mode 100644 source/includes/note-write-concerns.rst diff --git a/draft/applications/create.txt b/draft/applications/create.txt index adeafc77c08..abead2ecc26 100644 --- a/draft/applications/create.txt +++ b/draft/applications/create.txt @@ -5,82 +5,436 @@ Create .. default-domain:: mongodb Create operation adds new :term:`documents ` to a -:term:`collection`. MongoDB provides the :ref:`insert() ` -method to perform create operations. Additionally, the :ref:`update() -with upsert option ` method and the :ref:`save() -` method also provide functionality to create -documents. +:term:`collection`. MongoDB provides the following methods to perform +create operations: -All three methods exhibit the following behavior during the create -operation: +- :ref:`insert ` + +- :ref:`update with upsert ` + +- :ref:`save ` + +Additionally, the three methods exhibit the following behavior during +the create operation: - If the new document does not specify an :term:`_id` field, these - methods will add the ``_id`` field to the document and assign as - its value a unique :term:`objectid`. + methods add the ``_id`` field to the document and assign as + its value a unique :term:`ObjectId `. -- If the document specifies a new field, these methods will add - the document with the new field **without** requiring a schema change - to the collection or any change to the existing documents. +- If the new document specifies an ``_id`` field, the ``_id`` + field must be unique within the collection. -Keep in mind that MongoDB v2.2 has a limit on document size of 16 -megabytes (MB). +- If the new document specifies a new field not found in existing + documents, these methods add the document **without** requiring a + schema change to the collection or any change to the existing + documents. +MongoDB v2.2 has a 16 megabytes limit on document size. -.. _insert: +.. include:: /includes/note-write-concerns.rst -Insert() --------- +.. _crud-create-insert: + +Insert +------ The :method:`insert() ` method is the primary -method to insert a document or documents into a collection. The -:method:`insert() ` is analogous to the ``SQL -INSERT`` except the :method:`insert() ` method -provides these additional functionalities: +method to insert a document or documents into a collection. + +The :method:`insert() ` method has the +following syntax: + +.. code-block:: javascript + + db.collection.insert( ) + +The :method:`insert() ` method is analogous to +the ``SQL INSERT``. + +Consider the following examples that illustrate the usage of the +:method:`insert() ` method: - If the collection does not exist, then the :method:`insert() - ` method will create the collection. + ` method creates the collection during the + first insert. + + The following operation creates the collection ``presidents`` and + inserts the document: + + .. code-block:: javascript + + db.presidents.insert( { + _id: 1, + name: { first: 'George', last: 'Washington'}, + title: [ 'President', 'General' ], + born: new Date('02/22/1732'), + died: new Date('12/14/1799'), + state: 'Virginia', + email: [ { type: 'work', addr: 'george.no1@example.net' }, + { type: 'home', addr: 'geo.wash@example.net' } ], + spouse: 'Martha', + office: [ { term:1, from: 1789, to: 1793 }, + { term:2, from: 1793, to: 1797 } ] + } ) + + You can verify the results of this operation by querying the + ``presidents`` collection: + + .. code-block:: javascript -- If the new document does not specify an ``_id`` field, then - :method:`insert() ` will add the ``_id`` - field to the document and assign a unique ``objectid`` as its - value. + > db.presidents.find() + + { "_id": 1, + "name": { "first": "George", "last": "Washington" }, + "title": [ "President", "General" ], + "born": ISODate("1732-02-22T05:00:00Z"), + "died": ISODate("1799-12-14T05:00:00Z"), + "state": "Virginia", + "email": [ { "type": "work", "addr": "george.no1@example.net" }, + { "type": "home", "addr": "geo.wash@example.net" } ], + "spouse": "Martha", + "office": [ { "term": 1, "from": 1789, "to": 1793 }, + { "term": 2, "from": 1793, "to": 1797 } ] + } + +- If the new document does not contain an ``_id`` field, then the + :method:`insert() ` method adds the ``_id`` + field to the document and assigns a unique ``ObjectId`` as its value. -- If passed an array of documents, the :method:`insert() - ` method can perform bulk inserts into a + The following operation adds the ``_id`` field to the document, + assigns to the field a unique ``ObjectId``, and inserts the document + into the ``presidents`` collection: + + .. code-block:: javascript + + db.presidents.insert( { + name: { first: 'John', last: 'Adams'}, + title: [ 'President', 'Vice President', 'Ambassador' ], + born: new Date('10/30/1735'), + died: new Date('07/04/1826'), + state: 'Massachusetts', + email: [ { type: 'work', addr: 'john.no2@example.net' }, + { type: 'home', addr: 'adams.the.father@example.net' } ], + spouse: 'Abigail', + office: [ { term:1, from: 1797, to: 1801 } ] + } ) + + You can verify the addition of the ``_id`` field to the inserted + document by the querying the ``presidents`` collection: + + .. code-block:: javascript + + > db.presidents.find( { name: { first: 'John', last: 'Adams' } } ) + + { "_id": ObjectId("5076d64dbcf86cd7994f68e5"), + "name": { "first": "John", "last": "Adams" }, + "title": [ "President", "Vice President", "Ambassador" ], + "born": ISODate("1735-10-30T04:00:00Z"), + "died": ISODate("1826-07-04T04:00:00Z"), + "state": "Massachusetts", + "email": [ { "type": "work", "addr": "john.no2@example.net" }, + { "type": "home", "addr": "adams.the.father@example.net" } ], + "spouse": "Abigail", + "office": [ { "term": 1, "from": 1797, "to": 1801 } ] + } + +- If the argument to the :method:`insert() ` + method is an array of documents, then the :method:`insert() + ` method performs a bulk insert into a collection. -.. _update_and_save: - -Update() with Upsert Option and Save() --------------------------------------- - -Both the :method:`update() ` method and the -:method:`save() ` method will be discussed in -fuller detail in the Update section. But a quick introduction to their -insert capabilities is presented here for completeness. - -Update() with Upsert Option -```````````````````````````` - -The :method:`update() with upsert option ` or -an ``upsert`` will insert a single document into a collection if no -document exists that matches the update query criteria. The inserted -document will contain the fields and values of both the update query -criteria and the update operation. If the ``_id`` is not specified in -either the query criteria and the update operation documents, the -``upsert`` will add the ``_id`` field to the document and assign a -unique ``objectid`` as its value. - -The ``upsert`` removes the need to perform a separate query to -check for the existence of a record before performing either an insert -or an update. - -Save() -`````` - -The :method:`save() ` will insert a document into -a :term:`collection` if the document does not contain the ``_id`` field -or contains an ``_id`` field with a value not in the collection. If the -``_id`` is not specified in the document parameter, :method:`save() -` will add the ``_id`` field to the document -and assign a unique ``objectid`` as its value. + The following operation inserts three documents into the + ``presidents`` collection. The operation also illustrates the + *dynamic schema* characteristic of MongoDB. Although the document + with ``_id: 4`` contains a field ``works`` which does not appear in + the other documents, MongoDB does not require the other documents to + contain this field: + + .. code-block:: javascript + + db.presidents.insert( [ + { + _id: 3, + name: { first: 'Thomas', last: 'Jefferson'}, + title: [ 'President', 'Vice President', 'Ambassador' ], + born: new Date('04/13/1743'), + died: new Date('07/04/1826'), + state: 'Virginia', + email: [ { type: 'work', addr: 'thomas.no3@example.net' }, + { type: 'home', addr: 'tommy.j@example.net' } ], + spouse: 'Martha', + office: [ { term:1, from: 1801, to: 1805 }, + { term:2, from: 1805, to: 1809 } ] + }, + { + _id: 4, + name: { first: 'James', last: 'Madison'}, + title: [ 'President', 'Secretary of State' ], + born: new Date('03/16/1751'), + died: new Date('06/28/1836'), + state: 'Virginia', + works: [ 'Bill of Rights'], + email: [ { type: 'work', addr: 'james.no4@example.net' }, + { type: 'home', addr: 'constitution.man@example.net' } ], + spouse: 'Dolley', + office: [ { term:1, from: 1809, to: 1813 }, + { term:2, from: 1813, to: 1817 } ] + }, + { + _id: 5, + name: { first: 'James', last: 'Monroe'}, + title: [ 'President', 'Secretary of War', 'Secretary of State' ], + born: new Date('04/28/1758'), + died: new Date('07/04/1831'), + state: 'Virginia', + email: [ { type: 'work', addr: 'james.no5@example.net' }, + { type: 'home', addr: 'jm2@example.net' } ], + spouse: 'Elizabeth', + office: [ { term:1, from: 1817, to: 1821 }, + { term:2, from: 1821, to: 1825 } ] + } + ] ) + +.. _crud-create-update: + +Update with Upsert +------------------ + +The ``upsert``, or more specifically the :method:`update() +` method with the ``upsert`` option, inserts a +single document into a collection if no document exists that matches +the ``query`` argument. The ``upsert`` eliminates the need to perform a +separate database call to check for the existence of a record before +performing either an insert or an update. + +An ``upsert`` has the following syntax: + +.. code-block:: javascript + + db.collection.update( , + , + { upsert: true } ) + +Consider the following examples that illustrate the usage of the +``upsert`` to perform create operations: + +- If the ``update`` argument contains only ``field:value`` pairs and no + document matches the ``query`` argument, the ``upsert`` operation + inserts a new document containing the fields and values in the + ``update`` argument and the ``_id`` field if not found in the + ``update`` argument. + + The following operation inserts a new document into the + ``presidents`` collection since there is no document matching the + ``name`` field as specified in the ``query`` argument. Since the + ``update`` argument contains only ``field:value`` pairs, the new + document contains only these fields and values: + + .. code-block:: javascript + + db.presidents.update( + { name: { first: 'John', middle: 'Quincy', last: 'Adams'} }, + { + _id: 6, + name: { first: 'John', middle: 'Quincy', last: 'Adams'}, + title: [ 'President', 'U.S. Representative' ], + born: new Date('07/11/1767'), + died: new Date('02/23/1848'), + state: 'Massachusetts', + email: [ { type: 'work', addr: 'james.no6@example.net' }, + { type: 'home', addr: 'adams.the.son@example.net' } ], + spouse: 'Louisa', + office: [ { term:1, from: 1825, to: 1829 } ] + }, + { upsert: true } + ) + +- If the ``update`` argument includes only :ref:`update operators + `, the ``upsert`` operation inserts a new document + containing the fields and values in the ``update`` argument and the + fields and values in the ``query`` argument. + + The following operation inserts a new document into the + ``presidents`` collection since there is no document matching the + ``_id`` field and the ``name`` field as specified in the ``query`` + argument. Since the ``update`` argument contains only :ref:`update + operators `, the inserted document contains fields + and values from both the ``query`` and the ``update`` arguments. + + .. code-block:: javascript + + db.presidents.update( + { _id: 7, name: { first: 'Andrew', last: 'Jackson'} }, + { + $set: { + title: [ 'President', 'General', 'Old Hickory' ], + born: new Date('03/15/1767'), + died: new Date('06/08/1845'), + state: 'Carolinas', + email: [ { type: 'work', addr: 'andrew.7@example.net' }, + { type: 'home', addr: 'old.hickory@example.net' } ], + spouse: 'Rachel', + office: [ { term:1, from: 1829, to: 1833 }, + { term:2, from: 1833, to: 1837 } ] + } + }, + { upsert: true } + ) + + You can verify that the inserted document contains the ``_id`` and + the ``name`` fields from the ``query`` argument as well as the fields + and values from the ``update`` argument by querying the + ``presidents`` collection: + + .. code-block:: javascript + + > db.presidents.find( { _id: 7 } ) + + { "_id": 7, + "born": ISODate("1767-03-15T05:00:00Z"), + "died": ISODate("1845-06-08T04:00:00Z"), + "email": [ { "type": "work", "addr": "andrew.7@example.net" }, + { "type": "home", "addr": "old.hickory@example.net" } ], + "name": { "first": "Andrew", "last": "Jackson" }, + "office": [ { "term": 1, "from": 1829, "to": 1833 }, + { "term": 2, "from": 1833, "to": 1837 } ], + "spouse": "Rachel", + "state": "Carolinas", + "title": [ "President", "General", "Old Hickory" ] + } + +- If the ``_id`` is not specified in either the ``query`` argument and + the ``update`` argument, the ``upsert`` operation adds the ``_id`` + field to the document and assigns a unique ``ObjectId`` as its value. + + The following operation inserts a new document into the + ``presidents`` collection since there is no document matching the + ``name`` field as specified in the ``query`` argument. Because the + ``update`` argument does not contain the ``_id`` field, the + ``upsert`` operation adds the ``_id`` field to the document and + assigns to the field a unique ``ObjectId``: + + .. code-block:: javascript + + db.presidents.update( + { name: { first: 'Martin', last: 'Van Buren'} }, + { + name: { first: 'Martin', last: 'Van Buren' }, + title: [ 'President', 'Vice President', 'Secretary of State' ], + born: new Date('12/05/1782'), + died: new Date('07/24/1862'), + state: 'New York', + email: [ { type: 'work', addr: 'martin.8@example.net' }, + { type: 'home', addr: 'free.soil@example.net' } ], + spouse: 'Hannah', + office: [ { term:1, from: 1837, to: 1841 } ] + }, + { upsert: true } + ) + + You can verify the addition of the ``_id`` field to the inserted + document by the querying the ``presidents`` collection: + + .. code-block:: javascript + + > db.presidents.find( { name: { first: 'Martin', last: 'Van Buren' } } ) + + { "_id": ObjectId("5076d6e28fada716c89d000f"), + "name": { "first": "Martin", "last": "Van Buren" }, + "title": [ "President", "Vice President", "Secretary of State" ], + "born": ISODate("1782-12-05T05:00:00Z"), + "died": ISODate("1862-07-24T04:00:00Z"), + "state": "New York", + "email": [ { "type": "work", "addr": "martin.8@example.net" }, + { "type": "home", "addr": "free.soil@example.net" } ], + "spouse": "Hannah", + "office": [ { "term": 1, "from": 1837, "to": 1841 } ] + } + +.. _crud-create-save: + +Save +---- + +The :method:`save() ` method inserts a document +into a collection if the document does not contain the ``_id`` field or +contains an ``_id`` field with a value not in the collection. If the +document does not contain the ``_id`` field, the :method:`save() +` method adds the ``_id`` field to the document +and assigns a unique ``ObjectId`` as its value. + +The :method:`save() ` method has the +following syntax: + +.. code-block:: javascript + + db.collection.save( ) + +Consider the following examples that illustrate the usage of the +:method:`insert() ` method for create +operations: + +- If the ``document`` does not contain the ``_id`` field, the + :method:`save() ` method adds the ``_id`` field + to the document and performs an insert. + + The following operation performs an insert into the ``presidents`` + collection since the document does not contain the ``_id`` field: + + .. code-block:: javascript + + db.presidents.save( { + name: { first: 'William', middle: 'Henry',last: 'Harrison' }, + title: [ 'President' ], + born: new Date('02/09/1773'), + died: new Date('04/04/1841'), + state: 'Virginia', + email: [ { type: 'work', addr: 'william.9@example.net' }, + { type: 'home', addr: 'tippecanoe@example.net' } ], + spouse: 'Anna', + office: [ { term:1, from: 1841, to: 1841 } ] + } ) + + You can verify the addition of the ``_id`` field during the operation + by querying the ``presidents`` collection: + + .. code-block:: javascript + + > db.presidents.find ( { 'name.first': 'William', 'name.last': 'Harrison' } ) + + { "_id": ObjectId("5076d6febcf86cd7994f68e6"), + "name": { "first": "William", "middle": "Henry", "last": "Harrison" }, + "title": [ "President" ], + "born": ISODate("1773-02-09T05:00:00Z"), + "died": ISODate("1841-04-04T05:00:00Z"), + "state": "Virginia", + "email": [ { "type": "work", "addr": "william.9@example.net" }, + { "type": "home", "addr": "tippecanoe@example.net" } ], + "spouse": "Anna", + "office": [ { "term": 1, "from": 1841, "to": 1841 } ] + } + +- If the ``document`` contains an ``_id`` field but has a value not + found in the collection, the :method:`save() ` + method performs an insert. + + The following operation performs an insert into the ``presidents`` + collection since the document contains an ``_id`` field whose value + ``10`` is not found in the ``presidents`` collection: + + .. code-block:: javascript + + db.presidents.save( { + _id: 10, + name: { first: 'John', last: 'Tyler' }, + title: [ 'President', 'Vice President' ], + born: new Date('03/29/1790'), + died: new Date('01/18/1862'), + state: 'Virginia', + email: [ { type: 'work', addr: 'john.10@example.net' }, + { type: 'home', addr: 'remember.me@example.net' } ], + spouse: [ 'Letitia', 'Julia' ], + office: [ { term:1, from: 1841, to: 1845 } ] + } ) + + \ No newline at end of file diff --git a/draft/applications/delete.txt b/draft/applications/delete.txt index 8184c05dafb..1845a249690 100644 --- a/draft/applications/delete.txt +++ b/draft/applications/delete.txt @@ -5,20 +5,67 @@ Delete .. default-domain:: mongodb Delete operation removes documents from a :term:`collection`. MongoDB -provides the :ref:`remove() ` method to perform delete operations. +provides the :ref:`remove() ` method to perform +delete operations. -.. _remove: +.. include:: /includes/note-write-concerns.rst -Remove() --------- +.. _crud-delete-remove: + +Remove +------ The :method:`remove() ` method is the method to -delete documents from a collection. By default, the :method:`remove() -` deletes all documents that meet the delete -selection criteria. However, using the ``justOne`` option limits the -deletion to just one document. +delete documents from a collection. The :method:`remove() +` method does not delete indexes. + +The :method:`remove() ` method has the +following syntax: + +.. code-block:: javascript + + db.collection.delete( , ) + +The :method:`remove() ` method is analogous to the +``SQL DELETE`` with the ``query`` argument analogous to the ``WHERE`` +statement and the ``justOne`` argument analogous to the ``LIMIT 1``. + +Consider the following examples that illustrate the usage of the +:method:`remove() ` method: + +- If there is a ``query`` argument, the :method:`remove() + ` method deletes from the collection all + documents that match the ``query``. + + The following operation deletes all documents from the ``presidents`` + collection where the ``title`` field contained the element + ``Governor``: + + .. code-block:: javascript + + db.presidents.remove( { title: 'Governor' } ) + +- If there is a ``query`` argument and there is a ``justOne`` argument, + the :method:`remove() ` method deletes from + the collection a single documents that match the ``query``. + + The following operation deletes a single documents from the + ``presidents`` collection where the ``state`` field equals + ``Virginia``: + + .. code-block:: javascript + + db.presidents.remove( { state: 'Virginia' }, 1 ) -Note that calling :method:`remove() ` without -specifying the delete selection criteria removes all documents in the -collection. +- If there is no ``query`` argument, the :method:`remove() + ` method deletes all documents from a + collection. The method does not remove the indexes on the collection + nor does it :method:`drop` the collection. + + The following operation deletes all documents from the ``presidents`` + collection: + .. code-block:: javascript + + db.presidents.remove() + \ No newline at end of file diff --git a/draft/applications/read.txt b/draft/applications/read.txt index 4196aca6dcc..87def4706ce 100644 --- a/draft/applications/read.txt +++ b/draft/applications/read.txt @@ -4,42 +4,147 @@ Read .. default-domain:: mongodb -Read operation selects documents from a collection. MongoDB -provides the :ref:`find() ` method to perform read operations. -Additionally, the :ref:`Aggregation Framework ` also -provides read operations that involve various aggregation functions, -such as ``SUM``. +Read operation selects documents from a :term:`collection`. MongoDB +provides the :ref:`find ` method to perform read +operations. -.. _find: +.. _crud-read-find: -Find() ------- +Find +---- The :method:`find() ` method is the primary -method to select documents from a collection. The find() method returns -a cursor to the selected documents. The :method:`find() -` method can accept a selection criteria on -document fields, including array fields and subdocuments, to limit the -selection. +method to select documents from a collection. The :method:`find() +` method returns a cursor to the selected +documents. Use the cursor handling methods of the language drivers to +iterate through the cursor and access the documents. -The :method:`find() ` method offers the -flexibility to specify the fields to return through the include/exclude -flags of the ``projection`` document. For instance, if selecting 11 out -of 15 fields, with the :method:`find() ` method, you -can choose to specify the 4 to exclude rather than the 11 to include. +The :method:`find() ` method has the following +syntax: -.. TODO -- sort/limit/other options... +.. code-block:: javascript -.. _aggregation: + db.collection.find( , ) -Aggregation Framework ---------------------- +The :method:`find() ` method is analogous to the +``SQL SELECT`` with the ``query`` argument analogous to the ``WHERE`` +statement and the ``projection`` argument analogous to the selected +fields to return. -The Aggregation Framework provides a rich set of tools for performing -various sequence of operations, not the least of which is the read operation. +Consider the following examples that illustrate the usage of the +:method:`find() ` method: -Although the Aggregation Framework is discussed in detail in its own -section, a brief introduction to the aggregation read operation is -provided here for completeness. +.. note:: -.. seealso:: :doc:`/applications/aggregation` + In the :program:`mongo` shell, you can format the output by adding + ``.pretty()`` to the :method:`find() ` method + call. + +- If there is no ``query`` argument, the :method:`find() + ` method selects all documents from a collection. + + The following operation returns all documents (or more + specifically, a cursor to all documents) in the ``presidents`` + collection: + + .. code-block:: javascript + + db.presidents.find() + +- If there is a ``query`` argument, the :method:`find() + ` method selects all documents from a + collection that meets the ``query``: + + - The following operation returns all documents in the ``presidents`` + collection where the field ``state`` equals ``Virginia``: + + .. code-block:: javascript + + db.presidents.find( { state: 'Virginia' } ) + + - The following operation returns all documents in the ``presidents`` + collection where the array field ``title`` contains the element + ``Governor``: + + .. code-block:: javascript + + db.presidents.find( { title: 'Governor' } ) + + - The following operation returns all documents in the ``presidents`` + collection where the subdocument ``name`` contains a field + ``first`` with value ``John`` and a field ``last`` with the value + ``Adams``: + + .. code-block:: javascript + + db.presidents.find( { 'name.first': 'John', 'name.last': 'Adams' } ) + + The operation finds documents with ``name : { first: 'John', last: + 'Adams' }`` and ``name : { first: 'John', middle : 'Quincy', last : + 'Adams'}``. + + - The following operation returns all documents in the ``presidents`` + collection where the subdocument ``name`` is ``{ first: + 'John', last: 'Adams' }``: + + .. code-block:: javascript + + db.presidents.find( { name: { first: 'John', last: 'Adams' } } ) + + The operation finds only the documents with ``name : { first: + 'John', last: 'Adams' }``. + + - The following operation returns all documents in the ``presidents`` + collection where the subdocument ``name`` contains the field + ``first`` with the value of either ``John`` or ``James``: + + .. code-block:: javascript + + db.presidents.find( { 'name.first': { $in: ['John', 'James'] } } ) + + - The following operation returns all documents in the ``presidents`` + collection where the field ``state`` equals ``Virginia`` **and** + the subdocument ``name`` contains the field ``first`` with the + value of either ``John`` or ``James``: + + .. code-block:: javascript + + db.presidents.find( { + state: 'Virginia' , + 'name.first': { $in: ['John', 'James'] } + } ) + + - The following operation returns all documents in the ``presidents`` + collection where ``office`` array contains a subdocument element + that contains the ``term`` field equal to ``1`` and the ``from`` + field less than ``1800``: + + .. code-block:: javascript + + db.presidents.find( { office: { $elemMatch: { + term: 1, + from: { $lt: 1800 } + } } } ) + +- If there is a ``projection`` argument, the :method:`find() + ` method returns only those fields as specified + in the ``projection`` argument to include or exclude (the ``_id`` + field is implicitly included in the ``projection`` argument): + + - The following operation returns only the ``name`` field, the + ``state`` field, and the ``_id`` field from all documents in the + ``presidents`` collection: + + .. code-block:: javascript + + db.presidents.find( { }, { name: 1, state: 1 } ) + + - The following operation returns all fields *except* the ``_id`` + field, the ``first`` field in the ``name`` subdocument, and the + ``office`` field from the documents in the + ``presidents`` collection where the ``state`` is ``Virginia``: + + .. code-block:: javascript + + db.presidents.find( { state: 'Virginia' }, + { _id: 0, 'name.first': 0, office: 0 } ) diff --git a/draft/applications/update.txt b/draft/applications/update.txt index f7b227f687c..92f868507c9 100644 --- a/draft/applications/update.txt +++ b/draft/applications/update.txt @@ -5,63 +5,269 @@ Update .. default-domain:: mongodb Update operation modifies an existing :term:`document ` or -documents in a :term:`collection`. MongoDB provides the :ref:`update() -` method to perform update operations. -Additionally, the :ref:`save() ` method also provides the -functionality to update documents. +documents in a :term:`collection`. MongoDB provides the following +methods to perform update operations: -Note that the two methods also provide the option to insert a new -document into a collection. +- :ref:`update ` -.. TODO ? findAndModify? +- :ref:`save ` -.. _update: +.. include:: /includes/note-write-concerns.rst + +.. _crud-update-update: Update ------ The :method:`update() ` method is the primary -method to update an existing document or documents in a collection. The +method to update an existing document or documents in a collection. By +default the :method:`update() ` method updates +a single document, but by using the ``multi`` option, the method can +update all documents that match the ``query`` criteria. The :method:`update() ` method can either replace the existing document with the new document or update specific fields in the existing document. -By default the :method:`update() ` method -updates a single document, but by using the ``multi`` option, the -method can update all documents that match the update selection -criteria. +The :method:`update() ` method has the +following syntax: + +.. code-block:: javascript + + db.collection.update( , , ) + +The :method:`update() ` method is analogous to +the ``SQL UPDATE`` with the ``query`` argument analogous to the +``WHERE`` statement and the ``update`` argument analogous to the ``SET +...`` statement; however, the :method:`update() +` method provides additional flexibility and +control in use. + +Consider the following examples that illustrate the usage of the +:method:`update() ` method: + +- If the ``update`` argument contains only :ref:`update operators + ` expressions such as the :operator:`$set` operator + expression, the :method:`update() ` method + updates only the corresponding fields in the document. + + The following operation queries the ``presidents`` collection for the + first document that has an ``_id`` field equal to ``1`` and sets the + ``spouse`` field to ``Martha Dandridge Custis`` and adds a new + element to the ``email`` field: + + .. code-block:: javascript + + db.presidents.update( { _id: 1 }, + { $set: { spouse: 'Martha Dandridge Custis' }, + $push: { email: { type: 'personal', + addr: 'i.m.number.1@example.net' } } + } ) + +- If the ``update`` argument contains :operator:`$unset` operator, the + :method:`update() ` method removes the field + from the document. + + The following operation queries the ``presidents`` collection for the + first document that has an ``_id`` field equal to ``3`` and removes + the ``spouse`` field from the document: + + .. code-block:: javascript + + db.presidents.update( { _id: 3 }, + { $unset: { spouse: 1 } } ) + +- If the ``update`` argument contains fields not currently in the + document, the :method:`update() ` method + adds the new fields to the document. + + The following operation queries the ``presidents`` collection for the + first document that has an ``_id`` field equal to ``1`` and adds to + the document a new ``vp`` field set to value ``John Adams``: + + .. code-block:: javascript + + db.presidents.update( { _id: 1 }, + { $set: { vp: 'John Adams' } } ) + +- If the ``update`` argument contains only ``field:value`` pairs, the + :method:`update() ` method *replaces* the + existing document with the ``updates`` argument except for the + ``_id`` field. + + The following operation queries the ``presidents`` collection for the + first document that has a ``name`` field equal to ``{ first: 'John', + last: 'Adams' }`` and replaces all but the ``_id`` field in the + document with the fields in the ``update`` argument: + + .. code-block:: javascript + + db.presidents.update( { name: { first: 'John', last: 'Adams' } }, + { name: { first: 'John', last: 'Adams' }, + email: [ { type: 'work', addr: 'prez.no2@example.net' }, + { type: 'home', addr: 'adams.family@example.net' } ], + spouse: 'Abigail Smith', + office: [ { term: 1, from: 1797, to: 1801 } ] + } ) + +- If the update operation requires an update of an element in an array + field: + + - The :method:`update() ` method can perform + the update using the position of the element. Arrays in MongoDB are + zero-based. + + The following operation queries the ``presidents`` collection for + the document with ``_id`` field equal to ``6`` and updates the + second element in the ``title`` array: + + .. code-block:: javascript + + db.presidents.update ( { _id: 6 } , + { $set: { 'title.1': "Secretary of State" } } ) + + - The :method:`update() ` method can perform + the update using the :operator:`$` positional operator if the + position is not known. The array field must appear in the ``query`` + argument in order to determine which array element. + + The following operation queries the ``presidents`` collection for a + document with the ``_id`` field equal to ``6`` and the ``title`` + array contains an element equal to ``Secretary of State``. If + found, the :method:`update() ` method + updates the matching element to ``Senator`` in the document: -Additionally, if no existing document match the update selection -criteria, by using the ``upsert`` option, the method can insert -a new document into the collection. + .. code-block:: javascript -Note also that the :method:`update() ` method -can also modify the name of the ``field`` in a document using the -:operator:`$rename` operator. + db.presidents.update ( { _id: 6, 'title': "Secretary of State" } , + { $set: { 'title.$': "Senator" } } ) + + - The :method:`update() ` method can perform + the update of an array that contains subdocuments by using the + :operator:`$` positional operator and the :wiki:`dot notation + `. + + The following operation queries the ``presidents`` collection for a + document with the ``_id`` field equal to ``6`` and the ``email`` + array contains a subdocument element with the ``type`` field equal + to ``home``. If found, the :method:`update() + ` method updates the ``addr`` field in the + first matching subdocument: - .. _save: + .. code-block:: javascript + + db.presidents.update ( { _id: 6, 'email.type': "home" } , + { $set: { 'email.$.addr': "jqa@example.net" } } ) + +- If the ``options`` argument contains the ``multi`` option set to + ``true`` or ``1``, the :method:`update() ` + method updates all documents that match the query. + + The following operation queries the ``presidents`` collection for all + documents where the subdocument ``name`` contains a field ``first`` + with value ``John`` and a field ``last`` with the value ``Adams`` and + sets the ``dynasty`` field to ``true`` in the documents: + + .. code-block:: javascript + + db.presidents.update( { 'name.first': 'John', 'name.last': 'Adams' }, + { $set: { dynasty: true } }, + { multi: true } ) + +- If the ``options`` argument contains the ``upsert`` option set to + ``true`` or ``1`` and no existing document match the ``query`` + argument, the :method:`update() ` method can + insert a new document into the collection: + + The following operation queries the ``presidents`` collection for a + document with the ``_id`` field equal to ``6``. If a document is + found, the operation performs an update operation, replacing the + existing document with the fields and values in the ``update`` + argument. If a document is not found, the operation performs an + insert operation of a new document with the fields and values in the + ``update`` argument. + + .. code-block::javascript + + db.presidents.update( { _id: 11 }, + { _id: 11, + name: { first: 'James', middle: 'Knox', last: 'Polk'}, + title: [ 'President', 'Speaker of the House', 'Governor' ], + born: new Date('11/02/1795'), + died: new Date('06/15/1849'), + state: 'North Carolina', + email: [ { type: 'work', addr: 'james.no11@example.net' }, + { type: 'home', addr: 'coast.to.coast@example.net' } ], + spouse: 'Sarah Childress', + office: [ { term:1, from: 1845, to: 1849 } ] }, + { upsert: true } ) + + See also :ref:`Create `. + + .. _crud-update-save: Save ---- The :method:`save() ` method updates an existing -document or inserts a document depending on the parameter. The -:method:`save() ` method is like an ``upsert`` -operation that has the update selection criteria on the :term:`_id` -field: - -- If no ``_id`` field exists, the :method:`save() - ` method performs an insert. The insert will - add the ``_id`` field and assign a unique :term:`objectid` as its - value. - -- If ``_id`` field exists but does not match any document in the - collection, the :method:`save() ` method - performs an insert. The insert will add the ``_id`` field and assign - a unique :term:`objectid` as its value. - -- If ``_id`` field exists and matches an existing document in the - collection, the :method:`save() ` method - performs an update that replaces the existing document with the new - document. - +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`` +field. + +The :method:`save() ` method has the +following syntax: + +.. code-block:: javascript + + db.collection.save( ) + +Consider the following examples of the :method:`save() +` method: + +- If the ``document`` 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. + + The following operation queries the ``presidents`` collection for a + document where the ``_id`` equals + ``ObjectId("5076d6e28fada716c89d000f")`` and replaces the document + with the ``document`` argument: + + .. code-block:: javascript + + db.presidents.save( { _id: ObjectId("5076d6e28fada716c89d000f"), + name: { first: 'Martin', last: 'Van Buren' }, + title: [ 'President', 'Governor'], + born: new Date('12/05/1782'), + died: new Date('07/24/1862'), + bplace: 'Kinderhook, New York', + email: [ { type: 'work', addr: 'martin.8@example.net' }, + { type: 'home', addr: 'free.soil@example.net' } ], + vp: 'Richard Johnson', + office: [ { term:1, from: 1837, to: 1841 } ] } ) + +- If no ``_id`` field exists or if the ``_id`` field exists but does + not match any document in the collection, the :method:`save() + ` method performs an insert. If no ``_id`` + field exists, the insert will add the ``_id`` field and assign a + unique :term:`objectid` as its value. + + The following operation adds the ``_id`` field to the document, + assigns to the field a unique ``ObjectId``, and inserts into the + ``presidents`` collection: + + .. code-block:: javascript + + db.presidents.save( { name: { first: 'Zachary', last: 'Taylor' }, + title: [ 'President', 'Governor'], + born: new Date('11/24/1784'), + died: new Date('07/09/1850'), + state: 'Virginia', + email: [ { type: 'work', addr: 'zachary.12@example.net' }, + { type: 'home', addr: 'old.rough.ready@example.net' } ], + vp: 'Millard Fillmore', + office: [ { term:1, from: 1849, to: 1850 } ] } ) + + See also :ref:`Create `. diff --git a/source/includes/note-write-concerns.rst b/source/includes/note-write-concerns.rst new file mode 100644 index 00000000000..20f3d1c3275 --- /dev/null +++ b/source/includes/note-write-concerns.rst @@ -0,0 +1,6 @@ +.. note:: + + All write operations in MongoDB by default are unsafe or + *fire-and-forget*. See the documentation of :ref:`write concern + ` and :doc:`/applications/write-operations` for more + information. \ No newline at end of file diff --git a/source/reference/method/db.collection.find.txt b/source/reference/method/db.collection.find.txt index 0cbba9b07d7..37282f6df1b 100644 --- a/source/reference/method/db.collection.find.txt +++ b/source/reference/method/db.collection.find.txt @@ -6,9 +6,9 @@ db.collection.find() .. method:: db.collection.find(query,projection) - The :method:`find() ` method selects - documents in a collection and returns a - :term:`cursor` to the selected documents. + The :method:`find() ` method selects documents + in a collection and returns a :term:`cursor` to the selected + documents. The :method:`find() ` method takes the following parameters. @@ -48,6 +48,15 @@ db.collection.find() A :term:`cursor` to the documents that match the ``query`` criteria and contain the ``projection`` fields. + .. note:: + + In the :program:`mongo` shell, you can access the returned + documents directly without explicitly using the JavaScript cursor + handling method. Executing the query directly on the + :program:`mongo` shell prompt automatically iterates the cursor + to display up to the first 20 documents. Type ``it`` to continue + iteration. + .. examples-begin Consider the following examples of the :method:`find() diff --git a/source/reference/method/db.collection.update.txt b/source/reference/method/db.collection.update.txt index e7227da0675..034917a97b3 100644 --- a/source/reference/method/db.collection.update.txt +++ b/source/reference/method/db.collection.update.txt @@ -75,12 +75,13 @@ db.collection.update() Optional. Specifies an :term:`upsert` operation - The default value is ``false``. When - ``true``, the :method:`update() ` method will + The default value is ``false``. When ``true``, the + :method:`update() ` method will update an existing document that matches the ``query`` selection criteria **or** if no document matches the criteria, insert a new document with the fields and values of - the ``query`` and ``update`` arguments. + the ``update`` parameter and if the ``update`` included only + ``update operators``, the ``query`` parameter as well . In version 2.2 of the :program:`mongo` shell, you may also specify ``upsert`` in the ``options`` parameter.