FetchXML - Complete Reference - MSXRMTOOLS

4/3/2018 FetchXML - Complete Reference - MSXRMTOOLS
MSXRMTOOLS Tools MCQ Q&A About Contact Dynamics 365 Training Online Log in Register
;
FetchXML - Complete Reference

Retrieve All Attributes -
• FetchXML Query
(/fetchxml/reference#1)
FetchXML Summary Retrieve All Records -
FetchXML is a query language used in Microsoft Dynamics CRM and has following
features:
• FetchXML Query
FetchXML can be used for retrieving data from Microsoft Dynamics CRM. Filter Records Based On
FetchXML cannot be used for Create, Update and Delete operations. • Related Entity
FetchXML can perform aggregations like Sum, Average, Minimum, Maximum,
Count(*), Count(attributename)
Complete List Of
FetchXML query can do GoupBy, Sorting and Filter on linked entity.
FetchXML queries are defined in XML format.
• FetchXML Operators
FetchXML query can retrieve upto 5000 records in a single request.
FetchXML allows paging results using paging cookie. Limit Maximum Number
FetchXML can be saved as user-owned view in the userquery entity and as an • Of Records Returned
organization-owned view in the savedquery entity.
• Inner Join In FetchXML

Left Outer Join In

Retrieve All Attributes - FetchXML Query • FetchXML
In the following example, the FetchXML statement retrieves all attributes for account
records: Aggregates in FetchXML
1. <fetch mapping='logical' >
2. name='account' > About
·
<entity
3. <all-attributes/> Aggregation
4. </entity> (/fetchxml/reference#
5. </fetch> Average
Explanation · Aggregates
(/fetchxml/reference#
<all-attributes /> clause makes FetchXML query to retrive all attributes for an Count
entity.
· Aggregate
As a best-practice retrieve only the required attributes for better performance. Retrieving
selected attributes is explained below. Countcolumn
· Aggregate
• (/fetchxml/reference#
Retrieve All Records - FetchXML Query ·

Count Distinct
Columns
In the following example, the FetchXML statement retrieves all accounts, with selected (/fetchxml/reference#
attributes:

· Max Aggregate
·
2. <entity name='account' > Min Aggregate
3. <attribute name='accountid' /> (/fetchxml/reference#
4. <attribute name='name' />
5. </entity> · Sum Aggregate
6. </fetch>
Multiple
Explanation
· Aggregates
http://msxrmtools.com/fetchxml/reference 1/21
FetchXML query will return all the records if no filter applied. (/fetchxml/reference#
To retrieve the selected attributes for an entity specify each attribute separately.
Group By
<attribute name='accountid' /> (/fetchxml/reference#18)
Group by with
<attribute name='name' />
· linked entity
· Group By Year
Filter Records Based On Related Entity

Group By
In the following example, the FetchXML statement retrieves all accounts where the last · Quarter
•
name of the owning user is not equal to Cannon: (/fetchxml/reference#
1. mapping='logical' >
· Group By Month
<fetch
2. <entity name='account' > (/fetchxml/reference#
·
3. <attribute name='accountid' /> Group By Week
4. <attribute name='name' /> (/fetchxml/reference#
5. <link-entity name='systemuser' to='owninguser' >
6.
7.
<filter type='and' >
<condition attribute='lastname' operator='ne' value='Ca
· Group By Day
8. Multiple group
·
</filter>
9. </link-entity> by
10. </entity> (/fetchxml/reference#
• Order
11. </fetch>
by
Explanation
Fiscal Date in FetchXML
To filter entity records add <link-entity> clause, ex <link-entity
name='systemuser' to='owninguser'> . Where name attributes contains linked
entity logical name and to attribute contains logical name of attribute in main entity Last Fiscal
which is linked to related entity
Specify filter clause within link-entity.
· Period
FetchXML Query
Within filter specify the filter criteria using <condition attribute='lastname' (/fetchxml/reference#
operator='ne' value='Cannon' /> . Where attribute contains logical name of In Fiscal Year
attribute in related entity, operator defines the comparison type here ne means
not-equal and value defines the value to compare.
· FetchXML Query
Complete list of FetchXML operators is defined below. • in-fiscal-period
· FetchXML Query
Complete List Of FetchXML Operators

in-fiscal-period-
· and-year Query
FetchXML Operator Descritption
fiscal-period
lt Less Than · FetchXML Query
gt Greater Than
Using "older than" clauses
le Less Than or Equal To
• for date and time values in
FetchXML Query
ge Greater Than or Equal To (/fetchxml/reference#33)
eq Equals
ne Not Equals
neq Not Equal To
null Does Not Contain Data
not-null Contains Data
in Is In
not-in Is Not In
between Between
not-between Is Not Between
like Like
not-like Not Like
yesterday Yesterday
today Today
tomorrow Tomorrow
next-seven-days Next Seven Days
last-seven-days Last Seven Days
next-week Next Week
last-week Last Week
this-month This Month
last-month Last Month
next-month Next Month
on On
on-or-before On or Before
on-or-after On on After
this-year This Year
last-year Last Year
next-year Next Year
eq-userid Equals Current User
ne-userid Does Not Equal Current User
eq-businessid Equals Current Business Unit
ne-businessid Does Not Equal Current Business Unit
this-week This Week
last-x-months Last X Months
eq-userlanguage Equals User Language
eq-userteams Equals Current User’s Teams
in-fiscal-year In Fiscal Year
in-fiscal-period In Fiscal Period
in-fiscal-period-and-year In Fiscal Period and Year
in-or-after-fiscal-period-and-year In or After Fiscal Period and Year
in-or-before-fiscal-period-and-year In or Before Fiscal Period and Year
last-fiscal-year Last Fiscal Year
this-fiscal-year This Fiscal Year
next-fiscal-year Next Fiscal Year
last-x-fiscal-years Last X Fiscal Years
next-x-fiscal-years Next X Fiscal Years
last-fiscal-period Last Fiscal Period
this-fiscal-period This Fiscal Period
next-fiscal-period Next Fiscal Period
last-x-fiscal-periods Last X Fiscal Periods
next-x-fiscal-periods Next X Fiscal Periods
Limit Maximum Number Of Records

Returned.
In the below example, the FetchXML returns top 3 records of account.
1. <fetch mapping='logical' count='3' >

2. <entity name='account' >
3. <attribute name='name' alias='name' />
4. </entity>
5. </fetch>
Explanation
To limit maximum number of records returned specify count attribute in fetch

node.
Maximum 5000 records can be returned from FetchXML query.
Inner Join In FetchXML.

In the below example, the FetchXML performs inner join on account and contact entity
and returns contacts where accountid of account matches parentcustomerid of contact.
1. <fetch version='1.0' mapping='logical' distinct='false' >

2. <entity name='contact' >
3. <attribute name='fullname' />
4. <link-entity name='account' to='parentcustomerid' from='accou
>
6. </link-entity>
7. </entity>
8. </fetch>
Explanation
To perform inner join in FetchXML query set following attributes in link-entity

clause.
Set name attribute to logical name of related entity.
Set to attribute to linking attribute in primary entity.
Set from attribute to linking attribute in related entity.
Set link-type attribute to inner.
Now within link-entity clause specify attributes from related entity to retrieve
Left Outer Join In FetchXML

A left outer join returns each row that satisfies the join of the first input with the second
input. It also returns any rows from the first input that had no matching rows in the second
input. The nonmatching rows in the second input are returned as null values.
In the below example, the FetchXML finds all accounts that have no leads

2. <entity name='account' >
4. <link-entity name='lead' from='leadid' to='originatingleadid
/>
5. <filter type='and' >
6. <condition entityname='lead' attribute='leadid' operato
/>
7. </filter>
8. </entity>
9. </fetch>
Explanation
You can perform a left outer join in FetchXML by using the entityname attribute as a
condition operator. The entityname attribute is valid in conditions, filters, and nested
filters.
To perform left outer join in FetchXML query set following attributes in link-entity
clause.
Set name attribute to logical name of related entity.
Set to attribute to linking attribute in primary entity.
Set from attribute to linking attribute in related entity.
Set link-type attribute to outer.

In filter clause specify the condition with following attrbutes
Set entityname attribute to logical name of related entity.
Set attribute to linking attribute in related entity
Set operator to valid FetchXML operator(null in this case).
Aggregates in FetchXML
In Microsoft Dynamics CRM FetchXML includes grouping and aggregation features that let
you calculate sum, average, minimum, maximum and count.
The following aggregate functions are supported:
sum
avg
min
max
count(*)
count(attribute name)
About Aggregation
To create an aggregate attribute,
Set the keyword aggregate to true in fetch node.

Specify a valid entity name, attribute name, and alias (variable name).
You must also specify the type of aggregation you want to perform, for
example count, min, max etc.
The following example shows a simple aggregate attribute in FetchXML.
1. <fetch distinct='false' mapping='logical' aggregate='true

2. <entity name='entity name' >
3. <attribute name='attribute name' aggregate='count' ali
4. </entity>
5. </fetch>
Average Aggregates
Following FetchXML calculates average of estimated value from opportunity.

2. <entity name='opportunity' >
3. <attribute name='estimatedvalue' alias='estimatedvalue
4. </entity>
5. </fetch>
Explanation
To calculate average set following:
Set aggregate to true in <fetch> clause.
<fetch distinct='false' mapping='logical' aggregate='true'
In <aggregate> attribute set aggregate to avg
<attribute name='estimatedvalue' alias='estimatedvalue_avg'
Limitation with null values while computing average

Null values are not considered when Microsoft Dynamics CRM computes the
average of data. However, zero (0) is used.
In the following example, with the following data, the average for Account 1
(two entries) is shown as 250 whereas the average for Account 2 (two entries) is
shown as 125.
Topic Potential Customer Estimated value
Opportunity 1 Account 1 null
Opportunity 2 Account 1 250
Count Aggregate
The following FetchXML counts opportunity records

3. <attribute name='name' alias='opportunity_count' aggre
4. </entity>
5. </fetch>
Explanation
To calculate count set following:
In <aggregate> attribute set aggregate to count
<attribute name='name' alias='opportunity_count' aggregate='
Countcolumn Aggregate
Countcolumn aggregate counts records where specified column don’t have null.
In the following FetchXML opportunity count is returned where name column

don’t have null values.

3. <attribute name='name' alias='opportunity_colcount' ag
4. </entity>
5. </fetch>
Explanation
To use countcolumn aggregate
Set aggregate to countcolumn in aggregate attribute.
<attribute name='name' alias='opportunity_colcount' aggregat
Count Distinct Columns

The following FetchXML counts all opportunities with distinct names

3. <attribute name='name' alias='opportunity_distcount' a
4. </entity>
5. </fetch>
Explanation
To count distinct column values
Set aggregate to true in fetch clause.

Set aggregate to countcoumn in aggregate attribute
Set distinct to true
Max Aggregate
Max aggregate returns the maximum value in a specified column.
maximum of data. However, zero (0) is used.
The following FetchXML shows how to get the maximum value from estimated
column of opportunity entity.

4. </entity>
5. </fetch>
Explanation
To get maximum value from a column set:
Set aggregate to true in fetch node.

Set aggregate to max in aggregate attribute.
Min Aggregate
Min aggregate returns the minimum value in a specified column.
minimum of data. However, zero (0) is used.
The following FetchXML shows how to get the maximum value from estimated
column of opportunity entity.

4. </entity>
5. </fetch>
Explanation
To get minimum value from a column set:

Set aggregate to min in aggregate attribute.
Sum Aggregate
The following FetchXML calculates the sum of estimated value from
opportunity entity.

4. </entity>
5. </fetch>
Explanation
To get the sum of values in a column:

Set aggregate to sum in aggregate attribute.
Multiple Aggregates
Multiple aggregates can be computed in a single FetchXML query.
Following FetchXML calculates count, sum and avg from opportunity entity.

3. <attribute name='opportunityid' alias='opportunity_cou
6. </entity>
7. </fetch>
Explanation
To calculate multiple aggregate in single FetchXML query

For each type of aggregate add separate aggregate attribute and set
aggregate value accordingly.
Group By
Aggregates can be grouped in FetchXML, to group aggregates set groupby attribute to
true.
The following example returns opportunity records grouped by their owners.
1. <fetch distinct='false' mapping='logical' aggregate='true' >

3. <attribute name='name' alias='opportunity_count' aggregate='cou
4. <attribute name='ownerid' alias='ownerid' groupby='true' />
5. </entity>
6. </fetch>
Explanation
To group aggregates in FetchXML query
<fetch distinct='false' mapping='logical' aggregate='true' >
Add required aggregate attribute.
<attribute name='name' alias='opportunity_count' aggregate='countcolu
Add group by attribute and set keyword groupby to true.
<attribute name='ownerid' alias='ownerid' groupby='true' />
Group by with linked entity

The following FetchXML returns opportunities grouped by opportunity owner’s
managers.

3. <attribute name='name' alias='opportunity_count' aggre
4. <link-entity name='systemuser' from='systemuserid' to=
>
5. <attribute name='parentsystemuserid' alias='manageri
/>
6. </link-entity>
7. </entity>
8. </fetch>
Explanation
To create group by with linked entity FetchXML
Add required aggregate attribute in entity clause.
<attribute name='name' alias='opportunity_count' aggregate=
Add link-entity clause in entity clause.
<link-entity name='systemuser' from='systemuserid' to='owner
Add group by attribute in link-entity clause and set keyword groupby to

true.
<attribute name='parentsystemuserid' alias='managerid' group

/>
Group By Year
Group By for dates uses the day, week, month, quarter or year value.
The following FetchXML query shows how to use the aggregate attribute and
the groupby attribute to group the results by year.

>
3. <attribute name='opportunityid' alias='opportunity_c
/>
4. <attribute name='estimatedvalue' alias='estimatedval
/>
/>
6. <attribute name='actualclosedate' groupby='true' dat
/>
8. <condition attribute='statecode' operator='eq' va
/>
9. </filter>
10. </entity>
11. </fetch>
Explanation
To create group by Year FetchXML query:
Add group by attribute set keyword groupby to true and dategrouping

to year.
<attribute name='actualclosedate' groupby='true' dategroupin

/>
Group By Quarter
The following example shows how to use the aggregate attribute and the
groupby attribute to group the results by quarter.

>
/>
/>
/>
/>
/>
9. </filter>
10. </entity>
11. </fetch>
Explanation
To create group by Quarter FetchXML query:

to quarter.

/>
Group By Month
The following FetchXML shows how to use the aggregate attribute and the
groupby attribute to group the results by month.

>
/>
/>
/>
/>
/>
9. </filter>
10. </entity>
11. </fetch>
Explanation
To create group by Month FetchXML query:

to month.

/>
Group By Week
groupby attribute to group the results by week.

>
/>
/>
/>
/>
/>
9. </filter>
10. </entity>
11. </fetch>
Explanation
To create group by Week FetchXML query:

to week.

/>
Group By Day
groupby attribute to group the results by week.

>
/>
/>
/>
/>
/>
9. </filter>
10. </entity>
11. </fetch>
Explanation
To create group by Day FetchXML query:

to day.

/>
Multiple group by
The following FetchXML shows how to use the aggregate attribute and
multiple groupby clauses.

>
/>
/>
/>
/>
/>
/>
10. </filter>
11. </entity>
12. </fetch>
Explanation
To create multiple group by FetchXML query:
Add required aggregate attributes in entity clause.
Add multiple group by attributes by setting keyword groupby to true.

/>

/>
Order by
The following FetchXML query shows how to use the aggregate attribute and multiple
orderby clauses.
1. <fetch distinct='false' mapping='logical' aggregate='true' >

3. <attribute name='opportunityid' alias='opportunity_count' agg
/>
4. <attribute name='estimatedvalue' alias='estimatedvalue_sum' a
/>
5. <attribute name='estimatedvalue' alias='estimatedvalue_avg' a
/>
6. <attribute name='actualclosedate' groupby='true' dategrouping
/>
7. <attribute name='actualclosedate' groupby='true' dategrouping
/>
8. <order alias='year' descending='false' />
9. <order alias='quarter' descending='false' />
11. <condition attribute='statecode' operator='eq' value='Won'
/>
12. </filter>
13. </entity>
14. </fetch>
Explanation
To create order by FetchXML query:
Add order clause in entity and set descending keyword to true or false.
<order alias='year' descending='false' />
Fiscal Date in FetchXML

A FetchXML query can query data on fiscal dates. For example, a FetchXML query can find
all orders fulfilled in the last fiscal month or urgent cases with high severity that are older
than 15 minutes.
For all fiscal date queries, the FetchXML query uses the organization’s fiscal year settings.
Last Fiscal Period FetchXML Query

The following example shows a FetchXML expression that finds all orders
fulfilled in the last fiscal period, according to the organization’s fiscal year
settings.
For example, if the organization uses fiscal months, the query returns orders
fulfilled in the last fiscal month. If the organization uses fiscal quarters, the
query returns orders fulfilled in the last fiscal quarter. If the organization uses
fiscal semesters, orders fulfilled in the last fiscal semester are returned.
1. <fetch>
2. <entity name="order" >
3. <attribute name="name" />
4. <filter type="and" >
5. <condition attribute="datefulfilled" operator="last-fis
/>
6. </filter>
7. </entity>
8. </fetch>
Explanation
To create last fiscal period FetchXML query:
In condition attribute set operator keyword to last-fiscal-period.
<condition attribute="datefulfilled" operator="last-fiscal-p
In Fiscal Year FetchXML Query

The following example shows a FetchXML expression that finds all accounts
created in fiscal year 2013.
1. <fetch>
2. <entity name="account" >
5. <condition attribute="createdon" operator="in-fiscal-ye
/>
6. </filter>
7. </entity>
8. </fetch>
Explanation
To create In Fiscal Year FetchXML query:
In condition attribute set operator keyword to in-fiscal-year.
<condition attribute="createdon" operator="in-fiscal-year" v
next-x-fiscal-years Query
The following example shows a FetchXML expression that finds all
opportunities with an estimated close date in the next three fiscal years, based
on the organization’s fiscal year settings.
1. <fetch>
2. <entity name="opportunity" >
5. <condition attribute="estimatedclosedate" operator="nex
/>
6. </filter>
7. </entity>
8. </fetch>
Explanation
To create next-x-fiscal-years FetchXML query:
In condition attribute set operator keyword to next-x-fiscal-years.
<condition attribute="createdon" operator="in-fiscal-year" v
Specify value of x in value attribute of condition tag.
in-fiscal-period FetchXML Query

fulfilled in period three of any fiscal year, according to the organization’s fiscal
year settings. The fiscal period value is specified in the value attribute of the
condition tag. If the organization uses fiscal months, the query returns results
from month three. If the organization uses fiscal quarters, the query returns
results from quarter three. If the organization uses fiscal semesters, no results
are returned; there are only two semesters, and the value supplied is therefore
out-of-range.
1. <fetch>
5. <condition attribute="datefulfilled" operator="in-fisca
/>
6. </filter>
7. </entity>
8. </fetch>
Explanation
To create in-fiscal-period FetchXML query:
In condition attribute set operator keyword to in-fiscal-period.
<condition attribute="datefulfilled" operator="in-fiscal-per
Specify value of fiscal period in value attribute of condition tag.
in-fiscal-period-and-year Query
fulfilled in period three of fiscal year 2013, according to the organization’s fiscal
year settings. If the organization uses fiscal months, the query returns results
from month three. If the organization uses fiscal quarters, the query returns
results from quarter three. If the organization uses fiscal semesters, no results
are returned; there are only two semesters, and the value supplied is therefore
out-of-range.
1. <fetch>
5. <condition attribute="datefulfilled" operator="in-fisca
>
6. <value> 3 </value>
7. <value> 2013 </value>
8. </condition>
9. </filter>
10. </entity>
11. </fetch>
Explanation
To create in-fiscal-period-and-year FetchXML query:
In condition attribute set operator keyword to in-fiscal-period-and-

year.
<condition attribute="datefulfilled" operator="in-fiscal-per
Specify value of fiscal period in value attribute of condition tag.
<value> 3 </value>
Specify value of fiscal year in another value attribute of condition tag.
<value> 2013 </value>
fiscal-period FetchXML Query

The following example shows a FetchXML aggregation expression that sums
the total amount of orders fulfilled and groups the result by fiscal semester and
fiscal year.
1. <fetch aggregate="true" >

3. <attribute name="totalamount" aggregate="sum" alias="tot
/>
4. <attribute name="datefulfilled" groupby="true" dategroup
/>
5. </entity>
6. </fetch>
Explanation
To create group by with linked entity FetchXML:
Create an aggregate query

Add link-entity node for entity which contains group by attribute
(systemuser entity in this case.)
In link-entity node add required attribute containing groupby keyword
with value set to true.
Using "older than" clauses for date

and time values in FetchXML Query
The following example shows a FetchXML that finds incidents that are older
than 30 minutes.
1. <fetch>
2. <entity name="incident" >
3. <attribute name="title" />
4. <attribute name="ticketnumber" />
5. <attribute name="createdon" />
6. <attribute name="incidentid" />
8. <condition attribute="createdon" operator="olderthan
/>
9. </filter>
10. </entity>
11. </fetch>
Use the following syntax to specify various

older than clauses in a FetchXML expression.
Clause Syntax
<condition attribute=" <AttributeName> " operator="olderthan-x-minutes" value=" <VALUE> " />

Older
than X
minutes
This clause is not supported for date and time attributes with DateOnly behavior.
<condition attribute=" <AttributeName> " operator="olderthan-x-hours" value=" <VALUE> " />

Older
than X
hours
This clause is not supported for date and time attributes with DateOnly behavior.
Older <condition attribute=" <AttributeName> " operator="olderthan-x-days" value=" <VALUE> " />
than X
days
Older <condition attribute=" <AttributeName> " operator="olderthan-x-weeks" value=" <VALUE> " />
than X
weeks
Older <condition attribute=" <AttributeName> " operator="olderthan-x-months" value=" <VALUE> " />
than X
months
Older <condition attribute=" <AttributeName> " operator="olderthan-x-years" value=" <VALUE> " />
than X
years
© 2018 - MSXRMTOOLS

FetchXML - Complete Reference - MSXRMTOOLS

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

FetchXML - Complete Reference - MSXRMTOOLS

Uploaded by

Copyright:

Available Formats

4/3/2018 FetchXML - Complete Reference - MSXRMTOOLS

FetchXML - Complete Reference

• Inner Join In FetchXML

Left Outer Join In

Retrieve All Records - FetchXML Query ·

1. <fetch mapping='logical' >

Filter Records Based On Related Entity

Complete List Of FetchXML Operators

FetchXML Operator Descritption

neq Not Equal To

null Does Not Contain Data

not-null Contains Data

not-between Is Not Between

not-like Not Like

next-seven-days Next Seven Days

last-seven-days Last Seven Days

next-week Next Week

last-week Last Week

this-month This Month

last-month Last Month

next-month Next Month

this-year This Year

last-year Last Year

next-year Next Year

eq-userid Equals Current User

ne-userid Does Not Equal Current User

eq-businessid Equals Current Business Unit

ne-businessid Does Not Equal Current Business Unit

this-week This Week

FetchXML Operator Descritption

last-x-months Last X Months

eq-userlanguage Equals User Language

eq-userteams Equals Current User’s Teams

in-fiscal-year In Fiscal Year

in-fiscal-period In Fiscal Period

in-fiscal-period-and-year In Fiscal Period and Year

in-or-after-fiscal-period-and-year In or After Fiscal Period and Year

in-or-before-fiscal-period-and-year In or Before Fiscal Period and Year

last-fiscal-year Last Fiscal Year

this-fiscal-year This Fiscal Year

next-fiscal-year Next Fiscal Year

last-x-fiscal-years Last X Fiscal Years

next-x-fiscal-years Next X Fiscal Years

last-fiscal-period Last Fiscal Period

this-fiscal-period This Fiscal Period

next-fiscal-period Next Fiscal Period

last-x-fiscal-periods Last X Fiscal Periods

next-x-fiscal-periods Next X Fiscal Periods

Limit Maximum Number Of Records

1. <fetch mapping='logical' count='3' >

To limit maximum number of records returned specify count attribute in fetch

Inner Join In FetchXML.

1. <fetch version='1.0' mapping='logical' distinct='false' >

To perform inner join in FetchXML query set following attributes in link-entity

Left Outer Join In FetchXML

1. <fetch mapping='logical' >

Set link-type attribute to outer.

The following aggregate functions are supported:

Set the keyword aggregate to true in fetch node.

The following example shows a simple aggregate attribute in FetchXML.

1. <fetch distinct='false' mapping='logical' aggregate='true

1. <fetch distinct='false' mapping='logical' aggregate='true

Set aggregate to true in <fetch> clause.

<fetch distinct='false' mapping='logical' aggregate='true'