diff --git a/draft/applications/create.txt b/draft/applications/create.txt index abead2ecc26..00d2e950748 100644 --- a/draft/applications/create.txt +++ b/draft/applications/create.txt @@ -58,44 +58,61 @@ Consider the following examples that illustrate the usage of the ` method creates the collection during the first insert. - The following operation creates the collection ``presidents`` and + The following operation creates the collection ``csbios`` and inserts the document: .. code-block:: javascript - db.presidents.insert( { + db.csbios.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 } ] + 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 verify the results of this operation by querying the - ``presidents`` collection: + ``csbios`` collection: .. code-block:: javascript - > db.presidents.find() + > db.csbios.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 } ] - } + { + "_id" : 1, + "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" } + ] + } - If the new document does not contain an ``_id`` field, then the :method:`insert() ` method adds the ``_id`` @@ -103,95 +120,128 @@ Consider the following examples that illustrate the usage of the 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: + into the ``csbios`` 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 } ] + 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 addition of the ``_id`` field to the inserted - document by the querying the ``presidents`` collection: + document by the querying the ``csbios`` 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 } ] + > db.csbios.find( { name: { first: 'John', last: 'McCarthy' } } ) + + { + "_id" : ObjectId("507c294cbcf86cd7994f6c0a"), + "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" } + ] } + - 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. The following operation inserts three documents into the - ``presidents`` collection. The operation also illustrates the + ``csbios`` 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 + with ``_id: 3`` contains a field ``title`` 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( [ + db.csbios.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: 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: '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: 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: '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 } ] + _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' } + ] } ] ) @@ -225,28 +275,37 @@ Consider the following examples that illustrate the usage of the ``update`` argument. The following operation inserts a new document into the - ``presidents`` collection since there is no document matching the + ``csbios`` 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'} }, + db.csbios.update( + { name: { first: 'Dennis', last: 'Ritchie'} }, { _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 } ] + 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 } + { upsert: true } ) - If the ``update`` argument includes only :ref:`update operators @@ -255,7 +314,7 @@ Consider the following examples that illustrate the usage of 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 + ``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 @@ -263,20 +322,32 @@ Consider the following examples that illustrate the usage of the .. code-block:: javascript - db.presidents.update( - { _id: 7, name: { first: 'Andrew', last: 'Jackson'} }, + db.csbios.update( + { _id: 7, + name: { first: 'Ken', last: 'Thompson'} + }, { $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 } ] - } + 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 } ) @@ -284,23 +355,34 @@ Consider the following examples that illustrate the usage of the 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: + ``csbios`` 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" ] + > db.csbios.find( { _id: 7 } ) + + { + "_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 ``_id`` is not specified in either the ``query`` argument and @@ -308,7 +390,7 @@ Consider the following examples that illustrate the usage of the 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 + ``csbios`` 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 @@ -316,39 +398,44 @@ Consider the following examples that illustrate the usage of the .. code-block:: javascript - db.presidents.update( - { name: { first: 'Martin', last: 'Van Buren'} }, + db.csbios.update( + { name: { first: 'Bjarne', last: 'Stroustrup' } }, { - 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 } ] + 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 } + { upsert: true } ) You can verify the addition of the ``_id`` field to the inserted - document by the querying the ``presidents`` collection: + document by the querying the ``csbios`` 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 } ] + > db.csbios.find( { name: { first: 'Bjarne', last: 'Stroustrup' } } ) + + { + "_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: @@ -378,63 +465,69 @@ operations: :method:`save() ` method adds the ``_id`` field to the document and performs an insert. - The following operation performs an insert into the ``presidents`` + The following operation performs an insert into the ``csbios`` 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 } ] + 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'} + ] } ) You can verify the addition of the ``_id`` field during the operation - by querying the ``presidents`` collection: - + by querying the ``csbios`` 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 } ] + > db.csbios.find( { name: { first: 'Guido', last: 'van Rossum'} } ) + + { + "_id" : ObjectId("507c387cbcf86cd7994f6c0b"), + "name" : { "first" : "Guido", "last" : "van Rossum" }, + "birth" : ISODate("1956-01-31T05:00:00Z"), + "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 ``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`` + The following operation performs an insert into the ``csbios`` collection since the document contains an ``_id`` field whose value - ``10`` is not found in the ``presidents`` collection: + ``10`` is not found in the ``csbios`` 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 } ] - } ) + db.csbios.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', + year: '2011', + by: 'Free Software Foundation' } + ] + } + ) \ No newline at end of file diff --git a/draft/applications/delete.txt b/draft/applications/delete.txt index 1845a249690..c1e59eedaa0 100644 --- a/draft/applications/delete.txt +++ b/draft/applications/delete.txt @@ -37,35 +37,35 @@ Consider the following examples that illustrate the usage of the ` 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``: + The following operation deletes all documents from the ``csbios`` + collection where the ``first`` field in the subdocument ``name`` + starts with ``G``: .. code-block:: javascript - db.presidents.remove( { title: 'Governor' } ) + db.csbios.remove( { 'name.first' : /^G/ } ) - 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``: + ``csbios`` collection where the ``turing`` field equals + ``true``: .. code-block:: javascript - db.presidents.remove( { state: 'Virginia' }, 1 ) + db.csbios.remove( { turing: true }, 1 ) - 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`` + The following operation deletes all documents from the ``csbios`` collection: .. code-block:: javascript - db.presidents.remove() + db.csbios.remove() \ No newline at end of file diff --git a/draft/applications/read.txt b/draft/applications/read.txt index 87def4706ce..0d95c9ce20b 100644 --- a/draft/applications/read.txt +++ b/draft/applications/read.txt @@ -5,8 +5,11 @@ Read .. default-domain:: mongodb Read operation selects documents from a :term:`collection`. MongoDB -provides the :ref:`find ` method to perform read -operations. +provides the following methods to perform create operations: + +- :ref:`find ` + +- :ref:`findOne ` .. _crud-read-find: @@ -24,7 +27,7 @@ syntax: .. code-block:: javascript - db.collection.find( , ) + db.collection.find( , ) The :method:`find() ` method is analogous to the ``SQL SELECT`` with the ``query`` argument analogous to the ``WHERE`` @@ -43,108 +46,216 @@ Consider the following examples that illustrate the usage of the - 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: + - The following operation returns all documents (or more + precisely, a cursor to all documents) in the ``csbios`` + collection: - .. code-block:: javascript + .. code-block:: javascript - db.presidents.find() + db.csbios.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``: + - The following operation returns all documents in the ``csbios`` + collection where the field ``_id`` equals ``5`` or + ``ObjectId("507c35dd8fada716c89d0013")``: .. code-block:: javascript - db.presidents.find( { state: 'Virginia' } ) + db.csbios.find( { _id: { $in: [ 5, ObjectId("507c35dd8fada716c89d0013") ] } } ) - - The following operation returns all documents in the ``presidents`` - collection where the array field ``title`` contains the element - ``Governor``: + - The following operation returns all documents in the ``csbios`` + collection where the array field ``contribs`` contains the element + ``UNIX``: .. code-block:: javascript - db.presidents.find( { title: 'Governor' } ) + db.csbios.find( { contribs: 'UNIX' } ) - - The following operation returns all documents in the ``presidents`` + - The following operation returns all documents in the ``csbios`` collection where the subdocument ``name`` contains a field - ``first`` with value ``John`` and a field ``last`` with the value - ``Adams``: + ``first`` with the value ``Yukihiro`` and a field ``last`` with the + value ``Matsumoto``: .. code-block:: javascript - db.presidents.find( { 'name.first': 'John', 'name.last': 'Adams' } ) + db.csbios.find( { 'name.first': 'Yukihiro', 'name.last': 'Matsumoto' } ) - The operation finds documents with ``name : { first: 'John', last: - 'Adams' }`` and ``name : { first: 'John', middle : 'Quincy', last : - 'Adams'}``. + The query matches the document with ``name`` field equal to ``{ + first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'}``. - - The following operation returns all documents in the ``presidents`` - collection where the subdocument ``name`` is ``{ first: - 'John', last: 'Adams' }``: + - The following operation returns all documents in the ``csbios`` + collection where the subdocument ``name`` is *exactly* ``{ first: + 'Yukihiro', last: 'Matsumoto' }``, including the order of the + fields: .. code-block:: javascript - db.presidents.find( { name: { first: 'John', last: 'Adams' } } ) + db.csbios.find( { name: { first: 'Yukihiro', last: 'Matsumoto' } } ) - The operation finds only the documents with ``name : { first: - 'John', last: 'Adams' }``. + The query does *not* match the document with ``name`` field equal + to ``{ first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'}`` nor + does it match a document with the ``name`` field equal to ``{ last: + 'Matsumoto' , first: 'Yukihiro' }``. - - 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``: + - The following operation returns all documents in the ``csbios`` + 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.presidents.find( { 'name.first': { $in: ['John', 'James'] } } ) + db.csbios.find( { $or: [ { 'name.first' : /^G/ }, + { birth: { $lt: new Date('01/01/1945') } } + ] } ) + - - 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``: + - The following operation returns all documents in the ``csbios`` + 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.presidents.find( { - state: 'Virginia' , - 'name.first': { $in: ['John', 'James'] } - } ) + db.csbios.find( { 'name.first': /^K/, + contribs: 'UNIX' } ) - - 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``: + - The following operation returns all documents in the ``csbios`` + collection where ``awards`` array contains a subdocument element + that contains the ``award`` field equal to ``Turing Award`` and the + ``year`` field greater than ``1980``: .. code-block:: javascript - db.presidents.find( { office: { $elemMatch: { - term: 1, - from: { $lt: 1800 } - } } } ) + db.csbios.find( { awards: { $elemMatch: { + award: 'Turing Award', + year: { $gt: '1980' } + } } } ) - 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: + - The following operation finds all documents in the ``csbios`` + collection and returns only the ``name`` field, the ``contribs`` + field, and the ``_id`` field: + + .. code-block:: javascript + + db.csbios.find( { }, { name: 1, contribs: 1 } ) + + - The following operation finds the documents in the ``csbios`` + 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`` + field from the matching documents: + + .. code-block:: javascript + + db.csbios.find( { contribs: 'OOP' }, + { _id: 0, 'name.first': 0, birth: 0 } ) + +In addition to the ``query`` and the ``projection`` arguments, MongoDB +provides the cursor methods that work with the :method:`find() +` method: + +- The :method:`sort ` orders the resulting documents and + is analogous to ``SQL ORDER BY``. + + The following operation returns all documents (or more precisely, a + cursor to all documents) in the ``csbios`` collection ordered by the + ``name`` field ascending: + + .. code-block:: javascript + + db.csbios.find().sort( { name: 1 } ) + +- The :method:`limit ` method limits the number of + documents returned and is analogous to ``SQL LIMIT``. + + The following operation returns at most ``5`` documents (or more + precisely, a cursor to at most 5 documents) in the ``csbios`` + collection: + + .. code-block:: javascript + + db.csbios.find().limit( 5 ) + + +.. _crud-read-findOne: + +FindOne +------- + +The :method:`findOne() ` method selects a +single document from a collection and returns the document rather than +a cursor. + +The :method:`findOne() ` method has the following +syntax: + +.. code-block:: javascript + + db.collection.findOne( , ) + +The :method:`findOne() ` method is similar to +the :method:`find() ` method except the +:method:`findOne() ` method returns the +single document rather than a cursor. + +Consider the following examples that illustrate the usage of the +:method:`findOne() ` method: + +- If there is no ``query`` argument, the :method:`findOne() + ` method selects just one document from a + collection. + + - The following operation returns a single document from the + ``csbios`` collection: + + .. code-block:: javascript + + db.csbios.findOne() + +- If there is a ``query`` argument, the :method:`findOne() + ` method selects the first document from a + collection that meets the ``query`` argument: + + - The following operation returns the first matching document from + the ``csbios`` 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') } } + ] } ) + +- If there is a ``projection`` argument, the :method:`findOne() + ` 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 finds a document in the ``csbios`` + collection and returns only the ``name`` field, the ``contribs`` + field, and the ``_id`` field: .. code-block:: javascript - db.presidents.find( { }, { name: 1, state: 1 } ) + db.csbios.findOne( { }, { name: 1, contribs: 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``: + - The following operation finds a document in the ``csbios`` + 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`` + field from the matching documents: .. code-block:: javascript - db.presidents.find( { state: 'Virginia' }, - { _id: 0, 'name.first': 0, office: 0 } ) + db.csbios.findOne( { contribs: 'OOP' }, + { _id: 0, 'name.first': 0, birth: 0 } ) + \ No newline at end of file diff --git a/draft/applications/update.txt b/draft/applications/update.txt index 92f868507c9..4d9954ce9c5 100644 --- a/draft/applications/update.txt +++ b/draft/applications/update.txt @@ -50,156 +50,179 @@ Consider the following examples that illustrate the usage of the 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: + 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: .. code-block:: javascript - db.presidents.update( { _id: 1 }, - { $set: { spouse: 'Martha Dandridge Custis' }, - $push: { email: { type: 'personal', - addr: 'i.m.number.1@example.net' } } - } ) + db.csbios.update( { _id: 1 }, + { $set: { 'name.middle': 'Warner' }, + $push: { awards: { award: 'IBM Fellow', + year: '1963', + by: 'IBM' } } + } ) - 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 + The following operation queries the ``csbios`` collection for the first document that has an ``_id`` field equal to ``3`` and removes - the ``spouse`` field from the document: + the ``birth`` field from the document: .. code-block:: javascript - db.presidents.update( { _id: 3 }, - { $unset: { spouse: 1 } } ) + db.csbios.update( { _id: 3 }, + { $unset: { birth: 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``: + The following operation queries the ``csbios`` 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.presidents.update( { _id: 1 }, - { $set: { vp: 'John Adams' } } ) + db.csbios.update( { _id: 3 }, + { $set: { mbranch: 'Navy', + 'name.aka': 'Amazing Grace'} } ) - 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 + The following operation queries the ``csbios`` 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 + last: 'McCarthy' }`` 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 } ] - } ) + 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' } + ] + } ) - 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 + The following operation queries the ``csbios`` collection for + the document with ``_id`` field equal to ``1`` and updates the + second element in the ``contribs`` array: + + .. code-block:: javascript - db.presidents.update ( { _id: 6 } , - { $set: { 'title.1': "Secretary of State" } } ) + db.csbios.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. - 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: + The following operation queries the ``csbios`` collection for a + document with the ``_id`` field equal to ``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 + document: - .. code-block:: javascript + .. code-block:: javascript + + db.csbios.update( { _id: 3, 'contribs': 'compiler' }, + { $set: { 'contribs.$': 'A compiler' } } ) - 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 + + The following operation queries the ``csbios`` collection for a + document with the ``_id`` field equal to ``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 first matching subdocument: - .. code-block:: javascript + .. code-block:: javascript - db.presidents.update ( { _id: 6, 'email.type': "home" } , - { $set: { 'email.$.addr': "jqa@example.net" } } ) + db.csbios.update( { _id: 6, 'awards.by': 'ACM' } , + { $set: { 'awards.$.by': 'Association for Computing Machinery' } } ) - If the ``options`` argument contains the ``multi`` option set to ``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: + The following operation queries the ``csbios`` 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.presidents.update( { 'name.first': 'John', 'name.last': 'Adams' }, - { $set: { dynasty: true } }, - { multi: true } ) + db.csbios.update( { 'awards.award': 'Turing' }, + { $set: { turing: 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. + The following operation queries the ``csbios`` collection for a + document with the ``_id`` field equal to ``11`` and the ``name`` + field equal to ``{ first: 'James', last: 'Gosling'}``. If a document + is found, the operation performs an update operation. 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 and + the ``query`` argument since the ``update`` argument contains only + :ref:`update operators ` expressions. .. 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 } ) + db.csbios.update( + { _id:11, name: { first: 'James', last: 'Gosling' } }, + { + $set: { + born: new Date('May 19, 1955'), + contribs: [ 'Java' ], + awards: [ + { award: 'The Economist Innovation Award', + year: '2002', + by: 'The Economist' }, + { award: 'Officer of the Order of Canada', + year: '2007', + by: 'Canada' } + ] + } + }, + { upsert: true } + ) See also :ref:`Create `. @@ -230,23 +253,17 @@ Consider the following examples of the :method:`save() performs an update that replaces the existing document with the document argument. - The following operation queries the ``presidents`` collection for a + The following operation queries the ``csbios`` collection for a document where the ``_id`` equals - ``ObjectId("5076d6e28fada716c89d000f")`` and replaces the document + ``ObjectId("507c4e138fada716c89d0014")`` 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 } ] } ) + db.csbios.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() @@ -256,18 +273,11 @@ Consider the following examples of the :method:`save() The following operation adds the ``_id`` field to the document, assigns to the field a unique ``ObjectId``, and inserts into the - ``presidents`` collection: + ``csbios`` 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 } ] } ) + db.csbios.save( { name: { first: 'Larry', last: 'Wall' }, + contribs: [ 'Perl' ] } ) See also :ref:`Create `. diff --git a/draft/core/documents.txt b/draft/core/documents.txt new file mode 100644 index 00000000000..1872bbacb94 --- /dev/null +++ b/draft/core/documents.txt @@ -0,0 +1,130 @@ +========= +Documents +========= + +.. default-domain:: mongodb + +Documents in MongoDB refer to the data structure of the records stored +in :term:`collections `, the query criteria, the update actions, and +other arguments to MongoDB methods and operators. + +Documents in MongoDB are :term:`BSON` objects with support for the full +range of :term:`BSON types`; however, conceptually, documents may be +viewed as :term:`JSON` objects with the following structure: + +.. code-block:: javascript + + { + field1: value1, + field2: value2, + field3: value3, + ... + fieldN: valueN + } + +Having support for the full range of :term:`BSON types`, MongoDB +documents may contain ``field:value`` pairs where the value can be +another document, an array, an array of documents as well as the basic +types such as ``Double``, ``String``, or ``Date``. + +Consider the following examples of MongoDB documents: + +- The following document specifies a record in a collection. Documents + in a collection contain a unique ``_id`` field: + + .. code-block:: javascript + + { + _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: 'National Medal of Science', + year: '1975', + by: 'National Science Foundation' }, + { award: 'Turing Award', + year: '1977', + by: 'ACM' } + ] + } + + .. include:: /includes/note-insert-id-field.rst + +- The following documents specify the query criteria: + + - The following document specifies the query criteria where ``_id`` + is equal to ``1``: + + .. code-block:: javascript + + { _id: 1 } + + - The following document specifies the query criteria where ``_id`` + is greater to ``3``: + + .. code-block:: javascript + + { _id: { $gt: 3 } } + + - The following document specifies the query criteria where ``_id`` + is equal to ``1`` and the ``name`` field equals the document ``{ + first: 'John', last: 'Backus' }``: + + .. code-block:: javascript + + { _id: 1, name: { first: 'John', last: 'Backus' } } + + When passed as an argument to methods such as the :method:`find() + ` method or the :method:`update() + ` method, the query document limits the + records returned or updated: + + .. code-block:: javascript + + db.csbios.find( { _id: 1 } ) + db.csbios.find( { _id: { $gt: 3 } } ) + db.csbios.find( { _id: 1, name: { first: 'John', last: 'Backus' } } ) + +- The following document specifies the update actions: + + .. code-block:: javascript + + { $set: { 'name.middle': 'Warner' }, + $push: { awards: { award: 'IBM Fellow', + year: '1963', + by: 'IBM' } + + When passed as an argument to the :method:`update() + ` method, the document specifies the update + actions to perform on the document: + + .. code-block:: javascript + + db.csbios.update( { _id: 1 }, + { $set: { 'name.middle': 'Warner' }, + $push: { awards: { award: 'IBM Fellow', + year: '1963', + by: 'IBM' } } } + ) + +- The following document specifies the sort order: + + .. code-block:: javascript + + { 'name.last': 1 } + + When passed as an argument to the :method:`sort() ` + method, the document specifies the sort order: + + .. code-block:: javascript + + db.csbios.find().sort( { 'name.last': 1 } ) + + When passed as an argument to the :method:`ensureIndex() ` + method, the document specifies the index to create: + + .. code-block:: javascript + + db.csbios.ensureIndex( { 'name.last': 1 } )