feat: implement upsert and upsertmultiple functionality with alternate key support

Author: Samson Gebre

src/PowerPlatform/Dataverse/data/_odata.py

@@ -352,6 +352,110 @@ 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.
+        :type alternate_key: ``dict[str, Any]``
+
+        :return: Comma-separated key=value pairs suitable for use in a URL segment.
+        :rtype: ``str``
+        """
+        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.
+        """
+        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):
+            combined: Dict[str, Any] = {}
+            combined.update(self._lowercase_keys(alt_key))
+            record_processed = self._lowercase_keys(record)
+            record_processed = self._convert_labels_to_ints(table_schema_name, record_processed)
+            combined.update(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]

src/PowerPlatform/Dataverse/operations/records.py

@@ -7,6 +7,8 @@
 
 from typing import Any, Dict, List, Optional, Union, overload, TYPE_CHECKING
 
+from ..models.upsert import UpsertItem
+
 if TYPE_CHECKING:
     from ..client import DataverseClient
 
@@ -256,3 +258,102 @@ def get(
             raise TypeError("record_id must be str")
         with self._client._scoped_odata() as od:
             return od._get(table, record_id, select=select)
+
+    # ------------------------------------------------------------------ upsert
+
+    def upsert(self, table: str, items: List[Union[UpsertItem, Dict[str, Any]]]) -> None:
+        """Upsert one or more records identified by alternate keys.
+
+        When ``items`` contains a single entry, performs a single upsert via PATCH
+        using the alternate key in the URL. When ``items`` contains multiple entries,
+        uses the ``UpsertMultiple`` bulk action.
+
+        Each item must be either a :class:`~PowerPlatform.Dataverse.models.upsert.UpsertItem`
+        or a plain ``dict`` with ``"alternate_key"`` and ``"record"`` keys (both dicts).
+
+        :param table: Schema name of the table (e.g. ``"account"`` or ``"new_MyTestTable"``).
+        :type table: str
+        :param items: Non-empty list of :class:`~PowerPlatform.Dataverse.models.upsert.UpsertItem`
+            instances or dicts with ``"alternate_key"`` and ``"record"`` keys.
+        :type items: list[UpsertItem | dict]
+
+        :return: ``None``
+        :rtype: None
+
+        :raises TypeError: If ``items`` is not a non-empty list, or if any element is
+            neither a :class:`~PowerPlatform.Dataverse.models.upsert.UpsertItem` nor a
+            dict with ``"alternate_key"`` and ``"record"`` keys.
+
+        Example:
+            Upsert a single record using ``UpsertItem``::
+
+                from PowerPlatform.Dataverse.models.upsert import UpsertItem
+
+                client.records.upsert("account", [
+                    UpsertItem(
+                        alternate_key={"accountnumber": "ACC-001"},
+                        record={"name": "Contoso Ltd", "description": "Primary account"},
+                    )
+                ])
+
+            Upsert a single record using a plain dict::
+
+                client.records.upsert("account", [
+                    {
+                        "alternate_key": {"accountnumber": "ACC-001"},
+                        "record": {"name": "Contoso Ltd", "description": "Primary account"},
+                    },
+                ])
+
+            Upsert multiple records using ``UpsertItem``::
+
+                from PowerPlatform.Dataverse.models.upsert import UpsertItem
+
+                client.records.upsert("account", [
+                    UpsertItem(
+                        alternate_key={"accountnumber": "ACC-001"},
+                        record={"name": "Contoso Ltd", "description": "Primary account"},
+                    ),
+                    UpsertItem(
+                        alternate_key={"accountnumber": "ACC-002"},
+                        record={"name": "Fabrikam Inc", "description": "Partner account"},
+                    ),
+                ])
+
+            Upsert multiple records using plain dicts::
+
+                client.records.upsert("account", [
+                    {
+                        "alternate_key": {"accountnumber": "ACC-001"},
+                        "record": {"name": "Contoso Ltd", "description": "Primary account"},
+                    },
+                    {
+                        "alternate_key": {"accountnumber": "ACC-002"},
+                        "record": {"name": "Fabrikam Inc", "description": "Partner account"},
+                    },
+                ])
+
+            The ``alternate_key`` dict may contain multiple columns when the configured
+            alternate key is composite, e.g.
+            ``{"accountnumber": "ACC-001", "address1_postalcode": "98052"}``.
+        """
+        if not isinstance(items, list) or not items:
+            raise TypeError("items must be a non-empty list of UpsertItem or dicts")
+        normalized: List[UpsertItem] = []
+        for i in items:
+            if isinstance(i, UpsertItem):
+                normalized.append(i)
+            elif isinstance(i, dict) and isinstance(i.get("alternate_key"), dict) and isinstance(i.get("record"), dict):
+                normalized.append(UpsertItem(alternate_key=i["alternate_key"], record=i["record"]))
+            else:
+                raise TypeError("Each item must be a UpsertItem or a dict with 'alternate_key' and 'record' keys")
+        with self._client._scoped_odata() as od:
+            entity_set = od._entity_set_from_schema_name(table)
+            if len(normalized) == 1:
+                item = normalized[0]
+                od._upsert(entity_set, table, item.alternate_key, item.record)
+            else:
+                alternate_keys = [i.alternate_key for i in normalized]
+                records = [i.record for i in normalized]
+                od._upsert_multiple(entity_set, table, alternate_keys, records)
+        return None