DOCS-249 First draft of Write Operations documentation

draft/core/write-operations.txt

@@ -4,23 +4,29 @@ Write Operations
 
 .. default-domain:: mongodb
 
-Synopsis
---------
+Write operations create, update, and delete data in MongoDB databases.
+MongoDB databases store data as :term:`documents <document>` in
+:term:`collections <collection>`.
+
+This section of the manual describes how MongoDB performs write
+operations and how different factors affect the efficiency of those
+operations.
 
-Operations
-----------
+.. index:: write operators
+.. _write-operations-operators:
 
-The :doc:`/crud` section of this manual contains specific
-documentation for the major classes of write operations for MongoDB
-databases. Read the following pages for additional examples and
-documentation:
+Write Operators
+---------------
 
-:doc:`/applications/create`
-:doc:`/applications/delete`
-:doc:`/applications/update`
+For information on write operators and how to write data to a MongoDB
+database, see the following:
 
-Also consider the following methods in the :program:`mongo` JavaScript
-shell that allow you to write or change data in a MongoDB database.
+- :doc:`/applications/create`
+- :doc:`/applications/update`
+- :doc:`/applications/delete`
+
+For information on specific :program:`mongo` shell methods used in write
+operations, see the following:
 
 - :method:`db.collection.insert()`
 - :method:`db.collection.update()`
@@ -29,43 +35,230 @@ shell that allow you to write or change data in a MongoDB database.
 - :method:`db.collection.remove()`
 - :method:`db.collection.delete()`
 
-Consider the documentation for your client library or :doc:`driver
-</applications/drivers>` for more information on how to access this
-functionality from within your application.
+For information on how to perform write operations from within an
+application, see the :doc:`/applications/drivers` documentation or the
+documentation for your client library.
+
+.. index:: write concern
+.. _write-operations-write-concern:
+
+Write Concern
+-------------
+
+:term:`Write concern <write concern>` confirms the success of write
+operations to MongoDB databases by returning an object indicating
+operational success. Beginning with version 2.2.x, the :program:`mongo`
+shell and MongoDB drivers enable write concern by default. Prior to
+2.2.x, the shell disables write concern by default, while the behavior
+for drivers varies. For your driver's behavior, see the
+:doc:`/applications/drivers` documentation.
+
+
+.. todo add note about all drivers after `date` will have w:1 write
+   concern for all operations by default.
+
+Write concern issues the :dbcommand:`getLastError` command after write
+operations to return an object with success information. The returned
+object's ``err`` field contains either a value of ``null``, which
+indicates write operations have completed successfully, or contains a
+description of the last error encountered.
+
+A successful write operation means the :program:`mongod` instance
+received the write operation and has committed the operation to the
+in-memory representation of the database. This provides a simple and
+low-latency level of write concern and will allow your application to
+detect situations where the :program:`mongod` instance becomes
+inaccessible or detect insertion errors caused by :ref:`duplicate key errors
+<index-type-unique>`.
+
+Write concern provides confirmation of write operations but also adds to
+performance costs. In situations where confirmation is unnecessary, it
+can be advantageous to disable write concern.
+
+You can modify the level of write concern returned by issuing the
+:dbcommand:`getLastError` command with one or both of following options:
+
+- ``j`` or "journal" option
+
+  This option confirms that the :program:`mongod` instance has written
+  the data to the on-disk journal and ensures data is not lost if the
+  :program:`mongod` instance shuts down unexpectedly. Set to ``true`` to
+  enable, as shown in the following example:
+
+  .. code-block:: javascript
+
+     db.runCommand( { getLastError: 1, j: "true" } )
+
+- ``w`` option
+
+  This option is used either to configure write concern on members of
+  :term:`replica sets <replica set>` *or* to disable write concern
+  entirely. By default, the ``w`` option is set to ``1``, which enables
+  write concern on a single :program:`mongod` instance or on the
+  :term:`primary` in a replica set.
+
+  The ``w`` option takes the following values:
+
+  - ``-1``
+
+    Turns off reporting of network errors.
+
+  - ``0``
+
+    Disables write concern.
+
+    .. note:: If you disable write concern but enable the journal
+       option, as shown here:
+
+       .. code-block:: javascript
+
+          { getLastError: 1, w: 0, j: "true" }
 
-Write Concern and Write Safety
-------------------------------
+       The setting with the ``j`` option prevails. Write concern is
+       enabled with journaling.
 
-.. todo:: import and tweak section from the replica-set page. When we
-   publish this document we'll have to do a quick deletion/reduction
-   of the replica-set section, but during the editorial process the
-   content can be duplicated.
+  - ``1``
+
+    Enables write concern on a standalone :program:`mongod` or the
+    :term:`primary` in a replica set.
+
+  - *A number greater than 1*
+
+    Confirms that write operations have replicated to the specified
+    number of replica set members, including the primary. If you set
+    ``w`` to a number that is greater than the number of set members
+    that hold data, MongoDB waits for the non-existent members become
+    available, which means MongoDB blocks indefinitely.
+
+  - ``majority``
+
+    Confirms that write operations have replicated to the majority of
+    set members.
+
+For more information on write concern and replica sets, see :ref:`Write
+Concern for Replica Sets <replica-set-write-concern>`.
+
+.. _write-operations-bulk-insert:
 
 Bulk Inserts
 ------------
 
-:issue:`SERVER-2395`
+Bulk inserts let you insert many documents at once in a single database
+call by letting you pass multiple documents to a single insert
+operation.
+
+Bulk insert can significantly increase performance by distributing
+:ref:`write concern <write-operations-write-concern>` costs. Beginning
+in version 2.2.x, write concern is enabled by default.
+
+Bulk inserts are often used with :term:`sharded collections <sharded
+collection>` and are more effective when the collection is already
+populated and MongoDB has already determined the key distribution. For
+more information on bulk inserts into sharded collections, see
+:doc:`/source/administration/sharding`.
+
+.. todo Chnange the above link from :doc:`/source/administration/sharding`
+   to :ref:`sharding-bulk-inserts` once the Write Operations document
+   goes live
+
+When performing bulk inserts through a driver, you can use the
+``ContinueOnError`` option in your driver's insert command to continue
+to insert remaining documents even if an insert fails. This option is
+available in MongoDB versions 2.0 and higher. If errors occur, only the
+most recent is reported. For a :term:`sharded collection`,
+``ContinueOnError`` is implied and cannot be disabled. For details on
+performing bulk inserts through your driver, see the
+:doc:`/applications/drivers` documentation for your driver.
+
+Beginning with version 2.2, you can perform bulk inserts through the
+:program:`mongo` shell by passing an array of documents to the
+:method:`insert() <db.collection.insert()>` method.
+
+For more information, see :ref:`write-operations-sharded-clusters`,
+:ref:`sharding-bulk-inserts`, and :doc:`/administration/import-export`.
 
-.. todo:: import the best content from: http://www.mongodb.org/display/DOCS/Bulk+Inserts sl
-   split between this section and the sharded clusters section.
+.. _write-operations-indexing:
 
 Indexing
 --------
 
-.. todo:: short section on the impact of indexes and index maintenance
-   on write operations.
+After every insert, update, or delete operation, MongoDB updates not
+only the collection but also *every* index associated with the
+collection. Therefore, every index on a collection adds some amount of
+write-performance penalty.
+
+In general, the performance gains that indexes realize for *read
+operations* are worth the insertion penalty. But if your application is
+write-heavy, be careful when creating new indexes.
+
+For more information, see :doc:`/source/applications/indexes`.
+
+.. _write-operations-isolation:
 
 Isolation
 ---------
 
-- atomicity
-- :doc:`/tutorial/perform-two-phase-commits`
+All operations inside of a MongoDB document are atomic. An update
+operation may modify more than one document at more than one level
+(nesting) in a single operation that will either succeed or fail and
+cannot leave the document in an in-between state.
+
+For more information see :doc:`Isolated write operations
+</reference/operator/atomic>` and
+:doc:`/tutorial/perform-two-phase-commits`.
 
 Architecture
 ------------
 
+.. _write-operations-replica-sets:
+
 Replica Sets
 ~~~~~~~~~~~~
 
+In :term:`replica sets <replica set>`, all write operations go to the
+set's :term:`primary`. MongoDB applies the write operations to the
+primary and then records the operations on the primary's :term:`oplog`.
+The :term:`secondary` members then replicate the oplog and apply the
+operations to themselves in an asynchronous process.
+
+If you are performing a large data ingestion or bulk load operation that
+requires a large number of writes to the primary, the secondaries might
+not be able to read the oplog fast enough to keep up with changes. The
+oplog is a :term:`capped collection` and overwrites its oldest entries
+when it reaches a certain size. If the secondaries have not yet applied
+those entries because a large write operation has prevented them from
+reading the oplog, the secondaries will have fallen too far behind to
+catch up and will have become stale.
+
+To prevent this, use :ref:`write concern
+<write-operations-write-concern>` to return write confirmation every
+100, 1,000, or other designated number of operations. This provides an
+opportunity for secondaries to catch up with the primary. Write concern
+can slow the overall progress of write operations but prevents the
+secondaries from falling too far behind.
+
+For more information on replica sets and write operations, see
+:ref:`replica-set-write-concern`, :ref:`replica-set-oplog-sizing`,
+:ref:`replica-set-oplog`,
+:ref:`replica-set-procedure-change-oplog-size`, and
+
+.. todo add this :ref:`replica-set-resync-stale-member` WHEN
+   the "Resyncing a Member of a Replica Set" topic is added to
+   source/administration/replica-sets.txt.
+   (See pull request "DOCS-449 resync stale replica set member")
+
+.. _write-operations-sharded-clustsers:
+
 Sharded Clusters
 ~~~~~~~~~~~~~~~~
+
+In a :term:`sharded cluster`, MongoDB directs a given write operation to
+a :term:`shard` and then performs the write on a particular
+:term:`chunk` on that shard. Shards and chunks are range-based.
+:term:`Shard keys <shard keys>` affect how MongoDB distributes documents
+among shards. Choosing the correct shard key can have a great impact on
+the performance, capability, and functioning of your database and
+cluster.
+
+For more information, see :doc:`/administration/sharding` and
+:ref:`write-operations-bulk-insert`.