diff --git a/draft/core/write-operations.txt b/draft/core/write-operations.txt index 6058d6ca7f1..93cfa158693 100644 --- a/draft/core/write-operations.txt +++ b/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 ` in +:term:`collections `. + +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 -` 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 ` 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 +`. + +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 ` *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 `. + +.. _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 ` costs. Beginning +in version 2.2.x, write concern is enabled by default. + +Bulk inserts are often used with :term:`sharded collections ` 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() ` 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 +` and +:doc:`/tutorial/perform-two-phase-commits`. Architecture ------------ +.. _write-operations-replica-sets: + Replica Sets ~~~~~~~~~~~~ +In :term:`replica sets `, 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 +` 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 ` 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`. \ No newline at end of file