FetchXML is an XML-based query language developed by Microsoft for querying data from Microsoft Dataverse (formerly Common Data Service) and Dynamics 365. If you work on Power Platform, Power Automate, custom Dynamics 365 apps, or any integration that reads data from Dataverse, you will encounter and need to write FetchXML.
Why FetchXML Exists
Dataverse is a cloud-hosted relational data service. It exposes data through an OData-based REST API, but FetchXML provides capabilities that OData lacks for complex scenarios: multi-entity joins with aliases, aggregate functions, linked entity conditions, and the ability to express queries that would require multiple OData requests in a single round trip.
FetchXML is also the query format used natively by the Dynamics 365 Advanced Find feature and many SDK operations.
The Basic FetchXML Structure
A FetchXML query is an XML document with a fetch root element. Inside it, a single entity element specifies the table to query. The name attribute gives the logical name of the table (for example, contact, account, or opportunity). Child attribute elements list the columns to return. A filter element contains condition elements that filter the results.
The entity logical name is lowercase and follows Dataverse naming conventions. Column names are also lowercase logical names, not the display names shown in the model-driven app interface.
Joins and Linked Entities
FetchXML supports joins through link-entity elements. A link-entity element inside the main entity element defines a join to another table. The from and to attributes specify the columns used for the join. The link-type attribute controls whether it is an inner join (returns only rows that have a matching record in the linked table) or an outer join (returns all rows from the main table whether or not there is a matching linked record).
Conditions on linked entities are placed inside the link-entity element rather than the top-level filter.
Aggregate Queries
FetchXML supports aggregate functions using the aggregate and groupby attributes on attribute elements. Set aggregate="true" on the fetch element to enable aggregation mode. Then add attribute elements with aggregate="count", aggregate="sum", aggregate="avg", aggregate="min", or aggregate="max". Group the results by adding groupby="true" to the attribute elements you want to group on.
Using FetchXML in Power Automate
In a Power Automate flow, the Dataverse connector provides a List rows action. The FetchXML Query field accepts a FetchXML query string. The results are returned as an array of records. This is the most flexible way to retrieve complex filtered, joined, or aggregated data from Dataverse in a flow.
Using the DevHexLab FetchXML Builder
Open the tool at /tools/developer/fetchxml-builder. Select the entity. Choose the attributes to return. Add filter conditions using the condition builder. The tool generates the FetchXML for you. Copy it into your Power Automate flow, Dataverse Web API request, or SDK call.
Frequently Asked Questions
What is the maximum number of records FetchXML returns?
By default, FetchXML returns 5000 records. Use the count attribute on the fetch element to limit results and the paging cookie mechanism to page through large result sets.
Can I use FetchXML with the Web API directly?
Yes. Send the FetchXML as a URL-encoded string in a GET request to the fetchXml query parameter of the Web API endpoint.
What is the difference between FetchXML and OData?
OData ($filter, $select, $expand) covers most scenarios and is easier to construct dynamically. FetchXML is more powerful for complex aggregates and multi-level joins and is required for some Dynamics 365 SDK operations.
Use the FetchXML Builder to construct complex queries visually and never write raw FetchXML XML by hand.