12.1 Example of Named Query

A named query is a special type of service operation for parameterized queries. The main differences between named queries and ordinary service operations are the following:

Named queries may be invoked via the HTTP GET method. In this case, the parameters are passed via the URL instead of being posted.
Named queries may also be invoked via HTTP POST. In this case, the parameters are posted via an Atom Entry (like a normal service operation).
Named queries always return a feed of entries

Here is an example of a named query invocation:

GET /sdata/myApp/myContract/-/products/$queries/reorder?_family=computer&_threshold=20

This request queries the list of “computer” products that need to be reordered because their stock level is below 20. If the operation is successful, the server sends the following response:

200 OK
Content-Type: application/atom+xml; type=feed
 
<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/sdata/myApp/myContract/-/products/$queries/reorder?_family=computer&_minStock=20</id>
  <title type="text">Reorder query</title>
  <updated>2008-03-31T14:52:28Z</updated>

  <link rel="http://schemas.sage.com/sdata/link-relations/schema" 
        type="application/xml" title="Schema" 
        href="http://www.example.com/sdata/myApp/myContract/-/$schema?version=5#productReorder" />
  <link rel="http://schemas.sage.com/sdata/link-relations/queries" 
        type="application/atom+xml; type=feed" title="Queries" 
        href="http://www.example.com/sdata/myApp/myContract/-/products/$queries" />
  <category scheme="http://schemas.sage.com/sdata/categories" 
            term="response" label="Response"/>
  <entry
    <id>http://www.example.com/sdata/myApp/myContract/-/products/$queries/reorder('40127')</id> 
    <title type="text">Reorder 40127</title>
    <updated>2008-03-31T14:52:28Z</updated>
    <sdata:payload>
      <productReorder xmlns="http://schemas.sage.com/myContract">
        <response>
          <productId>40127</productId>
          <description>Red T-Shirt</description>
          <stock>12</stock>
        </response>
      </productReorder >  
    </sdata:payload>
  </entry>

  <entry
    <id>http://www.example.com/sdata/myApp/myContract/-/products/$queries/reorder('40312')</id> 
    <title type="text">Reorder 40312</title>
    <updated>2008-03-31T14:52:28Z</updated>
    <sdata:payload>
      <productReorder xmlns="http://schemas.sage.com/myContract">
        <response>
          <productId>40312</productId>
          <description>Blue shirt</description>
          <stock>8</stock>
        </response>
      </productReorder >  
    </sdata:payload>
  </entry>

</feed>

If the query returns a large collection, the service SHOULD break the result into pages and SHOULD use the usual SData paging mechanisms (link rel=next/prev) to iterate through the pages.

SData providers MAY expose any number of named queries (including none). SData providers that expose named queries MUST use the protocol described in this page and the following ones.