Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Add documentation for cosmos db provider transactional batches #5100

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
JoasE wants to merge 6 commits into dotnet:live
base: live
Choose a base branch
Loading
from JoasE:cosmos-transactional-batch
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions entity-framework/core/providers/cosmos/limitations.md
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ The Azure Cosmos DB database provider targets the Azure Cosmos DB NoSQL store, w

Common EF Core patterns that either do not apply, or are a pit-of-failure, when using a document database include:

- 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 [Saving data](saving) for further details.
- Schema migration is not supported, since there is no defined schema for the documents. However, there could be other mechanisms for dealing with evolving data shapes that do make sense with Azure Cosmos DB NoSQL, For example, [Schema versioning pattern with Azure Cosmos DB](https://github.com/dotnet/efcore/issues/23753), and [Azure Cosmos DB data migration](https://github.com/dotnet/efcore/issues/11099).
- Reverse-engineering (scaffolding) a model from an existing database is not supported. Again, this is not supported because there is no defined database schema to scaffold from. However, see [Use shape of documents in the Azure Cosmos DB database to scaffold a schema](https://github.com/dotnet/efcore/issues/30290).
- Schema concepts defined on the EF model, like indexes and constraints, are ignored when using a document database, since there is no schema. Note that Azure Cosmos DB NoSQL performs [automatic indexing of documents](/azure/cosmos-db/index-overview).
Expand Down
26 changes: 26 additions & 0 deletions entity-framework/core/providers/cosmos/saving.md
View file Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
---
title: Saving data - Azure Cosmos DB Provider - EF Core
description: Explains saving data with the Azure Cosmos DB Provider as compared to other providers
author: JoasE
ms.date: 09/10/2025
uid: core/providers/cosmos/saving
---
# Saving data

In Azure Cosmos DB there is limited support for atomic transactions. This is a common limitation of document databases, where the focus is on scalability and availability rather than strict transactional semantics. Azure Cosmos DB supports [transactional batch](/azure/cosmos-db/nosql/transactional-batch) which allows up to 100 operations to be executed together as a batch within a single partition. Atomicity is guaranteed within a single batch: if any operation fails, the entire batch is rolled back and none of its changes are applied. However, once a batch is written, it cannot be rolled back or deferred, and atomicity cannot be enforced across multiple batches.

> [!WARNING]
> Azure Cosmos DB does not allow document writes with [pre- or post-triggers](/azure/cosmos-db/nosql/stored-procedures-triggers-udfs#triggers) to be part of a transactional batch. Because of this, any entities configured with triggers are executed separately and before any transactional batches. This can affect ordering and consistency in mixed scenarios.

By default, the EF Core Azure Cosmos DB provider leverages transactional batches whenever possible, providing a best-effort approximation of atomicity when saving changes. The batching behavior is controlled by the <xref:Microsoft.EntityFrameworkCore.Storage.IDatabase.AutoTransactionBehavior> property. This setting allows developers to trade off between performance, consistency guarantees, and failure behavior depending on the application’s needs.

* **Auto** (default) – Entries are grouped 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.This generally provides good performance for writing to multiple entities within the same partition with a best-effort approximation of atomicity.
* **Never** – All entries are written individually and sequentially, in the exact order they were tracked. This avoids batching and can be slower, especially for large numbers of entries.
* **Always** – Requires that all changes can be executed as a single atomic operation. If any entries cannot be included in a batch (for example, due to partitioning, exceeding 100 items, or there are multiple changed entries including one with triggers), the provider will throw an exception.

```csharp
using var context = new BlogsContext();
context.Database.AutoTransactionBehavior = AutoTransactionBehavior.Always;
context.AddRange(Enumerable.Range(0, 101).Select(i => new Post())); // 101 entries exceeds the batch item limit of 100.
await context.SaveChangesAsync(); // Throws InvalidOperationException
```
2 changes: 2 additions & 0 deletions entity-framework/toc.yml
View file Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -442,6 +442,8 @@
href: core/providers/cosmos/vector-search.md
- name: Full text search
href: core/providers/cosmos/full-text-search.md
- name: Save data
href: core/providers/cosmos/saving.md
- name: Azure Cosmos DB limitations
href: core/providers/cosmos/limitations.md
- name: End-to-end sample
Expand Down

AltStyle によって変換されたページ (->オリジナル) /