Add Cosmos bulk execution #37033

JoasE · 2025-10-27T19:46:30Z

Adds BulkExecutionEnabled to CosmosDbContextOptionsBuilder
Execute non batchable document writes in parallel when bulk execution enabled
Add a warning exception when batching is enabled when using bulk execution

Implements: #36599

I've read the guidelines for contributing and seen the walkthrough
I've posted a comment on an issue with a detailed description of how I am planning to contribute and got approval from a member of the team
The code builds and tests pass locally (also verified by our automated build checks)
Commit messages follow this format:

        Summary of the changes
        - Detail 1
        - Detail 2

        Fixes #bugnumber

Tests for the changes have been added (for bug fixes / features)
Code follows the same patterns and style as existing code in this repo

JoasE · 2025-10-28T18:30:43Z

Pipeline appears to have an error running EFCore.InMemory.FunctionalTests but they succeed locally.

AndriySvyryd

Can you also add some functional tests, including ones that combine bulk execution with batching or eTags?

JoasE · 2025-11-01T16:05:37Z

@AndriySvyryd I don't think any behavior from cosmos or the sdk changes when you enable bulk execution. I can add a tests that verify that? Basically inheriting from the tests that already exist and running those with bulk enabled

JoasE · 2025-11-01T16:43:18Z

I'm actually now realizing that this doesn't make a lot of sense. When using bulk, you probably want to execute the entries to save in parallel. Otherwise the only bulk that can happen is between different contexts. Will close this if you agree and see if I have time to implement that after #37027 is merged. (as it will probably have conflicts) I will have to think on how to best handle the parallelism (with manual session token management) and if we should only do in parallel with bulk or maybe increase parallelism without as well. (but probably only with bulk)

…otnet#36599

Copilot

Pull request overview

This pull request adds bulk execution support to the Cosmos DB provider for Entity Framework Core. The implementation enables the Cosmos DB SDK's bulk execution feature, which can improve throughput for small write operations in high-volume scenarios.

Key Changes:

Added BulkExecutionEnabled option to CosmosDbContextOptionsBuilder to enable bulk execution
Modified CosmosDatabaseWrapper to execute non-batchable writes in parallel when bulk execution is enabled
Added warning when bulk execution is used with transactional batching, since transactional batches cannot be executed in bulk mode
Refactored test infrastructure to support skippable tests via SkippableTestMessageBus

Reviewed changes

Copilot reviewed 20 out of 21 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
test/EFCore.Specification.Tests/TestUtilities/Xunit/SkippableTestMessageBus.cs	New utility class to allow tests to be skipped by throwing SkipException
test/EFCore.Specification.Tests/TestUtilities/Xunit/ConditionalTheoryTestCase.cs	Updated to use SkippableTestMessageBus for handling skip exceptions
test/EFCore.Specification.Tests/TestUtilities/Xunit/ConditionalFactTestCase.cs	Updated to use SkippableTestMessageBus for handling skip exceptions
test/EFCore.Cosmos.Tests/Extensions/CosmosDbContextOptionsExtensionsTests.cs	Added test for BulkExecutionEnabled option
test/EFCore.Cosmos.FunctionalTests/EndToEndCosmosTest.cs	Refactored to support different context creation modes for bulk execution tests
test/EFCore.Cosmos.FunctionalTests/CosmosTransactionalBatchTest.cs	Refactored to use fixture-based testing pattern instead of NonSharedModelTestBase
test/EFCore.Cosmos.FunctionalTests/CosmosConcurrencyTest.cs	Added virtual CreateContext methods to support bulk execution testing
test/EFCore.Cosmos.FunctionalTests/CosmosBulkExecutionTest.cs	New test suite for bulk execution functionality
src/EFCore.Cosmos/Storage/Internal/SingletonCosmosClientWrapper.cs	Added configuration for AllowBulkExecution on CosmosClient
src/EFCore.Cosmos/Storage/Internal/CosmosDatabaseWrapper.cs	Implemented parallel execution of single writes when bulk execution is enabled
src/EFCore.Cosmos/Properties/CosmosStrings.resx	Added warning message for bulk execution with transactional batch
src/EFCore.Cosmos/Properties/CosmosStrings.Designer.cs	Generated code for new warning message
src/EFCore.Cosmos/Infrastructure/Internal/ICosmosSingletonOptions.cs	Added EnableBulkExecution property
src/EFCore.Cosmos/Infrastructure/Internal/CosmosSingletonOptions.cs	Implemented EnableBulkExecution property with validation
src/EFCore.Cosmos/Infrastructure/Internal/CosmosDbOptionExtension.cs	Added bulk execution option to extension
src/EFCore.Cosmos/Infrastructure/CosmosDbContextOptionsBuilder.cs	Added BulkExecutionEnabled API
src/EFCore.Cosmos/Diagnostics/Internal/CosmosLoggingDefinitions.cs	Added logging definition for bulk execution warning
src/EFCore.Cosmos/Diagnostics/Internal/CosmosLoggerExtensions.cs	Added logger extension for bulk execution warning
src/EFCore.Cosmos/Diagnostics/CosmosTransactionalBatchExecutedEventData.cs	Fixed typo in documentation
src/EFCore.Cosmos/Diagnostics/CosmosEventId.cs	Added event ID for bulk execution warning
src/EFCore.Cosmos/Diagnostics/BulkExecutionWithTransactionalBatchEventData.cs	New event data class for bulk execution warning

Files not reviewed (1)

src/EFCore.Cosmos/Properties/CosmosStrings.Designer.cs: Language not supported

You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.

test/EFCore.Cosmos.FunctionalTests/CosmosBulkExecutionTest.cs

src/EFCore.Cosmos/Infrastructure/Internal/CosmosSingletonOptions.cs

src/EFCore.Cosmos/Diagnostics/BulkExecutionWithTransactionalBatchEventData.cs

test/EFCore.Cosmos.FunctionalTests/CosmosBulkExecutionTest.cs

test/EFCore.Cosmos.FunctionalTests/CosmosTransactionalBatchTest.cs

src/EFCore.Cosmos/Diagnostics/CosmosTransactionalBatchExecutedEventData.cs

src/EFCore.Cosmos/Diagnostics/BulkExecutionWithTransactionalBatchEventData.cs

src/EFCore.Cosmos/Diagnostics/CosmosEventId.cs

AndriySvyryd · 2025-11-25T18:48:38Z

src/EFCore.Cosmos/Diagnostics/BulkExecutionWithTransactionalBatchEventData.cs

+/// <remarks>
+///     See <see href="https://aka.ms/efcore-docs-diagnostics">Logging, events, and diagnostics</see> for more information and examples.
+/// </remarks>
+public class BulkExecutionWithTransactionalBatchEventData : EventData


The distinguishing feature of this class is that it contains a AutoTransactionBehavior, so rename it to AutoTransactionBehaviorEventData and adjust docs accordingly

src/EFCore.Cosmos/Storage/Internal/CosmosDatabaseWrapper.cs

AndriySvyryd · 2025-11-25T19:05:42Z

src/EFCore.Cosmos/Storage/Internal/CosmosDatabaseWrapper.cs

+            }
+            catch (InvalidOperationException ex)
+            {
+                throw WrapUpdateException(ex, entries.AsReadOnly());


This shouldn't be wrapped as it's not an exception coming from the database

AndriySvyryd · 2025-11-25T19:09:04Z

src/EFCore.Cosmos/Storage/Internal/CosmosDatabaseWrapper.cs

            }

-            var firstEntry = entriesWithoutTriggers[0];
+            var firstEntry = batchableEntries[0];


Why is it safe to assume there's at least one entry in batchableEntries?

I understand you are asking about it as it isn't intuitively clear, but we know there is at-least 1 cosmosUpdateEntries as per line 197 and we know that that update entry is not a single update as per line 224. Thus there must be at-least 1 batchableEntries

if (cosmosUpdateEntries.Count == 0 || _currentDbContext.Context.Database.AutoTransactionBehavior == AutoTransactionBehavior.Never || (cosmosUpdateEntries.Count <= 1 && _currentDbContext.Context.Database.AutoTransactionBehavior != AutoTransactionBehavior.Always)) { return new SaveGroups .... }

if (singleUpdateEntries.Count >= 1) { .... return new SaveGroups... }

src/EFCore.Cosmos/Storage/Internal/CosmosDatabaseWrapper.cs

AndriySvyryd · 2025-11-25T19:18:49Z

test/EFCore.Cosmos.FunctionalTests/CosmosBulkExecutionTest.cs

+        Assert.Equal(CosmosEventId.ExecutedTransactionalBatch, Fixture.ListLoggerFactory.Log[3].Id);
+    }
+
+    public class EndToEndTest(NonSharedFixture fixture) : EndToEndCosmosTest(fixture), IClassFixture<NonSharedFixture>


Separate the classes to other files with a prefix (Bulk, BulkNoBatch, etc.)

AndriySvyryd · 2025-11-25T19:19:09Z

test/EFCore.Cosmos.FunctionalTests/CosmosBulkExecutionTest.cs

+using Microsoft.EntityFrameworkCore.Cosmos.Diagnostics.Internal;
+using Microsoft.EntityFrameworkCore.Cosmos.Internal;
+
+namespace Microsoft.EntityFrameworkCore;


Move to Update subfolder

AndriySvyryd

You also need to configure the warning to throw by default in

efcore/src/EFCore.Cosmos/Extensions/CosmosDbContextOptionsExtensions.cs

Line 263 in eeaf988

    
           ((IDbContextOptionsBuilderInfrastructure)optionsBuilder).AddOrUpdateExtension(coreOptionsExtension);

See

efcore/src/EFCore.InMemory/Extensions/InMemoryDbContextOptionsExtensions.cs

Lines 156 to 157 in eeaf988

    
           coreOptionsExtension.WarningsConfiguration.TryWithExplicit( 
        
               InMemoryEventId.TransactionIgnoredWarning, WarningBehavior.Throw));

for reference

Co-authored-by: Copilot <[email protected]> Co-authored-by: Andriy Svyryd <[email protected]>

Do not wrap BulkExecutionWithTransactionalBatch & dont use == true Rename BulkExecutionWithTransactionalBatchEventData

Add BulkExecutionEnabled to CosmosDbContextOptionsBuilder

c6f9282

JoasE marked this pull request as ready for review October 27, 2025 20:17

JoasE requested a review from a team as a code owner October 27, 2025 20:17

Remove blank line

47a6773

AndriySvyryd self-assigned this Oct 31, 2025

AndriySvyryd added the community-contribution label Oct 31, 2025

AndriySvyryd requested changes Oct 31, 2025

View reviewed changes

Update docs

841868e

JoasE marked this pull request as draft November 1, 2025 16:47

JoasE mentioned this pull request Nov 2, 2025

Cosmos: bulk execution #36599

Open

JoasE added 5 commits November 3, 2025 17:08

Merge branch 'main' of https://github.com/dotnet/efcore into feature/d…

29768f1

…otnet#36599

Merge branch 'main' of https://github.com/dotnet/efcore into feature/d…

79793d6

…otnet#36599

WIP

e633d42

Add warning

423732b

Move to SharedStoreFixtureBase for CosmosTransactionalBatchTest

a3dae7a

JoasE changed the title ~~Add BulkExecutionEnabled to CosmosDbContextOptionsBuilder~~ Add Cosmos bulk execution Nov 25, 2025

JoasE added 6 commits November 25, 2025 11:58

Add some tests and fix Always behaviour

1127f4b

Fix empty savechanges

9d8eaf5

Add more tests

e5186d3

Cleanup

39ace79

Make public api virtual

5451acd

Fix small mistake in test ConcurrencyContext CreateContext

f8d12d6

JoasE marked this pull request as ready for review November 25, 2025 15:00

JoasE requested a review from AndriySvyryd November 25, 2025 15:01

AndriySvyryd requested a review from Copilot November 25, 2025 18:30

Copilot started reviewing on behalf of AndriySvyryd November 25, 2025 18:30 View session

Copilot finished reviewing on behalf of AndriySvyryd November 25, 2025 18:34

Copilot AI reviewed Nov 25, 2025

View reviewed changes

AndriySvyryd reviewed Nov 25, 2025

View reviewed changes

src/EFCore.Cosmos/Storage/Internal/CosmosDatabaseWrapper.cs Outdated Show resolved Hide resolved

AndriySvyryd reviewed Nov 25, 2025

View reviewed changes

src/EFCore.Cosmos/Storage/Internal/CosmosDatabaseWrapper.cs Outdated Show resolved Hide resolved

AndriySvyryd reviewed Nov 25, 2025

View reviewed changes

AndriySvyryd requested changes Nov 25, 2025

View reviewed changes

JoasE and others added 5 commits November 26, 2025 11:37

Apply suggestions from code review

02a6c44

Co-authored-by: Copilot <[email protected]> Co-authored-by: Andriy Svyryd <[email protected]>

Reorganize tests

55dcd35

Small comment fixes

0f7535c

Do not wrap BulkExecutionWithTransactionalBatch & dont use == true Rename BulkExecutionWithTransactionalBatchEventData

Update CosmosBulkExecutionTest.cs

e255573

Configure warning to throw by default

bdc54be

	coreOptionsExtension.WarningsConfiguration.TryWithExplicit(
	InMemoryEventId.TransactionIgnoredWarning, WarningBehavior.Throw));

Add Cosmos bulk execution #37033

Are you sure you want to change the base?

Add Cosmos bulk execution #37033

Conversation

JoasE commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JoasE commented Oct 28, 2025

Uh oh!

AndriySvyryd left a comment

Choose a reason for hiding this comment

Uh oh!

JoasE commented Nov 1, 2025

Uh oh!

JoasE commented Nov 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AndriySvyryd Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AndriySvyryd Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

AndriySvyryd Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

JoasE Nov 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AndriySvyryd Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

AndriySvyryd Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

AndriySvyryd left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

JoasE commented Oct 27, 2025 •

edited

Loading

JoasE commented Nov 1, 2025 •

edited

Loading