Enhance SKILL.md and QueryBuilder to support advanced streaming and update deprecated methods

- Added simple and advanced streaming options in SKILL.md for records.list_pages() and execute_pages().
- Updated QueryBuilder to replace records.get() with records.list() in documentation and method calls.
- Improved unit tests to validate new streaming functionality and ensure correct method delegation.

Author: Samson Gebre

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

@@ -30,6 +30,16 @@ The SDK supports Dataverse's native bulk operations: Pass lists to `create()`, `
 ### Paging
 - Control page size with `page_size` parameter
 - Use `top` parameter to limit total records returned
+- Simple streaming: `records.list_pages(table, filter, select)` — yields one `QueryResult` per HTTP page (3 params only; use builder for advanced options)
+- Advanced streaming: `client.query.builder(table)....execute_pages()` — full builder options, one `QueryResult` per page
+- `execute(by_page=True/False)` is **deprecated** and emits `UserWarning`; use `execute_pages()` instead
+
+### QueryResult
+- Returned by `records.list()`, `records.retrieve()`, `execute()`, and each page from `list_pages()` / `execute_pages()`
+- Iterable: `for record in result` — each item is a `dict`-like `Record`
+- `.to_dataframe()` — convert to pandas DataFrame
+- `.first()` — return the first record or `None`
+- `len(result)` — number of records in this result/page
 
 ### DataFrame Support
 - DataFrame operations are accessed via the `client.dataframe` namespace: `client.dataframe.create()`, `client.dataframe.update()`, `client.dataframe.delete()` — `client.dataframe.get()` is deprecated; use `client.query.builder(table).where(...).execute().to_dataframe()` instead
@@ -90,7 +100,7 @@ account = client.records.retrieve("account", account_id, select=["name", "teleph
 # Query with filter — follows @odata.nextLink automatically (multiple HTTP requests if needed),
 # loads all matching records into memory, returns a single QueryResult.
 # Page size is Dataverse's default (~5000/page); use top to bound total records and round-trips.
-# For very large sets where memory is a concern, use query.builder().execute(by_page=True) instead.
+# For very large sets where memory is a concern, use records.list_pages() or execute_pages() instead.
 result = client.records.list(
     "account",
     select=["accountid", "name"],      # select is case-insensitive (automatically lowercased)
@@ -100,12 +110,22 @@ result = client.records.list(
 for record in result:
     print(record["name"])
 
-# For large result sets that must be streamed page-by-page (caller controls memory, one page at a time)
+# Simple streaming — page-by-page (3 params only; use builder for ordering/expand/count)
+for page in client.records.list_pages(
+    "account",
+    select=["accountid", "name"],
+    filter="statecode eq 0",
+):
+    for record in page:
+        print(record["name"])
+
+# Advanced streaming — full builder options, one QueryResult per HTTP page
+from PowerPlatform.Dataverse.models.filters import col
 for page in (client.query.builder("account")
              .select("accountid", "name")
              .where(col("statecode") == 0)
              .page_size(500)           # optional: override Dataverse default page size
-             .execute(by_page=True)):
+             .execute_pages()):
     for record in page:
         print(record["name"])
 
@@ -191,13 +211,14 @@ client.records.delete("account", [id1, id2, id3], use_bulk_delete=True)
 
 The SDK provides DataFrame wrappers for all CRUD operations via the `client.dataframe` namespace, using pandas DataFrames and Series as input/output.
 
-> **Note:** `client.dataframe.get()` is deprecated. Use `client.query.builder(table).select(...).filter(...).to_dataframe()` instead.
+> **Note:** `client.dataframe.get()` is deprecated. Use `client.query.builder(table).select(...).where(...).to_dataframe()` instead.
 
 ```python
 import pandas as pd
 
 # Query records -- returns a single DataFrame (GA builder pattern)
-df = client.query.builder("account").filter("statecode eq 0").select("name").to_dataframe()
+from PowerPlatform.Dataverse.models.filters import col
+df = client.query.builder("account").where(col("statecode") == 0).select("name").to_dataframe()
 print(f"Got {len(df)} rows")
 
 # Limit results with top
@@ -237,6 +258,34 @@ for record in results:
     print(record["name"])
 ```
 
+### FetchXML Queries
+
+`client.query.fetch_xml(xml)` returns an inert `FetchXmlQuery` object — **no HTTP request is made** until `.execute()` or `.execute_pages()` is called.
+
+```python
+xml = """
+<fetch top="50">
+  <entity name="account">
+    <attribute name="accountid" />
+    <attribute name="name" />
+    <filter>
+      <condition attribute="statecode" operator="eq" value="0" />
+    </filter>
+  </entity>
+</fetch>
+"""
+
+# Load all results into memory (simple, small-to-medium sets)
+query = client.query.fetch_xml(xml)
+result = query.execute()              # returns QueryResult — all pages fetched upfront
+for record in result:
+    print(record["name"])
+
+# Stream page-by-page (large sets or early exit)
+for page in query.execute_pages():    # yields one QueryResult per HTTP page
+    process(page.to_dataframe())
+```
+
 ### Table Management
 
 #### Create Custom Tables

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

@@ -30,6 +30,16 @@ The SDK supports Dataverse's native bulk operations: Pass lists to `create()`, `
 ### Paging
 - Control page size with `page_size` parameter
 - Use `top` parameter to limit total records returned
+- Simple streaming: `records.list_pages(table, filter, select)` — yields one `QueryResult` per HTTP page (3 params only; use builder for advanced options)
+- Advanced streaming: `client.query.builder(table)....execute_pages()` — full builder options, one `QueryResult` per page
+- `execute(by_page=True/False)` is **deprecated** and emits `UserWarning`; use `execute_pages()` instead
+
+### QueryResult
+- Returned by `records.list()`, `records.retrieve()`, `execute()`, and each page from `list_pages()` / `execute_pages()`
+- Iterable: `for record in result` — each item is a `dict`-like `Record`
+- `.to_dataframe()` — convert to pandas DataFrame
+- `.first()` — return the first record or `None`
+- `len(result)` — number of records in this result/page
 
 ### DataFrame Support
 - DataFrame operations are accessed via the `client.dataframe` namespace: `client.dataframe.create()`, `client.dataframe.update()`, `client.dataframe.delete()` — `client.dataframe.get()` is deprecated; use `client.query.builder(table).where(...).execute().to_dataframe()` instead
@@ -90,7 +100,7 @@ account = client.records.retrieve("account", account_id, select=["name", "teleph
 # Query with filter — follows @odata.nextLink automatically (multiple HTTP requests if needed),
 # loads all matching records into memory, returns a single QueryResult.
 # Page size is Dataverse's default (~5000/page); use top to bound total records and round-trips.
-# For very large sets where memory is a concern, use query.builder().execute(by_page=True) instead.
+# For very large sets where memory is a concern, use records.list_pages() or execute_pages() instead.
 result = client.records.list(
     "account",
     select=["accountid", "name"],      # select is case-insensitive (automatically lowercased)
@@ -100,12 +110,22 @@ result = client.records.list(
 for record in result:
     print(record["name"])
 
-# For large result sets that must be streamed page-by-page (caller controls memory, one page at a time)
+# Simple streaming — page-by-page (3 params only; use builder for ordering/expand/count)
+for page in client.records.list_pages(
+    "account",
+    select=["accountid", "name"],
+    filter="statecode eq 0",
+):
+    for record in page:
+        print(record["name"])
+
+# Advanced streaming — full builder options, one QueryResult per HTTP page
+from PowerPlatform.Dataverse.models.filters import col
 for page in (client.query.builder("account")
              .select("accountid", "name")
              .where(col("statecode") == 0)
              .page_size(500)           # optional: override Dataverse default page size
-             .execute(by_page=True)):
+             .execute_pages()):
     for record in page:
         print(record["name"])
 
@@ -191,13 +211,14 @@ client.records.delete("account", [id1, id2, id3], use_bulk_delete=True)
 
 The SDK provides DataFrame wrappers for all CRUD operations via the `client.dataframe` namespace, using pandas DataFrames and Series as input/output.
 
-> **Note:** `client.dataframe.get()` is deprecated. Use `client.query.builder(table).select(...).filter(...).to_dataframe()` instead.
+> **Note:** `client.dataframe.get()` is deprecated. Use `client.query.builder(table).select(...).where(...).to_dataframe()` instead.
 
 ```python
 import pandas as pd
 
 # Query records -- returns a single DataFrame (GA builder pattern)
-df = client.query.builder("account").filter("statecode eq 0").select("name").to_dataframe()
+from PowerPlatform.Dataverse.models.filters import col
+df = client.query.builder("account").where(col("statecode") == 0).select("name").to_dataframe()
 print(f"Got {len(df)} rows")
 
 # Limit results with top
@@ -237,6 +258,34 @@ for record in results:
     print(record["name"])
 ```
 
+### FetchXML Queries
+
+`client.query.fetch_xml(xml)` returns an inert `FetchXmlQuery` object — **no HTTP request is made** until `.execute()` or `.execute_pages()` is called.
+
+```python
+xml = """
+<fetch top="50">
+  <entity name="account">
+    <attribute name="accountid" />
+    <attribute name="name" />
+    <filter>
+      <condition attribute="statecode" operator="eq" value="0" />
+    </filter>
+  </entity>
+</fetch>
+"""
+
+# Load all results into memory (simple, small-to-medium sets)
+query = client.query.fetch_xml(xml)
+result = query.execute()              # returns QueryResult — all pages fetched upfront
+for record in result:
+    print(record["name"])
+
+# Stream page-by-page (large sets or early exit)
+for page in query.execute_pages():    # yields one QueryResult per HTTP page
+    process(page.to_dataframe())
+```
+
 ### Table Management
 
 #### Create Custom Tables

src/PowerPlatform/Dataverse/models/query_builder.py

@@ -50,7 +50,7 @@
 from __future__ import annotations
 
 import warnings
-from typing import Any, Dict, Iterable, Iterator, List, Optional, TypedDict, Union
+from typing import Any, Dict, Iterator, List, Optional, TypedDict, Union
 
 import pandas as pd
 
@@ -67,7 +67,7 @@ class QueryParams(TypedDict, total=False):
     """Typed dictionary returned by :meth:`QueryBuilder.build`.
 
     Provides IDE autocomplete when passing build results to
-    ``client.records.get()`` manually.
+    ``client.records.list()`` manually.
     """
 
     table: str
@@ -450,7 +450,7 @@ def build(self) -> QueryParams:
 
     # --------------------------------------------------------------- execute
 
-    def execute(self, *, by_page=_BY_PAGE_UNSET) -> Union[QueryResult, Iterable[List[Record]]]:
+    def execute(self, *, by_page=_BY_PAGE_UNSET) -> Union[QueryResult, Iterator[QueryResult]]:
         """Execute the query and return results.
 
         Returns a :class:`~PowerPlatform.Dataverse.models.record.QueryResult`
@@ -460,7 +460,7 @@ def execute(self, *, by_page=_BY_PAGE_UNSET) -> Union[QueryResult, Iterable[List
         This method is only available when the QueryBuilder was created
         via ``client.query.builder(table)``.  Standalone ``QueryBuilder``
         instances should use :meth:`build` to get parameters and pass them
-        to ``client.records.get()`` manually.
+        to ``client.records.list()`` manually.
 
         At least one of ``select()``, ``where()``, or ``top()`` must be
         called before ``execute()``; otherwise a :class:`ValueError` is
@@ -474,7 +474,7 @@ def execute(self, *, by_page=_BY_PAGE_UNSET) -> Union[QueryResult, Iterable[List
         :return: :class:`~PowerPlatform.Dataverse.models.record.QueryResult`
             with all pages collected (default), or page iterator (deprecated
             ``by_page=True``).
-        :rtype: QueryResult or Iterable[List[Record]]
+        :rtype: QueryResult or Iterator[QueryResult]
         :raises ValueError: If no ``select``, ``where``, or ``top``
             constraint has been set.
         :raises RuntimeError: If the query was not created via
@@ -510,7 +510,7 @@ def execute(self, *, by_page=_BY_PAGE_UNSET) -> Union[QueryResult, Iterable[List
         if self._query_ops is None:
             raise RuntimeError(
                 "Cannot execute: query was not created via client.query.builder(). "
-                "Use build() and pass parameters to client.records.get() instead."
+                "Use build() and pass parameters to client.records.list() instead."
             )
 
         if not self._select and not self._filter_parts and self._top is None:
@@ -522,11 +522,12 @@ def execute(self, *, by_page=_BY_PAGE_UNSET) -> Union[QueryResult, Iterable[List
         params = self.build()
         client = self._query_ops._client
 
-        # Suppress DeprecationWarning from records.get() — execute() is GA;
-        # records.get() is deprecated but still used as the internal paging mechanism.
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore", DeprecationWarning)
-            pages = client.records.get(
+        if use_by_page:
+            return self.execute_pages()
+
+        all_records: List[Record] = []
+        with client._scoped_odata() as od:
+            for page in od._get_multiple(
                 params["table"],
                 select=params.get("select"),
                 filter=params.get("filter"),
@@ -536,14 +537,8 @@ def execute(self, *, by_page=_BY_PAGE_UNSET) -> Union[QueryResult, Iterable[List
                 page_size=params.get("page_size"),
                 count=params.get("count", False),
                 include_annotations=params.get("include_annotations"),
-            )
-
-        if use_by_page:
-            return pages
-
-        all_records: List[Record] = []
-        for page in pages:
-            all_records.extend(page)
+            ):
+                all_records.extend(Record.from_api_response(params["table"], row) for row in page)
         return QueryResult(all_records)
 
     # ---------------------------------------------------------- execute_pages
@@ -579,7 +574,7 @@ def execute_pages(self) -> Iterator[QueryResult]:
         if self._query_ops is None:
             raise RuntimeError(
                 "Cannot execute: query was not created via client.query.builder(). "
-                "Use build() and pass parameters to client.records.get() instead."
+                "Use build() and pass parameters to client.records.list() instead."
             )
 
         if not self._select and not self._filter_parts and self._top is None:
@@ -591,9 +586,8 @@ def execute_pages(self) -> Iterator[QueryResult]:
         params = self.build()
         client = self._query_ops._client
 
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore", DeprecationWarning)
-            pages = client.records.get(
+        with client._scoped_odata() as od:
+            for page in od._get_multiple(
                 params["table"],
                 select=params.get("select"),
                 filter=params.get("filter"),
@@ -603,10 +597,8 @@ def execute_pages(self) -> Iterator[QueryResult]:
                 page_size=params.get("page_size"),
                 count=params.get("count", False),
                 include_annotations=params.get("include_annotations"),
-            )
-
-        for page in pages:
-            yield QueryResult(page)
+            ):
+                yield QueryResult([Record.from_api_response(params["table"], row) for row in page])
 
     # ----------------------------------------------------------- to_dataframe
 
@@ -653,7 +645,7 @@ def to_dataframe(self) -> pd.DataFrame:
         if self._query_ops is None:
             raise RuntimeError(
                 "Cannot execute: query was not created via client.query.builder(). "
-                "Use build() and pass parameters to client.records.get() instead."
+                "Use build() and pass parameters to client.records.list() instead."
             )
 
         result = self.execute()

src/PowerPlatform/Dataverse/operations/records.py

@@ -588,6 +588,9 @@ def list(
         GA replacement for ``records.get(table, filter=...)``. All pages are
         collected eagerly and returned as a single :class:`QueryResult`.
 
+        For advanced query options (ordering, expand, count, page size, or
+        OData annotations) use ``client.query.builder()`` instead.
+
         :param table: Schema name of the table (e.g. ``"account"``).
         :type table: :class:`str`
         :param filter: Optional OData filter string or :class:`FilterExpression`.
@@ -643,9 +646,12 @@ def list_pages(
     ) -> Iterator[QueryResult]:
         """Lazily yield one :class:`QueryResult` per HTTP page.
 
-        Symmetric with :meth:`~PowerPlatform.Dataverse.models.query_builder.QueryBuilder.execute_pages`
-        on the builder. Each iteration triggers a network request via
-        ``@odata.nextLink``. One-shot — do not iterate more than once.
+        Streaming counterpart to :meth:`list`. Each iteration triggers one
+        network request via ``@odata.nextLink``. One-shot — do not iterate
+        more than once.
+
+        For advanced query options (ordering, expand, count, page size, or
+        OData annotations) use ``client.query.builder().execute_pages()`` instead.
 
         :param table: Schema name of the table (e.g. ``"account"``).
         :type table: :class:`str`