Document atomicity trade-off and <=1000 guidance for chunked operations

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Abel Milash

.claude/skills/dataverse-sdk-use/SKILL.md

@@ -25,7 +25,7 @@ Use the PowerPlatform Dataverse Client Python SDK to interact with Microsoft Dat
 - `client.batch` -- batch multiple operations into a single HTTP request
 
 ### Bulk Operations
-The SDK supports Dataverse's native bulk operations: Pass lists to `create()`, `update()`, or `upsert()` for automatic bulk processing; for `delete()`, set `use_bulk_delete=True`. Lists exceeding 1,000 records are automatically split into sequential 1,000-record chunks — no manual pre-splitting needed. Operations across chunks are **not atomic**: a failure mid-way may leave earlier chunks applied.
+The SDK supports Dataverse's native bulk operations: Pass lists to `create()`, `update()`, or `upsert()` for automatic bulk processing; for `delete()`, set `use_bulk_delete=True`. Lists exceeding 1,000 records are automatically split into sequential 1,000-record chunks — no manual pre-splitting needed. Operations across chunks are **not atomic**: a failure mid-way may leave earlier chunks applied. Callers that require atomicity should limit their input to ≤ 1,000 records.
 
 ### Paging
 - Control page size with `page_size` parameter

README.md

@@ -188,7 +188,8 @@ client.records.delete("account", ids, use_bulk_delete=True)
 
 > **Large batches**: Lists exceeding 1,000 records are automatically split into sequential
 > 1,000-record chunks — no manual pre-splitting needed. Note that chunked operations are
-> **not atomic**: a failure mid-way may leave earlier chunks applied.
+> **not atomic**: a failure mid-way may leave earlier chunks applied. Callers that require
+> atomicity should limit their input to ≤ 1,000 records.
 
 ### Upsert operations
 

src/PowerPlatform/Dataverse/operations/dataframe.py

@@ -182,7 +182,8 @@ def create(
             1,000-row chunks before sending to ``CreateMultiple``. You do not
             need to pre-split large DataFrames. Note that chunked operations
             are **not atomic** — a failure mid-way may leave earlier chunks
-            applied.
+            applied. Callers that require atomicity should limit input to
+            ≤ 1,000 rows.
 
         Example:
             Create records from a DataFrame::
@@ -259,7 +260,8 @@ def update(
             1,000-row chunks before sending to ``UpdateMultiple`` (or a single
             PATCH for one row). You do not need to pre-split large DataFrames.
             Note that chunked operations are **not atomic** — a failure
-            mid-way may leave earlier chunks applied.
+            mid-way may leave earlier chunks applied. Callers that require
+            atomicity should limit input to ≤ 1,000 rows.
 
         Example:
             Update records with different values per row::

src/PowerPlatform/Dataverse/operations/records.py

@@ -77,6 +77,12 @@ def create(
 
         :raises TypeError: If ``data`` is not a dict or list[dict].
 
+        .. note::
+            Lists exceeding 1,000 records are automatically split into
+            sequential chunks. This is **not atomic** — a failure mid-way
+            may leave earlier chunks applied. Callers that require atomicity
+            should limit input to ≤ 1,000 records.
+
         Example:
             Create a single record::
 
@@ -135,6 +141,12 @@ def update(
         :raises TypeError: If ``ids`` is not str or list[str], or if ``changes``
             does not match the expected pattern.
 
+        .. note::
+            Lists exceeding 1,000 IDs are automatically split into sequential
+            chunks. This is **not atomic** — a failure mid-way may leave
+            earlier chunks applied. Callers that require atomicity should
+            limit input to ≤ 1,000 IDs.
+
         Example:
             Single update::
 
@@ -486,6 +498,12 @@ def upsert(self, table: str, items: List[Union[UpsertItem, Dict[str, Any]]]) ->
             neither a :class:`~PowerPlatform.Dataverse.models.upsert.UpsertItem` nor a
             dict with ``"alternate_key"`` and ``"record"`` keys.
 
+        .. note::
+            Lists exceeding 1,000 items are automatically split into
+            sequential chunks. This is **not atomic** — a failure mid-way
+            may leave earlier chunks applied. Callers that require atomicity
+            should limit input to ≤ 1,000 items.
+
         Example:
             Upsert a single record using ``UpsertItem``::