Add documentation for cosmos db provider transactional batches #5100
Conversation
|
Should probably only be merged once 11.0 is out? I could not find a 11.0 or release branching strategy in the repo and the contributing guide said to target main (I only found live) |
There was a problem hiding this comment.
Thanks for writing docs on this - that's much appreciated, even if quite early given this feature hasn't been merged yet and won't appear until EF 11 😅 I'm worried that additional PR changes/design discussions may still change some details which would require changing the docs again.
In any case, see below for some review comments.
|
|
||
| Common EF Core patterns that either do not apply, or are a pit-of-failure, when using a document database include: | ||
|
|
||
| - [Transactions](../../saving/transactions) are not supported, since Azure Cosmos DB does not implement relational-style transactions, as is typical of most document databases. However, the EF Core Azure Cosmos DB provider will use [Transactional batches](azure/cosmos-db/nosql/transactional-batch) when possible. See [Atomicity of SaveChanges](savechanges-atomicity) for further details. |
There was a problem hiding this comment.
| - [Transactions](../../saving/transactions) are not supported, since Azure Cosmos DB does not implement relational-style transactions, as is typical of most document databases. However, the EF Core Azure Cosmos DB provider will use [Transactional batches](azure/cosmos-db/nosql/transactional-batch) when possible. See [Atomicity of SaveChanges](savechanges-atomicity) for further details. | |
| Like most document databases, Azure Cosmos DB does not implement relational-style transactions, which provide full ACID guarantees across any number of operations and tables. However, the EF Core Azure Cosmos DB provider uses [Transactional batches](azure/cosmos-db/nosql/transactional-batch) when possible; see [Atomicity of SaveChanges](savechanges-atomicity) for further details. |
| --- | ||
| # EF Core Azure Cosmos DB Provider Atomicity of SaveChanges | ||
|
|
||
| Azure Cosmos DB does not support transactions in the relational database sense. That is, there is no concept of a single atomic transaction spanning arbitrary operations across containers or partitions. This is a common limitation of document databases, where the focus is on scalability and availability rather than strict transactional semantics. |
There was a problem hiding this comment.
The word feels a bit too hard, given that just below we discuss transactional batches which do provide relational-like transactional guarantees (albeit with some restrictions).
|
|
||
| ## How EF Core saves changes in batches | ||
|
|
||
| When SaveChanges or SaveChangesAsync is called, the provider groups pending changes into transactional batches. Each batch contains up to 100 entries, grouped by container and partition key. These batches are then executed sequentially. If a batch fails, execution stops immediately and no subsequent batches are attempted. Any batches that were successfully committed before the failure remain saved. |
There was a problem hiding this comment.
This seems to describe the default behavior (Auto), without mentioning that this behavior can be changed. I'd simply merge this doc section with the one below - both deal with the same thing.
| ms.date: 09/10/2025 | ||
| uid: core/providers/cosmos/savechanges-atomicity | ||
| --- | ||
| # EF Core Azure Cosmos DB Provider Atomicity of SaveChanges |
There was a problem hiding this comment.
I'd suggest putting this content in a general Cosmos page called "Save data" (just like the top-level docs category we already have); if we have other SaveChanges-related content, it seems like it would go into the same page rather than having a whole separate page just for atomicity, etc.
In any case, the title here (and above in the front matter) should be aligned with the way it's done in other pages.
|
@roji You're right! Sorry about that, should have probably at-least kept it as draft until the other PR was merged. Will do that now. I had some time left over so didn't mind working ahead a bit and making changes later if needed. Thank you for reviewing despite that! |
Adds documentation for the usage of TransactionalBatch in the Cosmos DB provider when saving changes.
See: dotnet/efcore#17308 and dotnet/efcore#36693