diff --git a/draft/applications/create.txt b/draft/applications/create.txt index 555a653e981..c6b189afc8e 100644 --- a/draft/applications/create.txt +++ b/draft/applications/create.txt @@ -6,10 +6,10 @@ Create Of the four basic database operations (i.e. CRUD), *create* operations are those that add new records or :term:`documents ` to a -:term:`collection` in MongoDB. For more information about document -creation and other write operations see :ref:`/core/write-operations`, -for documentation of other basic database operations see the -:doc:`/crud` page. +:term:`collection` in MongoDB. For general information related to +document creation and other write operations, see +:ref:`/core/write-operations`; for documentation of the other CRUD +operations, see the :doc:`/crud` page. Overview -------- @@ -23,15 +23,15 @@ following basic operations. - :ref:`save ` -All insert operations in MongoDB the following properties: +All insert operations in MongoDB exhibit the following properties: -- If you attempt to insert a document without :term:`_id` field, the - client library *or* the :program:`mongod` instance will add an - ``_id`` an populate the field with a unique :term:`ObjectId +- If you attempt to insert a document without the :term:`_id` field, + the client library *or* the :program:`mongod` instance will add an + ``_id`` field and populate the field with a unique :term:`ObjectId `. - If you specify an ``_id`` field, the ``_id`` field must be unique - within the collection, otherwise the :program:`mongod` will return a + within the collection; otherwise the :program:`mongod` will return a duplicate key exception. - .. include:: /includes/fact-document-max-size.rst @@ -55,17 +55,19 @@ the following syntax: db.collection.insert( ) -The :method:`insert() ` method is analogous to -the ``INSERT`` statement in SQL. To illustrate the behavior of -:method:`insert() `, consider the following -examples: +.. admonition:: Corresponding Operation in SQL + + The :method:`insert() ` method is analogous + to the ``INSERT`` statement. + +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. - - If the collection ``csbios`` does not exist, then following - operation will create this collection: + first insert. Specifically in the example, if the collection + ``csbios`` does not exist, then the insert operation will create this + collection: .. code-block:: javascript @@ -129,10 +131,6 @@ examples: :method:`insert() ` method adds the ``_id`` field to the document and generates a unique ``ObjectId`` for the value. - The following operation adds the ``_id`` field to the document, - assigns to the field a unique ``ObjectId``, and inserts the document - into the ``csbios`` collection: - .. code-block:: javascript db.csbios.insert( { @@ -186,7 +184,7 @@ examples: } - If you pass an array of documents to the :method:`insert() - ` method the :method:`insert() + ` method, the :method:`insert() ` performs a bulk insert into a collection. The following operation inserts three documents into the @@ -268,15 +266,20 @@ examples: Update with Upsert ------------------ -Typically update operations :doc:`update ` -existing documents, but in MongoDB, the :method:`update() -` operation has an ``upsert`` option. Upserts -are a hybrid operation, that use the query argument to the update -operation and: +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 ``upsert`` option as an argument. Upserts are a hybrid +operation that use the ``query`` argument to determine the write +operation: -- update the matching document if the query returns a result. +- If the query returns a result, the upsert updates the matching + document. -- inserts a single document if no document matches the query. +- If the query matches no document in the collection, the upsert + inserts a single document. Consider the following syntax for an upsert operation: @@ -286,7 +289,7 @@ Consider the following syntax for an upsert operation: , { upsert: true } ) -Consider the following examples that illustrate the use of the +The following examples illustrate the use of the upsert to perform create operations: - If the ```` argument contains only field and value @@ -472,12 +475,16 @@ upsert to perform create operations: Save ---- -The :method:`save() ` method inserts a document -into a collection if the document does not contain the ``_id`` field or -contains an ``_id`` field with a value not in the collection. If the -document does not contain the ``_id`` field, the :method:`save() -` method adds the ``_id`` field to the document -and assigns a unique ``ObjectId`` as its value. +The :method:`save() ` method is a specialized +upsert that use the ``_id`` field in document argument to determine +whether to perform an insert or an update: + +- If the document does not contain the ``_id`` field or contains an + ``_id`` field with a value not in the collection, the :method:`save() + ` method performs an insert of the document. + +- Otherwise, the :method:`save() ` method + performs an update. The :method:`save() ` method has the following syntax: @@ -487,12 +494,12 @@ following syntax: db.collection.save( ) Consider the following examples that illustrate the use of the -:method:`insert() ` method for create -operations: +:method:`save() ` method to perform inserts: - If the ``document`` does not contain the ``_id`` field, the - :method:`save() ` method adds the ``_id`` field - to the document and performs an insert. + :method:`save() ` method performs an insert. + 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`` collection since the document does not contain the ``_id`` field: @@ -513,36 +520,10 @@ operations: ] } ) - You can verify the addition of the ``_id`` field during the operation - by querying the ``csbios`` collection: - - .. code-block:: javascript - - 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"), - "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. + 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`` collection since the document contains an ``_id`` field whose value diff --git a/draft/applications/read.txt b/draft/applications/read.txt index 6cfb26dd8ae..c88ad18cc6b 100644 --- a/draft/applications/read.txt +++ b/draft/applications/read.txt @@ -6,10 +6,10 @@ Read Of the four basic database operations (i.e. CRUD), read operation are those that retrieve records or or :term:`documents ` from a -:term:`collection` in MongoDB. For more information about document -retrieval and other read operations see :ref:`/core/read-operations`, -for documentation of other basic database operations see the -:doc:`/crud` page. +:term:`collection` in MongoDB. For general information about read +operations and the factors that affect their performanace, see +:ref:`/core/read-operations`; for documentation of the other CRUD +operations, see the :doc:`/crud` page. Overview -------- @@ -31,7 +31,7 @@ method to select documents from a collection. The :method:`find() ` method returns a cursor that contains a number of documents. Most :doc:`drivers ` provide application developers with a native iterable interface for handling -cursors and accessing documents +cursors and accessing documents. The :method:`find() ` method has the following syntax: @@ -39,7 +39,7 @@ syntax: db.collection.find( , ) -.. optional:: Corresponding operations in SQL. +.. admonition:: Corresponding Operation in SQL The :method:`find() ` method is analogous to the ``SELECT`` statement, while: @@ -244,7 +244,7 @@ operation. These methods are: db.csbios.find().sort( { name: 1 } ) - :method:`sort() ` corresponds to the is ``ORDER BY`` + :method:`sort() ` corresponds to the ``ORDER BY`` statement in SQL. - The :method:`limit() ` method limits the number of