DOCS-555 update the main crud reference docs

Author: kay-kim

draft/applications/create.txt

@@ -0,0 +1,86 @@
+======
+Create
+======
+
+.. default-domain:: mongodb
+
+Create operation adds new :term:`documents <document>` to a
+:term:`collection`. MongoDB provides the :ref:`insert() <insert>`
+method to perform create operations. Additionally, the :ref:`update()
+with upsert option <update_and_save>` method and the :ref:`save()
+<update_and_save>` method also provide functionality to create
+documents.
+
+All three methods exhibit the following behavior during the create
+operation:
+
+- If the new document does not specify an :term:`_id` field, these
+  methods will add the ``_id`` field to the document and assign as
+  its value a unique :term:`objectid`.
+
+- If the document specifies a new field, these methods will add
+  the document with the new field **without** requiring a schema change
+  to the collection or any change to the existing documents.
+
+Keep in mind that MongoDB v2.2 has a limit on document size of 16
+megabytes (MB).
+
+
+.. _insert:
+
+Insert()
+--------
+
+The :method:`insert() <db.collection.insert()>` method is the primary
+method to insert a document or documents into a collection. The
+:method:`insert() <db.collection.insert()>` is analogous to the ``SQL
+INSERT`` except the :method:`insert() <db.collection.insert()>` method
+provides these additional functionalities:
+
+- If the collection does not exist, then the :method:`insert()
+  <db.collection.insert()>` method will create the collection.
+
+- If the new document does not specify an ``_id`` field, then
+  :method:`insert() <db.collection.insert()>` will add the ``_id``
+  field to the document and assign a unique ``objectid`` as its
+  value.
+  
+- If passed an array of documents, the :method:`insert()
+  <db.collection.insert()>` method can perform bulk inserts into a
+  collection.
+
+.. _update_and_save:
+
+Update() with Upsert Option and Save()
+--------------------------------------
+
+Both the :method:`update() <db.collection.update()>` method and the
+:method:`save() <db.collection.save()>` method will be discussed in
+fuller detail in the Update section. But a quick introduction to their
+insert capabilities is presented here for completeness.
+
+Update() with Upsert Option
+````````````````````````````
+
+The :method:`update() with upsert option <db.collection.update()>` or
+an ``upsert`` will insert a single document into a collection if no
+document exists that matches the update query criteria. The inserted
+document will contain the fields and values of both the update query
+criteria and the update operation. If the ``_id`` is not specified in
+either the query criteria and the update operation documents, the
+``upsert`` will add the ``_id`` field to the document and assign a
+unique ``objectid`` as its value.
+
+The ``upsert`` removes the need to perform a separate query to
+check for the existence of a record before performing either an insert
+or an update.
+
+Save()
+``````
+
+The :method:`save() <db.collection.save()>` will insert a document into
+a :term:`collection` if the document does not contain the ``_id`` field
+or contains an ``_id`` field with a value not in the collection. If the
+``_id`` is not specified in the document parameter, :method:`save()
+<db.collection.save()>` will add the ``_id`` field to the document
+and assign a unique ``objectid`` as its value.

draft/applications/delete.txt

@@ -0,0 +1,24 @@
+======
+Delete
+======
+
+.. default-domain:: mongodb
+
+Delete operation removes documents from a :term:`collection`. MongoDB
+provides the :ref:`remove() <remove>` method to perform delete operations.
+
+.. _remove:
+
+Remove()
+--------
+
+The :method:`remove() <db.collection.remove()>` method is the method to
+delete documents from a collection. By default, the :method:`remove()
+<db.collection.remove()>` deletes all documents that meet the delete
+selection criteria. However, using the ``justOne`` option limits the
+deletion to just one document.
+
+Note that calling :method:`remove() <db.collection.remove()>` without
+specifying the delete selection criteria removes all documents in the
+collection.
+

draft/applications/read.txt

@@ -0,0 +1,45 @@
+====
+Read
+====
+
+.. default-domain:: mongodb
+
+Read operation selects documents from a collection. MongoDB
+provides the :ref:`find() <find>` method to perform read operations.
+Additionally, the :ref:`Aggregation Framework <aggregation>` also
+provides read operations that involve various aggregation functions,
+such as ``SUM``.
+
+.. _find:
+
+Find()
+------
+
+The :method:`find() <db.collection.find()>` method is the primary
+method to select documents from a collection. The find() method returns
+a cursor to the selected documents. The :method:`find()
+<db.collection.find()>` method can accept a selection criteria on
+document fields, including array fields and subdocuments, to limit the
+selection.
+
+The :method:`find() <db.collection.find()>` method offers the
+flexibility to specify the fields to return through the include/exclude
+flags of the ``projection`` document. For instance, if selecting 11 out
+of 15 fields, with the :method:`find() <db.collection.find()>` method, you
+can choose to specify the 4 to exclude rather than the 11 to include.
+
+.. TODO -- sort/limit/other options...
+
+.. _aggregation:
+
+Aggregation Framework
+---------------------
+
+The Aggregation Framework provides a rich set of tools for performing
+various sequence of operations, not the least of which is the read operation.
+
+Although the Aggregation Framework is discussed in detail in its own
+section, a brief introduction to the aggregation read operation is
+provided here for completeness.
+
+.. seealso:: :doc:`/applications/aggregation`

draft/applications/update.txt

@@ -0,0 +1,67 @@
+======
+Update
+======
+
+.. default-domain:: mongodb
+
+Update operation modifies an existing :term:`document <document>` or
+documents in a :term:`collection`. MongoDB provides the :ref:`update()
+<update>` method to perform update operations.
+Additionally, the :ref:`save() <save>` method also provides the
+functionality to update documents.
+
+Note that the two methods also provide the option to insert a new
+document into a collection.
+
+.. TODO  ? findAndModify?
+
+.. _update:
+
+Update
+------
+
+The :method:`update() <db.collection.update()>` method is the primary
+method to update an existing document or documents in a collection. The
+:method:`update() <db.collection.update()>` method can either replace
+the existing document with the new document or update specific fields
+in the existing document.
+
+By default the :method:`update() <db.collection.update()>` method
+updates a single document, but by using the ``multi`` option, the
+method can update all documents that match the update selection
+criteria.
+
+Additionally, if no existing document match the update selection
+criteria, by using the ``upsert`` option, the method can insert
+a new document into the collection.
+
+Note also that the :method:`update() <db.collection.update()>` method
+can also modify the name of the ``field`` in a document using the
+:operator:`$rename` operator.
+
+ .. _save:
+
+Save
+----
+
+The :method:`save() <db.collection.save()>` method updates an existing
+document or inserts a document depending on the parameter. The
+:method:`save() <db.collection.save()>` method is like an ``upsert``
+operation that has the update selection criteria on the :term:`_id`
+field:
+
+- If no ``_id`` field exists, the :method:`save()
+  <db.collection.save()>` method performs an insert. The insert will
+  add the ``_id`` field and assign a unique :term:`objectid` as its
+  value.
+
+- If ``_id`` field exists but does not match any document in the
+  collection, the :method:`save() <db.collection.save()>` method
+  performs an insert. The insert will add the ``_id`` field and assign
+  a unique :term:`objectid` as its value.
+  
+- If ``_id`` field exists and matches an existing document in the
+  collection, the :method:`save() <db.collection.save()>` method
+  performs an update that replaces the existing document with the new
+  document. 
+  

source/reference/method/db.collection.find.txt

@@ -6,18 +6,118 @@ db.collection.find()
 
 .. method:: db.collection.find(query,projection)
 
-   :param document query: A :term:`document` that specifies the
-                          :term:`query` using the JSON-like syntax and
-                          :doc:`query operators </reference/operators>`.
+   The :method:`find() <db.collection.find()>` method selects
+   documents in a collection and returns a
+   :term:`cursor` to the selected documents.
 
-   :param document projection: Optional. A :term:`document` that
-                               controls the :term:`projection`, or the
-                               contents of the data returned.
+   The :method:`find() <db.collection.find()>` method can take the
+   following parameters:
 
-   :returns: A cursor whose iteration visits all of the documents that
-             match the ``query`` document.
+   :param document query:
 
-   Queries for documents matching ``query``. The argument to
-   :method:`find() <db.collection.find>` takes the form of a :term:`document`. See
-   the ":doc:`/reference/operators`" for an overview of the available
-   operators for specifying and narrowing the query.
+         Optional. A document that specifies
+         the selection criteria using :doc:`query operators
+         </reference/operators>`. Omit the ``query`` parameter or pass
+         an empty ``{}`` document to return all documents in the
+         collection.
+
+   :param document projection:
+          
+          Optional. A document that controls the fields to return, or
+          the :term:`projection`. The ``projection`` document has
+          the following syntax:
+          
+          .. code-block:: javascript
+
+              { field1: boolean, field2: boolean ... }
+
+          The ``boolean`` can take the following include/exclude values:
+          
+          - ``1`` or ``true`` to include. The :method:`find()
+            <db.collection.find()>` method always includes the
+            :term:`_id` field even if the field is not explicitly
+            stated to return in the :term:`projection` parameter. 
+
+          - ``0`` or ``false`` to exclude.
+
+          Currently, you cannot mix include and exclude fields in
+          the projection document.
+
+   :returns:
+
+      A :term:`cursor` to the documents that match
+      the ``query`` criteria and contain the ``projection`` fields.
+
+   .. examples-begin
+
+   Consider the following examples of the :method:`find()
+   <db.collection.find()>` method.
+
+   - To select all documents in a collection, call the
+     :method:`find() <db.collection.find()>` method with no parameters:
+
+     .. code-block:: javascript
+
+        db.products.find()
+
+     The query will return all the documents with all the fields from
+     the collection ``products``. By default, in the :program:`mongo`
+     shell, the cursor returns the first batch of 20 matching
+     documents. In the :program:`mongo` shell, iterate through the next
+     batch by typing ``it``. Use the appropriate cursor
+     handling mechanism for your specific language driver.
+
+   - To select the documents that match a selection criteria, call the
+     :method:`find() <db.collection.find()>` method with the ``query``
+     criteria:
+
+     .. code-block:: javascript
+
+        db.products.find( { qty: { $gt: 25 } } )
+
+     The query will return all the documents from the collection
+     ``products`` where ``qty`` is greater than ``25``. The resulting
+     documents will contain all their respective fields.
+
+   - To select the documents that match a selection criteria and return
+     only certain fields, call the :method:`find()
+     <db.collection.find()>` method with the ``query`` criteria and the
+     ``projection`` parameter using the ``include`` syntax:
+
+     .. code-block:: javascript
+
+        db.products.find( { qty: { $gt: 25 } }, { item: 1, qty: 1 } )
+    
+     The query will return all the documents from the collection
+     ``products`` where ``qty`` is greater than ``25``. The resulting
+     documents will contain only the ``_id``, ``item``, and ``qty``
+     fields. Note that the ``_id`` field is returned even without
+     explicitly including it.
+
+     .. code-block:: javascript
+
+        { "_id" : 11, "item" : "pencil", "qty" : 50 }
+        { "_id" : ObjectId("50634d86be4617f17bb159cd"), "item" : "bottle", "qty" : 30 }
+        { "_id" : ObjectId("50634dbcbe4617f17bb159d0"), "item" : "paper", "qty" : 100 }
+
+   - To select the documents that match a selection criteria and
+     exclude certain fields from the resulting documents, call the
+     :method:`find() <db.collection.find()>` method with the ``query``
+     criteria and the ``projection`` parameter using the ``exclude`` syntax:
+
+     .. code-block:: javascript
+
+        db.products.find( { qty: { $gt: 25 } }, { _id: 0, qty: 0 } )
+    
+     The query will return all the documents from the collection
+     ``products`` where ``qty`` is greater than ``25``. The resulting
+     documents will contain all fields **except** the ``_id`` and
+     ``qty`` fields. 
+     
+     .. code-block:: javascript
+     
+        { "item" : "pencil", "type" : "no.2" }
+        { "item" : "bottle", "type" : "blue" }
+        { "item" : "paper" }
+
+   .. examples-end