diff --git a/source/reference/read-concern-local.txt b/source/reference/read-concern-local.txt index 96be6feaef9..cab1ad33b10 100644 --- a/source/reference/read-concern-local.txt +++ b/source/reference/read-concern-local.txt @@ -9,8 +9,8 @@ Read Concern ``"local"`` ======================== .. meta:: - :description: read concern, local read concern, read isolation - :keywords: read concern, local read concern, read isolation + :description: read concern, local read concern, read isolation, transactions, multi-document transactions + :keywords: read concern, local read concern, read isolation, transactions, multi-document transactions A query with read concern ``"local"`` returns the instance's most @@ -33,6 +33,40 @@ Causally Consistent Sessions Read concern :readconcern:`local` is available for use with causally consistent sessions. +Read Concern ``"local"`` and Transactions +-------------------------------------------- + +In a multi-document transaction, read concern levels +:readconcern:`"local"` and :readconcern:`"snapshot"` are available for +:ref:`read and write operations that support read concern in a +transaction `. + +.. note:: + + For the operations in a transaction, you set the read concern at the + transaction level, not at the individual operation level. + +.. seealso:: :readconcern:`"snapshot"` + +Write Operations and Read Concern ``"local"`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In a multi-document transaction, both the read operations and the write +operations can accept the read concern level :readconcern:`"local"`. +The following write operations can accept a read concern level as part +of a transaction: + +- :dbcommand:`delete` + +- :dbcommand:`findAndModify` + +- :dbcommand:`insert` + +- :dbcommand:`update` + +For a list of all operations that accept read concerns, see +:ref:`read-concern-operations`. + Example ------- diff --git a/source/reference/read-concern-snapshot.txt b/source/reference/read-concern-snapshot.txt new file mode 100644 index 00000000000..fcaf5f55232 --- /dev/null +++ b/source/reference/read-concern-snapshot.txt @@ -0,0 +1,75 @@ +.. default-domain:: mongodb + +.. class:: hidden + + .. readconcern:: "snapshot" + +=========================== +Read Concern ``"snapshot"`` +=========================== + +.. meta:: + :description: read concern, snapshot read concern, read isolation, transactions, multi-document transactions + :keywords: read concern, snapshot read concern, read isolation, transactions, multi-document transactions + +.. versionadded:: 4.0 + +Read concern ``"snapshot"`` is only available for multi-document +transactions. + +- If the transaction is not part of a :ref:`causally consistent session + `, operations with read concern ``"snapshot"`` reads data + from a snapshot of the most recent majority committed data at + transaction start. + +- If the transaction is part of a :ref:`causally consistent session + `, operations with read concern ``"snapshot"`` reads data + from a snapshot of the first majority committed data that guarantees + causal consistency with the operation immediately prior to the + transaction start. The time of the snapshot may be after the + transaction start to guarantee causal consistency. + +Read Concern ``"snapshot"`` and Transactions +-------------------------------------------- + +In a multi-document transaction, read concern levels +:readconcern:`"local"` and :readconcern:`"snapshot"` are available for +:ref:`read and write operations that support read concern in a +transaction `. + +.. note:: + + For the operations in a transaction, you set the read concern at the + transaction level, not at the individual operation level. + +.. seealso:: :readconcern:`"local"` + +Write Operations and Read Concern ``"snapshot"`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In a multi-document transaction, both the read operations and the write +operations can accept the read concern level :readconcern:`"snapshot"`. +The following write operations can accept a read concern level as part +of a transaction: + +- :dbcommand:`delete` + +- :dbcommand:`findAndModify` + +- :dbcommand:`insert` + +- :dbcommand:`update` + +For a list of all operations that accept read concerns, see +:ref:`read-concern-operations`. + +Causally Consistent Sessions +---------------------------- + +:readconcern:`snapshot` is available for transactions that are part of +a causally consistent session. + +If the transaction is part of a :ref:`causally consistent session +`, the snapshot of the majority committed data reflects the +earliest time from the transaction start time(inclusive) that +guarantees causally consistency with the prior operation in the session. diff --git a/source/reference/read-concern.txt b/source/reference/read-concern.txt index bd567acad98..d9d78b74c65 100644 --- a/source/reference/read-concern.txt +++ b/source/reference/read-concern.txt @@ -132,6 +132,26 @@ The following read concern levels are available: For more information, see the :readconcern:`"linearizable"` reference page. + * - :readconcern:`"snapshot"` + + - Only available for operations within multi-document transactions. + + - If the transaction is not part of a :ref:`causally consistent session + `, operations with read concern ``"snapshot"`` read data + from a snapshot of the most recent majority committed data at + transaction start. + + - If the transaction is part of a :ref:`causally consistent session + `, operations with read concern ``"snapshot"`` reads data + from a snapshot of the first majority committed data that guarantees + causal consistency with the operation immediately prior to the + transaction start. The time of the snapshot may be after the + transaction start to guarantee causal consistency. + + Read concern :readconcern:`snapshot` is available for + multi-document transactions associated with causally consistent + sessions. + .. include:: /includes/fact-readConcern-most-recent-data-in-node.rst For more information on each read concern level, see: @@ -143,55 +163,190 @@ For more information on each read concern level, see: /reference/read-concern-available /reference/read-concern-majority /reference/read-concern-linearizable + /reference/read-concern-snapshot + +.. _read-concern-operations: + +``readConcern`` Support +----------------------- -``readConcern`` Syntax ----------------------- -You can specify a ``readConcern`` level [#after-cluster-time]_ as an -option: +You can specify a ``readConcern`` level as an option to commands and +methods that support read concern: .. code-block:: javascript - readConcern: { level: <"majority"|"local"|"linearizable"|"available"> } + readConcern: { level: } -.. note:: +To specify the read concern level for the :binary:`~bin.mongo` shell +method :method:`db.collection.find()`, use the +:method:`cursor.readConcern()` method: - For operations in :ref:`causally consistent sessions - `, only :readconcern:`"local"` and - :readconcern:`"majority"` levels are available. - -The following operations support the ``readConcern`` option: +.. code-block:: javascript -- :dbcommand:`find` command + db.collection.find().readConcern() -- :dbcommand:`aggregate` command and the - :method:`db.collection.aggregate()` method +The following operations support read concern: -- :dbcommand:`distinct` command +.. note:: -- :dbcommand:`count` command + - For operations in a multi-document transaction, read concern + levels :readconcern:`"local"` and :readconcern:`"snapshot"` are + available. Read concern level :readconcern:`"snapshot"` is only + available for operations in a multi-document transaction. -- :dbcommand:`parallelCollectionScan` command + - Write commands that are part of a multi-document transaction can + support read concern of either :readconcern:`"local"` or + :readconcern:`"snapshot"`. -- :dbcommand:`geoNear` command + - For operations in a :ref:`causally consistent session + `, :readconcern:`"local"` and + :readconcern:`"majority"` levels are available. If a + multi-document transaction is associated with a causally + consistent session, :readconcern:`"snapshot"` is also available for + the operations in the transaction. -- :dbcommand:`geoSearch` command +.. important:: -- :dbcommand:`group` command + To set read concern for operations in a transaction, you set the + read concern at the transaction level, not at the individual + operation level. -To specify the read concern level for the :binary:`~bin.mongo` shell method -:method:`db.collection.find()`, use the :method:`cursor.readConcern()` -method: +.. list-table:: + :header-rows: 1 -.. code-block:: javascript + * - Operation + - :readconcern:`"local"` + - :readconcern:`"available"` + - :readconcern:`"majority"` + - :readconcern:`"snapshot"` + - :readconcern:`"linearizable"` + + * - :dbcommand:`count` + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + + * - :dbcommand:`distinct` + + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + + + * - :dbcommand:`find` + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + + * - :method:`db.collection.find()` + shell method using + :method:`cursor.readConcern()` + + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + + * - :dbcommand:`geoNear` + - |checkmark| + - |checkmark| + - |checkmark| + - + - |checkmark| + + * - :dbcommand:`geoSearch` + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + + * - :dbcommand:`getMore` + - |checkmark| + - + - + - + - |checkmark| + + * - :dbcommand:`group` + - |checkmark| + - |checkmark| + - |checkmark| + - + - |checkmark| + + * - :dbcommand:`aggregate` + :method:`db.collection.aggregate()` shell method + + *Only when against a collection, not a view.* + + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + - |checkmark| + + * - :dbcommand:`parallelCollectionScan` + - |checkmark| + - |checkmark| + - |checkmark| + - + - |checkmark| + +The following write operations can also accept a read concern if part +of a multi-document transaction: - db.collection.find().readConcern(<"majority"|"local"|"linearizable"|"available">) +.. important:: -.. [#after-cluster-time] + To set read concern for operations in a transaction, you set the + read concern at the transaction level, not at the individual + operation level. - For :ref:`causally consistent sessions `, - MongoDB drivers automatically specifies the :ref:`afterClusterTime - ` value in the read concern. +.. list-table:: + :header-rows: 1 + + * - Command + - :readconcern:`"local"` + - :readconcern:`"available"` + - :readconcern:`"majority"` + - :readconcern:`"snapshot"` + - :readconcern:`"linearizable"` + + * - :dbcommand:`delete` + - |checkmark| + - + - + - |checkmark| + - + + * - :dbcommand:`findAndModify` + - |checkmark| + - + - + - |checkmark| + - + + * - :dbcommand:`insert` + - |checkmark| + - + - + - |checkmark| + - + + * - :dbcommand:`update` + - |checkmark| + - + - + - |checkmark| + - Considerations -------------- @@ -258,20 +413,12 @@ session, MongoDB 3.6 introduces the ``afterClusterTime`` read concern option to be set automatically by the drivers for operations associated with causally consistent sessions. -The ``afterClusterTime`` read concern option is available for -:readconcern:`"local"` and :readconcern:`"majority"` read -concern levels: - .. important:: Do not manually set ``afterClusterTime``. MongoDB drivers set this value automatically for operations associated with causally consistent sessions. -.. code-block:: javascript - - readConcern: { level: <"majority"|"local"> , afterClusterTime: } - To satisfy a read request with an ``afterClusterTime`` value of ``T``, a :binary:`~bin.mongod` must perform the request after its oplog reaches time ``T``. If its oplog has not reached time ``T``, the @@ -283,3 +430,5 @@ requirement and the specified ``afterClusterTime`` requirement. For read operations not associated with causally consistent sessions, ``afterClusterTime`` is unset. + +.. include:: /includes/unicode-checkmark.rst