This wiki is locked. Future workgroup activity and specification development must take place at
our new wiki
. For more information, see
this blog post about the new governance model
and
this post about changes to the website
.
TWiki
>
Main Web
>
AssetHome
>
AssetMgSpecificationV1
>
AssetMgQuerySyntaxV1
(21 Apr 2010,
TWikiAdminUser
)
(raw view)
---+ Asset Management Query Syntax ---++ 1.0 Specification ---++ <a name="Contents"></a> Contents * [[#Introduction][ Introduction]] * [[#Notation_and_Conventions][ Notation and Conventions]] * [[#Query_Syntax][ Query Syntax]] * [[#Returning_Properties][ Returning Properties]] * [[#Using_Namespaces][ Using Namespaces]] * [[#Selecting_properties_and_inlinin][ Selecting properties and inlining]] * [[#Encoding_Example][ Encoding Example]] * [[#References][ References]] ---++ <a name="Introduction"></a> Introduction Asset management scenarios have outlined a need for a simple query mechanism. This is provided by supplying the query terms that can be URL-encoded and performed by using a HTTP GET. The query syntax described here is based loosely on the <a target="_top" href="http://www.loc.gov/standards/sru/specs/cql.html">Library of Congress Contextual Query Language (CQL)</a> but where CQL is for describing structured text searches the language here is intended for more precise queries. So, whereas CQL allows search terms that are not evaluated in the context of a property the language here always scopes a term to a particular property ( _property op value_). Also, while CQL does support a sort modifier we also introduce a limit modifier to return only a subset of possible results. ---++ <a name="Notation_and_Conventions"></a> Notation and Conventions The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in <a target="_top" href="http://www.ietf.org/rfc/rfc2119.txt">RFC2119</a>. Domain name examples use <a target="_top" href="http://tools.ietf.org/html/rfc2606">RFC2606</a>. ---++ <a name="Query_Syntax"></a> Query Syntax The following sections describe the basic query syntax. *Comparison Operators* * *=* test for equality of a term, * *!=* test for inequality of a term, * *<* test less-than, * *>* test greater-than, * *<=* test less-than or equal, * *>=* test greater-than or equal, * *in* test for equality of any of the terms. *Boolean Operators* * *and*; conjunction *Query Modifiers* * */sort*; set the sort order for returned items *Full text Search* * *oslc_asset:searchTerms*; a list of terms to apply to a <a target="_top" href="http://en.wikipedia.org/wiki/Full_text_search">full text search</a> processor *BNF* <verbatim> query ::= (term (boolean_op term)*)+ modifiers term ::= (identifier operator)? value+ | (identifier "in")? in_val | fulltext operator ::= "=" | "!=" | "<" | ">" | "<=" | ">=" boolean_op ::= "and" modifiers ::= sort? sort ::= "/sort" "=" identifier fulltext ::= "oslc_asset:searchTerms" "=" '"' value+ '"' identifier ::= word (":" word)? in_val ::= "[" value ("," value)* "]" value ::= (integer | string) word ::= /any sequence of letters and numbers, starting with a letter/ string ::= '"' + /any sequence of characters/ + '"' integer ::= /any sequence of integers/ </verbatim> *Notes* 1 a word consists of any character with the Unicode class Alpha (alpha-numeric) as well as the characters ".", "-" and "_". 1 a string may include the quote character if preceded by the escape character "\", as in "my \"quoted\" example". ---+++ <a name="Returning_Properties"></a> Returning Properties A query should not only declare a set of query terms but can also specify a list of properties that should be returned (if present) for any resource that matches the specified terms. This is not a component of the query syntax itself but split into a separate URI query parameter, with semantics of [[CmRestApiV1#Selective_properties][ oslc_asset.properties ]]. The query parameter takes a comma separated list of identifiers, which are of course, to be URL encoded. For example, to return the creator and created time for any matching resource the following can be added to the URL: <pre>&oslc_asset.properties=dc:creator,dc:created &oslc_asset.properties=dc%3Acreator%2Cdc%3Acreated </pre> ---+++ <a name="Using_Namespaces"></a> Using Namespaces In the query part and the properties part of the URL we use qualified names to refer to identifiers, the prefix is intended to reflect a particular namespace where some of these prefixes are pre-defined by an application and some may be user-defined. For example an application may publish the fact that it recognizes the prefix dc: and maps it to the Dublin Core Metadata Terms namespace (<a target="_top" href="http://purl.org/dc/terms/">http://purl.org/dc/terms/</a>). These pre-defined namespaces should be published by the application as a part of it's specification. Clients and service providers MUST support the predefined set of namespace prefixed defined in the [[AssetMgRestApiV1][Asset Management REST API specification]. ---+++ <a name="Selecting_properties_and_inlinin"></a> Selecting properties and inlining Query for resources whose state property is equal to "states/approved" and only return the properties of title and full owners details. <pre>?oslc_asset.query=state="states/approved"&oslc_asset.properties="dc:title,dc:owner{*}" </pre> ---+++ <a name="sorting"></a> Sorting Append /sort=proertyName to sort the results in ascending order by the given property name and /sort=-propertyName to sort the results in descending order. <pre>?oslc_asset.query=dc:type="Web Service"/sort=-dc:modified</pre> ---+++ <a name="Encoding_Example"></a> Encoding Example Not encoded: <pre>?oslc_asset.query=dc:title="Employee Services Application" and dc:modified>="08-02-2009T18:42:30"</pre>Encoded: <br /><pre>?oslc_asset.query=dc%3Atitle%3D%22Employee%20Services%20Application%22%20and%20dc%3Amodified%3E%3D%2208-02-2009T18 %3A42%3A30%22%20</pre> ---++ <a name="References"></a> References * <a target="_top" href="http://www.loc.gov/standards/sru/specs/cql.html">Library of Congress Contextual Query Language (CQL)</a> * <a target="_top" href="http://www.w3.org/TR/rdf-sparql-query/">SPARQL Query Language for RDF</a>
E
dit
|
A
ttach
|
P
rint version
|
H
istory
: r10
<
r9
<
r8
<
r7
<
r6
|
B
acklinks
|
V
iew topic
|
Ra
w
edit
|
M
ore topic actions
Topic revision: r10 - 21 Apr 2010 - 17:46:38 -
TWikiAdminUser
Main
Main Web
Create New Topic
Index
Search
Changes
Notifications
RSS Feed
Statistics
Preferences
Webs
Main
Sandbox
TWiki
Български
Cesky
Dansk
Deutsch
English
Español
Français
Italiano
日本語
Nederlands
Polski
Português
Русский
Svenska
简体中文
簡體中文
Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our
Terms of Use
Ideas, requests, problems regarding this site?
Send feedback