Merge pull request #272007 from TheovanKraay/multi-region-write-updates

JamesJBarnett · web-flow · commit b3183b87bf1b · 2024-04-22T11:56:16.000-07:00
multi-region writes doc updates
diff --git a/articles/cosmos-db/cassandra/TOC.yml b/articles/cosmos-db/cassandra/TOC.yml
@@ -177,10 +177,16 @@
             - name: Mapping Cassandra consistency levels
               href: consistency-mapping.md
             - name: High availability
-              href: ../high-availability.md
-            - name: Conflict types and resolution policies
-              displayName: last write wins, custom, multi-region writes, multi-master
-              href: ../conflict-resolution-policies.md
+              items:
+                - name: High availability overview
+                  href: ../high-availability.md
+                - name: Multi-region writes
+                  items:
+                    - name: Understanding multi-region writes
+                      href: ../multi-region-writes.md
+                    - name: Conflict resolution
+                      displayName: last write wins, custom, multi-region writes, multi-master
+                      href: ../conflict-resolution-policies.md
             - name: Global distribution - under the hood
               href: ../global-dist-under-the-hood.md
         - name: Security
diff --git a/articles/cosmos-db/change-feed.md b/articles/cosmos-db/change-feed.md
@@ -67,6 +67,14 @@ Change feed is available for partition key ranges of an Azure Cosmos DB containe
 
 Change feed items come in the order of their modification time. This sort order is guaranteed per partition key, and there's no guaranteed order across the partition key values.
 
+> [!NOTE]
+> For [multi-region write](multi-region-writes.md) accounts, there are two timestamps:
+> - The server epoch time at which the record was written in the local region. This is recorded as `_ts`.
+> - The epoch time at which the absence of a conflict was confirmed, or the conflict was resolved in the [hub region](multi-region-writes.md#hub-region) for that record. This is recorded as `crts`. 
+> 
+> Change feed items come in the order recorded by `crts`.
+
+
 ### Change feed in multi-region Azure Cosmos DB accounts
 
 In a multi-region Azure Cosmos DB account, changes in one region are available in all regions. If a write-region fails over, change feed works across the manual failover operation, and it's contiguous. For accounts with multiple write regions, there's no guarantee of when changes will be available. Incoming changes to the same document may be dropped in latest version mode if there was a more recent change in another region, and all changes will be captured in all versions and deletes mode.
diff --git a/articles/cosmos-db/get-latest-restore-timestamp.md b/articles/cosmos-db/get-latest-restore-timestamp.md
@@ -18,6 +18,9 @@ This article describes how to get the [latest restorable timestamp](latest-resto
 
 This feature is supported for Azure Cosmos DB API for NoSQL containers, API for MongoDB , Table API and API for Gremlin graphs.
 
+> [!IMPORTANT]
+> For [multi-region write](multi-region-writes.md) accounts, the latest restorable timestamp is determinded by a [conflict resolution timestamp (`crts`)](multi-region-writes.md#understanding-timestamps). This is not returned by the methods listed below. See GitHub sample [here](https://github.com/Azure-Samples/cosmosdb-get-conflict-resolved-timestamp-from-changefeed) to learn how to consume Azure Cosmos DB's Change Feed and return documents with `ConflictResolvedTimestamp(crts)` in a container. 
+
 ## SQL container
 
 ### PowerShell
diff --git a/articles/cosmos-db/gremlin/TOC.yml b/articles/cosmos-db/gremlin/TOC.yml
@@ -185,10 +185,16 @@
           displayName: session, consistency prefix, strong, eventual, bounded staleness
           href: ../consistency-levels.md
         - name: High availability
-          href: ../high-availability.md
-        - name: Conflict types and resolution policies
-          displayName: last write wins, custom, multi-region writes, multi-master
-          href: ../conflict-resolution-policies.md
+          items:
+            - name: High availability overview
+              href: ../high-availability.md
+            - name: Multi-region writes
+              items:
+                - name: Understanding multi-region writes
+                  href: ../multi-region-writes.md
+                - name: Conflict resolution
+                  displayName: last write wins, custom, multi-region writes, multi-master
+                  href: ../conflict-resolution-policies.md
         - name: Global distribution - under the hood
           href: ../global-dist-under-the-hood.md
     - name: Security
diff --git a/articles/cosmos-db/mongodb/TOC.yml b/articles/cosmos-db/mongodb/TOC.yml
@@ -254,10 +254,16 @@
             - name: Mapping MongoDB consistency levels
               href: consistency-mapping.md
             - name: High availability
-              href: ../high-availability.md
-            - name: Conflict types and resolution policies
-              displayName: last write wins, custom, multi-region writes, multi-master
-              href: ../conflict-resolution-policies.md
+              items:
+                - name: High availability overview
+                  href: ../high-availability.md
+                - name: Multi-region writes
+                  items:
+                    - name: Understanding multi-region writes
+                      href: ../multi-region-writes.md
+                    - name: Conflict resolution
+                      displayName: last write wins, custom, multi-region writes, multi-master
+                      href: ../conflict-resolution-policies.md
             - name: Global distribution - under the hood
               href: ../global-dist-under-the-hood.md
         - name: Security
diff --git a/articles/cosmos-db/multi-region-writes.md b/articles/cosmos-db/multi-region-writes.md
@@ -0,0 +1,50 @@
+---
+title: Understanding multi-region writes in Azure Cosmos DB
+description: This article describes how multi-region writes work in Azure Cosmos DB.
+author: TheovanKraay
+ms.service: cosmos-db
+ms.topic: conceptual
+ms.date: 04/12/2024
+ms.author: thvankra
+ms.reviewer: thvankra
+---
+
+# Understanding multi-region writes in Azure Cosmos DB
+
+[!INCLUDE[NoSQL, MongoDB, Cassandra, Gremlin, Table](includes/appliesto-nosql-mongodb-cassandra-gremlin-table.md)]
+
+The best way to achieve near-zero downtime in either a partial or total outage scenario where consistency of reads doesn't need to be guaranteed, is to configure your account for multi-region writes. This article covers the key concepts to be aware of when configuring a multi-region write account. 
+
+## Hub region
+In a multi-region-write database account with two or more regions, the first region in which your account was created is called the "hub" region. All other regions that are then added to the account are called "satellite" regions. If the hub region is removed from the account, the next region, in the order they were added, is automatically chosen as the hub region.  
+
+Any writes arriving in satellite regions are quorum committed in the local region and then later sent to the Hub region for [conflict resolution](conflict-resolution-policies.md), asynchronously. Once a write goes to the hub region and gets conflict resolved, it becomes a "confirmed" write. Until then, it's called a "tentative" write or an "unconfirmed" write. Any write served from the hub region immediately becomes a confirmed write. 
+
+## Understanding timestamps  
+
+One of the primary differences in a multi-region-write account is the presence of two server timestamp values associated with each entity. The first is the server epoch time at which the entity was written in that region. This timestamp is available in both single-region write and multi-region write accounts. The second server timestamp value is associated with the epoch time at which the absence of a conflict was confirmed, or the conflict was resolved in the hub region. A confirmed or conflict resolved write has a conflict-resolution timestamp (`crts`) assigned, whereas an unconfirmed or tentative write doesn't have `crts`. There are two timestamps in Cosmos DB set by the server. The primary difference is whether the region configuration of the account is Single-Write or Multi-Write.
+
+| Timestamp | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | When exposed                                                                                                                                                                 |
+| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `_ts`       | The server epoch time at which the entity was written.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Always exposed by all read and query APIs.                                                                                                                                   |
+| `crts`      | The epoch time at which the Multi-Write conflict was resolved, or the absence of a conflict was confirmed. For Multi-Write region configuration, this timestamp defines the order of changes for Continuous backup and Change Feed:<br><br><ul><li>Used to find start time for Change Feed requests</li><li>Used as sort order for in Change Feed response.</li><li>Used to order the writes for Continuous Backup</li><li>The log backup only captures confirmed or conflict resolved writes and hence restore result of a Continuous backup only returns confirmed writes.</li></ul> | Exposed in response to Change Feed requests and only when "New Wire Model" is enabled by the request. This is the default for [All versions and deletes](change-feed.md#all-versions-and-deletes-mode-preview) Change Feed mode. |
+
+
+
+## Next steps
+
+Next, you can read the following articles:
+
+* [Conflict types and resolution policies when using multiple write regions](conflict-resolution-policies.md)
+
+* [Configure multi-region writes in your applications that use Azure Cosmos DB](how-to-multi-master.md)
+
+* [Consistency levels in Azure Cosmos DB](./consistency-levels.md)
+
+* [Request Units in Azure Cosmos DB](./request-units.md)
+
+* [Global data distribution with Azure Cosmos DB - under the hood](global-dist-under-the-hood.md)
+
+* [Consistency levels in Azure Cosmos DB](consistency-levels.md)
+
+* [Diagnose and troubleshoot the availability of Azure Cosmos DB SDKs in multiregional environments](troubleshoot-sdk-availability.md)
diff --git a/articles/cosmos-db/nosql/TOC.yml b/articles/cosmos-db/nosql/TOC.yml
@@ -346,10 +346,16 @@
           displayName: session, consistency prefix, strong, eventual, bounded staleness
           href: ../consistency-levels.md
         - name: High availability
-          href: ../high-availability.md
-        - name: Conflict types and resolution policies
-          displayName: last write wins, custom, multi-region writes, multi-master
-          href: ../conflict-resolution-policies.md
+          items:
+            - name: High availability overview
+              href: ../high-availability.md
+            - name: Multi-region writes
+              items:
+                - name: Understanding multi-region writes
+                  href: ../multi-region-writes.md
+                - name: Conflict resolution
+                  displayName: last write wins, custom, multi-region writes, multi-master
+                  href: ../conflict-resolution-policies.md
         - name: Global distribution - under the hood
           href: ../global-dist-under-the-hood.md
     - name: Security
diff --git a/articles/cosmos-db/table/TOC.yml b/articles/cosmos-db/table/TOC.yml
@@ -191,10 +191,16 @@
           displayName: session, consistency prefix, strong, eventual, bounded staleness
           href: ../consistency-levels.md
         - name: High availability
-          href: ../high-availability.md
-        - name: Conflict types and resolution policies
-          displayName: last write wins, custom, multi-region writes, multi-master
-          href: ../conflict-resolution-policies.md
+          items:
+              - name: High availability overview
+                href: ../high-availability.md
+              - name: Multi-region writes
+                items:
+                  - name: Understanding multi-region writes
+                    href: ../multi-region-writes.md
+                  - name: Conflict resolution
+                    displayName: last write wins, custom, multi-region writes, multi-master
+                    href: ../conflict-resolution-policies.md
         - name: Global distribution - under the hood
           href: ../global-dist-under-the-hood.md
     - name: Security
