FetchXmlQuery Class

Inert FetchXML query object. No HTTP request is made until execute or execute_pages is called.

Obtained via client.query.fetchxml(xml).

Constructor

FetchXmlQuery(xml: str, entity_name: str, client: DataverseClient)

Parameters

Name Description
xml
Required

Stripped, well-formed FetchXML string.
entity_name
Required

Entity schema name from the <entity> element.
client
Required

Parent DataverseClient.

Methods

execute

Execute the FetchXML query and return all results as a QueryResult.

Blocking — fetches all pages upfront and holds every record in memory before returning. Simple for small-to-medium result sets; use execute_pages when the result set may be large or you want to process records as they arrive.

Example:


   rows = client.query.fetchxml(xml).execute()
   df = rows.to_dataframe()
execute_pages

Lazily yield one QueryResult per HTTP page.

Streaming — each iteration fires one HTTP request and yields one page. Prefer over execute when:

  • The result set may be large and you do not want all records in memory at once.

  • You want early exit: stop iterating once you find what you need and the remaining HTTP round-trips are skipped automatically.

  • You need per-page progress reporting or batched downstream writes.

One-shot — do not iterate more than once.

Example:


   for page in client.query.fetchxml(xml).execute_pages():
       process(page.to_dataframe())

execute

Execute the FetchXML query and return all results as a QueryResult.

Blocking — fetches all pages upfront and holds every record in memory before returning. Simple for small-to-medium result sets; use execute_pages when the result set may be large or you want to process records as they arrive.

Example:


   rows = client.query.fetchxml(xml).execute()
   df = rows.to_dataframe()

execute() -> QueryResult

Returns

Type Description
QueryResult

All matching records across all pages.

execute_pages

Lazily yield one QueryResult per HTTP page.

Streaming — each iteration fires one HTTP request and yields one page. Prefer over execute when:

  • The result set may be large and you do not want all records in memory at once.

  • You want early exit: stop iterating once you find what you need and the remaining HTTP round-trips are skipped automatically.

  • You need per-page progress reporting or batched downstream writes.

One-shot — do not iterate more than once.

Example:


   for page in client.query.fetchxml(xml).execute_pages():
       process(page.to_dataframe())

execute_pages() -> Iterator[QueryResult]

Returns

Type Description
Iterator[QueryResult]

Iterator of per-page QueryResult objects.