diff --git a/content/en/docs/refguide/modeling/integration/published-odata-services/odata-query-options.md b/content/en/docs/refguide/modeling/integration/published-odata-services/odata-operations.md similarity index 87% rename from content/en/docs/refguide/modeling/integration/published-odata-services/odata-query-options.md rename to content/en/docs/refguide/modeling/integration/published-odata-services/odata-operations.md index 09059e7b144..1bf3b680532 100644 --- a/content/en/docs/refguide/modeling/integration/published-odata-services/odata-query-options.md +++ b/content/en/docs/refguide/modeling/integration/published-odata-services/odata-operations.md @@ -1,28 +1,28 @@ --- -title: "OData Query Options" -url: /refguide/odata-query-options/ +title: "OData Operations" +url: /refguide/odata-operations/ tags: ["OData", "filter", "count", "sort", "select", "page", "studio pro"] --- -## 1 Introduction +## 1 Reading objects -This is a list of query options for OData. +### 1.1 Retrieving Objects + +This section contains of available query options for OData. {{% alert color="info" %}} We currently only support the options described here. {{% /alert %}} -## 2 Retrieving Objects - -### 2.1 Retrieving All Objects +#### 1.1.1 Retrieving All Objects All objects can be retrieved by specifying the URI. For example: `/odata/myservice/v1/Employees`. You can see this if you specify the URI in a browser. -### 2.2 Retrieving a Single Object +#### 1.1.2 Retrieving a Single Object A single object can be retrieved by passing the object identifier in the URI. For example: `/odata/myservice/v1/Employees(8444249301330581)`. -### 2.3 Retrieving Associated Objects +#### 1.1.3 Retrieving Associated Objects For this example, imagine that you have four entities in your domain model: **Employee**, **Car**, **Address**, and **City**. They include the following: @@ -32,23 +32,23 @@ For this example, imagine that you have four entities in your domain model: **Em Associated objects can be retrieved by passing the `$expand` query parameter. For example: `/odata/myservice/v1/Employees?$expand=Cars,Address($expand=City)` (OData 4) or `/odata/myservice/v1/Employees?$expand=Cars,Address/City` (OData 3). -## 3 Counting the Number of Objects +### 1.2 Counting the Number of Objects -### 3.1 Retrieving a Count of Objects +#### 1.2.1 Retrieving a Count of Objects You can find out how many objects there are by passing the `$count` query option. In this case, the result is an integer which is the number of objects. For example: `/odata/myservice/v1/Employees/$count`. -### 3.2 (Inline) Count +#### 1.2.2 (Inline) Count For OData 4, by setting the `$count` query option to `true`, a count of the number of items returned will be included in the result. For example: `?$count=true`. For OData 3, by setting the `$inlinecount` query option to `allpages`, a count of the number of items returned will be included in the result. For example: `?$inlinecount=allpages`. -## 4 Filtering +### 1.3 Filtering Filters are applied by appending a `$filter=...` parameter to the request. For example: `/Employees?$filter=Name eq 'John'`. -### 4.1 Passing attributes +#### 1.3.1 Passing attributes This table describes how to pass values for different attribute types: @@ -59,7 +59,7 @@ This table describes how to pass values for different attribute types: | Datetime | For OData 4: a plain value (for example, `2021-12-31`). For OData 3: Preceded with `datetime` and enclosed in single quotes (for example, `datetime'2021-12-31'` or `datetime''`) | | Other | Plain value (for example, 15) | -### 4.2 Comparison Operators +#### 1.3.2 Comparison Operators We support the following comparison operators: @@ -72,7 +72,7 @@ We support the following comparison operators: | ge | greater than or equal to | `/Employees?$filter=Age ge 15` | | le | less than or equal to | `/Employees?$filter=Age le 15` | -### 4.3 Arithmetic Operators +#### 1.3.3 Arithmetic Operators | Operator | Meaning | Example | Returns | | --- | --- | --- | --- | @@ -82,7 +82,7 @@ We support the following comparison operators: | div | divided by |`/Products?$filter=Prices div 2 eq 10` | All products with price 20 | | mod | modulus |`/Products?$filter=Prices mod 5 eq 0` | All products with price divisible by 5 | -### 4.4 Functions +#### 1.3.4 Functions | Function | Example | Returns | | --- | --- | --- | @@ -99,7 +99,7 @@ We support the following comparison operators: 1 In OData 3, the `contains` function is called `substringof`, and its arguments are reversed For example, `/Employees?$filter=substringof('f', Name)` -### 4.5 Combining Filters +#### 1.3.5 Combining Filters Filters can be combined with `and`, `or`, `not`, and `()`. For example: `?$filter=Name eq 'John' and (Age gt 65 or Age lt 11)`. @@ -110,7 +110,7 @@ Filters can be combined with `and`, `or`, `not`, and `()`. For example: `?$filte | not | `/Employees?$filter=not(Name eq 'John')` | | ( ) | `/Employees?$filter=Name eq 'John' and (Age gt 65 or Age lt 11)` | -### 4.6 Filtering by Association +#### 1.3.6 Filtering by Association You can filter on attributes of an associated entity. The way you do this depends on whether the association exposes one object or a list of objects. @@ -121,7 +121,7 @@ You can filter on attributes of an associated entity. The way you do this depend Filtering on an associated object or list in this way is possible when you [expose associations as a link](/refguide/odata-representation/#associations). It is not possible when you [expose associations as an associated object ID](/refguide/odata-representation/#associations). -## 5 Sorting +### 1.4 Sorting You can sort the result using the `$orderby` query option. For example: `?$orderby=Name` or `?$orderby=BirthPlace/CityName`. @@ -131,21 +131,21 @@ You can also order the result in a descending direction. For example: `?$orderby It is possible to sort on multiple attributes, which have to be comma-separated. For example: `?$orderby=Name asc,Age desc`. -## 6 Selecting fields +### 1.5 Selecting fields You can select which attributes and associations to return by specifying the `$select` query option. For example: `?$select=Name,Age`. -## 7 Paging {#paging} +### 1.6 Paging {#paging} -### 7.1 Top (Limit) +#### 1.6.1 Top (Limit) You can limit the number of returned objects using the `$top` query option, where the limit is a positive integer. For example: `?$top=100`. -### 7.2 Skip (Offset) +#### 1.6.2 Skip (Offset) You can skip a number of objects before retrieving the result using the `$skip` query option, where the offset is a positive integer. For example: `?$skip=100` will return objects starting with the 101st object in the list. -## 8 Null Literals +### 1.7 Null Literals You can compare values against the `null` literal. For example: `?$filter=Name eq null`. @@ -153,7 +153,7 @@ In this example, `Name` is a string attribute that can have no assigned value in When you filter against associations, null literals can be quite useful. For example: `?$filter=Association_A_B ne null`. In this example, you query for objects of entity type `A` that have at least one association set to objects of entity type `B`. -## 9 Passing Query Options in the Request Body +### 1.8 Passing Query Options in the Request Body If the OData query is too long to be sent as a `GET` request, clients can send the query as a `POST` request to the `/$query` endpoint. For example, `GET /Products?$select=Name,Price` and `POST /Products/$query` with `$select=Name,Price` in the request body give the same result. These `POST` requests must specify the header `Content-Type: text/plain`. @@ -161,7 +161,9 @@ If the OData query is too long to be sent as a `GET` request, clients can send t The body must adhere to *URL encoding* principles. So, for instance, spaces, tabs, and newlines are not allowed. {{% /alert %}} -## 10 Updating Objects {#updating-objects} +## 2 Updating Objects {#updating-objects} + +### 2.1 Updating attributes When a published resource has the [Updatable](/refguide/published-odata-resource/#capabilities) capability, clients can update its attributes and associations by sending a `PATCH` request to the URL of the object (for example, `PATCH /odata/myservice/v1/Employees(8444249301330581)`). @@ -175,6 +177,23 @@ Specify new values for attributes in the body of the request. Here is an example } ``` +### 2.1.1 Updating enumerations + +Attributes of an enumeration type can be updated by specifying the exposed value of the enumeration, without the prefix of the enumeration type, in the body of the `PATCH` request. +For an attribute of type `Country` with values `MyModule.Country.FR`, `MyModule.Country.BR` and `MyModule.Country.JP`, exposed as `France`, `Brazil`, and `Japan` respectively, you can update your object as follows: + +```json +{ + "Country": "Brazil" +} +``` + +{{% alert color="info" %}} +Specifying the enumeration member by its numeric value is not supported. +{{% /alert %}} + +### 2.2 Updating asociations + When the association refers to a single object, use the `@id` syntax to set an associated object, or use `null` to empty the associated object. Here is an example: ```json @@ -208,7 +227,7 @@ Clients can only update an association from the entity that is the [owner](/refg The *updating attributes* functionality was introduced in Studio Pro [9.6.0](/releasenotes/studio-pro/9.6/). The *updating associations* functionality was introduced in Studio Pro [9.8.0](/releasenotes/studio-pro/9.8/). {{% /alert %}} -## 10 Inserting Objects {#inserting-objects} +## 3 Inserting Objects {#inserting-objects} When a published resource has the [Insertable](/refguide/published-odata-resource/#capabilities) capability, clients can create new objects by sending a `POST` request to the URL of the entity set (for example, `POST /odata/myservice/v1/Employees`). @@ -229,7 +248,7 @@ Clients can only set values for an association from the entity that is the [owne The *inserting objects* functionality was introduced in Studio Pro [9.12.0](/releasenotes/studio-pro/9.12/). {{% /alert %}} -## 11 Deleting Objects {#deleting-objects} +## 4 Deleting Objects {#deleting-objects} When a published resource has the [Deletable](/refguide/published-odata-resource/#capabilities) capability, clients can delete an object by sending a `DELETE` request to the URL of the object (for example, `PATCH /odata/myservice/v1/Employees(8444249301330581)`).