Merge origin/main into batch branch: bring in files namespace and model reorganization

- Keep both client.files and client.batch namespaces
- Accept origin/main's _list_entities with filter/select parameters
- Fix imports: models.metadata was reorganized into relationship.py + labels.py

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

Author: Samson Gebre

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

@@ -21,6 +21,7 @@ Use the PowerPlatform Dataverse Client Python SDK to interact with Microsoft Dat
 - `client.records` -- CRUD and OData queries
 - `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
@@ -108,6 +109,40 @@ client.records.update("account", account_id, {"telephone1": "555-0200"})
 client.records.update("account", [id1, id2, id3], {"industry": "Technology"})
 ```
 
+#### Upsert Records
+Creates or updates records identified by alternate keys. Single item → PATCH; multiple items → `UpsertMultiple` bulk action.
+> **Prerequisite**: The table must have an alternate key configured in Dataverse for the columns used in `alternate_key`. Without it, Dataverse will reject the request with a 400 error.
+```python
+from PowerPlatform.Dataverse.models.upsert import UpsertItem
+
+# Single upsert
+client.records.upsert("account", [
+    UpsertItem(
+        alternate_key={"accountnumber": "ACC-001"},
+        record={"name": "Contoso Ltd", "telephone1": "555-0100"},
+    )
+])
+
+# Bulk upsert (uses UpsertMultiple API automatically)
+client.records.upsert("account", [
+    UpsertItem(alternate_key={"accountnumber": "ACC-001"}, record={"name": "Contoso Ltd"}),
+    UpsertItem(alternate_key={"accountnumber": "ACC-002"}, record={"name": "Fabrikam Inc"}),
+])
+
+# Composite alternate key
+client.records.upsert("account", [
+    UpsertItem(
+        alternate_key={"accountnumber": "ACC-001", "address1_postalcode": "98052"},
+        record={"name": "Contoso Ltd"},
+    )
+])
+
+# Plain dict syntax (no import needed)
+client.records.upsert("account", [
+    {"alternate_key": {"accountnumber": "ACC-001"}, "record": {"name": "Contoso Ltd"}}
+])
+```
+
 #### Delete Records
 ```python
 # Single delete
@@ -198,7 +233,7 @@ client.tables.delete("new_Product")
 
 #### Create One-to-Many Relationship
 ```python
-from PowerPlatform.Dataverse.models.metadata import (
+from PowerPlatform.Dataverse.models.relationship import (
     LookupAttributeMetadata,
     OneToManyRelationshipMetadata,
     Label,
@@ -230,7 +265,7 @@ print(f"Created lookup field: {result['lookup_schema_name']}")
 
 #### Create Many-to-Many Relationship
 ```python
-from PowerPlatform.Dataverse.models.metadata import ManyToManyRelationshipMetadata
+from PowerPlatform.Dataverse.models.relationship import ManyToManyRelationshipMetadata
 
 relationship = ManyToManyRelationshipMetadata(
     schema_name="new_employee_project",
@@ -268,11 +303,11 @@ client.tables.delete_relationship(result["relationship_id"])
 
 ```python
 # Upload file to a file column
-client.upload_file(
-    table_schema_name="account",
+client.files.upload(
+    table="account",
     record_id=account_id,
-    file_name_attribute="new_Document",  # If the file column doesn't exist, it will be created automatically
-    path="/path/to/document.pdf"
+    file_column="new_Document",  # If the file column doesn't exist, it will be created automatically
+    path="/path/to/document.pdf",
 )
 ```
 

.github/workflows/ado-pipeline-yaml-pr-warning.yml

@@ -0,0 +1,55 @@
+name: Warn when ADO pipeline YAML file changes
+
+on:
+  pull_request:
+    paths:
+      - ".azdo/ci-pr.yaml"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  warn:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Emit warning in logs
+        run: |
+          echo "::warning file=.azdo/ci-pr.yaml::This PR changes .azdo/ci-pr.yaml. After merge, Azure DevOps may disable/require approval for the PR pipeline YAML until it is re-enabled/approved."
+
+          echo "ADO pipeline: DV-Python-SDK-PullRequest (definitionId=29922)"
+          echo "https://dev.azure.com/dynamicscrm/OneCRM/_build?definitionId=29922"
+
+      - name: Add workflow summary
+        run: |
+          {
+            echo "## ADO PR pipeline YAML change detected"
+            echo ""
+            echo "**File changed:** \`.azdo/ci-pr.yaml\`"
+            echo ""
+            echo "**Why this matters:** After this is merged, Azure DevOps may disable/require approval for the PR pipeline YAML."
+            echo ""
+            echo "**Action required (post-merge):** Re-enable / approve the updated YAML for:"
+            echo "- **DV-Python-SDK-PullRequest** (definitionId=29922)"
+            echo "- https://dev.azure.com/dynamicscrm/OneCRM/_build?definitionId=29922"
+            echo ""
+            echo "Then trigger a run to confirm PR validation works."
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Post resolvable PR review comment
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          jq -n \
+            --arg sha "${{ github.event.pull_request.head.sha }}" \
+            '{
+              path: ".azdo/ci-pr.yaml",
+              subject_type: "file",
+              commit_id: $sha,
+              body: "> [!WARNING]\n> **ADO PR pipeline YAML change detected**\n>\n> This PR modifies `.azdo/ci-pr.yaml`. After merge, Azure DevOps may disable or require approval for the PR validation pipeline.\n>\n> **Action required (post-merge):** Re-enable / approve the updated YAML for:\n> - **DV-Python-SDK-PullRequest** (definitionId=29922)\n> - https://dev.azure.com/dynamicscrm/OneCRM/_build?definitionId=29922\n>\n> Please resolve this comment after completing the post-merge steps."
+            }' | \
+          gh api \
+            --method POST \
+            -H "Accept: application/vnd.github+json" \
+            /repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/comments \
+            --input -

CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.0b4] - 2026-02-25
+
+### Added
+- Operation namespaces: `client.records`, `client.query`, `client.tables`, `client.files` (#102)
+- Relationship management: `create_one_to_many_relationship`, `create_many_to_many_relationship`, `get_relationship`, `delete_relationship`, `create_lookup_field` with typed `RelationshipInfo` return model (#105, #114)
+- `client.records.upsert()` for upsert operations with alternate key support (#106)
+- `client.files.upload()` for file upload operations (#111)
+- `client.tables.list(filter=, select=)` parameters for filtering and projecting table metadata (#112)
+- Cascade behavior constants (`CASCADE_BEHAVIOR_CASCADE`, `CASCADE_BEHAVIOR_REMOVE_LINK`, etc.) and input models (`CascadeConfiguration`, `LookupAttributeMetadata`, `Label`, `LocalizedLabel`)
+
+### Deprecated
+- All flat methods on `DataverseClient` (`create`, `update`, `delete`, `get`, `query_sql`, `upload_file`, etc.) now emit `DeprecationWarning` and delegate to the corresponding namespaced operations
+
+## [0.1.0b3] - 2025-12-19
+
+### Added
+- Client-side correlation ID and client request ID for request tracing (#70)
+- Unit tests for `DataverseClient` (#71)
+
+### Changed
+- Standardized package versioning (#84)
+- Updated package link (#69)
+
+### Fixed
+- Retry logic for examples (#72)
+- Removed double space formatting issue (#82)
+- Updated CI trigger to include main branch (#81)
+
+## [0.1.0b2] - 2025-11-17
+
+### Added
+- Enforce Black formatting across the codebase (#61, #62)
+- Python 3.14 support added to `pyproject.toml` (#55)
+
+### Changed
+- Removed `pandas` dependency (#57)
+- Refactored SDK architecture and quality improvements (#55)
+- Prefixed table names with schema name for consistency (#51)
+- Updated docstrings across core modules (#54, #63)
+
+### Fixed
+- Fixed `get` for single-select option set columns (#52)
+- Fixed example filename references and documentation URLs (#60)
+- Fixed API documentation link in examples (#64)
+- Fixed CI pipeline to use modern `pyproject.toml` dev dependencies (#56, #59)
+
 ## [0.1.0b1] - 2025-11-14
 
 ### Added
@@ -19,6 +65,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Comprehensive error handling with specific exception types (`DataverseError`, `AuthenticationError`, etc.) (#22, #24)
 - HTTP retry logic with exponential backoff for resilient operations (#72)
 
+[0.1.0b4]: https://github.com/microsoft/PowerPlatform-DataverseClient-Python/compare/v0.1.0b3...v0.1.0b4
 [0.1.0b3]: https://github.com/microsoft/PowerPlatform-DataverseClient-Python/compare/v0.1.0b2...v0.1.0b3
 [0.1.0b2]: https://github.com/microsoft/PowerPlatform-DataverseClient-Python/compare/v0.1.0b1...v0.1.0b2
 [0.1.0b1]: https://github.com/microsoft/PowerPlatform-DataverseClient-Python/releases/tag/v0.1.0b1

CONTRIBUTING.md

@@ -109,4 +109,16 @@ Brief summary of the release
 ### Fixed
 - Bug fix 1 (#125)
 - Bug fix 2 (#126)
+```
+
+**Post-Release Version Bump:**
+
+After tagging and publishing a release, immediately bump the version on `main` to the next
+development target. This ensures builds from source are clearly distinguished from the
+published release:
+
+```bash
+# After publishing v0.1.0b4, bump to v0.1.0b5 on main
+# Update both pyproject.toml and src/PowerPlatform/Dataverse/__version__.py
+# Commit directly to main: "Bump version to 0.1.0b5 for next development cycle"
 ```

README.md

@@ -23,6 +23,7 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
   - [Quick start](#quick-start)
   - [Basic CRUD operations](#basic-crud-operations)
   - [Bulk operations](#bulk-operations)
+  - [Upsert operations](#upsert-operations)
   - [Query data](#query-data)
   - [Table management](#table-management)
   - [Relationship management](#relationship-management)
@@ -35,7 +36,7 @@ A Python client library for Microsoft Dataverse that provides a unified interfac
 ## Key features
 
 - **🔄 CRUD Operations**: Create, read, update, and delete records with support for bulk operations and automatic retry
-- **⚡ True Bulk Operations**: Automatically uses Dataverse's native `CreateMultiple`, `UpdateMultiple`, and `BulkDelete` Web API operations for maximum performance and transactional integrity
+- **⚡ True Bulk Operations**: Automatically uses Dataverse's native `CreateMultiple`, `UpdateMultiple`, `UpsertMultiple`, and `BulkDelete` Web API operations for maximum performance and transactional integrity
 - **📊 SQL Queries**: Execute read-only SQL queries via the Dataverse Web API `?sql=` parameter  
 - **🏗️ Table Management**: Create, inspect, and delete custom tables and columns programmatically
 - **🔗 Relationship Management**: Create one-to-many and many-to-many relationships between tables with full metadata control
@@ -113,8 +114,8 @@ The SDK provides a simple, pythonic interface for Dataverse operations:
 
 | Concept | Description |
 |---------|-------------|
-| **DataverseClient** | Main entry point; provides `records`, `query`, `tables`, and `batch` namespaces |
-| **Namespaces** | Operations are organized into `client.records` (CRUD & OData queries), `client.query` (query & search), `client.tables` (metadata), and `client.batch` (batch requests) |
+| **DataverseClient** | Main entry point; provides `records`, `query`, `tables`, `files`, and `batch` namespaces |
+| **Namespaces** | Operations are organized into `client.records` (CRUD & OData queries), `client.query` (query & search), `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 |
@@ -180,6 +181,57 @@ client.records.update("account", ids, {"industry": "Technology"})
 client.records.delete("account", ids, use_bulk_delete=True)
 ```
 
+### Upsert operations
+
+Use `client.records.upsert()` to create or update records identified by alternate keys. When the
+key matches an existing record it is updated; otherwise the record is created. A single item uses
+a PATCH request; multiple items use the `UpsertMultiple` bulk action.
+
+> **Prerequisite**: The table must have an **alternate key** configured in Dataverse for the
+> columns used in `alternate_key`. Alternate keys are defined in the table's metadata (Power Apps
+> maker portal → Table → Keys, or via the Dataverse API). Without a configured alternate key,
+> upsert requests will be rejected by Dataverse with a 400 error.
+
+```python
+from PowerPlatform.Dataverse.models.upsert import UpsertItem
+
+# Upsert a single record
+client.records.upsert("account", [
+    UpsertItem(
+        alternate_key={"accountnumber": "ACC-001"},
+        record={"name": "Contoso Ltd", "telephone1": "555-0100"},
+    )
+])
+
+# Upsert multiple records (uses UpsertMultiple bulk action)
+client.records.upsert("account", [
+    UpsertItem(
+        alternate_key={"accountnumber": "ACC-001"},
+        record={"name": "Contoso Ltd"},
+    ),
+    UpsertItem(
+        alternate_key={"accountnumber": "ACC-002"},
+        record={"name": "Fabrikam Inc"},
+    ),
+])
+
+# Composite alternate key (multiple columns identify the record)
+client.records.upsert("account", [
+    UpsertItem(
+        alternate_key={"accountnumber": "ACC-001", "address1_postalcode": "98052"},
+        record={"name": "Contoso Ltd"},
+    )
+])
+
+# Plain dict syntax (no import needed)
+client.records.upsert("account", [
+    {
+        "alternate_key": {"accountnumber": "ACC-001"},
+        "record": {"name": "Contoso Ltd"},
+    }
+])
+```
+
 ### Query data
 
 ```python
@@ -267,13 +319,12 @@ client.tables.delete("new_Product")
 Create relationships between tables using the relationship API. For a complete working example, see [examples/advanced/relationships.py](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/blob/main/examples/advanced/relationships.py).
 
 ```python
-from PowerPlatform.Dataverse.models.metadata import (
+from PowerPlatform.Dataverse.models.relationship import (
     LookupAttributeMetadata,
     OneToManyRelationshipMetadata,
     ManyToManyRelationshipMetadata,
-    Label,
-    LocalizedLabel,
 )
+from PowerPlatform.Dataverse.models.labels import Label, LocalizedLabel
 
 # Create a one-to-many relationship: Department (1) -> Employee (N)
 # This adds a "Department" lookup field to the Employee table
@@ -328,11 +379,11 @@ result = client.tables.create_lookup_field(
 
 ```python
 # Upload a file to a record
-client.upload_file(
-    table_schema_name="account",
-    record_id=account_id,
-    file_name_attribute="new_Document",  # If the file column doesn't exist, it will be created automatically
-    path="/path/to/document.pdf"
+client.files.upload(
+    "account",
+    account_id,
+    "new_Document",  # If the file column doesn't exist, it will be created automatically
+    "/path/to/document.pdf",
 )
 ```