feat: upsert and upsertmultiple functionality with alternate key support (#106)

* feat: implement upsert and upsertmultiple functionality with alternate key support

* enhance upsert validation and add unit tests for alternate key handling

* fix format with black

* fix: apply black formatting to records.py

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

* docs: add upsert usage to README and SKILL.md

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

* docs: add upsert section to README and SKILL.md with prerequisite note

Documents client.records.upsert() usage including single, bulk, composite
key, and plain dict (no-import) examples. Adds prerequisite note that an
alternate key must be configured in Dataverse before upsert will work.

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

---------

Co-authored-by: Samson Gebre <sagebree@microsoft.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 3 people

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

@@ -107,6 +107,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

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)
@@ -34,7 +35,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
@@ -178,6 +179,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

src/PowerPlatform/Dataverse/claude_skill/dataverse-sdk-use/SKILL.md

@@ -107,6 +107,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

src/PowerPlatform/Dataverse/data/_odata.py

@@ -352,6 +352,124 @@ def _create_multiple(self, entity_set: str, table_schema_name: str, records: Lis
             return out
         return []
 
+    def _build_alternate_key_str(self, alternate_key: Dict[str, Any]) -> str:
+        """Build an OData alternate key segment from a mapping of key names to values.
+
+        String values are single-quoted and escaped; all other values are rendered as-is.
+
+        :param alternate_key: Mapping of alternate key attribute names to their values.
+            Must be a non-empty dict with string keys.
+        :type alternate_key: ``dict[str, Any]``
+
+        :return: Comma-separated key=value pairs suitable for use in a URL segment.
+        :rtype: ``str``
+
+        :raises ValueError: If ``alternate_key`` is empty.
+        :raises TypeError: If any key in ``alternate_key`` is not a string.
+        """
+        if not alternate_key:
+            raise ValueError("alternate_key must be a non-empty dict")
+        bad_keys = [k for k in alternate_key if not isinstance(k, str)]
+        if bad_keys:
+            raise TypeError(f"alternate_key keys must be strings; got: {bad_keys!r}")
+        parts = []
+        for k, v in alternate_key.items():
+            k_lower = k.lower() if isinstance(k, str) else k
+            if isinstance(v, str):
+                v_escaped = self._escape_odata_quotes(v)
+                parts.append(f"{k_lower}='{v_escaped}'")
+            else:
+                parts.append(f"{k_lower}={v}")
+        return ",".join(parts)
+
+    def _upsert(
+        self,
+        entity_set: str,
+        table_schema_name: str,
+        alternate_key: Dict[str, Any],
+        record: Dict[str, Any],
+    ) -> None:
+        """Upsert a single record using an alternate key.
+
+        Issues a PATCH request to ``{entity_set}({key_pairs})`` where ``key_pairs``
+        is the OData alternate key segment built from ``alternate_key``. Creates the
+        record if it does not exist; updates it if it does.
+
+        :param entity_set: Resolved entity set (plural) name.
+        :type entity_set: ``str``
+        :param table_schema_name: Schema name of the table.
+        :type table_schema_name: ``str``
+        :param alternate_key: Mapping of alternate key attribute names to their values
+            used to identify the target record in the URL.
+        :type alternate_key: ``dict[str, Any]``
+        :param record: Attribute payload to set on the record.
+        :type record: ``dict[str, Any]``
+
+        :return: ``None``
+        :rtype: ``None``
+        """
+        record = self._lowercase_keys(record)
+        record = self._convert_labels_to_ints(table_schema_name, record)
+        key_str = self._build_alternate_key_str(alternate_key)
+        url = f"{self.api}/{entity_set}({key_str})"
+        self._request("patch", url, json=record, expected=(200, 201, 204))
+
+    def _upsert_multiple(
+        self,
+        entity_set: str,
+        table_schema_name: str,
+        alternate_keys: List[Dict[str, Any]],
+        records: List[Dict[str, Any]],
+    ) -> None:
+        """Upsert multiple records using the collection-bound ``UpsertMultiple`` action.
+
+        Each target is formed by merging the corresponding alternate key fields and record
+        fields. The ``@odata.type`` annotation is injected automatically if absent.
+
+        :param entity_set: Resolved entity set (plural) name.
+        :type entity_set: ``str``
+        :param table_schema_name: Schema name of the table.
+        :type table_schema_name: ``str``
+        :param alternate_keys: List of alternate key dictionaries, one per record.
+            Order is significant: ``alternate_keys[i]`` must correspond to ``records[i]``.
+            Python ``list`` preserves insertion order, so the correspondence is guaranteed
+            as long as both lists are built from the same source in the same order.
+        :type alternate_keys: ``list[dict[str, Any]]``
+        :param records: List of record payload dictionaries, one per record.
+            Must be the same length as ``alternate_keys``.
+        :type records: ``list[dict[str, Any]]``
+
+        :return: ``None``
+        :rtype: ``None``
+
+        :raises ValueError: If ``alternate_keys`` and ``records`` differ in length, or if
+            any record payload contains an alternate key field with a conflicting value.
+        """
+        if len(alternate_keys) != len(records):
+            raise ValueError(
+                f"alternate_keys and records must have the same length " f"({len(alternate_keys)} != {len(records)})"
+            )
+        logical_name = table_schema_name.lower()
+        targets: List[Dict[str, Any]] = []
+        for alt_key, record in zip(alternate_keys, records):
+            alt_key_lower = self._lowercase_keys(alt_key)
+            record_processed = self._lowercase_keys(record)
+            record_processed = self._convert_labels_to_ints(table_schema_name, record_processed)
+            conflicting = {
+                k for k in set(alt_key_lower) & set(record_processed) if alt_key_lower[k] != record_processed[k]
+            }
+            if conflicting:
+                raise ValueError(f"record payload conflicts with alternate_key on fields: {sorted(conflicting)!r}")
+            combined: Dict[str, Any] = {**alt_key_lower, **record_processed}
+            if "@odata.type" not in combined:
+                combined["@odata.type"] = f"Microsoft.Dynamics.CRM.{logical_name}"
+            key_str = self._build_alternate_key_str(alt_key)
+            combined["@odata.id"] = f"{entity_set}({key_str})"
+            targets.append(combined)
+        payload = {"Targets": targets}
+        url = f"{self.api}/{entity_set}/Microsoft.Dynamics.CRM.UpsertMultiple"
+        self._request("post", url, json=payload, expected=(200, 201, 204))
+
     # --- Derived helpers for high-level client ergonomics ---
     def _primary_id_attr(self, table_schema_name: str) -> str:
         """Return primary key attribute using metadata; error if unavailable."""

src/PowerPlatform/Dataverse/models/upsert.py

@@ -0,0 +1,39 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+
+"""Upsert data models for the Dataverse SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict
+
+__all__ = ["UpsertItem"]
+
+
+@dataclass
+class UpsertItem:
+    """Represents a single upsert operation targeting a record by its alternate key.
+
+    Used with :meth:`~PowerPlatform.Dataverse.operations.records.RecordOperations.upsert`
+    to upsert one or more records identified by alternate keys rather than primary GUIDs.
+
+    :param alternate_key: Dictionary mapping alternate key attribute names to their values.
+        String values are automatically quoted and escaped in the OData URL. Integer and
+        other non-string values are included without quotes.
+    :type alternate_key: dict[str, Any]
+    :param record: Dictionary of attribute names to values for the record payload.
+        Keys are automatically lowercased. Picklist labels are resolved to integer option
+        values when a matching option set is found.
+    :type record: dict[str, Any]
+
+    Example::
+
+        item = UpsertItem(
+            alternate_key={"accountnumber": "ACC-001", "address1_postalcode": "98052"},
+            record={"name": "Contoso Ltd", "telephone1": "555-0100"},
+        )
+    """
+
+    alternate_key: Dict[str, Any]
+    record: Dict[str, Any]