diff --git a/draft/applications/create.txt b/draft/applications/create.txt index 1d779e55a3b..e561a288a62 100644 --- a/draft/applications/create.txt +++ b/draft/applications/create.txt @@ -19,9 +19,9 @@ following basic operations. - :ref:`insert ` -- :ref:`update with upsert ` +- :ref:`create with save ` -- :ref:`save ` +- :ref:`create with upsert ` All insert operations in MongoDB exhibit the following properties: @@ -41,7 +41,7 @@ All insert operations in MongoDB exhibit the following properties: .. note:: - .. include:: /includes/fact-write-concerns.rst +.. .. include:: /includes/fact-write-concerns.rst .. _crud-create-insert: @@ -64,124 +64,154 @@ the following syntax: Consider the following examples that illustrate the behavior of :method:`insert() `: -- If the collection does not exist, then the :method:`insert() - ` method creates the collection during the - first insert. Specifically in the example, if the collection - ``csbios`` does not exist, then the insert operation will create this - collection: +- If the collection does not exist [#show-collection]_, then the + :method:`insert() ` method creates the + collection during the first insert. Specifically in the example, if + the collection ``bios`` does not exist , then the insert operation + will create this collection: .. code-block:: javascript - db.csbios.insert( { - _id: 1, - name: { first: 'John', last: 'Backus' }, - birth: new Date('Dec 03, 1924'), - death: new Date('Mar 17, 2007'), - contribs: [ 'Fortran', 'ALGOL', 'Backus-Naur Form', 'FP' ], - awards: [ - { award: 'W.W. McDowell Award', - year: '1967', - by: 'IEEE Computer Society' }, - { award: 'National Medal of Science', - year: '1975', - by: 'National Science Foundation' }, - { award: 'Turing Award', - year: '1977', - by: 'ACM' }, - { award: 'Draper Prize', - year: '1993', - by: 'National Academy of Engineering' } - ] - } ) - - You can confirm the insert [#show-collection]_ by :doc:`querying - ` the ``csbios`` collection: + db.bios.insert( + { + _id: 1, + name: { first: 'John', last: 'Backus' }, + birth: new Date('Dec 03, 1924'), + death: new Date('Mar 17, 2007'), + contribs: [ 'Fortran', 'ALGOL', 'Backus-Naur Form', 'FP' ], + awards: [ + { + award: 'W.W. McDowell Award', + year: 1967, + by: 'IEEE Computer Society' + }, + { + award: 'National Medal of Science', + year: 1975, + by: 'National Science Foundation' + }, + { + award: 'Turing Award', + year: 1977, + by: 'ACM' + }, + { + award: 'Draper Prize', + year: 1993, + by: 'National Academy of Engineering' + } + ] + } + ) + + You can confirm the insert by :doc:`querying ` + the ``bios`` collection: .. code-block:: javascript - db.csbios.find() + db.bios.find() - This operation returns the following document from the ``csbios`` + This operation returns the following document from the ``bios`` collection: .. code-block:: javascript { "_id" : 1, - "name" : { "first" : "John", "last" :"Backus" }, + "name" : { "first" : "John", "last" : "Backus" }, "birth" : ISODate("1924-12-03T05:00:00Z"), "death" : ISODate("2007-03-17T04:00:00Z"), "contribs" : [ "Fortran", "ALGOL", "Backus-Naur Form", "FP" ], "awards" : [ - { "award" : "W.W. McDowellAward", - "year" : "1967", - "by" : "IEEE Computer Society" }, - { "award" : "National Medal of Science", - "year" : "1975", - "by" : "National Science Foundation" }, - { "award" : "Turing Award", - "year" : "1977", - "by" : "ACM" }, - { "award" : "Draper Prize", - "year" : "1993", - "by" : "National Academy of Engineering" } - ] - } + { + "award" : "W.W. McDowell Award", + "year" : 1967, + "by" : "IEEE Computer Society" + }, + { + "award" : "National Medal of Science", + "year" : 1975, + "by" : "National Science Foundation" + }, + { + "award" : "Turing Award", + "year" : 1977, + "by" : "ACM" + }, + { "award" : "Draper Prize", + "year" : 1993, + "by" : "National Academy of Engineering" + } + ] + } - - If the new document does not contain an ``_id`` field, then the +- If the new document does not contain an ``_id`` field, then the :method:`insert() ` method adds the ``_id`` field to the document and generates a unique ``ObjectId`` for the value. .. code-block:: javascript - db.csbios.insert( { - name: { first: 'John', last: 'McCarthy' }, - birth: new Date('Sep 04, 1927'), - death: new Date('Dec 24, 2011'), - contribs: [ 'Lisp', 'Artificial Intelligence', 'ALGOL' ], - awards: [ - { award: 'Turing Award', - year: '1971', - by: 'ACM' }, - { award: 'Kyoto Prize', - year: '1988', - by: 'Inamori Foundation'}, - { award: 'National Medal of Science', - year: '1990', - by: 'National Science Foundation' } - ] - - } ) - - You can verify the inserted document by the querying the ``csbios`` + db.bios.insert( + { + name: { first: 'John', last: 'McCarthy' }, + birth: new Date('Sep 04, 1927'), + death: new Date('Dec 24, 2011'), + contribs: [ 'Lisp', 'Artificial Intelligence', 'ALGOL' ], + awards: [ + { + award: 'Turing Award', + year: 1971, + by: 'ACM' + }, + { + award: 'Kyoto Prize', + year: 1988, + by: 'Inamori Foundation' + }, + { + award: 'National Medal of Science', + year: 1990, + by: 'National Science Foundation' + } + ] + } + ) + + You can verify the inserted document by the querying the ``bios`` collection: .. code-block:: javascript - db.csbios.find( { name: { first: 'John', last: 'McCarthy' } } ) + db.bios.find( { name: { first: 'John', last: 'McCarthy' } } ) The returned document contains an ``_id`` field with the generated ``ObjectId`` value: .. code-block:: javascript - { - "_id" : ObjectId("507c294cbcf86cd7994f6c0a"), + { + "_id" : ObjectId("50a1880488d113a4ae94a94a"), "name" : { "first" : "John", "last" : "McCarthy" }, "birth" : ISODate("1927-09-04T04:00:00Z"), "death" : ISODate("2011-12-24T05:00:00Z"), "contribs" : [ "Lisp", "Artificial Intelligence", "ALGOL" ], "awards" : [ - { "award" : "Turing Award", - "year" : "1971", - "by" : "ACM" }, - { "award" : "Kyoto Prize", - "year" : "1988", - "by" : "Inamori Foundation" }, - { "award" : "National Medal of Science", - "year" : "1990", - "by" : "National Science Foundation" } - ] + { + "award" : "Turing Award", + "year" : 1971, + "by" : "ACM" + }, + { + "award" : "Kyoto Prize", + "year" :1988, + "by" : "Inamori Foundation" + }, + { + "award" : "National Medal of Science", + "year" : 1990, + "by" : "National Science Foundation" + } + ] } - If you pass an array of documents to the :method:`insert() @@ -189,7 +219,7 @@ Consider the following examples that illustrate the behavior of ` performs a bulk insert into a collection. The following operation inserts three documents into the - ``csbios`` collection. The operation also illustrates the + ``bios`` collection. The operation also illustrates the *dynamic schema* characteristic of MongoDB. Although the document with ``_id: 3`` contains a field ``title`` which does not appear in the other documents, MongoDB does not require the other documents to @@ -197,284 +227,97 @@ Consider the following examples that illustrate the behavior of .. code-block:: javascript - db.csbios.insert( [ - { - _id: 3, - name: { first: 'Grace', last: 'Hopper' }, - title: 'Rear Admiral', - birth: new Date('Dec 09, 1906'), - death: new Date('Jan 01, 1992'), - contribs: [ 'UNIVAC', 'compiler', 'FLOW-MATIC', 'COBOL' ], - awards: [ - { award: 'Computer Sciences Man of the Year', - year: '1969', - by: 'Data Processing Management Association' }, - { award: 'Distinguished Fellow', - year: '1973', - by: ' British Computer Society' }, - { award: 'W. W. McDowell Award', - year: '1976', - by: 'IEEE Computer Society' }, - { award: 'National Medal of Technology', - year: '1991', - by: 'United States' } - ] - }, - { - _id: 4, - name: { first: 'Kristen', last: 'Nygaard' }, - birth: new Date('Aug 27, 1926'), - death: new Date('Aug 10, 2002'), - contribs: [ 'OOP', 'Simula' ], - awards: [ - { award: 'Rosing Prize', - year: '1999', - by: 'Norwegian Data Association' }, - { award: 'Turing Award', - year: '2001', - by: 'ACM' }, - { award: 'IEEE John von Neumann Medal', - year: '2001', - by: 'IEEE' } - ] - }, - { - _id: 5, - name: { first: 'Ole-Johan', last: 'Dahl' }, - birth: new Date('Oct 12, 1931'), - death: new Date('Jun 29, 2002'), - contribs: [ 'OOP', 'Simula' ], - awards: [ - { award: 'Rosing Prize', - year: '1999', - by: 'Norwegian Data Association' }, - { award: 'Turing Award', - year: '2001', - by: 'ACM' }, - { award: 'IEEE John von Neumann Medal', - year: '2001', - by: 'IEEE' } - ] - } - ] ) + db.bios.insert( + [ + { + _id: 3, + name: { first: 'Grace', last: 'Hopper' }, + title: 'Rear Admiral', + birth: new Date('Dec 09, 1906'), + death: new Date('Jan 01, 1992'), + contribs: [ 'UNIVAC', 'compiler', 'FLOW-MATIC', 'COBOL' ], + awards: [ + { + award: 'Computer Sciences Man of the Year', + year: 1969, + by: 'Data Processing Management Association' + }, + { + award: 'Distinguished Fellow', + year: 1973, + by: ' British Computer Society' + }, + { + award: 'W. W. McDowell Award', + year: 1976, + by: 'IEEE Computer Society' + }, + { + award: 'National Medal of Technology', + year: 1991, + by: 'United States' + } + ] + }, + { + _id: 4, + name: { first: 'Kristen', last: 'Nygaard' }, + birth: new Date('Aug 27, 1926'), + death: new Date('Aug 10, 2002'), + contribs: [ 'OOP', 'Simula' ], + awards: [ + { + award: 'Rosing Prize', + year: 1999, + by: 'Norwegian Data Association' + }, + { + award: 'Turing Award', + year: 2001, + by: 'ACM' + }, + { + award: 'IEEE John von Neumann Medal', + year: 2001, + by: 'IEEE' + } + ] + }, + { + _id: 5, + name: { first: 'Ole-Johan', last: 'Dahl' }, + birth: new Date('Oct 12, 1931'), + death: new Date('Jun 29, 2002'), + contribs: [ 'OOP', 'Simula' ], + awards: [ + { + award: 'Rosing Prize', + year: 1999, + by: 'Norwegian Data Association' + }, + { + award: 'Turing Award', + year: 2001, + by: 'ACM' + }, + { + award: 'IEEE John von Neumann Medal', + year: 2001, + by: 'IEEE' + } + ] + } + ] + ) .. [#show-collection] You can also view a list of the existing collections in the database using the ``show collections`` operation in the :program:`mongo` shell. -.. _crud-create-update: - -Update with Upsert ------------------- - -An update with upsert or an *upsert* eliminates the need to perform a -separate database call to check for the existence of a record before -performing either an update or an insert operation. Typically update -operations :doc:`update ` existing documents, but -in MongoDB, the :method:`update() ` operation -can accept an ```` option as an argument. Upserts are a hybrid -operation that use the ```` argument to determine the write -operation: - -- If the query returns a result, the upsert updates the matching - document. - -- If the query matches no document in the collection, the upsert - inserts a single document. - -Consider the following syntax for an upsert operation: - -.. code-block:: javascript - - db.collection.update( , - , - { upsert: true } ) - -The following examples illustrate the use of the -upsert to perform create operations: - -- If the ```` argument contains only field and value - declarations, no document in the collection matches the ```` - argument, the upsert operation will insert a new document containing - the fields and values in the ```` argument will generate an - ``_id`` field if not found in the ```` argument. - - The following operation inserts a new document into the ``csbios`` - collection since there is no document that match the ``name`` field - in the ```` argument. Since the ```` argument - contains only field and value pairs, the new document contains only - these fields and values: - - .. code-block:: javascript - - db.csbios.update( - { name: { first: 'Dennis', last: 'Ritchie'} }, - { - _id: 6, - name: { first: 'Dennis', last: 'Ritchie'}, - birth: new Date('Sep 09, 1941'), - died: new Date('Oct 12, 2011'), - contribs: [ 'UNIX', 'C' ], - awards: [ - { award: 'Turing Award', - year: '1983', - by: 'ACM' }, - { award: 'IEEE Richard W. Hamming Medal', - year: '1990', - by: 'IEEE'}, - { award: 'National Medal of Technology', - year: '1998', - by: 'United States' }, - { award: 'Japan Prize', - year: '2011', - by: 'The Japan Prize Foundation' } - ] - }, - { upsert: true } - ) - -- If the ```` argument includes only :ref:`update operators - `, the upsert operation inserts a new document - containing the fields and values from ```` argument and the - fields and values in the ```` argument. - - The following operation inserts a new document into the - ``csbios`` 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 ```` and the ```` arguments. - - .. code-block:: javascript - - db.csbios.update( - { _id: 7, - name: { first: 'Ken', last: 'Thompson'} - }, - { - $set: { - birth: new Date('Feb 04, 1943'), - contribs: [ 'UNIX', 'C', 'B', 'UTF-8' ], - awards: [ - { award: 'Turing Award', - year: '1983', - by: 'ACM' }, - { award: 'IEEE Richard W. Hamming Medal', - year: '1990', - by: 'IEEE'}, - { award: 'National Medal of Technology', - year: '1998', - by: 'United States' }, - { award: 'Tsutomu Kanai Award', - year: '1999', - by: 'IEEE' }, - { award: 'Japan Prize', - year: '2011', - by: 'The Japan Prize Foundation' } - ] - } - }, - { upsert: true } - ) - - You can verify the inserted document by querying the ``csbios`` - collection: - - .. code-block:: javascript - - db.csbios.find( { _id: 7 } ) - - This operation will return the document created by the last upsert - operation: - - .. code-block:: javascript - - { - "_id" : 7, - "awards" : [ - { "award" : "Turing Award", - "year" : "1983", - "by" : "ACM" }, - { "award" : "IEEE Richard W. Hamming Medal", - "year" : "1990", - "by" : "IEEE" }, - { "award" : "National Medal of Technology", - "year" : "1998", - "by" : "United States" }, - { "award" : "Tsutomu Kanai Award", - "year" : "1999", - "by" : "IEEE" }, - { "award" : "Japan Prize", - "year" : "2011", - "by" : "The Japan Prize Foundation" } - ], - "birth" : ISODate("1943-02-04T05:00:00Z"), - "contribs" : [ "UNIX", "C", "B", "UTF-8" ], - "name" : { "first" : "Ken", "last" : "Thompson" } - } - -- If the ```` and ```` arguments do not specify an - ``_id`` field, the ``upsert`` operation adds the ``_id`` field to - the document and generates an ``ObjectId`` for the value. - - The following operation inserts a new document into the - ``csbios`` collection since there is no document that matches the - ``name`` field specified in the ```` argument. Because the - ```` argument does not contain an ``_id`` field, the - ``upsert`` operation adds the ``_id`` field to the document and - generates a ``ObjectId`` for its value: - - .. code-block:: javascript - - db.csbios.update( - { name: { first: 'Bjarne', last: 'Stroustrup' } }, - { - name: { first: 'Bjarne', last: 'Stroustrup' }, - birth: new Date('Jun 11, 1950'), - contribs: [ 'C++' ], - awards: [ - { award: 'Grace Murray Hopper Award', - year: '1992', - by: 'ACM' }, - { award: 'Computer Entrepreneur Award', - year: '2004', - by: 'IEEE'} - ] - }, - { upsert: true } - ) - - Issue the following query to the ``csbios`` collection to verify the - operation: - - .. code-block:: javascript - - db.csbios.find( { name: { first: 'Bjarne', last: 'Stroustrup' } } ) - - The returned document contains an ``_id`` field with the generated - ``ObjectId`` value: - - .. code-block:: javascript - - { - "_id" : ObjectId("507c35dd8fada716c89d0013"), - "name" : { "first" : "Bjarne", "last" : "Stroustrup" }, - "birth" : ISODate("1950-06-11T04:00:00Z"), - "contribs" : [ "C++" ], - "awards" : [ - { "award" : "Grace Murray Hopper Award", - "year" : "1992", - "by" : "ACM" }, - { "award" : "Computer Entrepreneur Award", - "year" : "2004", - "by" : "IEEE" } - ] - } - .. _crud-create-save: -Save ----- +Create with Save +---------------- The :method:`save() ` method is a specialized upsert that use the ``_id`` field in the ```` argument to @@ -503,46 +346,176 @@ Consider the following examples that illustrate the use of the Refer to the :ref:`insert ` section for details of the insert operation of a document without an ``_id`` field. - The following operation performs an insert into the ``csbios`` + The following operation performs an insert into the ``bios`` collection since the document does not contain the ``_id`` field: .. code-block:: javascript - db.csbios.save( { - name: { first: 'Guido', last: 'van Rossum'}, - birth: new Date('Jan 31, 1956'), - contribs: [ 'Python' ], - awards: [ - { award: 'Award for the Advancement of Free Software', - year: '2001', - by: 'Free Software Foundation' }, - { award: 'NLUUG Award', - year: '2003', - by: 'NLUUG'} - ] - } ) + db.bios.save( + { + name: { first: 'Guido', last: 'van Rossum'}, + birth: new Date('Jan 31, 1956'), + contribs: [ 'Python' ], + awards: [ + { + award: 'Award for the Advancement of Free Software', + year: 2001, + by: 'Free Software Foundation' + }, + { + award: 'NLUUG Award', + year: 2003, + by: 'NLUUG' + } + ] + } + ) - If the ```` contains an ``_id`` field but has a value not found in the collection, the :method:`save() ` method performs an insert. Refer to the :ref:`insert ` section for details of the insert operation. - The following operation performs an insert into the ``csbios`` + The following operation performs an insert into the ``bios`` collection since the document contains an ``_id`` field whose value - ``10`` is not found in the ``csbios`` collection: + ``10`` is not found in the ``bios`` collection: .. code-block:: javascript - db.csbios.save( + db.bios.save( { _id: 10, name: { first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'}, birth: new Date('Apr 14, 1965'), contribs: [ 'Ruby' ], awards: [ - { award: 'Award for the Advancement of Free Software', + { + award: 'Award for the Advancement of Free Software', year: '2011', - by: 'Free Software Foundation' } - ] + by: 'Free Software Foundation' + } + ] } ) + +.. _crud-create-update: + +Create with Upsert +------------------ + +An *upsert* eliminates the need to perform a separate database call to +check for the existence of a record before performing either an update +or an insert operation. Typically update operations :doc:`update +` existing documents, but in MongoDB, the +:method:`update() ` operation can accept an +```` option as an argument. Upserts are a hybrid operation that +use the ```` argument to determine the write operation: + +- If the query matches an existing document(s), the upsert performs an + update. + +- If the query matches no document in the collection, the upsert + inserts a single document. + +Consider the following syntax for an upsert operation: + +.. code-block:: javascript + + db.collection.update( , + , + { upsert: true } ) + +The following examples illustrate the use of the upsert to perform +create operations: + +- If no document matches the ```` argument, the ``upsert`` + performs an insert. If the ```` argument includes only field + and value pairs, the new document contains the fields and values + specified in the ```` argument. If the ``_id`` field is + omitted, the operation adds the ``_id`` field and generates a unique + ``ObjectId`` for its value. + + The following ``upsert`` operation inserts a new document into the + ``bios`` collection: + + .. code-block:: javascript + + db.bios.update( + { name: { first: 'Dennis', last: 'Ritchie'} }, + { + name: { first: 'Dennis', last: 'Ritchie'}, + birth: new Date('Sep 09, 1941'), + died: new Date('Oct 12, 2011'), + contribs: [ 'UNIX', 'C' ], + awards: [ + { + award: 'Turing Award', + year: 1983, + by: 'ACM' + }, + { + award: 'National Medal of Technology', + year: 1998, + by: 'United States' + }, + { + award: 'Japan Prize', + year: 2011, + by: 'The Japan Prize Foundation' + } + ] + }, + { upsert: true } + ) + +- If no document matches the ```` argument, the upsert operation + inserts a new document. If the ```` argument includes only + :ref:`update operators `, the new document contains + the fields and values from ```` argument with the operations + from the ```` argument applied. + + The following operation inserts a new document into the + ``bios`` collection: + + .. code-block:: javascript + + db.bios.update( + { + _id: 7, + name: { first: 'Ken', last: 'Thompson' } + }, + { + $set: { + birth: new Date('Feb 04, 1943'), + contribs: [ 'UNIX', 'C', 'B', 'UTF-8' ], + awards: [ + { + award: 'Turing Award', + year: 1983, + by: 'ACM' + }, + { + award: 'IEEE Richard W. Hamming Medal', + year: 1990, + by: 'IEEE' + }, + { + award: 'National Medal of Technology', + year: 1998, + by: 'United States' + }, + { + award: 'Tsutomu Kanai Award', + year: 1999, + by: 'IEEE' + }, + { + award: 'Japan Prize', + year: 2011, + by: 'The Japan Prize Foundation' + } + ] + } + }, + { upsert: true } + ) diff --git a/draft/applications/delete.txt b/draft/applications/delete.txt index 778f5644f5f..4204d4640e4 100644 --- a/draft/applications/delete.txt +++ b/draft/applications/delete.txt @@ -20,20 +20,23 @@ shell provides this operation, as do corresponding methods in the .. note:: - .. include:: /includes/fact-write-concerns.rst +.. .. include:: /includes/fact-write-concerns.rst .. _crud-delete-remove: Remove ------ -Use the :method:`remove() ` method to -delete documents from a collection. [#indexes]_ Consider the syntax of -the following prototype operation: +Use the :method:`remove() ` method to delete +documents from a collection; this action does not remove the indexes. +[#drop]_ + +The :method:`remove() ` method has the +following syntax: .. code-block:: javascript - db.collection.delete( , ) + db.collection.delete( , ) .. admonition:: Corresponding operation in SQL @@ -51,41 +54,44 @@ Consider the following examples that illustrate the use of the ` method deletes from the collection all documents that match the argument. - The following operation deletes all documents from the ``csbios`` - collection where the ``first`` field in the subdocument ``name`` - starts with ``G``: + The following operation deletes all documents from the ``bios`` + collection where the subdocument ``name`` contains a field ``first`` + whose value starts with ``G``: .. code-block:: javascript - db.csbios.remove( { 'name.first' : /^G/ } ) + db.bios.remove( { 'name.first' : /^G/ } ) - If there is a ```` argument and you specify the ```` - argument, :method:`remove() ` only deletes a - single documents from the collection that matches the query. + argument as ``true`` or ``1``, :method:`remove() + ` only deletes a single document from the + collection that matches the query. - The following operation deletes a single document from the - ``csbios`` collection where the ``turing`` field equals ``true``: + The following operation deletes a single document from the ``bios`` + collection where the ``turing`` field equals ``true``: .. code-block:: javascript - db.csbios.remove( { turing: true }, 1 ) + db.bios.remove( { turing: true }, 1 ) - 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: + ``bios`` collection: .. code-block:: javascript - db.csbios.remove() + db.bios.remove() .. note:: This operation is not equivalent to the :method:`drop() ` method. -.. [#indexes] The :method:`remove() ` method - does not delete indexes. +.. [#drop] To remove all documents from a collection, it may be faster + to use the :method:`drop() ` method to drop the + entire collection, including the indexes, and then recreate the + collection and rebuild the indexes. .. _crud-delete-remove-isolation: @@ -102,11 +108,10 @@ If the ```` argument to the :method:`remove() 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 ```` parameter as in -the following example: +isolation operator, effectively isolating the delete operation from +other write operations. To isolate the operation, include ``$atomic: +1`` in the ```` parameter as in the following example: .. code-block:: javascript - db.csbios.remove( { turing: true, $atomic: 1 } ) + db.bios.remove( { turing: true, $atomic: 1 } ) diff --git a/draft/applications/read.txt b/draft/applications/read.txt index e84b1a7aa04..c65a0d1abe1 100644 --- a/draft/applications/read.txt +++ b/draft/applications/read.txt @@ -53,31 +53,42 @@ syntax: Consider the following examples that illustrate the use of the :method:`find() ` method: -.. pull-quote:: The examples refer to a collection named ``csbios`` +.. pull-quote:: The examples refer to a collection named ``bios`` that contains documents with the following prototype: .. code-block:: javascript { "_id" : 1, - "name" : { "first" : "John", "last" :"Backus" }, + "name" : { + "first" : "John", + "last" :"Backus" + }, "birth" : ISODate("1924-12-03T05:00:00Z"), "death" : ISODate("2007-03-17T04:00:00Z"), "contribs" : [ "Fortran", "ALGOL", "Backus-Naur Form", "FP" ], "awards" : [ - { "award" : "W.W. McDowellAward", - "year" : "1967", - "by" : "IEEE Computer Society" }, - { "award" : "National Medal of Science", - "year" : "1975", - "by" : "National Science Foundation" }, - { "award" : "Turing Award", - "year" : "1977", - "by" : "ACM" }, - { "award" : "Draper Prize", - "year" : "1993", - "by" : "National Academy of Engineering" } - ] + { + "award" : "W.W. McDowellAward", + "year" : 1967, + "by" : "IEEE Computer Society" + }, + { + "award" : "National Medal of Science", + "year" : 1975, + "by" : "National Science Foundation" + }, + { + "award" : "Turing Award", + "year" : 1977, + "by" : "ACM" + }, + { + "award" : "Draper Prize", + "year" : 1993, + "by" : "National Academy of Engineering" + } + ] } .. note:: @@ -90,102 +101,152 @@ Consider the following examples that illustrate the use of the ` method selects all documents from a collection. - The following operation returns all documents (or more - precisely, a cursor to all documents) in the ``csbios`` + precisely, a cursor to all documents) in the ``bios`` collection: .. code-block:: javascript - db.csbios.find() + db.bios.find() - If there is a ```` argument, the :method:`find() ` method selects all documents from a collection that satisfies the criteria of the query: - - The following operation returns all documents in the ``csbios`` + - The following operation returns all documents in the ``bios`` collection where the field ``_id`` equals ``5`` or ``ObjectId("507c35dd8fada716c89d0013")``: .. code-block:: javascript - db.csbios.find( { _id: { $in: [ 5, ObjectId("507c35dd8fada716c89d0013") ] } } ) + db.bios.find( + { + _id: { $in: [ 5, ObjectId("507c35dd8fada716c89d0013") ] } + } + ) - - The following operation returns all documents in the ``csbios`` + - The following operation returns all documents in the ``bios`` collection where the array field ``contribs`` contains the element ``UNIX``: .. code-block:: javascript - db.csbios.find( { contribs: 'UNIX' } ) + db.bios.find( + { + contribs: 'UNIX' + } + ) - - The following operation returns all documents in the ``csbios`` + - The following operation returns all documents in the ``bios`` collection where the subdocument ``name`` contains a field ``first`` with the value ``Yukihiro`` and a field ``last`` with the value ``Matsumoto``: .. code-block:: javascript - db.csbios.find( { 'name.first': 'Yukihiro', 'name.last': 'Matsumoto' } ) + db.bios.find( + { + 'name.first': 'Yukihiro', + 'name.last': 'Matsumoto' + } + ) The query matches the document where the ``name`` field contains a - field ``first`` with the value ``Yukihiro`` and a field ``last`` - with the value ``Matsumoto``. For instance, the query would match - documents with ``name`` either fields that held either of the - following values: + subdocument with the field ``first`` with the value ``Yukihiro`` + and a field ``last`` with the value ``Matsumoto``. For instance, + the query would match documents with ``name`` fields that + held either of the following values: .. code-block:: javascript - { first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'} - { last: 'Matsumoto', first: 'Yukihiro'} - - - The following operation returns all documents in the ``csbios`` + { + first: 'Yukihiro', + aka: 'Matz', + last: 'Matsumoto' + } + + { + last: 'Matsumoto', + first: 'Yukihiro' + } + + - The following operation returns all documents in the ``bios`` collection where the subdocument ``name`` is *exactly* ``{ first: - 'Yukihiro', last: 'Matsumoto' }``: + 'Yukihiro', last: 'Matsumoto' }``, including the order: .. code-block:: javascript - db.csbios.find( { name: { first: 'Yukihiro', last: 'Matsumoto' } } ) + db.bios.find( + { + name: { + first: 'Yukihiro', + last: 'Matsumoto' + } + } + ) - The order of fields in the sub-document must match exactly. For - instance, the query would **not** match documents with ``name`` - either fields that held either of the following values: + The ``name`` field must match the sub-document exactly, including + order. For instance, the query would **not** match documents with + ``name`` fields that held either of the following values: .. code-block:: javascript - { first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'} - { last: 'Matsumoto' , first: 'Yukihiro' } - - - The following operation returns all documents in the ``csbios`` + { + first: 'Yukihiro', + aka: 'Matz', + last: 'Matsumoto' + } + + { + last: 'Matsumoto', + first: 'Yukihiro' + } + + - The following operation returns all documents in the ``bios`` collection where either the field ``first`` in the sub-document ``name`` starts with the letter ``G`` **or** where the field ``birth`` is less than ``new Date('01/01/1945')``: .. code-block:: javascript - db.csbios.find( { $or: [ { 'name.first' : /^G/ }, - { birth: { $lt: new Date('01/01/1945') } } - ] } ) + db.bios.find( + { $or: [ + { 'name.first' : /^G/ }, + { birth: { $lt: new Date('01/01/1945') } } + ] + } + ) - - The following operation returns all documents in the ``csbios`` + - The following operation returns all documents in the ``bios`` collection where the field ``first`` in the subdocument ``name`` starts with the letter ``K`` **and** the array field ``contribs`` contains the element ``UNIX``: .. code-block:: javascript - db.csbios.find( { 'name.first': /^K/, - contribs: 'UNIX' } ) + db.bios.find( + { + 'name.first': /^K/, + contribs: 'UNIX' + } + ) - - The following operation returns all documents in the ``csbios`` + - The following operation returns all documents in the ``bios`` collection where ``awards`` array contains a subdocument element that contains the ``award`` field equal to ``Turing Award`` and the - ``year`` field greater than ``1980``: + ``year`` field greater than 1980: .. code-block:: javascript - db.csbios.find( { awards: { $elemMatch: { - award: 'Turing Award', - year: { $gt: '1980' } - } } } ) + db.bios.find( + { + awards: { + $elemMatch: { + award: 'Turing Award', + year: { $gt: 1980 } + } + } + } + ) - If there is a ```` argument, the :method:`find() ` method returns only those fields as specified @@ -197,23 +258,29 @@ Consider the following examples that illustrate the use of the Otherwise, you cannot mix include field and exclude field specifications. - - The following operation finds all documents in the ``csbios`` + - The following operation finds all documents in the ``bios`` collection and returns only the ``name`` field, the ``contribs`` field, and the ``_id`` field: .. code-block:: javascript - db.csbios.find( { }, { name: 1, contribs: 1 } ) + db.bios.find( + { }, + { name: 1, contribs: 1 } + ) - - The following operation finds all documents in the ``csbios`` + - The following operation finds all documents in the ``bios`` collection and returns only the ``name`` field and the ``contribs`` field: .. code-block:: javascript - db.csbios.find( { }, { name: 1, contribs: 1, _id: 0 } ) + db.bios.find( + { }, + { name: 1, contribs: 1, _id: 0 } + ) - - The following operation finds the documents in the ``csbios`` + - The following operation finds the documents in the ``bios`` collection where the ``contribs`` field contains the element ``OOP`` and returns all fields *except* the ``_id`` field, the ``first`` field in the ``name`` subdocument, and the ``birth`` @@ -221,25 +288,67 @@ Consider the following examples that illustrate the use of the .. code-block:: javascript - db.csbios.find( { contribs: 'OOP' }, - { _id: 0, 'name.first': 0, birth: 0 } ) + db.bios.find( + { contribs: 'OOP' }, + { _id: 0, 'name.first': 0, birth: 0 } + ) + + - The following operation finds all documents in the ``bios`` + collection and returns the the ``last`` field in the ``name`` + subdocument and the first two elements in the ``contribs`` field: + + .. code-block:: javascript + + db.bios.find( + { }, + { + _id: 0, + 'name.last': 1, + contribs: { $slice: 2 } + } + ) + +Cursor +~~~~~~ + +:method:`find() ` returns a *cursor*; however, in +the :program:`mongo` shell, the cursor is automatically iterated up to +20 times to print the documents referenced by the cursor. To access the +documents, you must explicitly handle the cursor, as in the following +example: + +.. code-block:: javascript + + var myCursor = db.bios.find( { _id: 1 } ); + + var myDocument = myCursor.hasNext() ? myCursor.next() : null; + + if (myDocument) { + var myName = myDocument.name; + + print (tojson(myName)); + } + +See the :method:`cursor.forEach()`, :method:`cursor.hasNext()`, +:method:`cursor.next()` documentation for more information on cursor +handling. In addition to the ```` and the ```` arguments, the :program:`mongo` shell and the :doc:`drivers ` -provide several cursor methods that you can call on the -:method:`find() ` method to modify its -operation. These methods are: +provide several cursor methods that you can call on the *cursor* +returned by :method:`find() ` method to modify +its behavior, such as: - :method:`sort `, which orders the documents in the result set according to the field or fields specified to the method. The following operation returns all documents (or more precisely, a - cursor to all documents) in the ``csbios`` collection ordered by the + cursor to all documents) in the ``bios`` collection ordered by the ``name`` field ascending: .. code-block:: javascript - db.csbios.find().sort( { name: 1 } ) + db.bios.find().sort( { name: 1 } ) :method:`sort() ` corresponds to the ``ORDER BY`` statement in SQL. @@ -248,16 +357,35 @@ operation. These methods are: documents in the result set. The following operation returns at most ``5`` documents (or more - precisely, a cursor to at most 5 documents) in the ``csbios`` + precisely, a cursor to at most 5 documents) in the ``bios`` collection: .. code-block:: javascript - db.csbios.find().limit( 5 ) + db.bios.find().limit( 5 ) :method:`limit() ` corresponds to the ``LIMIT`` statement in SQL. +- The :method:`skip() ` method controls the starting + point of the results set. + + The following operation returns all documents, skipping the first + ``5`` documents in the ``bios`` collection: + + .. code-block:: javascript + + db.bios.find().skip( 5 ) + +These cursor methods may be chained together; however, the +:method:`limit() ` method is always applied after the +:method:`sort() ` even if you chain the methods in the +reverse order: + + .. code-block:: javascript + + db.bios.find().limit( 5 ).sort( { name: 1 } ) + .. _crud-read-findOne: .. _crud-read-find-one: @@ -278,49 +406,60 @@ syntax: Except for the return value, :method:`findOne() ` method is quite similar to the -:method:`find() ` method. Consider the following -examples that illustrate the use of the :method:`findOne() -` method: +:method:`find() ` method; in fact, internally, +the :method:`findOne() ` method is the +:method:`find() ` method with a limit of 1. + +Consider the following examples that illustrate the use of the +:method:`findOne() ` method: - If there is no ```` argument, the :method:`findOne() ` method selects just one document from a collection. - The following operation returns a single document from the - ``csbios`` collection: + ``bios`` collection: .. code-block:: javascript - db.csbios.findOne() + db.bios.findOne() - If there is a ```` argument, the :method:`findOne() ` method selects the first document from a collection that meets the ```` argument: - The following operation returns the first matching document from - the ``csbios`` collection where either the field ``first`` in the + the ``bios`` collection where either the field ``first`` in the subdocument ``name`` starts with the letter ``G`` **or** where the field ``birth`` is less than ``new Date('01/01/1945')``: .. code-block:: javascript - db.csbios.findOne( { $or: [ { 'name.first' : /^G/ }, - { birth: { $lt: new Date('01/01/1945') } } - ] } ) + db.bios.findOne( + { + $or: [ + { 'name.first' : /^G/ }, + { birth: { $lt: new Date('01/01/1945') } } + ] + } + ) - You can pass a ```` argument to :method:`findOne() ` to control the fields included in the result set: - - The following operation finds a document in the ``csbios`` + - The following operation finds a document in the ``bios`` collection and returns only the ``name`` field, the ``contribs`` field, and the ``_id`` field: .. code-block:: javascript - db.csbios.findOne( { }, { name: 1, contribs: 1 } ) + db.bios.findOne( + { }, + { name: 1, contribs: 1 } + ) - - The following operation returns a document in the ``csbios`` + - The following operation returns a document in the ``bios`` collection where the ``contribs`` field contains the element ``OOP`` and returns all fields *except* the ``_id`` field, the ``first`` field in the ``name`` subdocument, and the ``birth`` @@ -328,5 +467,25 @@ examples that illustrate the use of the :method:`findOne() .. code-block:: javascript - db.csbios.findOne( { contribs: 'OOP' }, - { _id: 0, 'name.first': 0, birth: 0 } ) + db.bios.findOne( + { contribs: 'OOP' }, + { _id: 0, 'name.first': 0, birth: 0 } + ) + +Although similar to the :method:`find() ` method, +because the :method:`findOne() ` method +returns a document rather than a cursor, you cannot apply the cursor +methods such as :method:`limit() `, :method:`sort() +`, and :method:`skip() ` to the result of +the :method:`findOne() ` method. However, you +can access the document directly, as in the following example: + +.. code-block:: javascript + + var myDocument = db.bios.findOne(); + + if (myDocument) { + var myName = myDocument.name; + + print (tojson(myName)); + } diff --git a/draft/applications/update.txt b/draft/applications/update.txt index 7274e5e4c72..7d5ff37c0b5 100644 --- a/draft/applications/update.txt +++ b/draft/applications/update.txt @@ -24,21 +24,21 @@ methods to perform update operations: .. note:: - - .. include:: /includes/fact-update-field-order.rst + .. include:: /includes/fact-update-field-order.rst - - .. include:: /includes/fact-write-concerns.rst +.. - .. include:: /includes/fact-write-concerns.rst .. _crud-update-update: Update ------ -The :method:`update() ` method is method used -to modify documents in a MongoDB collection. By default the -:method:`update() ` method updates a single -document, but by using the ``multi`` option, :method:`update() -` can update all documents that match the -query criteria in the collection. The :method:`update() +The :method:`update() ` method is the primary +method used to modify documents in a MongoDB collection. By default, +the :method:`update() ` method updates a +**single** document, but by using the ``multi`` option, +:method:`update() ` can update all documents +that match the query criteria in the collection. The :method:`update() ` method can either replace the existing document with the new document or update specific fields in the existing document. @@ -59,91 +59,103 @@ syntax: and - the ```` corresponds to the ``SET ...`` statement. - - However, :method:`update() ` is more - flexible and offers more control than its SQL equivalents. + + The default behavior of the :method:`update() + ` method updates a **single** document and + would correspond to the SQL ``UPDATE`` statement with the ``LIMIT + 1``. With the ``multi`` option, :method:`update() + ` method would correspond to the SQL + ``UPDATE`` statement without the ``LIMIT`` clause. Consider the following examples that illustrate the use of the :method:`update() ` method: -- If the ```` argument contains only :ref:`update operators +- If the ```` argument contains only :ref:`update operator ` expressions such as the :operator:`$set` operator expression, the :method:`update() ` method - updates only the corresponding fields in the document. + updates the corresponding fields in the document. - The following operation queries the ``csbios`` collection for the - document that has an ``_id`` field equal to ``1`` and sets the - ``middle`` field in the ``name`` subdocument to ``Warner`` and adds a - new element to the ``awards`` field: + The following operation queries the ``bios`` collection for the first + document that has an ``_id`` field equal to ``1`` and sets the field + named ``middle`` to the value ``Warner`` in the ``name`` subdocument + and adds a new element to the ``awards`` field: .. code-block:: javascript - db.csbios.update( { _id: 1 }, - { $set: { 'name.middle': 'Warner' }, - $push: { awards: { award: 'IBM Fellow', - year: '1963', - by: 'IBM' } } - } ) + db.bios.update( + { _id: 1 }, + { + $set: { 'name.middle': 'Warner' }, + $push: { awards: { award: 'IBM Fellow', year: 1963, by: 'IBM' } } + } + ) - If the ```` argument contains :operator:`$unset` operator, the :method:`update() ` method removes the field from the document. - The following operation queries the ``csbios`` collection for the + The following operation queries the ``bios`` collection for the first document that has an ``_id`` field equal to ``3`` and removes the ``birth`` field from the document: .. code-block:: javascript - db.csbios.update( { _id: 3 }, - { $unset: { birth: 1 } } ) + db.bios.update( + { _id: 3 }, + { $unset: { birth: 1 } } + ) - If the ```` argument contains fields not currently in the document, the :method:`update() ` method adds the new fields to the document. - The following operation queries the ``csbios`` collection for the + The following operation queries the ``bios`` collection for the first document that has an ``_id`` field equal to ``3`` and adds to the document a new ``mbranch`` field and a new ``aka`` field in the subdocument ``name``: .. code-block:: javascript - db.csbios.update( { _id: 3 }, - { $set: { mbranch: 'Navy', - 'name.aka': 'Amazing Grace'} } ) + db.bios.update( + { _id: 3 }, + { $set: { + mbranch: 'Navy', + 'name.aka': 'Amazing Grace' + } + } + ) - If the ```` argument contains only field and value pairs, the :method:`update() ` method *replaces* the existing document with the document in the ```` argument, except for the ``_id`` field. - The following operation queries the ``csbios`` collection for the + The following operation queries the ``bios`` 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 ```` argument: .. code-block:: javascript - db.csbios.update( - { name: { first: 'John', last: 'McCarthy' } }, - { - name: { first: 'Ken', last: 'Iverson' }, - born: new Date('Dec 17, 1941'), - died: new Date('Oct 19, 2004'), - contribs: [ 'APL', 'J' ], - awards: [ - { award: 'Turing Award', - year: '1979', - by: 'ACM' }, - { award: 'Harry H. Goode Memorial Award', - year: '1975', - by: 'IEEE Computer Society' }, - { award: 'IBM Fellow', - year: '1970', - by: 'IBM' } - ] - } ) + db.bios.update( + { name: { first: 'John', last: 'McCarthy' } }, + { name: { first: 'Ken', last: 'Iverson' }, + born: new Date('Dec 17, 1941'), + died: new Date('Oct 19, 2004'), + contribs: [ 'APL', 'J' ], + awards: [ + { award: 'Turing Award', + year: 1979, + by: 'ACM' }, + { award: 'Harry H. Goode Memorial Award', + year: 1975, + by: 'IEEE Computer Society' }, + { award: 'IBM Fellow', + year: 1970, + by: 'IBM' } + ] + } + ) - If the update operation requires an update of an element in an array field: @@ -152,22 +164,24 @@ Consider the following examples that illustrate the use of the the update using the position of the element. Arrays in MongoDB are zero-based. - The following operation queries the ``csbios`` collection for - the document with ``_id`` field equal to ``1`` and updates the + The following operation queries the ``bios`` collection for + the first document with ``_id`` field equal to ``1`` and updates the second element in the ``contribs`` array: .. code-block:: javascript - db.csbios.update( { _id: 1 } , - { $set: { 'contribs.1': 'ALGOL 58' } } ) + db.bios.update( + { _id: 1 }, + { $set: { 'contribs.1': 'ALGOL 58' } } + ) - 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. + argument in order to determine which array element to update. - The following operation queries the ``csbios`` collection for a - document with the ``_id`` field equal to ``3`` and the ``contribs`` + The following operation queries the ``bios`` collection for the first + document where the ``_id`` field equals ``3`` and the ``contribs`` array contains an element equal to ``compiler``. If found, the :method:`update() ` method updates the first matching element in the array to ``A compiler`` in the @@ -175,16 +189,18 @@ Consider the following examples that illustrate the use of the .. code-block:: javascript - db.csbios.update( { _id: 3, 'contribs': 'compiler' }, - { $set: { 'contribs.$': 'A compiler' } } ) + db.bios.update( + { _id: 3, 'contribs': 'compiler' }, + { $set: { 'contribs.$': 'A compiler' } } + ) - 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 ``csbios`` collection for a - document with the ``_id`` field equal to ``6`` and the ``awards`` + The following operation queries the ``bios`` collection for the first + document where the ``_id`` field equals ``6`` and the ``awards`` array contains a subdocument element with the ``by`` field equal to ``ACM``. If found, the :method:`update() ` method updates the ``by`` field in the @@ -192,42 +208,45 @@ Consider the following examples that illustrate the use of the .. code-block:: javascript - db.csbios.update( { _id: 6, 'awards.by': 'ACM' } , - { $set: { 'awards.$.by': 'Association for Computing Machinery' } } ) + db.bios.update( + { _id: 6, 'awards.by': 'ACM' } , + { $set: { 'awards.$.by': 'Association for Computing Machinery' } } + ) - If the ```` 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 ``csbios`` collection for all + The following operation queries the ``bios`` collection for all documents where the ``awards`` field contains a subdocument element with the ``award`` field equal to ``Turing`` and sets the ``turing`` field to ``true`` in the matching documents: .. code-block:: javascript - db.csbios.update( { 'awards.award': 'Turing' }, - { $set: { turing: true } }, - { multi: true } ) + db.bios.update( + { 'awards.award': 'Turing' }, + { $set: { turing: true } }, + { multi: true } + ) - 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: + insert a new document into the collection. - The following operation queries the ``csbios`` collection for a + The following operation queries the ``bios`` 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 ```` argument and the ```` argument - since the ```` argument contains only :ref:`update operators - ` expressions. + inserts a new document containing the fields and values from + ```` argument with the operations from the ```` + argument applied. [#upsert-update-operators]_ - .. code-block::javascript + .. code-block:: javascript - db.csbios.update( + db.bios.update( { _id:11, name: { first: 'James', last: 'Gosling' } }, { $set: { @@ -235,10 +254,10 @@ Consider the following examples that illustrate the use of the contribs: [ 'Java' ], awards: [ { award: 'The Economist Innovation Award', - year: '2002', + year: 2002, by: 'The Economist' }, { award: 'Officer of the Order of Canada', - year: '2007', + year: 2007, by: 'Canada' } ] } @@ -246,10 +265,18 @@ Consider the following examples that illustrate the use of the { upsert: true } ) - See also :ref:`Create `. + See also :ref:`Create with Upsert`. .. _crud-update-save: +.. [#upsert-update-operators] If the ```` + argument includes only field and value pairs, the new document + contains the fields and values specified in the ```` + argument. If the ```` argument includes only :ref:`update + operators `, the new document contains the fields + and values from ```` argument with the operations from the + ```` argument applied. + Save ---- @@ -275,31 +302,36 @@ Consider the following examples of the :method:`save() performs an update that replaces the existing document with the ```` argument. - The following operation queries the ``csbios`` collection for a + The following operation queries the ``bios`` collection for a document where the ``_id`` equals ``ObjectId("507c4e138fada716c89d0014")`` and replaces the document with the ```` argument: .. code-block:: javascript - db.csbios.save( { _id: ObjectId("507c4e138fada716c89d0014"), - name: { first: 'Martin', last: 'Odersky' }, - contribs: [ 'Scala' ] - } ) + db.bios.save( + { + _id: ObjectId("507c4e138fada716c89d0014"), + name: { first: 'Martin', last: 'Odersky' }, + contribs: [ 'Scala' ] + } + ) - 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 generate a unique :term:`Object` for - and create an ``_id`` field for the new document. + ` method performs an insert. The following operation adds the ``_id`` field to the document, - assigns to the field a unique ``ObjectId``, and inserts into the - ``csbios`` collection: + assigns to the field a unique :term:`ObjectId `, and + inserts the document into the ``bios`` collection: .. code-block:: javascript - db.csbios.save( { name: { first: 'Larry', last: 'Wall' }, - contribs: [ 'Perl' ] } ) + db.bios.save( + { + name: { first: 'Larry', last: 'Wall' }, + contribs: [ 'Perl' ] + } + ) - Upserts are also :ref:`create ` operations. + See also :ref:`Create with Save `. diff --git a/source/includes/fact-update-field-order.rst b/source/includes/fact-update-field-order.rst index eb5b6989a9b..84e7c3626ec 100644 --- a/source/includes/fact-update-field-order.rst +++ b/source/includes/fact-update-field-order.rst @@ -1,5 +1,5 @@ When performing update operations that increase the document size beyond the allocated space for that document, the update operation -relocates the document on disk and orders the document fields -alphanumerically. +relocates the document on disk and may reorder the document fields +depending on the type of update. diff --git a/source/includes/note-duplicate-id-feild.rst b/source/includes/note-duplicate-id-field.rst similarity index 100% rename from source/includes/note-duplicate-id-feild.rst rename to source/includes/note-duplicate-id-field.rst