[Cosmos] Add optimistic concurrency samples (etag/ifmatch) (#33812)

Author: simorenoh

sdk/cosmos/azure-cosmos/samples/document_management.py

@@ -119,8 +119,35 @@ def replace_item(container, doc_id):
     print('Replaced Item\'s Id is {0}, new subtotal={1}'.format(response['id'], response['subtotal']))
 
 
+def replace_item_using_etags(container, doc_id):
+    print('\n1.7 Replace an Item using Etags and IfMatch\n')
+    # The use of etags and if-match/if-none-match options allows users to run conditional replace operations
+    # based on the etag value passed. When using if-match, the request will only succeed if the item's latest etag
+    # matches the passed in value. For more on optimistic concurrency control, see the link below:
+    # https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency
+
+    read_item = container.read_item(item=doc_id, partition_key=doc_id)
+    item_etag = read_item["_etag"]
+    read_item['subtotal'] = read_item['subtotal'] + 1
+    response = container.replace_item(
+        read_item,
+        read_item,
+        if_match=item_etag)
+
+    print('Replaced Item\'s Id is {0}, new subtotal={1}'.format(response['id'], response['subtotal']))
+
+    read_item = container.read_item(item=doc_id, partition_key=doc_id)
+    read_item['subtotal'] = read_item['subtotal'] + 1
+    response = container.replace_item(
+        read_item,
+        read_item,
+        if_none_match="some-etag")
+
+    print('Replaced Item\'s Id is {0}, new subtotal={1}'.format(response['id'], response['subtotal']))
+
+
 def upsert_item(container, doc_id):
-    print('\n1.7 Upserting an item\n')
+    print('\n1.8 Upserting an item\n')
 
     read_item = container.read_item(item=doc_id, partition_key=doc_id)
     read_item['subtotal'] = read_item['subtotal'] + 1
@@ -130,7 +157,7 @@ def upsert_item(container, doc_id):
 
 
 def conditional_patch_item(container, doc_id):
-    print('\n1.8 Patching Item by Id based on filter\n')
+    print('\n1.9 Patching Item by Id based on filter\n')
     operations = [
         {"op": "add", "path": "/favorite_color", "value": "red"},
         {"op": "remove", "path": "/ttl"},
@@ -151,7 +178,7 @@ def conditional_patch_item(container, doc_id):
 
 
 def patch_item(container, doc_id):
-    print('\n1.9 Patching Item by Id\n')
+    print('\n1.10 Patching Item by Id\n')
 
     operations = [
         {"op": "add", "path": "/favorite_color", "value": "red"},
@@ -172,7 +199,7 @@ def patch_item(container, doc_id):
 
 
 def execute_item_batch(database):
-    print('\n1.10 Executing Batch Item operations\n')
+    print('\n1.11 Executing Batch Item operations\n')
     container = database.create_container_if_not_exists(id="batch_container",
                                                         partition_key=PartitionKey(path='/account_number'))
     # We create three items to use for the sample.
@@ -227,15 +254,15 @@ def execute_item_batch(database):
 
 
 def delete_item(container, doc_id):
-    print('\n1.11 Deleting Item by Id\n')
+    print('\n1.12 Deleting Item by Id\n')
 
     response = container.delete_item(item=doc_id, partition_key=doc_id)
 
     print('Deleted item\'s Id is {0}'.format(doc_id))
 
 
 def delete_all_items_by_partition_key(db, partitionkey):
-    print('\n1.12 Deleting all Items by Partition Key\n')
+    print('\n1.13 Deleting all Items by Partition Key\n')
 
     # A container with a partition key that is different from id is needed
     container = db.create_container_if_not_exists(id="Partition Key Delete Container",
@@ -278,7 +305,7 @@ def delete_all_items_by_partition_key(db, partitionkey):
 
 def create_mh_items(container):
     print('Creating Items')
-    print('\n1.13 Create Item with Multi Hash Partition Key\n')
+    print('\n2.1 Create Item with Multi Hash Partition Key\n')
 
     # Create a SalesOrder object. This object has nested properties and various types including numbers, DateTimes and strings.
     # This can be saved as JSON as is without converting into rows/columns.
@@ -292,7 +319,7 @@ def create_mh_items(container):
 
 
 def read_mh_item(container, doc_id, pk):
-    print('\n1.14 Reading Item by Multi Hash Partition Key\n')
+    print('\n2.2 Reading Item by Multi Hash Partition Key\n')
 
     # Note that Reads require a partition key to be specified.
     response = container.read_item(item=doc_id, partition_key=pk)
@@ -303,7 +330,7 @@ def read_mh_item(container, doc_id, pk):
 
 
 def query_mh_items(container, pk):
-    print('\n1.15 Querying for an  Item by Multi Hash Partition Key\n')
+    print('\n2.3 Querying for an  Item by Multi Hash Partition Key\n')
 
     # enable_cross_partition_query should be set to True as the container is partitioned
     items = list(container.query_items(
@@ -320,7 +347,7 @@ def query_mh_items(container, pk):
 
 
 def replace_mh_item(container, doc_id, pk):
-    print('\n1.16 Replace an Item with Multi Hash Partition Key\n')
+    print('\n2.4 Replace an Item with Multi Hash Partition Key\n')
 
     read_item = container.read_item(item=doc_id, partition_key=pk)
     read_item['subtotal'] = read_item['subtotal'] + 1
@@ -331,7 +358,7 @@ def replace_mh_item(container, doc_id, pk):
 
 
 def upsert_mh_item(container, doc_id, pk):
-    print('\n1.17 Upserting an item with Multi Hash Partition Key\n')
+    print('\n2.5 Upserting an item with Multi Hash Partition Key\n')
 
     read_item = container.read_item(item=doc_id, partition_key=pk)
     read_item['subtotal'] = read_item['subtotal'] + 1
@@ -342,7 +369,7 @@ def upsert_mh_item(container, doc_id, pk):
 
 
 def patch_mh_item(container, doc_id, pk):
-    print('\n1.18 Patching Item by Multi Hash Partition Key\n')
+    print('\n2.6 Patching Item by Multi Hash Partition Key\n')
 
     operations = [
         {"op": "add", "path": "/favorite_color", "value": "red"},
@@ -363,14 +390,14 @@ def patch_mh_item(container, doc_id, pk):
 
 
 def delete_mh_item(container, doc_id, pk):
-    print('\n1.19 Deleting Item by Multi Hash Partition Key\n')
+    print('\n2.7 Deleting Item by Multi Hash Partition Key\n')
 
     response = container.delete_item(item=doc_id, partition_key=pk)
     print('Deleted item\'s Account Number is {0} Purchase Order Number is {1}'.format(pk[0], pk[1]))
 
 
 def delete_all_items_by_partition_key_mh(db, partitionkey):
-    print('\n1.20 Deleting all Items by Partition Key Multi Hash\n')
+    print('\n2.8 Deleting all Items by Partition Key Multi Hash\n')
 
     # A container with a partition key that is different from id is needed
     container = db.create_container_if_not_exists(id="Partition Key Delete Container Multi Hash",
@@ -413,7 +440,7 @@ def delete_all_items_by_partition_key_mh(db, partitionkey):
 
 
 def query_items_with_continuation_token_size_limit(container, doc_id):
-    print('\n1.21 Query Items With Continuation Token Size Limit.\n')
+    print('\n2.9 Query Items With Continuation Token Size Limit.\n')
 
     size_limit_in_kb = 8
     sales_order = get_sales_order(doc_id)
@@ -495,6 +522,7 @@ def run_sample():
         query_items(container, 'SalesOrder1')
         query_items_with_continuation_token(container)
         replace_item(container, 'SalesOrder1')
+        replace_item_using_etags(container, 'SalesOrder1')
         upsert_item(container, 'SalesOrder1')
         conditional_patch_item(container, 'SalesOrder1')
         patch_item(container, 'SalesOrder1')

sdk/cosmos/azure-cosmos/samples/document_management_async.py

@@ -136,8 +136,35 @@ async def replace_item(container, doc_id):
     print('Replaced Item\'s Id is {0}, new subtotal={1}'.format(response['id'], response['subtotal']))
 
 
+async def replace_item_using_etags(container, doc_id):
+    print('\n1.7 Replace an Item using Etags and IfMatch\n')
+    # The use of etags and if-match/if-none-match options allows users to run conditional replace operations
+    # based on the etag value passed. When using if-match, the request will only succeed if the item's latest etag
+    # matches the passed in value. For more on optimistic concurrency control, see the link below:
+    # https://learn.microsoft.com/azure/cosmos-db/nosql/database-transactions-optimistic-concurrency
+
+    read_item = await container.read_item(item=doc_id, partition_key=doc_id)
+    item_etag = read_item["_etag"]
+    read_item['subtotal'] = read_item['subtotal'] + 1
+    response = await container.replace_item(
+        read_item,
+        read_item,
+        if_match=item_etag)
+
+    print('Replaced Item\'s Id is {0}, new subtotal={1}'.format(response['id'], response['subtotal']))
+
+    read_item = await container.read_item(item=doc_id, partition_key=doc_id)
+    read_item['subtotal'] = read_item['subtotal'] + 1
+    response = await container.replace_item(
+        read_item,
+        read_item,
+        if_none_match="some-etag")
+
+    print('Replaced Item\'s Id is {0}, new subtotal={1}'.format(response['id'], response['subtotal']))
+
+
 async def upsert_item(container, doc_id):
-    print('\n1.7 Upserting an item\n')
+    print('\n1.8 Upserting an item\n')
 
     read_item = await container.read_item(item=doc_id, partition_key=doc_id)
     read_item['subtotal'] = read_item['subtotal'] + 1
@@ -147,7 +174,7 @@ async def upsert_item(container, doc_id):
 
 
 async def conditional_patch_item(container, doc_id):
-    print('\n1.8 Patching Item by Id based on filter\n')
+    print('\n1.9 Patching Item by Id based on filter\n')
     operations = [
         {"op": "add", "path": "/favorite_color", "value": "red"},
         {"op": "remove", "path": "/ttl"},
@@ -168,7 +195,7 @@ async def conditional_patch_item(container, doc_id):
 
 
 async def patch_item(container, doc_id):
-    print('\n1.9 Patching Item by Id\n')
+    print('\n1.10 Patching Item by Id\n')
 
     operations = [
         {"op": "add", "path": "/favorite_color", "value": "red"},
@@ -191,7 +218,7 @@ async def patch_item(container, doc_id):
 
 
 async def execute_item_batch(database):
-    print('\n1.10 Executing Batch Item operations\n')
+    print('\n1.11 Executing Batch Item operations\n')
     container = await database.create_container_if_not_exists(id="batch_container",
                                                               partition_key=PartitionKey(path='/account_number'))
     # We create three items to use for the sample.
@@ -246,15 +273,15 @@ async def execute_item_batch(database):
 
 
 async def delete_item(container, doc_id):
-    print('\n1.11 Deleting Item by Id\n')
+    print('\n1.12 Deleting Item by Id\n')
 
     await container.delete_item(item=doc_id, partition_key=doc_id)
 
     print('Deleted item\'s Id is {0}'.format(doc_id))
 
 
 async def delete_all_items_by_partition_key(db, partitionkey):
-    print('\n1.12 Deleting all Items by Partition Key\n')
+    print('\n1.13 Deleting all Items by Partition Key\n')
 
     # A container with a partition key that is different from id is needed
     container = await db.create_container_if_not_exists(id="Partition Key Delete Container",
@@ -297,7 +324,7 @@ async def delete_all_items_by_partition_key(db, partitionkey):
 
 async def create_mh_items(container):
     print('Creating Items')
-    print('\n1.13 Create Item with Multi Hash Partition Key\n')
+    print('\n2.1 Create Item with Multi Hash Partition Key\n')
 
     # Create a SalesOrder object. This object has nested properties and various types including numbers, DateTimes and strings.
     # This can be saved as JSON as is without converting into rows/columns.
@@ -311,7 +338,7 @@ async def create_mh_items(container):
 
 
 async def read_mh_item(container, doc_id, pk):
-    print('\n1.14 Reading Item by Multi Hash Partition Key\n')
+    print('\n2.2 Reading Item by Multi Hash Partition Key\n')
 
     # Note that Reads require a partition key to be specified.
     response = await container.read_item(item=doc_id, partition_key=pk)
@@ -322,7 +349,7 @@ async def read_mh_item(container, doc_id, pk):
 
 
 async def query_mh_items(container, pk):
-    print('\n1.15 Querying for an  Item by Multi Hash Partition Key\n')
+    print('\n2.3 Querying for an  Item by Multi Hash Partition Key\n')
 
     query_items_response = container.query_items(
         query="SELECT * FROM r WHERE r.account_number=@account_number and r.purchase_order_number=@purchase_order_number",
@@ -339,7 +366,7 @@ async def query_mh_items(container, pk):
 
 
 async def replace_mh_item(container, doc_id, pk):
-    print('\n1.16 Replace an Item with Multi Hash Partition Key\n')
+    print('\n2.4 Replace an Item with Multi Hash Partition Key\n')
 
     read_item = await container.read_item(item=doc_id, partition_key=pk)
     read_item['subtotal'] = read_item['subtotal'] + 1
@@ -350,7 +377,7 @@ async def replace_mh_item(container, doc_id, pk):
 
 
 async def upsert_mh_item(container, doc_id, pk):
-    print('\n1.17 Upserting an item with Multi Hash Partition Key\n')
+    print('\n2.5 Upserting an item with Multi Hash Partition Key\n')
 
     read_item = await container.read_item(item=doc_id, partition_key=pk)
     read_item['subtotal'] = read_item['subtotal'] + 1
@@ -361,7 +388,7 @@ async def upsert_mh_item(container, doc_id, pk):
 
 
 async def patch_mh_item(container, doc_id, pk):
-    print('\n1.18 Patching Item by Multi Hash Partition Key\n')
+    print('\n2.6 Patching Item by Multi Hash Partition Key\n')
 
     operations = [
         {"op": "add", "path": "/favorite_color", "value": "red"},
@@ -382,14 +409,14 @@ async def patch_mh_item(container, doc_id, pk):
 
 
 async def delete_mh_item(container, doc_id, pk):
-    print('\n1.19 Deleting Item by Multi Hash Partition Key\n')
+    print('\n2.7 Deleting Item by Multi Hash Partition Key\n')
 
     response = await container.delete_item(item=doc_id, partition_key=pk)
     print('Deleted item\'s Account Number is {0} Purchase Order Number is {1}'.format(pk[0], pk[1]))
 
 
 async def delete_all_items_by_partition_key_mh(db, partitionkey):
-    print('\n1.20 Deleting all Items by Partition Key Multi Hash\n')
+    print('\n2.8 Deleting all Items by Partition Key Multi Hash\n')
 
     # A container with a partition key that is different from id is needed
     container = await db.create_container_if_not_exists(id="Partition Key Delete Container Multi Hash",
@@ -432,7 +459,7 @@ async def delete_all_items_by_partition_key_mh(db, partitionkey):
 
 
 async def query_items_with_continuation_token_size_limit(container, doc_id):
-    print('\n1.21 Query Items With Continuation Token Size Limit.\n')
+    print('\n2.9 Query Items With Continuation Token Size Limit.\n')
 
     size_limit_in_kb = 8
     sales_order = get_sales_order(doc_id)
@@ -516,6 +543,7 @@ async def run_sample():
             await query_items(container, 'SalesOrder1')
             await query_items_with_continuation_token(container)
             await replace_item(container, 'SalesOrder1')
+            await replace_item_using_etags(container, 'SalesOrder1')
             await upsert_item(container, 'SalesOrder1')
             await conditional_patch_item(container, 'SalesOrder1')
             await patch_item(container, 'SalesOrder1')