You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/cosmos-db/how-to-migrate-from-bulk-executor-library.md
+24-26Lines changed: 24 additions & 26 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,55 +10,59 @@ ms.author: maquaran
10
10
11
11
# Migrate from the bulk executor library to the Azure Cosmos DB .NET V3 SDK
12
12
13
-
This article describes the required steps to migrate an existing application's code that uses the [.NET bulk executor library](bulk-executor-dot-net.md) to the [bulk support](tutorial-sql-api-dotnet-bulk-import.md) feature in the latest version of the .NET SDK (also referred as .NET V3 SDK) and it's useful if your current production code relies on the response types provided by the bulk executor library.
13
+
This article describes the required steps to migrate an existing application's code that uses the [.NET bulk executor library](bulk-executor-dot-net.md) to the [bulk support](tutorial-sql-api-dotnet-bulk-import.md) feature in the latest version of the .NET SDK.
14
14
15
15
## Enable bulk support
16
16
17
-
Make sure you are enabling bulk support on the `CosmosClient` instance through the [AllowBulkExecution](https://docs.microsoft.com/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions.allowbulkexecution) configuration flag:
17
+
Enable bulk support on the `CosmosClient` instance through the [AllowBulkExecution](https://docs.microsoft.com/dotnet/api/microsoft.azure.cosmos.cosmosclientoptions.allowbulkexecution) configuration:
Bulk support in the .NET SDK version 3 works by leveraging the [Task Parallel Library](https://docs.microsoft.com/dotnet/standard/parallel-programming/task-parallel-library-tpl) and grouping operations that occur concurrently. This means that there is no single method that will take your list of documents or operations as an input parameter, but rather, you need to create a Task for each operation you want to execute in bulk.
23
+
Bulk support in the .NET SDK works by leveraging the [Task Parallel Library](https://docs.microsoft.com/dotnet/standard/parallel-programming/task-parallel-library-tpl) and grouping operations that occur concurrently.
24
+
25
+
There is no single method that will take your list of documents or operations as an input parameter, but rather, you need to create a Task for each operation you want to execute in bulk.
24
26
25
27
If our initial input is a list of items where each item has, for example, this schema:
If you want to do bulk *import* (similar to using [BulkExecutor.BulkImportAsync](https://docs.microsoft.com/dotnet/api/microsoft.azure.cosmosdb.bulkexecutor.bulkexecutor.bulkimportasync)) it means you need to have concurrent calls to `CreateItemAsync` with each item value. For example:
31
+
If you want to do bulk import (similar to using BulkExecutor.BulkImportAsync), it means you need to have concurrent calls to `CreateItemAsync` with each item value. For example:
If you want to do bulk *update* (similar to using [BulkExecutor.BulkUpdateAsync](https://docs.microsoft.com/dotnet/api/microsoft.azure.cosmosdb.bulkexecutor.bulkexecutor.bulkupdateasync)), it means you need to have concurrent calls to `ReplaceItemAsync` after updating the item value. For example:
And if you want to do bulk *delete* (similar to using [BulkExecutor.BulkDeleteAsync](https://docs.microsoft.com/dotnet/api/microsoft.azure.cosmosdb.bulkexecutor.bulkexecutor.bulkdeleteasync)), it means you need to have concurrent calls to `DeleteItemAsync`, with the `id` and partition key of each item. For example:
In the previous code examples, we are creating a concurrent list of Tasks, and on each of them, calling `CaptureOperationResponse`. This is an extension that lets us maintain a *similar response schema* as BulkExecutor, by capturing any errors and tracking the [request units usage](request-units.md).
45
+
In the previous code examples, we are creating a concurrent list of Tasks, and on each of them, calling `CaptureOperationResponse`. This method is an extension that lets us maintain a *similar response schema* as BulkExecutor, by capturing any errors and tracking the [request units usage](request-units.md).
With the list of Tasks defined, all we need to do is wait until they are all completed, which would define the *scope* of our bulk operation. This is easily done by:
55
+
With the list of Tasks defined, all we need to do is wait until they are all completed, defining the *scope* of our bulk operation. Easily done by:
The code above not only waits until all operations are complete, but it also captures the time spent and calculates the required statistics. These statistics are similar to that of the bulk executor library's [BulkImportResponse](https://docs.microsoft.com/dotnet/api/microsoft.azure.cosmosdb.bulkexecutor.bulkimport.bulkimportresponse).
61
+
The code above waits until all operations are completed and calculates the required statistics.
62
+
63
+
These statistics are similar to that of the bulk executor library's [BulkImportResponse](https://docs.microsoft.com/dotnet/api/microsoft.azure.cosmosdb.bulkexecutor.bulkimport.bulkimportresponse).
@@ -69,18 +73,12 @@ The `BulkOperationResponse` will contain:
69
73
70
74
## Performance improvements
71
75
72
-
As with other operations with the .NET SDK, leveraging the stream APIs will be better performance-wise because it would avoid any unnecessary serialization, but it is only possible if the nature of the data we work with matches that of a stream of bytes (for example, file streams). In those cases, using the `CreateItemStreamAsync`, `ReplaceItemStreamAsync`, or `DeleteItemStreamAsync` APIs and working with `ResponseMessage` (instead of `ItemResponse`) will increase the throughput that can be achieved.
76
+
As with other operations with the .NET SDK, using the stream APIs will be better performance-wise by avoiding any unnecessary serialization.
77
+
78
+
It is only possible if the nature of the data we work with matches that of a stream of bytes (for example, file streams). In those cases, using the `CreateItemStreamAsync`, `ReplaceItemStreamAsync`, or `DeleteItemStreamAsync` APIs and working with `ResponseMessage` (instead of `ItemResponse`) will increase the throughput that can be achieved.
73
79
74
80
## Additional resources
75
81
76
82
*[Azure Cosmos DB SDK](sql-api-sdk-dotnet.md)
77
83
*[Complete migration source code on GitHub](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/master/Microsoft.Azure.Cosmos.Samples/Usage/BulkExecutorMigration)
78
-
*[Additional bulk samples on GitHub](https://github.com/Azure/azure-cosmos-dotnet-v3/tree/master/Microsoft.Azure.Cosmos.Samples/Usage/BulkSupport)
79
-
80
-
## Next steps
81
-
82
-
You can now proceed to learn more about change feed processor in the following articles:
83
-
84
-
*[Overview of change feed processor](change-feed-processor.md)
85
-
*[Using the change feed estimator](how-to-use-change-feed-estimator.md)
0 commit comments