Change QueryBuilder.execute() to flat iteration by default

execute() now yields individual records instead of pages, abstracting
away OData paging. Pass by_page=True for explicit page-level iteration.

This follows the abstraction-level heuristic: QueryBuilder is the
"abstract away OData" API, so paging should be transparent. The raw
records.get() API retains paged iteration for backward compatibility.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: tpellissier

examples/advanced/walkthrough.py

@@ -258,58 +258,51 @@ def main():
     print("7. QueryBuilder - Fluent Queries")
     print("=" * 80)
 
-    # Basic fluent query: active records sorted by amount
+    # Basic fluent query: active records sorted by amount (flat iteration)
     log_call("client.query.builder(...).select().filter_eq().order_by().execute()")
     print("Querying incomplete records ordered by amount (fluent builder)...")
-    qb_records = []
-    for page in backoff(
+    qb_records = list(backoff(
         lambda: client.query.builder(table_name)
         .select("new_Title", "new_Amount", "new_Priority")
         .filter_eq("new_Completed", False)
         .order_by("new_Amount", descending=True)
         .top(10)
         .execute()
-    ):
-        qb_records.extend(page)
+    ))
     print(f"[OK] QueryBuilder found {len(qb_records)} incomplete records:")
     for rec in qb_records[:5]:
         print(f"  - '{rec.get('new_title')}' Amount={rec.get('new_amount')}")
 
     # filter_in: records with specific priorities
     log_call("client.query.builder(...).filter_in('new_Priority', [HIGH, LOW]).execute()")
     print("Querying records with HIGH or LOW priority (filter_in)...")
-    priority_records = []
-    for page in backoff(
+    priority_records = list(backoff(
         lambda: client.query.builder(table_name)
         .select("new_Title", "new_Priority")
         .filter_in("new_Priority", [Priority.HIGH, Priority.LOW])
         .execute()
-    ):
-        priority_records.extend(page)
+    ))
     print(f"[OK] Found {len(priority_records)} records with HIGH or LOW priority")
     for rec in priority_records[:5]:
         print(f"  - '{rec.get('new_title')}' Priority={rec.get('new_priority')}")
 
     # filter_between: amount in a range
     log_call("client.query.builder(...).filter_between('new_Amount', 500, 1500).execute()")
     print("Querying records with amount between 500 and 1500 (filter_between)...")
-    range_records = []
-    for page in backoff(
+    range_records = list(backoff(
         lambda: client.query.builder(table_name)
         .select("new_Title", "new_Amount")
         .filter_between("new_Amount", 500, 1500)
         .execute()
-    ):
-        range_records.extend(page)
+    ))
     print(f"[OK] Found {len(range_records)} records with amount in [500, 1500]")
     for rec in range_records:
         print(f"  - '{rec.get('new_title')}' Amount={rec.get('new_amount')}")
 
     # Composable expression tree with where()
     log_call("client.query.builder(...).where((eq(...) | eq(...)) & gt(...)).execute()")
     print("Querying with composable expression tree (where)...")
-    expr_records = []
-    for page in backoff(
+    expr_records = list(backoff(
         lambda: client.query.builder(table_name)
         .select("new_Title", "new_Amount", "new_Quantity")
         .where(
@@ -318,16 +311,15 @@ def main():
         .order_by("new_Amount", descending=True)
         .top(5)
         .execute()
-    ):
-        expr_records.extend(page)
+    ))
     print(f"[OK] Expression tree query found {len(expr_records)} records:")
     for rec in expr_records:
         print(
             f"  - '{rec.get('new_title')}' Amount={rec.get('new_amount')} Qty={rec.get('new_quantity')}"
         )
 
-    # Combined: fluent filters + expression tree + paging
-    log_call("client.query.builder(...).filter_eq().where(between()).page_size().execute()")
+    # Combined: fluent filters + expression tree + paging (by_page=True)
+    log_call("client.query.builder(...).filter_eq().where(between()).page_size().execute(by_page=True)")
     print("Querying with combined fluent + expression filters and paging...")
     combined_page_count = 0
     combined_record_count = 0
@@ -338,7 +330,7 @@ def main():
         .where(between("new_Quantity", 1, 15))
         .order_by("new_Quantity")
         .page_size(3)
-        .execute()
+        .execute(by_page=True)
     ):
         combined_page_count += 1
         combined_record_count += len(page)

src/PowerPlatform/Dataverse/models/query_builder.py

@@ -9,29 +9,32 @@
 
 Example::
 
-    # Via client (recommended)
-    for page in (client.query.builder("account")
-                 .select("name", "revenue")
-                 .filter_eq("statecode", 0)
-                 .filter_gt("revenue", 1000000)
-                 .order_by("revenue", descending=True)
-                 .top(100)
-                 .page_size(50)
-                 .execute()):
-        for record in page:
-            print(record["name"])
+    # Via client (recommended) -- flat iteration over records
+    for record in (client.query.builder("account")
+                   .select("name", "revenue")
+                   .filter_eq("statecode", 0)
+                   .filter_gt("revenue", 1000000)
+                   .order_by("revenue", descending=True)
+                   .top(100)
+                   .execute()):
+        print(record["name"])
 
     # With composable expression tree
     from PowerPlatform.Dataverse.models.filters import eq, gt
 
+    for record in (client.query.builder("account")
+                   .select("name", "revenue")
+                   .where((eq("statecode", 0) | eq("statecode", 1))
+                          & gt("revenue", 100000))
+                   .top(100)
+                   .execute()):
+        print(record["name"])
+
+    # Opt-in paged iteration (for batch processing)
     for page in (client.query.builder("account")
-                 .select("name", "revenue")
-                 .where((eq("statecode", 0) | eq("statecode", 1))
-                        & gt("revenue", 100000))
-                 .top(100)
-                 .execute()):
-        for record in page:
-            print(record["name"])
+                 .select("name")
+                 .execute(by_page=True)):
+        process_batch(page)
 """
 
 from __future__ import annotations
@@ -394,28 +397,42 @@ def build(self) -> dict:
 
     # --------------------------------------------------------------- execute
 
-    def execute(self) -> Iterable[List[Dict[str, Any]]]:
-        """Execute the query and return paginated results.
+    def execute(self, *, by_page: bool = False) -> Union[Iterable[Dict[str, Any]], Iterable[List[Dict[str, Any]]]]:
+        """Execute the query and return results.
+
+        By default, returns a flat iterator over individual records,
+        abstracting away OData paging.  Pass ``by_page=True`` to get
+        page-level iteration instead (useful for batch processing).
 
         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.
 
-        :return: Generator yielding pages, where each page is a list of
-            record dictionaries.
-        :rtype: Iterable[List[Dict[str, Any]]]
+        :param by_page: If ``True``, yield pages (lists of record dicts)
+            instead of individual records. Defaults to ``False``.
+        :type by_page: bool
+        :return: Generator yielding individual record dicts (default) or
+            pages of record dicts (when ``by_page=True``).
+        :rtype: Iterable[Dict[str, Any]] or Iterable[List[Dict[str, Any]]]
         :raises RuntimeError: If the query was not created via
             ``client.query.builder()``.
 
-        Example::
+        Example:
+            Flat iteration (default)::
 
-            for page in (client.query.builder("account")
-                         .select("name")
-                         .filter_eq("statecode", 0)
-                         .execute()):
-                for record in page:
+                for record in (client.query.builder("account")
+                               .select("name")
+                               .filter_eq("statecode", 0)
+                               .execute()):
                     print(record["name"])
+
+            Paged iteration::
+
+                for page in (client.query.builder("account")
+                             .select("name")
+                             .execute(by_page=True)):
+                    process_batch(page)
         """
         if self._query_ops is None:
             raise RuntimeError(
@@ -437,4 +454,11 @@ def _paged() -> Iterable[List[Dict[str, Any]]]:
                     page_size=params.get("page_size"),
                 )
 
-        return _paged()
+        if by_page:
+            return _paged()
+
+        def _flat() -> Iterable[Dict[str, Any]]:
+            for page in _paged():
+                yield from page
+
+        return _flat()

tests/unit/models/test_query_builder.py

@@ -452,22 +452,44 @@ def test_execute_calls_get_multiple(self):
             page_size=50,
         )
 
-    def test_execute_returns_result(self):
+    def test_execute_returns_flat_records_by_default(self):
         mock_query_ops = MagicMock()
         mock_client = mock_query_ops._client
         mock_odata = MagicMock()
         mock_client._scoped_odata.return_value.__enter__ = MagicMock(return_value=mock_odata)
         mock_client._scoped_odata.return_value.__exit__ = MagicMock(return_value=False)
 
-        expected = [{"name": "Test"}]
-        mock_odata._get_multiple.return_value = iter([expected])
+        mock_odata._get_multiple.return_value = iter(
+            [[{"name": "A"}, {"name": "B"}], [{"name": "C"}]]
+        )
+
+        qb = QueryBuilder("account")
+        qb._query_ops = mock_query_ops
+        records = list(qb.execute())
+
+        self.assertEqual(len(records), 3)
+        self.assertEqual(records[0]["name"], "A")
+        self.assertEqual(records[1]["name"], "B")
+        self.assertEqual(records[2]["name"], "C")
+
+    def test_execute_by_page_returns_pages(self):
+        mock_query_ops = MagicMock()
+        mock_client = mock_query_ops._client
+        mock_odata = MagicMock()
+        mock_client._scoped_odata.return_value.__enter__ = MagicMock(return_value=mock_odata)
+        mock_client._scoped_odata.return_value.__exit__ = MagicMock(return_value=False)
+
+        page1 = [{"name": "A"}, {"name": "B"}]
+        page2 = [{"name": "C"}]
+        mock_odata._get_multiple.return_value = iter([page1, page2])
 
         qb = QueryBuilder("account")
         qb._query_ops = mock_query_ops
-        pages = list(qb.execute())
+        pages = list(qb.execute(by_page=True))
 
-        self.assertEqual(len(pages), 1)
-        self.assertEqual(pages[0], expected)
+        self.assertEqual(len(pages), 2)
+        self.assertEqual(pages[0], page1)
+        self.assertEqual(pages[1], page2)
 
     def test_execute_passes_none_for_empty_options(self):
         mock_query_ops = MagicMock()

tests/unit/test_query_operations.py

@@ -63,12 +63,13 @@ def test_builder_returns_query_builder(self):
         self.assertEqual(qb.table, "account")
         self.assertIs(qb._query_ops, self.client.query)
 
-    def test_builder_execute_basic(self):
-        """builder().execute() should call _get_multiple with built params."""
-        expected_page = [{"accountid": "1", "name": "Test"}]
-        self.client._odata._get_multiple.return_value = iter([expected_page])
+    def test_builder_execute_flat_default(self):
+        """builder().execute() should return flat records by default."""
+        self.client._odata._get_multiple.return_value = iter(
+            [[{"accountid": "1", "name": "Test"}]]
+        )
 
-        pages = list(
+        records = list(
             self.client.query.builder("account")
             .select("name")
             .filter_eq("statecode", 0)
@@ -85,8 +86,34 @@ def test_builder_execute_basic(self):
             expand=None,
             page_size=None,
         )
-        self.assertEqual(len(pages), 1)
-        self.assertEqual(pages[0], expected_page)
+        self.assertEqual(len(records), 1)
+        self.assertEqual(records[0]["name"], "Test")
+
+    def test_builder_execute_flat_multiple_pages(self):
+        """execute() should flatten records from multiple pages."""
+        self.client._odata._get_multiple.return_value = iter(
+            [[{"accountid": "1"}], [{"accountid": "2"}]]
+        )
+
+        records = list(self.client.query.builder("account").execute())
+
+        self.assertEqual(len(records), 2)
+        self.assertEqual(records[0]["accountid"], "1")
+        self.assertEqual(records[1]["accountid"], "2")
+
+    def test_builder_execute_by_page(self):
+        """execute(by_page=True) should yield pages."""
+        page1 = [{"accountid": "1"}]
+        page2 = [{"accountid": "2"}]
+        self.client._odata._get_multiple.return_value = iter([page1, page2])
+
+        pages = list(
+            self.client.query.builder("account").execute(by_page=True)
+        )
+
+        self.assertEqual(len(pages), 2)
+        self.assertEqual(pages[0], page1)
+        self.assertEqual(pages[1], page2)
 
     def test_builder_execute_all_params(self):
         """builder().execute() should forward all parameters."""
@@ -114,20 +141,6 @@ def test_builder_execute_all_params(self):
             page_size=25,
         )
 
-    def test_builder_execute_multiple_pages(self):
-        """builder().execute() should yield multiple pages."""
-        page1 = [{"accountid": "1"}]
-        page2 = [{"accountid": "2"}]
-        self.client._odata._get_multiple.return_value = iter([page1, page2])
-
-        pages = list(
-            self.client.query.builder("account").execute()
-        )
-
-        self.assertEqual(len(pages), 2)
-        self.assertEqual(pages[0], page1)
-        self.assertEqual(pages[1], page2)
-
     def test_builder_execute_with_where(self):
         """builder().where().execute() should compile expression to filter."""
         from PowerPlatform.Dataverse.models.filters import eq, gt
@@ -148,13 +161,13 @@ def test_builder_execute_with_where(self):
 
     def test_builder_full_fluent_workflow(self):
         """End-to-end test of the fluent query workflow."""
-        expected_page = [
+        expected_records = [
             {"accountid": "1", "name": "Big Corp", "revenue": 5000000},
             {"accountid": "2", "name": "Mega Inc", "revenue": 4000000},
         ]
-        self.client._odata._get_multiple.return_value = iter([expected_page])
+        self.client._odata._get_multiple.return_value = iter([expected_records])
 
-        pages = list(
+        records = list(
             self.client.query.builder("account")
             .select("name", "revenue")
             .filter_eq("statecode", 0)
@@ -166,10 +179,9 @@ def test_builder_full_fluent_workflow(self):
             .execute()
         )
 
-        self.assertEqual(len(pages), 1)
-        self.assertEqual(len(pages[0]), 2)
-        self.assertEqual(pages[0][0]["name"], "Big Corp")
-        self.assertEqual(pages[0][1]["name"], "Mega Inc")
+        self.assertEqual(len(records), 2)
+        self.assertEqual(records[0]["name"], "Big Corp")
+        self.assertEqual(records[1]["name"], "Mega Inc")
 
 
 if __name__ == "__main__":