feat: Add support for $expand in record retrieval methods and update documentation

Author: Samson Gebre

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

@@ -99,6 +99,15 @@ contact_ids = client.records.create("contact", contacts)
 # Get single record by ID
 account = client.records.retrieve("account", account_id, select=["name", "telephone1"])
 
+# With expand — fetch a related record in the same HTTP request
+account = client.records.retrieve(
+    "account", account_id,
+    select=["name"],
+    expand=["primarycontactid"],
+)
+contact = (account.get("primarycontactid") or {})
+print(contact.get("fullname"))
+
 # Simple shortcut — use records.list() only for basic filter + select without composable logic.
 # Follows @odata.nextLink automatically and loads all matching records into memory.
 # For filtering, sorting, expansion, or formatted values, prefer client.query.builder() (see below).
@@ -481,7 +490,7 @@ Use `client.batch` to send multiple operations in one HTTP request. All batch me
 batch = client.batch.new()
 batch.records.create("account", {"name": "Contoso"})
 batch.records.update("account", account_id, {"telephone1": "555-0100"})
-batch.records.retrieve("account", account_id, select=["name"], include_annotations="OData.Community.Display.V1.FormattedValue")  # single record
+batch.records.retrieve("account", account_id, select=["name"], expand=["primarycontactid"], include_annotations="OData.Community.Display.V1.FormattedValue")  # single record with expand
 batch.records.list("account", filter="statecode eq 0", select=["name"], orderby=["name asc"], top=50, page_size=25, count=True)  # multi-record, single page
 batch.query.sql("SELECT TOP 5 name FROM account")
 

CHANGELOG.md

@@ -8,10 +8,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- `client.records.retrieve(table, record_id, *, select, include_annotations)` — fetch a single record by GUID; returns `None` on 404 instead of raising; `include_annotations` maps to the `Prefer: odata.include-annotations` header for formatted values and lookup labels (#175)
+- `client.records.retrieve(table, record_id, *, select, expand, include_annotations)` — fetch a single record by GUID; returns `None` on 404 instead of raising; `expand` adds `$expand` for navigation property expansion on the single-record GET; `include_annotations` maps to the `Prefer: odata.include-annotations` header for formatted values and lookup labels (#175)
 - `client.records.list(table, *, filter, select, top, orderby, expand, page_size, count, include_annotations)` — eager fetch returning a flat `QueryResult`; GA replacement for `records.get()` without a record ID; `page_size` controls `Prefer: odata.maxpagesize`, `count=True` adds `$count=true`, `include_annotations` requests formatted values (#175)
 - `client.records.list_pages(table, *, filter, select, top, orderby, expand, page_size, count, include_annotations)` — lazy iterator yielding one `QueryResult` per HTTP page; streaming counterpart to `list()`; same parameter set (#175)
-- `client.batch.records.retrieve()` and `client.batch.records.list()` now accept the same `include_annotations`, `orderby`, `expand`, `page_size`, and `count` parameters as their non-batch counterparts (#175)
 - `client.query.fetchxml(xml)` — FetchXML support returning an inert `FetchXmlQuery`; no HTTP request is made until `.execute()` or `.execute_pages()` is called (#175)
 - `FetchXmlQuery` implements the correct Dataverse paging cookie algorithm: annotation parsed as outer XML, `pagingcookie` attribute double URL-decoded, server-supplied `pagenumber` used for next page, `morerecords` handled as both `bool` and `"true"` string, `UserWarning` emitted on simple paging fallback, 32,768-character URL limit enforced (documented Dataverse GET cap), 10,000-page circuit breaker against runaway iteration (#175)
 - `QueryBuilder.execute_pages()` — lazy per-page streaming returning one `QueryResult` per HTTP page; replaces deprecated `execute(by_page=True)` (#175)

README.md

@@ -163,6 +163,15 @@ account_id = client.records.create("account", {"name": "Contoso Ltd"})
 account = client.records.retrieve("account", account_id)
 print(account["name"])
 
+# Read with expand — fetch a related record in the same HTTP request
+account = client.records.retrieve(
+    "account", account_id,
+    select=["name"],
+    expand=["primarycontactid"],
+)
+contact = (account.get("primarycontactid") or {})
+print(contact.get("fullname"))
+
 # Update a record
 client.records.update("account", account_id, {"telephone1": "555-0199"})
 
@@ -694,7 +703,7 @@ 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.retrieve("account", account_id, select=["name"])     # single record
+batch.records.retrieve("account", account_id, select=["name"], expand=["primarycontactid"])  # single record with expand
 batch.records.list(                                                # multi-record, single page
     "account",
     filter="statecode eq 0",

examples/basic/functional_testing.py

@@ -276,6 +276,21 @@ def test_read_record(client: DataverseClient, table_info: Dict[str, Any], record
         else:
             print(f"[WARN] include_annotations: expected key '{ann_key}' not present in response")
 
+        # -- expand: verify navigation property expansion on a single-record GET --
+        # owninguser is a system navigation property present on all user-owned tables.
+        try:
+            expanded = client.records.retrieve(
+                table_schema_name,
+                record_id,
+                select=[f"{attr_prefix}_name"],
+                expand=["owninguser"],
+            )
+            owner = (expanded.get("owninguser") or {}) if expanded else {}
+            owner_name = owner.get("fullname") or owner.get("domainname") or "(unknown)"
+            print(f"[OK] records.retrieve with expand=['owninguser']: owner='{owner_name}'")
+        except Exception as e:  # noqa: BLE001
+            print(f"[WARN] records.retrieve expand skipped: {e}")
+
         return record
 
     except HttpError as e:
@@ -597,11 +612,12 @@ def test_batch_all_operations(client: DataverseClient, table_info: Dict[str, Any
                 " + tables.get + tables.list + query.sql (5 ops, 1 POST $batch)"
             )
             batch = client.batch.new()
-            # [0] Single-record retrieve with annotations
+            # [0] Single-record retrieve with annotations and expand
             batch.records.retrieve(
                 table_schema_name,
                 all_ids[0],
                 select=[f"{attr_prefix}_name", f"{attr_prefix}_count", f"{attr_prefix}_is_active"],
+                expand=["owninguser"],
                 include_annotations=annotation,
             )
             # [1] Multi-record list with orderby, page_size, count, include_annotations
@@ -630,7 +646,10 @@ def test_batch_all_operations(client: DataverseClient, table_info: Dict[str, Any
                     name = resp.data.get(f"{attr_prefix}_name")
                     ann_key = f"{attr_prefix}_is_active@{annotation}"
                     ann_val = resp.data.get(ann_key, "<not returned>")
+                    owner = resp.data.get("owninguser") or {}
+                    owner_name = owner.get("fullname") or owner.get("domainname") or "<not returned>"
                     print(f"   records.retrieve → name='{name}', {ann_key}='{ann_val}'")
+                    print(f"   records.retrieve expand=['owninguser'] → owner='{owner_name}'")
                 elif i == 1 and resp.data:
                     rows = resp.data.get("value", [])
                     names_ordered = [r.get(f"{attr_prefix}_name") for r in rows]

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

@@ -99,6 +99,15 @@ contact_ids = client.records.create("contact", contacts)
 # Get single record by ID
 account = client.records.retrieve("account", account_id, select=["name", "telephone1"])
 
+# With expand — fetch a related record in the same HTTP request
+account = client.records.retrieve(
+    "account", account_id,
+    select=["name"],
+    expand=["primarycontactid"],
+)
+contact = (account.get("primarycontactid") or {})
+print(contact.get("fullname"))
+
 # Simple shortcut — use records.list() only for basic filter + select without composable logic.
 # Follows @odata.nextLink automatically and loads all matching records into memory.
 # For filtering, sorting, expansion, or formatted values, prefer client.query.builder() (see below).
@@ -481,7 +490,7 @@ Use `client.batch` to send multiple operations in one HTTP request. All batch me
 batch = client.batch.new()
 batch.records.create("account", {"name": "Contoso"})
 batch.records.update("account", account_id, {"telephone1": "555-0100"})
-batch.records.retrieve("account", account_id, select=["name"], include_annotations="OData.Community.Display.V1.FormattedValue")  # single record
+batch.records.retrieve("account", account_id, select=["name"], expand=["primarycontactid"], include_annotations="OData.Community.Display.V1.FormattedValue")  # single record with expand
 batch.records.list("account", filter="statecode eq 0", select=["name"], orderby=["name asc"], top=50, page_size=25, count=True)  # multi-record, single page
 batch.query.sql("SELECT TOP 5 name FROM account")
 

src/PowerPlatform/Dataverse/data/_batch.py

@@ -69,6 +69,7 @@ class _RecordGet:
     table: str
     record_id: str
     select: Optional[List[str]] = None
+    expand: Optional[List[str]] = None
     include_annotations: Optional[str] = None
 
 
@@ -399,7 +400,13 @@ def _resolve_record_delete(self, op: _RecordDelete) -> List[_RawRequest]:
 
     def _resolve_record_get(self, op: _RecordGet) -> List[_RawRequest]:
         return [
-            self._od._build_get(op.table, op.record_id, select=op.select, include_annotations=op.include_annotations)
+            self._od._build_get(
+                op.table,
+                op.record_id,
+                select=op.select,
+                expand=op.expand,
+                include_annotations=op.include_annotations,
+            )
         ]
 
     def _resolve_record_list(self, op: _RecordList) -> List[_RawRequest]:

src/PowerPlatform/Dataverse/data/_odata.py

@@ -689,6 +689,7 @@ def _get(
         table_schema_name: str,
         key: str,
         select: Optional[List[str]] = None,
+        expand: Optional[List[str]] = None,
         include_annotations: Optional[str] = None,
     ) -> Dict[str, Any]:
         """Retrieve a single record.
@@ -699,14 +700,18 @@ def _get(
         :type key: ``str``
         :param select: Columns to select; joined with commas into $select.
         :type select: ``list[str]`` | ``None``
+        :param expand: Navigation properties to expand (``$expand``); passed as-is (case-sensitive).
+        :type expand: ``list[str]`` | ``None``
         :param include_annotations: OData annotation pattern for the ``Prefer: odata.include-annotations`` header, or ``None``.
         :type include_annotations: ``str`` | ``None``
 
         :return: Retrieved record dictionary (may be empty if no selected attributes).
         :rtype: ``dict[str, Any]``
         """
         return self._execute_raw(
-            self._build_get(table_schema_name, key, select=select, include_annotations=include_annotations)
+            self._build_get(
+                table_schema_name, key, select=select, expand=expand, include_annotations=include_annotations
+            )
         ).json()
 
     def _get_multiple(
@@ -2319,13 +2324,19 @@ def _build_get(
         record_id: str,
         *,
         select: Optional[List[str]] = None,
+        expand: Optional[List[str]] = None,
         include_annotations: Optional[str] = None,
     ) -> _RawRequest:
         """Build a single-record GET request without sending it."""
         entity_set = self._entity_set_from_schema_name(table)
-        url = f"{self.api}/{entity_set}{self._format_key(record_id)}"
+        params: List[str] = []
         if select:
-            url += "?$select=" + ",".join(self._lowercase_list(select))
+            params.append("$select=" + ",".join(self._lowercase_list(select)))
+        if expand:
+            params.append("$expand=" + ",".join(expand))
+        url = f"{self.api}/{entity_set}{self._format_key(record_id)}"
+        if params:
+            url += "?" + "&".join(params)
         headers = None
         if include_annotations:
             headers = {"Prefer": f'odata.include-annotations="{include_annotations}"'}

src/PowerPlatform/Dataverse/operations/batch.py

@@ -335,6 +335,7 @@ def retrieve(
         record_id: str,
         *,
         select: Optional[List[str]] = None,
+        expand: Optional[List[str]] = None,
         include_annotations: Optional[str] = None,
     ) -> None:
         """
@@ -351,6 +352,10 @@ def retrieve(
         :type record_id: :class:`str`
         :param select: Optional list of column logical names to include.
         :type select: list[str] or None
+        :param expand: Optional list of navigation properties to expand.
+            Navigation property names are case-sensitive and must match the
+            entity's ``$metadata``.
+        :type expand: list[str] or None
         :param include_annotations: OData annotation pattern for the
             ``Prefer: odata.include-annotations`` header (e.g. ``"*"`` or
             ``"OData.Community.Display.V1.FormattedValue"``), or ``None``.
@@ -362,14 +367,22 @@ def retrieve(
             batch.records.retrieve(
                 "account", account_id,
                 select=["name", "statuscode"],
+                expand=["primarycontactid"],
                 include_annotations="OData.Community.Display.V1.FormattedValue",
             )
             result = batch.execute()
             record = result.responses[0].data
-            print(record["statuscode@OData.Community.Display.V1.FormattedValue"])
+            contact = (record.get("primarycontactid") or {})
+            print(contact.get("fullname"))
         """
         self._batch._items.append(
-            _RecordGet(table=table, record_id=record_id, select=select, include_annotations=include_annotations)
+            _RecordGet(
+                table=table,
+                record_id=record_id,
+                select=select,
+                expand=expand,
+                include_annotations=include_annotations,
+            )
         )
 
     def list(

src/PowerPlatform/Dataverse/operations/records.py

@@ -487,6 +487,7 @@ def retrieve(
         record_id: str,
         *,
         select: Optional[List[str]] = None,
+        expand: Optional[List[str]] = None,
         include_annotations: Optional[str] = None,
     ) -> Optional[Record]:
         """Fetch a single record by its GUID, returning ``None`` if not found.
@@ -500,6 +501,10 @@ def retrieve(
         :type record_id: :class:`str`
         :param select: Optional list of column logical names to include.
         :type select: list[str] or None
+        :param expand: Optional list of navigation properties to expand (e.g.
+            ``["primarycontactid"]``). Navigation property names are
+            case-sensitive and must match the entity's ``$metadata``.
+        :type expand: list[str] or None
         :param include_annotations: OData annotation pattern for the
             ``Prefer: odata.include-annotations`` header (e.g. ``"*"`` or
             ``"OData.Community.Display.V1.FormattedValue"``), or ``None``.
@@ -512,14 +517,16 @@ def retrieve(
             record = client.records.retrieve(
                 "account", account_id,
                 select=["name", "statuscode"],
+                expand=["primarycontactid"],
                 include_annotations="OData.Community.Display.V1.FormattedValue",
             )
             if record is not None:
-                print(record["statuscode@OData.Community.Display.V1.FormattedValue"])
+                contact = record.get("primarycontactid") or {}
+                print(contact.get("fullname"))
         """
         with self._client._scoped_odata() as od:
             try:
-                raw = od._get(table, record_id, select=select, include_annotations=include_annotations)
+                raw = od._get(table, record_id, select=select, expand=expand, include_annotations=include_annotations)
             except HttpError as exc:
                 if exc.status_code == 404:
                     return None

tests/unit/data/test_batch_serialization.py

@@ -253,7 +253,22 @@ def test_resolve_record_get(self):
         op = _RecordGet(table="account", record_id="guid-1", select=["name"])
         result = client._resolve_record_get(op)
 
-        od._build_get.assert_called_once_with("account", "guid-1", select=["name"], include_annotations=None)
+        od._build_get.assert_called_once_with(
+            "account", "guid-1", select=["name"], expand=None, include_annotations=None
+        )
+        self.assertEqual(result, [mock_req])
+
+    def test_resolve_record_get_with_expand(self):
+        client, od = self._client_and_od()
+        mock_req = MagicMock()
+        od._build_get.return_value = mock_req
+
+        op = _RecordGet(table="account", record_id="guid-1", select=["name"], expand=["primarycontactid"])
+        result = client._resolve_record_get(op)
+
+        od._build_get.assert_called_once_with(
+            "account", "guid-1", select=["name"], expand=["primarycontactid"], include_annotations=None
+        )
         self.assertEqual(result, [mock_req])
 
     def test_resolve_record_get_with_annotations(self):
@@ -265,7 +280,9 @@ def test_resolve_record_get_with_annotations(self):
         op = _RecordGet(table="account", record_id="guid-1", select=["name"], include_annotations=annotation)
         result = client._resolve_record_get(op)
 
-        od._build_get.assert_called_once_with("account", "guid-1", select=["name"], include_annotations=annotation)
+        od._build_get.assert_called_once_with(
+            "account", "guid-1", select=["name"], expand=None, include_annotations=annotation
+        )
         self.assertEqual(result, [mock_req])
 
     def test_resolve_record_list_basic(self):