DOCS-617 crud draft edits

kay-kim · kay-kim · commit 6d58fc58208a · 2012-10-22T12:33:24.000-04:00
diff --git a/draft/applications/create.txt b/draft/applications/create.txt
@@ -51,7 +51,7 @@ following syntax:
 The :method:`insert() <db.collection.insert()>` method is analogous to
 the ``SQL INSERT``.
 
-Consider the following examples that illustrate the usage of the
+Consider the following examples that illustrate the use of the
 :method:`insert() <db.collection.insert()>` method:
 
 - If the collection does not exist, then the :method:`insert()
@@ -90,8 +90,12 @@ Consider the following examples that illustrate the usage of the
 
   .. code-block:: javascript
 
-     > db.csbios.find()
-     
+     db.csbios.find()
+
+  This will return the document from the ``csbios`` collection:
+
+  .. code-block:: javascript
+
      { 
        "_id" : 1, 
        "name" : { "first" : "John", "last" :"Backus" },
@@ -143,12 +147,17 @@ Consider the following examples that illustrate the usage of the
 
      } )
 
-  You can verify the addition of the ``_id`` field to the inserted
-  document by the querying the ``csbios`` collection:
+  You can verify the inserted document by the querying the ``csbios``
+  collection:
 
   .. code-block:: javascript
 
-     > db.csbios.find( { name: { first: 'John', last: 'McCarthy' } } )
+     db.csbios.find( { name: { first: 'John', last: 'McCarthy' } } )
+
+  The returned document contains an ``_id`` field with the generated
+  ``ObjectId`` value:
+
+  .. code-block:: javascript
 
      {
        "_id" : ObjectId("507c294cbcf86cd7994f6c0a"),
@@ -169,7 +178,6 @@ Consider the following examples that illustrate the usage of the
                   ] 
      }
 
-
 - If the argument to the :method:`insert() <db.collection.insert()>`
   method is an array of documents, then the :method:`insert()
   <db.collection.insert()>` method performs a bulk insert into a
@@ -265,7 +273,7 @@ An ``upsert`` has the following syntax:
                          <update>,
                          { upsert: true } )
 
-Consider the following examples that illustrate the usage of the
+Consider the following examples that illustrate the use of the
 ``upsert`` to perform create operations:
 
 - If the ``update`` argument contains only ``field:value`` pairs and no
@@ -352,14 +360,18 @@ Consider the following examples that illustrate the usage of the
         { upsert: true }
      )
 
-  You can verify that the inserted document contains the ``_id`` and
-  the ``name`` fields from the ``query`` argument as well as the fields
-  and values from the ``update`` argument by querying the
-  ``csbios`` collection:
+  You can verify the inserted document by querying the ``csbios``
+  collection:
 
   .. code-block:: javascript
 
-     > db.csbios.find( { _id: 7 } )
+     db.csbios.find( { _id: 7 } )
+
+  The returned document contains the ``_id`` and the ``name`` fields
+  from the ``query`` argument as well as the fields and values from the
+  ``update`` argument:
+
+  .. code-block:: javascript
 
      {
        "_id" : 7,
@@ -416,12 +428,17 @@ Consider the following examples that illustrate the usage of the
         { upsert: true }
      )
 
-  You can verify the addition of the ``_id`` field to the inserted
-  document by the querying the ``csbios`` collection:
+  You can verify the inserted document by the querying the ``csbios``
+  collection:
 
   .. code-block:: javascript
 
-     > db.csbios.find( { name: { first: 'Bjarne', last: 'Stroustrup' } } )
+     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"),
@@ -457,7 +474,7 @@ following syntax:
 
    db.collection.save( <document> )
 
-Consider the following examples that illustrate the usage of the
+Consider the following examples that illustrate the use of the
 :method:`insert() <db.collection.insert()>` method for create
 operations:
 
@@ -489,7 +506,12 @@ operations:
 
   .. code-block:: javascript
 
-     > db.csbios.find( { name: { first: 'Guido', last: 'van Rossum'} } )
+     db.csbios.find( { name: { first: 'Guido', last: 'van Rossum'} } )
+
+  The returned document contains an ``_id`` field with the generated
+  ``ObjectId`` value:
+
+  .. code-block:: javascript
 
      {
        "_id" : ObjectId("507c387cbcf86cd7994f6c0b"),
@@ -503,7 +525,7 @@ operations:
                    { "award" : "NLUUG Award",
                      "year" : "2003",
                      "by" : "NLUUG" }
-                 ] 
+                 ]
      }
 
 - If the ``document`` contains an ``_id`` field but has a value not
@@ -516,18 +538,16 @@ operations:
 
   .. code-block:: javascript
 
-     db.csbios.save( 
-        { 
+     db.csbios.save(
+        {
           _id: 10,
           name: { first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'},
           birth: new Date('Apr 14, 1965'),
           contribs: [ 'Ruby' ],
-          awards: [ 
+          awards: [
                     { award: 'Award for the Advancement of Free Software',
                       year: '2011',
                       by: 'Free Software Foundation' }
                   ]
         }
      )
-
- 
diff --git a/draft/applications/read.txt b/draft/applications/read.txt
@@ -5,7 +5,7 @@ Read
 .. default-domain:: mongodb
 
 Read operation selects documents from a :term:`collection`. MongoDB
-provides the following methods to perform create operations:
+provides the following methods to perform read operations:
 
 - :ref:`find <crud-read-find>`
 
@@ -30,13 +30,43 @@ syntax:
    db.collection.find( <query>, <projection> )
 
 The :method:`find() <db.collection.find()>` method is analogous to the
-``SQL SELECT`` with the ``query`` argument analogous to the ``WHERE``
-statement and the ``projection`` argument analogous to the selected
-fields to return.
+``SQL SELECT`` with:
 
-Consider the following examples that illustrate the usage of the
+- The ``query`` argument analogous to the ``WHERE`` statement.
+
+- The ``projection`` argument analogous to the selected fields to
+  return.
+
+Consider the following examples that illustrate the use of the
 :method:`find() <db.collection.find()>` method:
 
+The examples refer to a collection named ``csbios`` that contains
+documents with the following prototype:
+
+.. code-block:: javascript
+
+   {
+     "_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" }
+                ]
+   }
+
 .. note::
 
    In the :program:`mongo` shell, you can format the output by adding
@@ -83,9 +113,13 @@ Consider the following examples that illustrate the usage of the
 
        db.csbios.find( { 'name.first': 'Yukihiro', 'name.last': 'Matsumoto' } )
 
-    The query matches the document with ``name`` field equal to ``{
-    first: 'Yukihiro', aka: 'Matz', 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 both: 
+    
+    - ``name: { first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'}``
+    - ``name: { last: 'Matsumoto', first: 'Yukihiro'}``.
+
   - 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
@@ -95,10 +129,12 @@ Consider the following examples that illustrate the usage of the
 
        db.csbios.find( { name: { first: 'Yukihiro', last: 'Matsumoto' } } )
 
-    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 query *only* matches the document where the ``name`` field is
+    *exactly* ``{ first: 'Yukihiro', last: 'Matsumoto' }``. For
+    instance, the query would **not** match either:
+
+    - ``name: { first: 'Yukihiro', aka: 'Matz', last: 'Matsumoto'}`` 
+    - ``name: { last: 'Matsumoto' , first: 'Yukihiro' }``.
 
   - The following operation returns all documents in the ``csbios``
     collection where either the field ``first`` in the subdocument
@@ -111,7 +147,6 @@ Consider the following examples that illustrate the usage of the
                                 { birth: { $lt: new Date('01/01/1945') } }
                               ]  } )
 
-
   - 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``
@@ -147,6 +182,19 @@ Consider the following examples that illustrate the usage of the
 
        db.csbios.find( { }, { name: 1, contribs: 1 } )
 
+  - The following operation finds all documents in the ``csbios``
+    collection and returns only the ``name`` field and the ``contribs``
+    field:
+
+    .. code-block:: javascript
+
+       db.csbios.find( { }, { name: 1, contribs: 1, _id: 0 } )
+
+    .. note:: 
+
+       The ``projection`` argument cannot contain both include and
+       exclude specifications *except* for the exclusion of the ``_id``.
+     
   - 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
@@ -184,7 +232,6 @@ provides the cursor methods that work with the :method:`find()
 
      db.csbios.find().limit( 5 )
 
-
 .. _crud-read-findOne:
 
 FindOne
@@ -206,7 +253,7 @@ the :method:`find() <db.collection.find()>` method except the
 :method:`findOne() <db.collection.findOne()>` method returns the
 single document rather than a cursor.
 
-Consider the following examples that illustrate the usage of the
+Consider the following examples that illustrate the use of the
 :method:`findOne() <db.collection.findOne()>` method:
 
 - If there is no ``query`` argument, the :method:`findOne()
diff --git a/draft/applications/update.txt b/draft/applications/update.txt
@@ -42,7 +42,7 @@ the ``SQL UPDATE`` with the ``query`` argument analogous to the
 <db.collection.update()>` method provides additional flexibility and
 control in use.
 
-Consider the following examples that illustrate the usage of the
+Consider the following examples that illustrate the use of the
 :method:`update() <db.collection.update()>` method:
 
 - If the ``update`` argument contains only :ref:`update operators
diff --git a/draft/core/documents.txt b/draft/core/documents.txt
@@ -4,13 +4,15 @@ Documents
 
 .. default-domain:: mongodb
 
-Documents in MongoDB refer to the data structure of the records stored
-in :term:`collections <collection>`, the query criteria, the update actions, and
-other arguments to MongoDB methods and operators.
+The document structure in MongoDB refer to the data structure of the
+records stored in :term:`collections <collection>`, 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:
+The document structure 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
 
@@ -69,7 +71,7 @@ Consider the following examples of MongoDB documents:
        { _id: { $gt: 3 } }
 
   - The following document specifies the query criteria where ``_id``
-    is equal to ``1`` and the ``name`` field equals the document ``{
+    is equal to ``1`` **and** the ``name`` field equals the document ``{
     first: 'John', last: 'Backus' }``:
 
     .. code-block:: javascript
@@ -112,19 +114,26 @@ Consider the following examples of MongoDB documents:
 - The following document specifies the sort order:
 
   .. code-block:: javascript
-  
+
      {  'name.last': 1  }
 
   When passed as an argument to the :method:`sort() <cursor.sort()>`
-  method, the document specifies the sort order:
+  method, the document specifies the sort order of the results:
 
   .. code-block:: javascript
-  
+
      db.csbios.find().sort( { 'name.last': 1 } )
 
-  When passed as an argument to the :method:`ensureIndex() <db.collection.ensureIndex()>`
-  method, the document specifies the index to create:
+- The following document specifies the index to create:
+
+  .. code-block:: javascript
+
+     {  id:1, 'name.last': 1 }
+
+  When passed as an argument to the :method:`ensureIndex()
+  <db.collection.ensureIndex()>` method, the document specifies the
+  multi-key index to create on the fields ``_id`` and ``name.last``:
 
   .. code-block:: javascript
 
-     db.csbios.ensureIndex( { 'name.last': 1 } )
+     db.csbios.ensureIndex( {  id:1, 'name.last': 1 } )
diff --git a/draft/core/read-operations.txt b/draft/core/read-operations.txt
diff --git a/source/reference/method/db.collection.find.txt b/source/reference/method/db.collection.find.txt
