Build queries with QueryExpression


Effective November 2020:

  • Common Data Service has been renamed to Microsoft Dataverse. Learn more
  • Some terminology in Microsoft Dataverse has been updated. For example, entity is now table and field is now column. Learn more

This article will be updated soon to reflect the latest terminology.

In Microsoft Dataverse, you can use the QueryExpression class to programmatically build a query containing data filters and search conditions that define the scope of a database search. A query expression is used for single-object searches. For example, you can create a search to return all accounts that match certain search criteria. The QueryBase class is the base class for query expressions. There are three derived classes: QueryExpression, QueryByAttribute and FetchExpression. The QueryExpression class supports complex queries. The QueryByAttribute class is a simple means to search for entities where attributes match specified values.


The third derived class, FetchExpression is used with FetchXML, the proprietary Dataverse query language, can be used to perform some queries by using XML-based queries. More information: Use FetchXML to construct a query

Query expressions are used in methods that retrieve more than one record, such as the IOrganizationService.RetrieveMultiple method, in messages that perform an operation on a result set specified by a query expression, such as BulkDeleteRequest and when the ID for a specific record is not known.


Don’t retrieve all attributes in a query because of the negative effect on performance. This is particularly true if the query is used as a parameter to an update request. In an update, if all attributes are included this sets all field values, even if they are unchanged, and often triggers cascaded updates to child records.

To save a query so you can re-use it, you can convert it to FetchXML by using the QueryExpressionToFetchXmlRequest and save it as a saved query. More information: Saved queries

Alternatives to QueryExpression

There are two additional ways to create queries to retrieve records from Dataverse.

Configuration for Quick find

In Model-driven apps, there is a Quick Find feature. If a user provides search criteria in quick find that is not selective enough, the system detects this and stops the search. This supports a faster form of quick find and can make a big performance difference. This is controlled by the Organization entity QuickFindRecordLimitEnabled attribute. When this Boolean attribute value is true, a limit is imposed on quick find queries.

In This Section

Using the QueryByAttribute Class
Using the QueryExpression Class
Using the ColumnSet Class
Using the ConditionExpression Class
Using the FilterExpression Class
Use a left outer join in QueryExpression to query for records "not in"
Testing for a Null Value
Page Large Result Sets with Query Expression and FetchXML
Sample: Retrieve With One-To-Many Relationship
Sample: Retrieve Multiple with Query By Attribute
Sample: Retrieve Multiple with Query Expression
Sample: Use QueryExpression with a paging cookie



See also

Sample: Convert queries between Fetch and QueryExpression


Can you tell us about your documentation language preferences? Take a short survey.

The survey will take about seven minutes. No personal data is collected (privacy statement).