Merge main into copilot/add-public-api-for-metadata

Resolved conflicts in _odata.py (kept write-blocking + guardrails from
HEAD, adopted _execute_raw/_build_sql pattern from main for proper URL
encoding; merged all error code imports) and test_sql_parse.py (kept
both JOIN extraction tests from HEAD and _build_sql URL encoding tests
from main).

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

Author: Samson Gebre

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

@@ -13,7 +13,7 @@ This skill provides guidance for developers working on the PowerPlatform Dataver
 
 ### API Design
 
-1. **Public methods in operation namespaces** - New public methods go in the appropriate namespace module under `src/PowerPlatform/Dataverse/operations/` (`records.py`, `query.py`, `tables.py`). The `client.py` file exposes these via namespace properties (`client.records`, `client.query`, `client.tables`). Public types and constants live in their own modules (e.g., `models/metadata.py`, `common/constants.py`)
+1. **Public methods in operation namespaces** - New public methods go in the appropriate namespace module under `src/PowerPlatform/Dataverse/operations/` (`records.py`, `query.py`, `tables.py`, `batch.py`). The `client.py` file exposes these via namespace properties (`client.records`, `client.query`, `client.tables`, `client.batch`). Public types and constants live in their own modules (e.g., `models/metadata.py`, `models/batch.py`, `common/constants.py`)
 2. **Every public method needs README example** - Public API methods must have examples in README.md
 3. **Reuse existing APIs** - Always check if an existing method can be used before making direct Web API calls
 4. **Update documentation** when adding features - Keep README and SKILL files (both copies) in sync

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

@@ -22,6 +22,7 @@ Use the PowerPlatform Dataverse Client Python SDK to interact with Microsoft Dat
 - `client.query` -- query and search operations
 - `client.tables` -- table metadata, columns, and relationships
 - `client.files` -- file upload operations
+- `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()` for automatic bulk processing, for `delete()`, set `use_bulk_delete` when passing lists to use bulk operation
@@ -369,6 +370,50 @@ client.files.upload(
 )
 ```
 
+### Batch Operations
+
+Use `client.batch` to send multiple operations in one HTTP request. All batch methods return `None`; results arrive via `BatchResult` after `execute()`.
+
+```python
+# Build a batch request
+batch = client.batch.new()
+batch.records.create("account", {"name": "Contoso"})
+batch.records.update("account", account_id, {"telephone1": "555-0100"})
+batch.records.get("account", account_id, select=["name"])
+batch.query.sql("SELECT TOP 5 name FROM account")
+
+result = batch.execute()
+for item in result.responses:
+    if item.is_success:
+        print(f"[OK] {item.status_code} entity_id={item.entity_id}")
+        if item.data:
+            # GET responses populate item.data with the parsed JSON record
+            print(item.data.get("name"))
+    else:
+        print(f"[ERR] {item.status_code}: {item.error_message}")
+
+# Transactional changeset (all succeed or roll back)
+with batch.changeset() as cs:
+    ref = cs.records.create("contact", {"firstname": "Alice"})
+    cs.records.update("account", account_id, {"primarycontactid@odata.bind": ref})
+
+# Continue on error
+result = batch.execute(continue_on_error=True)
+print(f"Succeeded: {len(result.succeeded)}, Failed: {len(result.failed)}")
+```
+
+**BatchResult properties:**
+- `result.responses` -- list of `BatchItemResponse` in submission order
+- `result.succeeded` -- responses with 2xx status codes
+- `result.failed` -- responses with non-2xx status codes
+- `result.has_errors` -- True if any response failed
+- `result.entity_ids` -- GUIDs from OData-EntityId headers (creates and updates)
+
+**Batch limitations:**
+- Maximum 1000 operations per batch
+- Paginated `records.get()` (without `record_id`) is not supported in batch
+- `flush_cache()` is not supported in batch
+
 ## Error Handling
 
 The SDK provides structured exceptions with detailed error information:

README.md

@@ -29,6 +29,7 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
   - [Table management](#table-management)
   - [Relationship management](#relationship-management)
   - [File operations](#file-operations)
+  - [Batch operations](#batch-operations)
 - [Next steps](#next-steps)
 - [Troubleshooting](#troubleshooting)
 - [Contributing](#contributing)
@@ -43,6 +44,7 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
 - **🔗 Relationship Management**: Create one-to-many and many-to-many relationships between tables with full metadata control
 - **🐼 DataFrame Support**: Pandas wrappers for all CRUD operations, returning DataFrames and Series
 - **📎 File Operations**: Upload files to Dataverse file columns with automatic chunking for large files
+- **📦 Batch Operations**: Send multiple CRUD, table metadata, and SQL query operations in a single HTTP request with optional transactional changesets
 - **🔐 Azure Identity**: Built-in authentication using Azure Identity credential providers with comprehensive support
 - **🛡️ Error Handling**: Structured exception hierarchy with detailed error context and retry guidance
 
@@ -115,9 +117,9 @@ The SDK provides a simple, pythonic interface for Dataverse operations:
 
 | Concept | Description |
 |---------|-------------|
-| **DataverseClient** | Main entry point; provides `records`, `query`, `tables`, and `files` namespaces |
+| **DataverseClient** | Main entry point; provides `records`, `query`, `tables`, `files`, and `batch` namespaces |
 | **Context Manager** | Use `with DataverseClient(...) as client:` for automatic cleanup and HTTP connection pooling |
-| **Namespaces** | Operations are organized into `client.records` (CRUD & OData queries), `client.query` (QueryBuilder & SQL), `client.tables` (metadata), and `client.files` (file uploads) |
+| **Namespaces** | Operations are organized into `client.records` (CRUD & OData queries), `client.query` (QueryBuilder & SQL), `client.tables` (metadata), `client.files` (file uploads), and `client.batch` (batch requests) |
 | **Records** | Dataverse records represented as Python dictionaries with column schema names |
 | **Schema names** | Use table schema names (`"account"`, `"new_MyTestTable"`) and column schema names (`"name"`, `"new_MyTestColumn"`). See: [Table definitions in Microsoft Dataverse](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/entity-metadata) |
 | **Bulk Operations** | Efficient bulk processing for multiple records with automatic optimization |
@@ -592,6 +594,90 @@ client.files.upload(
 )
 ```
 
+### Batch operations
+
+Use `client.batch` to send multiple operations in one HTTP request. The batch namespace mirrors `client.records`, `client.tables`, and `client.query`.
+
+```python
+# Build a batch request and add operations
+batch = client.batch.new()
+batch.records.create("account", {"name": "Contoso"})
+batch.records.create("account", [{"name": "Fabrikam"}, {"name": "Woodgrove"}])
+batch.records.update("account", account_id, {"telephone1": "555-0100"})
+batch.records.delete("account", old_id)
+batch.records.get("account", account_id, select=["name"])
+
+result = batch.execute()
+for item in result.responses:
+    if item.is_success:
+        print(f"[OK] {item.status_code} entity_id={item.entity_id}")
+    else:
+        print(f"[ERR] {item.status_code}: {item.error_message}")
+```
+
+**Transactional changeset** — all operations in a changeset succeed or roll back together:
+
+```python
+batch = client.batch.new()
+with batch.changeset() as cs:
+    lead_ref = cs.records.create("lead", {"firstname": "Ada"})
+    contact_ref = cs.records.create("contact", {"firstname": "Ada"})
+    cs.records.create("account", {
+        "name": "Babbage & Co.",
+        "originatingleadid@odata.bind": lead_ref,
+        "primarycontactid@odata.bind": contact_ref,
+    })
+result = batch.execute()
+print(f"Created {len(result.entity_ids)} records atomically")
+```
+
+**Table metadata and SQL queries in a batch:**
+
+```python
+batch = client.batch.new()
+batch.tables.create("new_Product", {"new_Price": "decimal", "new_InStock": "bool"})
+batch.tables.add_columns("new_Product", {"new_Rating": "int"})
+batch.tables.get("new_Product")
+batch.query.sql("SELECT TOP 5 name FROM account")
+
+result = batch.execute()
+```
+
+**Continue on error** — attempt all operations even when one fails:
+
+```python
+result = batch.execute(continue_on_error=True)
+print(f"Succeeded: {len(result.succeeded)}, Failed: {len(result.failed)}")
+for item in result.failed:
+    print(f"[ERR] {item.status_code}: {item.error_message}")
+```
+
+**DataFrame integration** -- feed pandas DataFrames directly into a batch:
+
+```python
+import pandas as pd
+
+batch = client.batch.new()
+
+# Create records from a DataFrame
+df = pd.DataFrame([{"name": "Contoso"}, {"name": "Fabrikam"}])
+batch.dataframe.create("account", df)
+
+# Update records from a DataFrame
+updates = pd.DataFrame([
+    {"accountid": id1, "telephone1": "555-0100"},
+    {"accountid": id2, "telephone1": "555-0200"},
+])
+batch.dataframe.update("account", updates, id_column="accountid")
+
+# Delete records from a Series
+batch.dataframe.delete("account", pd.Series([id1, id2]))
+
+result = batch.execute()
+```
+
+For a complete example see [examples/advanced/batch.py](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/batch.py).
+
 ## Next steps
 
 ### More sample code
@@ -606,6 +692,7 @@ Explore our comprehensive examples in the [`examples/`](https://github.com/micro
 - **[Complete Walkthrough](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/walkthrough.py)** - Full feature demonstration with production patterns
 - **[Relationship Management](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/relationships.py)** - Create and manage table relationships
 - **[File Upload](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/file_upload.py)** - Upload files to Dataverse file columns
+- **[Batch Operations](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/batch.py)** - Send multiple operations in a single request with changesets
 
 📖 See the [examples README](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/README.md) for detailed guidance and learning progression.