From 6c9b182dafcb348812b852cd4ae02f24e2c51eb7 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 24 Feb 2025 15:21:38 -0500 Subject: [PATCH 1/8] DOCSP-47041: Causal consistency --- source/crud/transactions.txt | 40 +++++++++++++++++++++++++++--------- 1 file changed, 30 insertions(+), 10 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 102804b1d..5238c0816 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -27,16 +27,6 @@ transaction is committed. If any operation in the transaction returns an error, the driver cancels the transaction and discards all data changes before they ever become visible. -In MongoDB, transactions run within logical **sessions**. A -:manual:`session ` is a grouping of related -read or write operations that you intend to run sequentially. Sessions -enable :manual:`causal consistency -` for a -group of operations or allow you to execute operations in an -:website:`ACID transaction `. MongoDB -guarantees that the data involved in your transaction operations remains -consistent, even if the operations encounter unexpected errors. - When using the {+driver-short+}, you can create a new session from a ``MongoClient`` instance as a ``ClientSession`` type. We recommend that you reuse your client for multiple sessions and transactions instead of @@ -54,6 +44,36 @@ instantiating a new client each time. You must include the ``session`` as a parameter for any operations that you want to include in a transaction. +Causal Consistency +~~~~~~~~~~~~~~~~~~ + +In MongoDB, transactions run within logical **sessions**. A +session is a grouping of related read or write operations that you +intend to run sequentially. + +MongoDB enables **causal consistency** in client sessions, which allows +you to execute operations in an :website:`ACID transaction `. +The causal consistency model guarantees that operations within a session +run in a causal order. Additionally, clients observe results that +are consistent with the causal relationships, or the dependencies between +operations. If you perform a series of operations where one operation +logically depends on the result of another, any subsequent +reads reflect the dependent relationship. + +In a causally consistent session, MongoDB ensures a +causal relationship between the following operations: + +- Read operations that have a ``MAJORITY`` read concern +- Write operations that have a ``MAJORITY`` write concern + +.. tip:: + + To learn more about the concepts mentioned in this section, see the + following {+mdb-server+} manual entries: + + - :manual:`Server Sessions ` + - :manual:`Causal Consistency ` + Methods ------- From 3b5d5ce9fb72f352412c30140e38f44cc2a0ee82 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 24 Feb 2025 15:29:54 -0500 Subject: [PATCH 2/8] edit --- source/crud/transactions.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 5238c0816..cebf2f64b 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -27,6 +27,10 @@ transaction is committed. If any operation in the transaction returns an error, the driver cancels the transaction and discards all data changes before they ever become visible. +In MongoDB, transactions run within logical **sessions**. A +session is a grouping of related read or write operations that you +intend to run sequentially. + When using the {+driver-short+}, you can create a new session from a ``MongoClient`` instance as a ``ClientSession`` type. We recommend that you reuse your client for multiple sessions and transactions instead of @@ -47,10 +51,6 @@ instantiating a new client each time. Causal Consistency ~~~~~~~~~~~~~~~~~~ -In MongoDB, transactions run within logical **sessions**. A -session is a grouping of related read or write operations that you -intend to run sequentially. - MongoDB enables **causal consistency** in client sessions, which allows you to execute operations in an :website:`ACID transaction `. The causal consistency model guarantees that operations within a session @@ -71,8 +71,8 @@ causal relationship between the following operations: To learn more about the concepts mentioned in this section, see the following {+mdb-server+} manual entries: - - :manual:`Server Sessions ` - :manual:`Causal Consistency ` + - :manual:`Causal Consistency and Read and Write Concerns ` Methods ------- From ca1e821618cd5b2350a7c33b70c87da1ccd77d57 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 24 Feb 2025 15:35:33 -0500 Subject: [PATCH 3/8] wording --- source/crud/transactions.txt | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index cebf2f64b..06e883c59 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -29,7 +29,9 @@ before they ever become visible. In MongoDB, transactions run within logical **sessions**. A session is a grouping of related read or write operations that you -intend to run sequentially. +intend to run sequentially. Sessions allow you to run operations +in an ACID-compliant transaction, which is a transaction that meets +an expectation of atomicity, consistency, isolation, and durability. When using the {+driver-short+}, you can create a new session from a ``MongoClient`` instance as a ``ClientSession`` type. We recommend that you reuse @@ -51,8 +53,7 @@ instantiating a new client each time. Causal Consistency ~~~~~~~~~~~~~~~~~~ -MongoDB enables **causal consistency** in client sessions, which allows -you to execute operations in an :website:`ACID transaction `. +MongoDB enables **causal consistency** in client sessions. The causal consistency model guarantees that operations within a session run in a causal order. Additionally, clients observe results that are consistent with the causal relationships, or the dependencies between From 213fdb1f54b065ff4735e42b43ba63b9c2aa978c Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 24 Feb 2025 15:49:29 -0500 Subject: [PATCH 4/8] table --- source/crud/transactions.txt | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 06e883c59..6b0a8a142 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -61,6 +61,31 @@ operations. If you perform a series of operations where one operation logically depends on the result of another, any subsequent reads reflect the dependent relationship. +The following tables describes the guarantees that causally +consistent sessions provide: + +.. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - Guarantee + - Description + + * - Read your writes + - Read operations reflect the results of preceding write operations. + + * - Monotonic reads + - Read operations do not return results that reflect an earlier data state than + a preceding read operation. + + * - Monotonic writes + - The driver runs write operations that logically must precede other write operations + before these dependent writes. + + * - Writes follow reads + - The driver runs write operations that logically must follow other read operations + after these reads. + In a causally consistent session, MongoDB ensures a causal relationship between the following operations: From 2a2536f46537d39b6848757f12e484b6636c23a6 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 24 Feb 2025 15:52:42 -0500 Subject: [PATCH 5/8] typo --- source/crud/transactions.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 6b0a8a142..e637f0a79 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -61,7 +61,7 @@ operations. If you perform a series of operations where one operation logically depends on the result of another, any subsequent reads reflect the dependent relationship. -The following tables describes the guarantees that causally +The following table describes the guarantees that causally consistent sessions provide: .. list-table:: From 85b27b80a0f59dcc72778b1c44e8fc3c8917c043 Mon Sep 17 00:00:00 2001 From: norareidy Date: Tue, 25 Feb 2025 11:15:27 -0500 Subject: [PATCH 6/8] JS feedback --- source/crud/transactions.txt | 24 ++++++++++++++++-------- source/includes/AtlasSearch.java | 28 ++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+), 8 deletions(-) create mode 100644 source/includes/AtlasSearch.java diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index e637f0a79..15e5d5692 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -55,10 +55,10 @@ Causal Consistency MongoDB enables **causal consistency** in client sessions. The causal consistency model guarantees that operations within a session -run in a causal order. Additionally, clients observe results that -are consistent with the causal relationships, or the dependencies between -operations. If you perform a series of operations where one operation -logically depends on the result of another, any subsequent +run in a causal order. Clients observe results that are consistent +with the causal relationships, or the dependencies between +operations. For example, if you perform a series of operations where +one operation logically depends on the result of another, any subsequent reads reflect the dependent relationship. The following table describes the guarantees that causally @@ -79,12 +79,20 @@ consistent sessions provide: a preceding read operation. * - Monotonic writes - - The driver runs write operations that logically must precede other write operations - before these dependent writes. + - If a write operation must precede other write operations, the driver + runs this write operation first. + + For example, if you call ``insertOne()`` to insert a document, then call + ``updateOne()`` to modify the inserted document, the driver runs the + insert operation first. * - Writes follow reads - - The driver runs write operations that logically must follow other read operations - after these reads. + - If a write operation must follow other read operations, the driver runs + the read operations first. + + For example, if you call ``find()`` to retrieve a document, then call + ``deleteOne()`` to delete the retrieved document, the driver runs the find + operation first. In a causally consistent session, MongoDB ensures a causal relationship between the following operations: diff --git a/source/includes/AtlasSearch.java b/source/includes/AtlasSearch.java new file mode 100644 index 000000000..b1ec4093e --- /dev/null +++ b/source/includes/AtlasSearch.java @@ -0,0 +1,28 @@ +package source.includes; + +import org.bson.Document; + +import com.mongodb.client.MongoClient; +import com.mongodb.client.MongoClients; +import com.mongodb.client.MongoCollection; +import com.mongodb.client.MongoDatabase; + +public class AtlasSearch { + public static void main( String[] args ) { + + // Replace the placeholder with your MongoDB deployment's connection string + String uri = ""; + + try (MongoClient mongoClient = MongoClients.create(uri)) { + MongoDatabase database = mongoClient.getDatabase("sample_mflix"); + MongoCollection collection = database.getCollection("movies"); + + Document doc = collection.find(eq("title", "Back to the Future")).first(); + if (doc != null) { + System.out.println(doc.toJson()); + } else { + System.out.println("No matching documents found."); + } + } + } +} From ae6ae0809f6d4763f0aaa16b1caa25523bbcc006 Mon Sep 17 00:00:00 2001 From: norareidy Date: Thu, 27 Feb 2025 14:38:24 -0500 Subject: [PATCH 7/8] remove file --- source/includes/AtlasSearch.java | 28 ---------------------------- 1 file changed, 28 deletions(-) delete mode 100644 source/includes/AtlasSearch.java diff --git a/source/includes/AtlasSearch.java b/source/includes/AtlasSearch.java deleted file mode 100644 index b1ec4093e..000000000 --- a/source/includes/AtlasSearch.java +++ /dev/null @@ -1,28 +0,0 @@ -package source.includes; - -import org.bson.Document; - -import com.mongodb.client.MongoClient; -import com.mongodb.client.MongoClients; -import com.mongodb.client.MongoCollection; -import com.mongodb.client.MongoDatabase; - -public class AtlasSearch { - public static void main( String[] args ) { - - // Replace the placeholder with your MongoDB deployment's connection string - String uri = ""; - - try (MongoClient mongoClient = MongoClients.create(uri)) { - MongoDatabase database = mongoClient.getDatabase("sample_mflix"); - MongoCollection collection = database.getCollection("movies"); - - Document doc = collection.find(eq("title", "Back to the Future")).first(); - if (doc != null) { - System.out.println(doc.toJson()); - } else { - System.out.println("No matching documents found."); - } - } - } -} From 22f79b432108bfc888fe5102b1a2f78030599e02 Mon Sep 17 00:00:00 2001 From: norareidy Date: Fri, 28 Feb 2025 11:01:58 -0500 Subject: [PATCH 8/8] sharedinclude --- source/crud/transactions.txt | 57 +++++++++--------------------------- 1 file changed, 14 insertions(+), 43 deletions(-) diff --git a/source/crud/transactions.txt b/source/crud/transactions.txt index 15e5d5692..f9c533412 100644 --- a/source/crud/transactions.txt +++ b/source/crud/transactions.txt @@ -53,61 +53,32 @@ instantiating a new client each time. Causal Consistency ~~~~~~~~~~~~~~~~~~ -MongoDB enables **causal consistency** in client sessions. -The causal consistency model guarantees that operations within a session -run in a causal order. Clients observe results that are consistent -with the causal relationships, or the dependencies between -operations. For example, if you perform a series of operations where -one operation logically depends on the result of another, any subsequent -reads reflect the dependent relationship. +.. sharedinclude:: dbx/causal-consistency.rst -The following table describes the guarantees that causally -consistent sessions provide: + .. replacement:: insert-one-method -.. list-table:: - :widths: 40 60 - :header-rows: 1 - - * - Guarantee - - Description - - * - Read your writes - - Read operations reflect the results of preceding write operations. - - * - Monotonic reads - - Read operations do not return results that reflect an earlier data state than - a preceding read operation. + ``insertOne()`` - * - Monotonic writes - - If a write operation must precede other write operations, the driver - runs this write operation first. + .. replacement:: update-one-method - For example, if you call ``insertOne()`` to insert a document, then call - ``updateOne()`` to modify the inserted document, the driver runs the - insert operation first. + ``updateOne()`` - * - Writes follow reads - - If a write operation must follow other read operations, the driver runs - the read operations first. + .. replacement:: find-one-method - For example, if you call ``find()`` to retrieve a document, then call - ``deleteOne()`` to delete the retrieved document, the driver runs the find - operation first. + ``find()`` -In a causally consistent session, MongoDB ensures a -causal relationship between the following operations: + .. replacement:: delete-one-method -- Read operations that have a ``MAJORITY`` read concern -- Write operations that have a ``MAJORITY`` write concern + ``deleteOne()`` -.. tip:: + .. replacement:: majority-rc - To learn more about the concepts mentioned in this section, see the - following {+mdb-server+} manual entries: + ``MAJORITY`` - - :manual:`Causal Consistency ` - - :manual:`Causal Consistency and Read and Write Concerns ` + .. replacement:: majority-wc + ``MAJORITY`` + Methods -------