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.