Add documentation for cosmos db provider transactional batches

entity-framework/core/providers/cosmos/limitations.md

@@ -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).

entity-framework/core/providers/cosmos/saving.md

@@ -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
+```

entity-framework/toc.yml

@@ -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