Previous Page Arrow Next Page Arrow

12.3 Named Query Metadata

In the schema, named queries follow the same pattern as service operations.

The metadata for a named query can be obtained by appending a $schema segment to the query’s URL. For example:

http://www.example.com/sdata/myApp/myContract/-/products/$queries/reorder/$schema

This URL works like the other SData schema URLs. It SHOULD redirect to an element that is defined in a global schema. The response to a GET on the above URL would typically be:

 HTTP 302 Found   
Location: http://www.example.com/sdata/myApp/myContract/-/$schema#productReorder
The query name has been prefixed by product to avoid a potential name clash with the same query name in a different URL branch.

The global schema would contain the following element definition:

  <xs:element name="productReorder" 
              type="tns:productReorder--type"
              sme:role="query"
              sme:path="products/$queries/reorder"
              sme:canGet="true"
              sme:invocationMode="sync"/>
  <xs:complexType name="productReorder--type">
    <xs:all>
      <xs:element name="request" type="tns:reorderRequest--type" minOccurs="0" />
      <xs:element name="response" type="tns:reorderResponse--type" minOccurs="0" />
    </xs:all>
  </xs:complexType>
 
  <xs:complexType name="reorderRequest--type">
    <xs:all>
      <xs:element name="family" type="xs:string" sme:label="Product family" />
      <xs:element name="threshold" type="xs:decimal" sme:label="Stock threshold" />
    </xs:all>
  </xs:complexType>
 
  <xs:complexType name="reorderResponse--type">
    <xs:all>
      <xs:element name="productId" type="xs:string" sme:label="Product ID" sme:canSort="true" sme:canFilter="true" />
      <xs:element name="description" type="xs:string" sme:label="Product description" sme:canFilter="true" />
      <xs:element name="stock" type="xs:decimal" sme:label="Stock count" sme:canSort="true" sme:canFilter="true" />
    </xs:all>
  </xs:complexType>

 This schema fragment follows the same pattern as a service operation schema fragment. The SME extensions used to encode named query options are now described:

Attribute Values Applies to Description
role query query element Differentiates this element from "resource kind" and service operation elements.
path relative URL query element Relative URL to execute the query.
invocationMode sync async syncOrAsync query element Indicates whether the querycan be started synchronously, asynchronously or in both modes.
canGet true false (default) query element Can the query be invoked via a GET request?
canPost true false (default) query element Can the query be invoked via a POST request?
unsupported true false (default) query element Is the operation part of a global contract that it is not supported by this specific provider?
hasTemplate true false (default) query element Does the service provide a $template URL for this operation? See Operation Template section for details.
This schema fragment is the equivalent of web service definition language (WSDL) in the SData world.

At least one of the canGet and canPost attributes MUST be set to true.

If the query is invoked through GET, the input parameters are passed by means of URL query parameters (_family and _threshold in the previous example). The names of the parameters are obtained by prefixing the element names for the schema’s request type by an underscore.

If the query is invoked though POST, the input parameters are encapsulated into an Atom <entry> element. The request is then similar to a service operation request (see the section on synchronous service calls), the only difference being that the response is an Atom <feed> rather than an Atom <entry>.

If the invocationMode allows asynchronous invocation, the query MAY be executed asynchonously. This imposes the POST method and it requires that a trackingId parameter be added to the URL. The protocol is similar to the one used for asynchronous service calls (see asynchronous service calls section for details).

SData providers MUST describe their named queries in the schema, in the format specified above.

Previous Page Arrow Next Page Arrow