6.5 Query Payload Control

SData provides three parameters to control the payload attached to every Atom entry: precedence, include and select.

precedence parameter

The first one, precedence, is very simple. It takes a numeric value and controls whether properties should be included in the payload or not, based on the precedence values set in the schema. If this parameter is set to 0, the payload MUST be omitted. This feature is useful when the consumer only needs basic information for each entry. For example, to fill a combo box. It saves processing on the provider side and bandwidth.

Here is a typical example:

GET /sdata/myApp/myContract/-/customers?precedence=2

This SData query returns atom entries for the customers, but it limits the payload to properties that have a precedence of 1 or 2 in schema. With this query, the consumer gets basic customer data such as customer code and customer name, assuming those properties have precedence 1 or 2. But not the administrative and financial details, assuming those have precedence 3 or above, or no precedence set.

include parameter

The second parameter, include, allows an SData consumer to request the payload includes related resources. Without this parameter, an SData query on a resource kind only returns the payload for the requested resource kind. It does not include the payload for related resources. The effect of this parameter is described in the Resource Linking and Embedding section.

For example, if sales orders and sales order line are exposed as two separate resource kinds, a query on sales orders will only return the sales order heading and a <link> to the lines. It will not return other lines in the XML payload. To get a payload with both heading and order lines, a consumer should use a request such as:

GET /sdata/myApp/myContract/-/salesOrders?include=orderLines

This request returns payload entries:

<salesOrder 
  sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43660')" 
  sdata:key="43660"
  sdata:uuid="44D446D4-5700-41cc-92FB-3BA0FF6017CC"
  xmlns="http://schemas.sage.com/myContract">
  <orderNumber>43660</orderNumber>
  <orderDate>2001-07-01</orderDate>
  <shipDate xsi:nil="true" />
  <contact 
    sdata:url="http://www.example.com/sdata/myApp/myContract/-/contacts('216')" 
    sdata:key="216" 
    sdata:uuid="4AB7DA77-C841-4bef-955A-08D661D86430"
    sdata:lookup="http://www.example.com/sdata/myApp/myContract/-/contacts" />
  <subTotal>7326.5034</subTotal>
  <orderLines 
    sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines?where=salesOrderID%20eq%2043660" >
    <salesOrderLine
      sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-1')"
      sdata:key="43660-1"
      sdata:uuid="36B2ECF4-4309-4e62-9878-28DF60B78CFD" >
      <orderNumber>43660</orderNumber>
      <lineNumber>1</lineNumber>
      <product
        sdata:url="http://www.example.com/sdata/myApp/myContract/-/products('758')" 
        sdata:key="758"
        sdata:uuid="455BCC8A-A261-4cf0-A105-599995160C5A"/>
      <orderQty>1</orderQty>
      <unitPrice>874.7940</unitPrice>
    </salesOrderLine>
    <salesOrderLine
      sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-2')"
      sdata:key="43660-2"
      sdata:uuid="CEFE3F52-5529-46b9-A166-79EDFD2D0595" >
      <orderNumber>43660</orderNumber>
      <lineNumber>2</lineNumber>
      <product
        sdata:url="http://www.example.com/sdata/myApp/myContract/-/products('437')" 
        sdata:key="437"
        sdata:uuid="5C9C54FE-B18C-42a9-A0E9-9FEC4BC05C10"/>
      <orderQty>2</orderQty>
      <unitPrice>820.70</unitPrice>
    </salesOrderLine>
  </orderLines>
</salesOrder>

The include mechanism only includes the requested subresources. It SHOULD NOT recurse to subresources of the subresources. However, this can be achieved by explicitly requesting subresources at a deeper level. For example, if order lines have notes, you can request that the order lines and their notes are included with include=orderLines,orderLines/salesOrderLine/notes.

The special $children value SHOULD be used to indicate that all child subresources should be included in the payload. If we replace include=orderLines by include=$children in the example, we will still get the order lines in the returned payload but we will also get the other child resources. For example the payload will include billing and delivery addresses if the application treats those as child resources (if every sales order has a private copy of these addresses).

When $children is used, the payload recursively includes all child subresources. Normally the datamodel should be such that child subresources are true “components” of the resource; so the returned tree should remain a reasonable size.

The special $descriptors value SHOULD be used to request that the payload include descriptors for the resource and all its related resources. These “descriptors” are human readable strings for the resources. For example, first name + last name for a contact resource. They are carried by additional sdata:descriptor attributes in the payload elements. For example, a consumer can obtain the descriptors with the following request:

GET /sdata/myApp/myContract/-/salesOrders?include=**$descriptors**

This request returns payload entries like:

<salesOrder 
  sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43660')" 
  sdata:key="43660"
  sdata:uuid="44D446D4-5700-41cc-92FB-3BA0FF6017CC"
**  sdata:descriptor="order 43660"
**  xmlns="http://schemas.sage.com/myContract">
  <orderNumber>43660</orderNumber>
  <orderDate>2001-07-01</orderDate>
  <shipDate xsi:nil="true" />
  <contact 
    sdata:url="http://www.example.com/sdata/myApp/myContract/-/contacts('216')" 
    sdata:key="216" 
    sdata:uuid="4AB7DA77-C841-4bef-955A-08D661D86430"
    sdata:lookup="http://www.example.com/sdata/myApp/myContract/-/contacts" 
**    sdata:descriptor="David Dunn"**/>
  <subTotal>7326.5034</subTotal>
</salesOrder>

Descriptors are useful when the result of the request is intended for human consumption rather than programmatic consumption. As there is usually some overhead in generating these descriptors (typically extra joins), SData provides a query parameter (include=$descriptors) to control their presence in the payload. Programmatic consumers should not include this parameter to avoid the eventual overhead.

select parameter

The select parameter gives more control on the depth and breadth of information returned. It allows the consumer to specify the list of properties that he wants in the response, very much like a SQL select clause. For example:

GET /sdata/myApp/myContract/-/salesOrders?select=orderDate,contact/*,orderLines/orderQty,orderLines/product

This request returns:

<salesOrder 
  sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrders('43660')" 
  sdata:key="43660"
  sdata:uuid="44D446D4-5700-41cc-92FB-3BA0FF6017CC"
  xmlns="http://schemas.sage.com/myContract">
  <orderDate>2001-07-01</orderDate>
  <contact 
    sdata:url="http://www.example.com/sdata/myApp/myContract/-/contacts('216')" 
    sdata:key="216" 
    sdata:uuid="4AB7DA77-C841-4bef-955A-08D661D86430"
    sdata:lookup="http://www.example.com/sdata/myApp/myContract/-/contacts">
    <firstName>John</firstName>
    <lastName>Doe</lastName>
    <email>john.doe@acme.com</email>
  </contact>
  <orderLines 
    sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines?where=salesOrderID%20eq%2043660" >
    <salesOrderLine
      sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-1')"
      sdata:key="43660-1"
      sdata:uuid="36B2ECF4-4309-4e62-9878-28DF60B78CFD" >
      <product
        sdata:url="http://www.example.com/sdata/myApp/myContract/-/products('758')" 
        sdata:key="758"
        sdata:uuid="455BCC8A-A261-4cf0-A105-599995160C5A"/>
      <orderQty>1</orderQty>
    </salesOrderLine>
    <salesOrderLine
      sdata:url="http://www.example.com/sdata/myApp/myContract/-/salesOrderLines('43660-2')"
      sdata:key="43660-2"
      sdata:uuid="CEFE3F52-5529-46b9-A166-79EDFD2D0595" >
      <salesOrderID>43660</salesOrderID>
      <product
        sdata:url="http://www.example.com/sdata/myApp/myContract/-/products('437')" 
        sdata:key="437"
        sdata:uuid="5C9C54FE-B18C-42a9-A0E9-9FEC4BC05C10"/>
      <orderQty>2</orderQty>
    </salesOrderLine>
  </orderLines>
</salesOrder>

The product element is included in the response but the product details are not. To include the product details, use orderLines/product/* instead of orderLines/product.

The intermediate salesOrderLine element is omitted in the select path (orderLines/product). The select path is based on the properties that are traversed (orderLines and then product), not on the XML hierarchy (orderLines/salesOrderLine/product).

Conformant SData providers MUST support these three mechanisms, as decribed above.

---