Move paginated query from client.query.get() to client.records.get() overload (#107)

- Add @overload to records.get(): with record_id returns dict, without
  returns paginated generator
- Remove get() from QueryOperations (client.query now only has sql())
- Update deprecated client.get() to route both cases to records.get()
- Update all examples, README, and tests

Co-authored-by: tpellissier <tpellissier@microsoft.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

README.md

@@ -112,7 +112,7 @@ The SDK provides a simple, pythonic interface for Dataverse operations:
 | Concept | Description |
 |---------|-------------|
 | **DataverseClient** | Main entry point; provides `records`, `query`, and `tables` namespaces |
-| **Namespaces** | Operations are organized into `client.records` (CRUD), `client.query` (queries), and `client.tables` (metadata & relationships) |
+| **Namespaces** | Operations are organized into `client.records` (CRUD & OData queries), `client.query` (query & search), and `client.tables` (metadata) |
 | **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 |
@@ -190,7 +190,7 @@ for record in results:
 
 # OData query with paging
 # Note: filter and expand parameters are case sensitive
-for page in client.query.get(
+for page in client.records.get(
     "account",
     select=["accountid", "name"],  # select is case-insensitive (automatically lowercased)
     filter="statecode eq 0",       # filter must use lowercase logical names (not transformed)
@@ -200,7 +200,7 @@ for page in client.query.get(
         print(record["name"])
 
 # Query with navigation property expansion (case-sensitive!)
-for page in client.query.get(
+for page in client.records.get(
     "account",
     select=["name"],
     expand=["primarycontactid"],  # Navigation property names are case-sensitive

examples/advanced/walkthrough.py

@@ -193,9 +193,9 @@ def main():
     )
 
     # Multiple read with filter
-    log_call(f"client.query.get('{table_name}', filter='new_quantity gt 5')")
+    log_call(f"client.records.get('{table_name}', filter='new_quantity gt 5')")
     all_records = []
-    records_iterator = backoff(lambda: client.query.get(table_name, filter="new_quantity gt 5"))
+    records_iterator = backoff(lambda: client.records.get(table_name, filter="new_quantity gt 5"))
     for page in records_iterator:
         all_records.extend(page)
     print(f"[OK] Found {len(all_records)} records with new_quantity > 5")
@@ -243,9 +243,9 @@ def main():
     print(f"[OK] Created {len(paging_ids)} records for paging demo")
 
     # Query with paging
-    log_call(f"client.query.get('{table_name}', page_size=5)")
+    log_call(f"client.records.get('{table_name}', page_size=5)")
     print("Fetching records with page_size=5...")
-    paging_iterator = backoff(lambda: client.query.get(table_name, orderby=["new_Quantity"], page_size=5))
+    paging_iterator = backoff(lambda: client.records.get(table_name, orderby=["new_Quantity"], page_size=5))
     for page_num, page in enumerate(paging_iterator, start=1):
         record_ids = [r.get("new_walkthroughdemoid")[:8] + "..." for r in page]
         print(f"  Page {page_num}: {len(page)} records - IDs: {record_ids}")

examples/basic/functional_testing.py

@@ -271,7 +271,7 @@ def test_query_records(client: DataverseClient, table_info: Dict[str, Any]) -> N
         print("Querying records from test table...")
         for attempt in range(1, retries + 1):
             try:
-                records_iterator = client.query.get(
+                records_iterator = client.records.get(
                     table_schema_name,
                     select=[f"{attr_prefix}_name", f"{attr_prefix}_count", f"{attr_prefix}_amount"],
                     filter=f"{attr_prefix}_is_active eq true",

examples/basic/installation_example.py

@@ -218,7 +218,7 @@ def show_usage_examples():
 Querying Data:
 ```python
 # Query with OData filter
-accounts = client.query.get("account",
+accounts = client.records.get("account",
                      filter="name eq 'Contoso Ltd'",
                      select=["name", "telephone1"],
                      top=10)

src/PowerPlatform/Dataverse/client.py

@@ -53,8 +53,8 @@ class DataverseClient:
 
     Operations are organized into namespaces:
 
-    - ``client.records`` -- create, update, delete, get individual records
-    - ``client.query`` -- paginated OData queries and read-only SQL queries (via Web API ``?sql=`` parameter)
+    - ``client.records`` -- create, update, delete, and get records (single or paginated queries)
+    - ``client.query`` -- query and search operations
     - ``client.tables`` -- table and column metadata management
 
     Example:
@@ -76,7 +76,7 @@ class DataverseClient:
             client.records.update("account", record_id, {"telephone1": "555-0100"})
 
             # Query records
-            for page in client.query.get("account", filter="name eq 'Contoso Ltd'"):
+            for page in client.records.get("account", filter="name eq 'Contoso Ltd'"):
                 for account in page:
                     print(account["name"])
 
@@ -283,10 +283,10 @@ def get(
     ) -> Union[Dict[str, Any], Iterable[List[Dict[str, Any]]]]:
         """
         .. note::
-            Deprecated. This method has been split into two:
+            Deprecated. Use :meth:`~PowerPlatform.Dataverse.operations.records.RecordOperations.get` instead.
 
-            - **Single record by ID** -- use ``client.records.get(table, record_id)``
-            - **Query / filter multiple records** -- use ``client.query.get(table, filter=..., select=...)``
+            - **Single record by ID** -- ``client.records.get(table, record_id)``
+            - **Query / filter multiple records** -- ``client.records.get(table, filter=..., select=...)``
 
         Fetch a single record by ID or query multiple records.
 
@@ -354,14 +354,14 @@ def get(
                     print(f"Batch size: {len(batch)}")
         """
         warnings.warn(
-            "client.get() is deprecated. Use client.records.get() or client.query.get() instead.",
+            "client.get() is deprecated. Use client.records.get() instead.",
             DeprecationWarning,
             stacklevel=2,
         )
         if record_id is not None:
             return self.records.get(table_schema_name, record_id, select=select)
         else:
-            return self.query.get(
+            return self.records.get(
                 table_schema_name,
                 select=select,
                 filter=filter,

src/PowerPlatform/Dataverse/operations/query.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Dict, Iterable, List, Optional, TYPE_CHECKING
+from typing import Any, Dict, List, TYPE_CHECKING
 
 if TYPE_CHECKING:
     from ..client import DataverseClient
@@ -15,10 +15,10 @@
 
 
 class QueryOperations:
-    """Namespace for query operations (multi-record retrieval and SQL).
+    """Namespace for query operations.
 
-    Accessed via ``client.query``. Provides paginated OData queries and SQL
-    query execution against Dataverse tables.
+    Accessed via ``client.query``. Provides query and search operations
+    against Dataverse tables.
 
     :param client: The parent :class:`~PowerPlatform.Dataverse.client.DataverseClient` instance.
     :type client: ~PowerPlatform.Dataverse.client.DataverseClient
@@ -27,12 +27,6 @@ class QueryOperations:
 
         client = DataverseClient(base_url, credential)
 
-        # Paginated query
-        for page in client.query.get("account", select=["name"], top=100):
-            for record in page:
-                print(record["name"])
-
-        # SQL query
         rows = client.query.sql("SELECT TOP 10 name FROM account ORDER BY name")
         for row in rows:
             print(row["name"])
@@ -41,89 +35,6 @@ class QueryOperations:
     def __init__(self, client: DataverseClient) -> None:
         self._client = client
 
-    # -------------------------------------------------------------------- get
-
-    def get(
-        self,
-        table: str,
-        *,
-        select: Optional[List[str]] = None,
-        filter: Optional[str] = None,
-        orderby: Optional[List[str]] = None,
-        top: Optional[int] = None,
-        expand: Optional[List[str]] = None,
-        page_size: Optional[int] = None,
-    ) -> Iterable[List[Dict[str, Any]]]:
-        """Query multiple records from a Dataverse table with pagination.
-
-        Returns a generator that yields one page (list of record dicts) at a
-        time. Automatically follows ``@odata.nextLink`` for server-side paging.
-
-        :param table: Schema name of the table (e.g. ``"account"`` or
-            ``"new_MyTestTable"``).
-        :type table: :class:`str`
-        :param select: Optional list of column logical names to include.
-            Column names are automatically lowercased.
-        :type select: :class:`list` of :class:`str` or None
-        :param filter: Optional OData ``$filter`` expression (e.g.
-            ``"name eq 'Contoso'"``). Column names in filter expressions must
-            use exact lowercase logical names. Passed directly without
-            transformation.
-        :type filter: :class:`str` or None
-        :param orderby: Optional list of sort expressions (e.g.
-            ``["name asc", "createdon desc"]``). Column names are automatically
-            lowercased.
-        :type orderby: :class:`list` of :class:`str` or None
-        :param top: Optional maximum total number of records to return.
-        :type top: :class:`int` or None
-        :param expand: Optional list of navigation properties to expand (e.g.
-            ``["primarycontactid"]``). Case-sensitive; must match server-defined
-            names exactly.
-        :type expand: :class:`list` of :class:`str` or None
-        :param page_size: Optional per-page size hint sent via
-            ``Prefer: odata.maxpagesize``.
-        :type page_size: :class:`int` or None
-
-        :return: Generator yielding pages, where each page is a list of record
-            dictionaries.
-        :rtype: :class:`collections.abc.Iterable` of :class:`list` of :class:`dict`
-
-        Example:
-            Query with filtering and pagination::
-
-                for page in client.query.get(
-                    "account",
-                    filter="statecode eq 0",
-                    select=["name", "telephone1"],
-                    page_size=50,
-                ):
-                    for record in page:
-                        print(record["name"])
-
-            Query with sorting and limit::
-
-                for page in client.query.get(
-                    "account",
-                    orderby=["createdon desc"],
-                    top=100,
-                ):
-                    print(f"Page size: {len(page)}")
-        """
-
-        def _paged() -> Iterable[List[Dict[str, Any]]]:
-            with self._client._scoped_odata() as od:
-                yield from od._get_multiple(
-                    table,
-                    select=select,
-                    filter=filter,
-                    orderby=orderby,
-                    top=top,
-                    expand=expand,
-                    page_size=page_size,
-                )
-
-        return _paged()
-
     # -------------------------------------------------------------------- sql
 
     def sql(self, sql: str) -> List[Dict[str, Any]]: