You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: powerapps-docs/developer/data-platform/webapi/query-data-web-api.md
+59-37Lines changed: 59 additions & 37 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: "Query data using the Web API (Microsoft Dataverse)| Microsoft Docs"
3
-
description: "Read about the various ways to query Microsoft Dataverse table data using the Web API and the various system query options that can be applied in these queries."
4
-
ms.date: 04/08/2022
3
+
description: "Learn how to query Microsoft Dataverse table data using the Web API and the options that can be applied in these queries."
4
+
ms.date: 04/18/2022
5
5
author: divka78
6
6
ms.author: dikamath
7
7
ms.reviewer: jdaly
@@ -30,7 +30,7 @@ If you want to retrieve data for an entity set, use a `GET` request. When retrie
30
30
**Request**
31
31
32
32
```http
33
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name
33
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name
You can limit the number of results returned by using the `$top` system query option. The following example will return just the first three account rows.
85
85
86
86
```http
87
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name,revenue&$top=3
87
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue&$top=3
88
88
```
89
89
90
90
> [!NOTE]
@@ -106,7 +106,7 @@ Use the `odata.maxpagesize` preference value to request the number of rows retur
106
106
**Request**
107
107
108
108
```http
109
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name HTTP/1.1
109
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name HTTP/1.1
Each of the system query options you append to the URL for the entity set is added using the syntax for query strings. The first is appended after [?] and subsequent query options are separated using [&]. All query options are case-sensitive as shown in the following example.
159
159
160
160
```http
161
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name,revenue
161
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
162
162
&$top=3
163
163
&$filter=revenue gt 100000
164
164
```
@@ -170,15 +170,15 @@ GET [Organization URI]/api/data/v9.1/accounts?$select=name,revenue
170
170
Use the `$select` system query option to limit the properties returned as shown in the following example.
171
171
172
172
```http
173
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name,revenue
173
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
174
174
```
175
175
176
176
> [!IMPORTANT]
177
177
> This is a performance best practice. If properties aren’t specified using `$select`, all properties will be returned.
178
178
179
179
When you request certain types of properties you can expect additional read-only properties to be returned automatically.
180
180
181
-
If you request a money value, the `_transactioncurrencyid_value` lookup property will be returned. This property contains only the GUID value of the transaction currency so you could use this value to retrieve information about the currency using the <xref:Microsoft.Dynamics.CRM.transactioncurrency?text=transactioncurrency EntityType />. Alternatively, by requesting annotations you can also get additional data in the same request. More information: [Retrieve data about lookup properties](#bkmk_lookupProperty)
181
+
If you request a money value, the `_transactioncurrencyid_value` lookup property will be returned. This property contains only the GUID value of the transaction currency so you could use this value to retrieve information about the currency using the <xref:Microsoft.Dynamics.CRM.transactioncurrency?text=transactioncurrency EntityType>. Alternatively, by requesting annotations you can also get additional data in the same request. More information: [Retrieve data about lookup properties](#bkmk_lookupProperty)
182
182
183
183
If you request a property that is part of a composite attribute for an address, you will get the composite property as well. For example, if your query requests the `address1_line1` property for a contact, the `address1_composite` property will be returned as well.
184
184
@@ -236,10 +236,10 @@ You can use wildcard characters when you construct queries using these standard
236
236
237
237
### Microsoft Dataverse Web API query functions
238
238
239
-
Dataverse provides a number of special functions that accept parameters, return Boolean values, and can be used as filter criteria in a query. See <xref:Microsoft.Dynamics.CRM.QueryFunctionIndex?displayProperty=nameWithType> for a list of these functions. The following is an example of the <xref:Microsoft.Dynamics.CRM.Between?text=Between Function /> searching for accounts with a number of employees between 5 and 2000.
239
+
Dataverse provides a number of special functions that accept parameters, return Boolean values, and can be used as filter criteria in a query. See <xref:Microsoft.Dynamics.CRM.QueryFunctionIndex?displayProperty=nameWithType> for a list of these functions. The following is an example of the <xref:Microsoft.Dynamics.CRM.Between?text=Between Function> searching for accounts with a number of employees between 5 and 2000.
240
240
241
241
```http
242
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name,numberofemployees
242
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name,numberofemployees
The example given below shows how you can retrieve all account entity records that have at least one email with "sometext" in the subject and whose statecode is active.
293
293
294
294
```http
295
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name
295
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name
296
296
&$filter=Account_Emails/any(o:contains(o/subject,'sometext') and
297
297
o/statecode eq 0) HTTP/1.1
298
298
Prefer: odata.include-annotations="*"
@@ -304,7 +304,7 @@ OData-Version: 4.0
304
304
The example given below shows how you can also create a nested query using `any` and `all` operators.
305
305
306
306
```http
307
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name
307
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name
308
308
&$filter=(contact_customer_accounts/any(c:c/jobtitle eq 'jobtitle' and
309
309
c/opportunity_customer_contacts/any(o:o/description ne 'N/A'))) and
310
310
endswith(name,'{0}') HTTP/1.1
@@ -325,7 +325,7 @@ The example given below shows how you can use the [/any operator](#bkmk_anyopera
325
325
**Request**
326
326
327
327
```http
328
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name
328
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name
329
329
&$filter=not opportunity_customer_accounts/any(o:o/description eq null and
330
330
o/budgetamount le 300 or
331
331
contains(o/description, 'bad')) and
@@ -351,7 +351,7 @@ For example:
351
351
**Request**
352
352
353
353
```http
354
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name
354
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name
@@ -430,7 +430,7 @@ The two options for filtering results based on values of collection-valued navig
430
430
Lambda operators allow you to apply filter on values of collection properties for a link-entity. The below example retrieves the records of `systemuser` entity type that are linked with `team` and `teammembership` entity types, that means it retrieves `systemuser` records who are also administrators of a team whose name is "CITTEST".
431
431
432
432
```http
433
-
GET [Organization URI]/api/data/v9.1/systemusers?$filter=(teammembership_association/any(t:t/name eq 'CITTEST'))
433
+
GET [Organization URI]/api/data/v9.2/systemusers?$filter=(teammembership_association/any(t:t/name eq 'CITTEST'))
@@ -446,10 +446,32 @@ To get the same results as the example above, you can retrieve records of two en
446
446
Follow the steps in the below example to understand how we can filter results using the iteration method:
447
447
448
448
1. Get a distinct list of <xref:Microsoft.Dynamics.CRM.team?displayProperty=nameWithType>._administratorid_value values.
449
-
-`GET [OrganizationURI]/api/data/v9.1/teams?$select=_administratorid_value&$filter=_administrator_value ne null`
449
+
-`GET [OrganizationURI]/api/data/v9.2/teams?$select=_administratorid_value&$filter=_administrator_value ne null`
450
450
- Then loop through the returned values to remove duplicates and get a distinct list. i.e. Create a new array, loop through the query results, for each check to see if they are already in the new array, if not, add them. This should give you a list of distinct `systemuserid` values
451
451
- The way you would do this in JavaScript vs C# would be different, but essentially you should be able to get the same results.
452
-
2. Query <xref:Microsoft.Dynamics.CRM.systemuser?displayProperty=nameWithType> using <xref:Microsoft.Dynamics.CRM.ContainValues?text=ContainValues Query Function /> to compare the `systemuserid` values with the list collected in Step 1.
452
+
2. Query <xref:Microsoft.Dynamics.CRM.systemuser?displayProperty=nameWithType> using <xref:Microsoft.Dynamics.CRM.ContainValues?text=ContainValues Query Function> to compare the `systemuserid` values with the list collected in Step 1.
453
+
454
+
### Manage single quotes in string filter values
455
+
456
+
When specifying values for comparison in filters that accept an array of string values, such as the <xref:Microsoft.Dynamics.CRM.In?text=In Query Function>, which contain single quote (apostrophe) characters, such as `O'Brian` or `Men's clothes` you must use double quotes around the values. For example:
457
+
458
+
```http
459
+
GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
Otherwise you will get the following error: `Invalid JSON. A comma character ',' was expected in scope 'Array'. Every two elements in an array and properties of an object must be separated by commas.`
466
+
467
+
If the filter is for a single value, replace the single quote character with two consecutive single quote characters. For example:
468
+
469
+
```http
470
+
GET [Organization URI]/api/data/v9.2/contacts?$select=fullname
471
+
&$filter=lastname eq 'O''Bryan'
472
+
```
473
+
474
+
Otherwise you will get an error like the following: `There is an unterminated literal at position 21 in 'lastname eq 'O'Bryan''.`
453
475
454
476
<aname="bkmk_order"></a>
455
477
@@ -458,7 +480,7 @@ Follow the steps in the below example to understand how we can filter results us
458
480
Specify the order in which items are returned using the `$orderby` system query option. Use the `asc` or `desc` suffix to specify ascending or descending order respectively. The default is ascending if the suffix isn’t applied. The following example shows retrieving the name and revenue properties of accounts ordered by ascending revenue and by descending name.
459
481
460
482
```http
461
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name,revenue
483
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
462
484
&$orderby=revenue asc,name desc
463
485
&$filter=revenue ne null
464
486
```
@@ -493,15 +515,15 @@ Additional details on OData data aggregation can be found here: [OData extension
493
515
Without parameter aliases:
494
516
495
517
```http
496
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name,revenue
518
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
497
519
&$orderby=revenue asc,name desc
498
520
&$filter=revenue ne null
499
521
```
500
522
501
523
With parameter aliases:
502
524
503
525
```http
504
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name,revenue
526
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name,revenue
505
527
&$orderby=@p1 asc,@p2 desc
506
528
&$filter=@p1 ne @p3&@p1=revenue&@p2=name
507
529
```
@@ -517,7 +539,7 @@ GET [Organization URI]/api/data/v9.1/accounts?$select=name,revenue
517
539
> [!NOTE]
518
540
> The count value does not represent the total number of rows in the system. It is limited by the maximum number of rows that can be returned. More information: [Limits on number of rows returned](#bkmk_limits)
519
541
>
520
-
> If you want to retrieve the total number of rows for a table beyond 5000, use the <xref:Microsoft.Dynamics.CRM.RetrieveTotalRecordCount?text=RetrieveTotalRecordCount Function />.
542
+
> If you want to retrieve the total number of rows for a table beyond 5000, use the <xref:Microsoft.Dynamics.CRM.RetrieveTotalRecordCount?text=RetrieveTotalRecordCount Function>.
521
543
522
544
The response `@odata.count` property will contain the number of rows that match the filter criteria irrespective of an `odata.maxpagesize` preference limitation.
523
545
@@ -529,7 +551,7 @@ GET [Organization URI]/api/data/v9.1/accounts?$select=name,revenue
529
551
**Request**
530
552
531
553
```http
532
-
GET [Organization URI]/api/data/v9.1/accounts?$select=name
554
+
GET [Organization URI]/api/data/v9.2/accounts?$select=name
0 commit comments