QueryBuilder Class

Fluent interface for building and executing OData queries against a sync client.

Provides method chaining for constructing complex queries with composable filter expressions. Can be used standalone (via build()) or bound to a client (via execute).

Constructor

QueryBuilder(table: str)

Parameters

Name	Description
table Required	str Table schema name to query.

Examples

Standalone query construction:


   from PowerPlatform.Dataverse.models import col

   query = (QueryBuilder("account")
            .select("name")
            .where(col("statecode") == 0)
            .top(10))
   params = query.build()
   # {"table": "account", "select": ["name"],
   #  "filter": "statecode eq 0", "top": 10}

Methods

execute

Execute the query and return results.

Returns a QueryResult with all pages collected. Use execute_pages for lazy per-page iteration.

This method is only available when the QueryBuilder was created via client.query.builder(table). Standalone QueryBuilder instances should use build() to get parameters and pass them to client.records.list() manually.

At least one of select(), where(), or top() must be called before execute(); otherwise a ValueError is raised to prevent accidental full-table scans.

Deprecated since version The: by_page parameter is deprecated. Use execute_pages for lazy per-page iteration, or plain execute() (no flag) for the default eager result.

Example:


   from PowerPlatform.Dataverse.models import col

   for record in (client.query.builder("account")
                  .select("name")
                  .where(col("statecode") == 0)
                  .execute()):
       print(record["name"])

execute_pages

Lazily yield one QueryResult per HTTP page.

Each iteration triggers a network request via @odata.nextLink. One-shot — do not iterate more than once.

At least one of select(), where(), or top() must be called before execute_pages(); otherwise a ValueError is raised to prevent accidental full-table scans.

Example:


   from PowerPlatform.Dataverse.models import col

   for page in (client.query.builder("account")
                .select("name")
                .where(col("statecode") == 0)
                .execute_pages()):
       process(page.to_dataframe())

to_dataframe

Execute the query and return results as a pandas DataFrame.

Deprecated since version Use: QueryBuilder.execute().to_dataframe() instead. QueryBuilder.to_dataframe() will be removed in a future release.

All pages are consolidated into a single DataFrame.

This method is only available when the QueryBuilder was created via client.query.builder(table).

At least one of select(), where(), or top() must be called before to_dataframe(); otherwise a ValueError is raised to prevent accidental full-table scans.

Example:


   from PowerPlatform.Dataverse.models import col

   df = (client.query.builder("account")
         .select("name", "telephone1")
         .where(col("statecode") == 0)
         .top(100)
         .execute()
         .to_dataframe())

execute

Execute the query and return results.

Returns a QueryResult with all pages collected. Use execute_pages for lazy per-page iteration.

At least one of select(), where(), or top() must be called before execute(); otherwise a ValueError is raised to prevent accidental full-table scans.

Deprecated since version The: by_page parameter is deprecated. Use execute_pages for lazy per-page iteration, or plain execute() (no flag) for the default eager result.

Example:


   from PowerPlatform.Dataverse.models import col

   for record in (client.query.builder("account")
                  .select("name")
                  .where(col("statecode") == 0)
                  .execute()):
       print(record["name"])

execute(*, by_page=<object object>) -> QueryResult | Iterator[QueryResult]

Keyword-Only Parameters

Name	Description
by_page	Default value: <object object at 0x0000021A213288E0>

Returns

Type	Description
QueryResult, Iterator[QueryResult]	QueryResult with all pages collected (default), or page iterator (deprecated `by_page=True`).

Exceptions

Type	Description
ValueError	If no `select` `where` `top` constraint has been set.
RuntimeError	If the query was not created via `client.query.builder()`

execute_pages

Lazily yield one QueryResult per HTTP page.

Each iteration triggers a network request via @odata.nextLink. One-shot — do not iterate more than once.

At least one of select(), where(), or top() must be called before execute_pages(); otherwise a ValueError is raised to prevent accidental full-table scans.

Example:


   from PowerPlatform.Dataverse.models import col

   for page in (client.query.builder("account")
                .select("name")
                .where(col("statecode") == 0)
                .execute_pages()):
       process(page.to_dataframe())

execute_pages() -> Iterator[QueryResult]

Returns

Type	Description
Iterator[QueryResult]	Iterator of per-page QueryResult.

Exceptions

Type	Description
ValueError	If no `select` `where` `top` constraint has been set.
RuntimeError	If the query was not created via `client.query.builder()`

to_dataframe

Execute the query and return results as a pandas DataFrame.

Deprecated since version Use: QueryBuilder.execute().to_dataframe() instead. QueryBuilder.to_dataframe() will be removed in a future release.

All pages are consolidated into a single DataFrame.

This method is only available when the QueryBuilder was created via client.query.builder(table).

At least one of select(), where(), or top() must be called before to_dataframe(); otherwise a ValueError is raised to prevent accidental full-table scans.

Example:


   from PowerPlatform.Dataverse.models import col

   df = (client.query.builder("account")
         .select("name", "telephone1")
         .where(col("statecode") == 0)
         .top(100)
         .execute()
         .to_dataframe())

to_dataframe() -> DataFrame

Returns

Type	Description
Dataframe	DataFrame containing all matching records. Returns an empty DataFrame when no records match.

Exceptions

Type	Description
ValueError	If no `select` `where` `top` constraint has been set.
RuntimeError	If the query was not created via `client.query.builder()`