Resource Query Languages (RQL) defines a syntactically simple query language for querying and retrieving resources. RQL is designed to be URI friendly, particularly as a query component of a URI, and highly extensible. RQL is a superset of HTML's URL encoding of form values, and a superset of Feed Item Query Language (FIQL). RQL basically consists of a set of nestable named operators which each have a set of arguments and operate on a collection of resources. An example of an RQL for finding resources with a category of "toy" and sorted by price in ascending order:
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”
This Internet-Draft will expire on January 1, 2011.
Copyright (c) 2010 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
7. Nested Operators
8. Defined Operators
9. Comparison Syntax
10. Typed Values
11. ABNF for RQL
13. IANA Considerations
14.1. Normative References
14.2. Informative References
Appendix A. Change Log
Appendix B. Open Issues
Resource Query Languages (RQL) defines a syntactically simple query language for querying and retrieving resources. RQL is designed to be URI friendly, particularly as a query component of a URI, and highly extensible. RQL is a superset of HTML's URL encoding of form values, and a superset of Feed Item Query Language (FIQL).
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 RFC 2119.
RQL consists of a set of nestable named operators which each have a set of arguments. RQL is designed to be applied to a collection of resources. Each top-level operator defines a constraint or modification to the result of the query from the base collection of resources. Nested operators provide constraint information for the operators within which they are embedded.
An operator consists of an operator name followed by a list of comma-delimited arguments within paranthesis:
Each argument may be a value (a string of unreserved or URL-encoded characters), an array, or another operator. The name of the operator indicates the type of action the operator will perform on the collection, using the given arguments. This document defines the semantics of a set of operators, but the query language can be extended with additional operators.
A simple RQL query with a single operator that indicates a search for any resources with a property of "foo" that has value of 3 could be written:
Simple values are simply URL-encoded sequences of characters. Unreserved characters do not need to be encoded, other characters should be encoding using standard URL encoding. Simple values can be decoded to determine the intended string of characters. Values can also include arrays or typed values. These are described in the "Typed Values" and "Arrays" section below.
One of the allowable arguments for operators is an array. An array is paranthesis-enclosed comma-delimited set of items. Each item in the array can be a value or an operator. A query that finds all the resources where the category can be "toy" or "food" could be written with an array argument:
Operators may be nested. For example, a set of operators can be used as the arguments for the "or" operator. Another query that finds all the resources where the category can be "toy" or "food" could be written with nested "eq" operators within an "or" operator:
RQL defines the following semantics for these operators:
sort(<+|-><property) - Sorts the returned query result by the given property. The order of sort is specified by the prefix (+ for ascending, - for descending) to property. To sort by foo in ascending order:
One can also do multiple property sorts. To sort by price in ascending order and rating in descending order:
select(<property>) - Returns a query result where each item is value of the property specified by the argument
select(<property>,<property>,...) - Trims each object down to the set of properties defined in the arguments
aggregate(<property|operator>,...) - The aggregate function can be used for aggregation, it aggregates the result set, grouping by objects that are distinct for the provided properties, and then reduces the remaining other property values using the provided operator. To calculate the sum of sales for each department:
distinct() - Returns a result set with duplicates removed
in(<property>,<array-of-values>) - Filters for objects where the specified property's value is in the provided array
contains(<property>,<value | array-of-values>) - Filters for objects where the specified property's value is an array and the array contains the provided value or contains a value in the provided array
limit(start,count) - Returns a limited range of records from the result set. The first parameter indicates the starting offset and the second parameter indicates the number of records to return.
and(<query>,<query>,...) - Returns a query result set applying all the given operators to constrain the query
or(<query>,<query>,...) - Returns a union result set of the given operators
eq(<property>,<value>) - Filters for objects where the specified property's value is equal to the provided value
lt(<property>,<value>) - Filters for objects where the specified property's value is less than the provided value
le(<property>,<value>) - Filters for objects where the specified property's value is less than or equal to the provided value
gt(<property>,<value>) - Filters for objects where the specified property's value is greater than the provided value
ge(<property>,<value>) - Filters for objects where the specified property's value is greater than or equal to the provided value
ne(<property>,<value>) - Filters for objects where the specified property's value is not equal to the provided value
sum(<property?>) - Finds the sum of every value in the array or if the property argument is provided, returns the sum of the value of property for every object in the array
mean(<property?>) - Finds the mean of every value in the array or if the property argument is provided, returns the mean of the value of property for every object in the array
max(<property?>) - Finds the maximum of every value in the array or if the property argument is provided, returns the maximum of the value of property for every object in the array
min(<property?>) - Finds the minimum of every value in the array or if the property argument is provided, returns the minimum of the value of property for every object in the array
recurse(<property?>) - Recursively searches, looking in children of the object as objects in arrays in the given property value
RQL provides a semantically equivelant syntactic alternate to operator syntax with comparison syntax. A comparison operator may be written in the form:
As shorthand for:
RQL also supports provides sugar for the "and" operator with ampersand delimited operators. The following form:
As shorthand for:
With these transformations, one can write queries of the form:
This makes the HTML's form url encoding of name value pairs a proper query within RQL.
Ampersand delimited operators may be grouped by placing them within paranthesis. Top level queries themselves are considered to be implicitly a part of an "and" operator group, and therefore the top level ampersand delimited operators do not need to be enclosed with paranthesis, but "and" groups used within other operators do need to be enclosed in paranthesis.
Pipe delimited operators may also be placed within paranthesis-enclosed groups as shorthand for the "or" operator. One can write a query:
Also, Feed Item Query Language is a subset of RQL valid. RQL supports named comparisons as shorthand for operators as well. The following form is a named comparison:
Which is shorthand for:
For example, to find resources with a "price" less than 10:
Basic values in RQL are simply a string of characters and it is up to the recipient of a query to determine how these characters should be interpreted and if they should be coerced to alternate data types understood by the language or database processing the query. However, RQL supports typed values to provide hints to the recipient of the intended data type of the value. The syntax of a typed value is:
RQL suggests the following types to be supported:
string - Indicates the value string should not be coerced, it should remain a string.
number - Indicates the value string should be coerced to a number.
boolean - Indicates the value string should be coerced to a boolean. A value of "true" should indicate true and a value of "false" should indicate false.
epoch - Indicates the value string should be treated as the milliseconds since the epoch and coerced to a date.
For example, to query for resources where foo explicitly equals the number 4:
The following is the collected ABNF for RQL:
query = and and = operator *( "&" operator ) operator = comparison / call-operator / group call-operator = name "(" [ argument *( "," argument ) ] ")" argument = call-operator / value value = *nchar / typed-value / array typed-value = 1*nchar ":" *nchar array = "(" [ value *( "," value ) ] ")" name = *nchar comparison = name ( "=" [ name "=" ] ) value group = "(" ( and / or ) ")" or = operator *( "|" operator ) nchar = unreserved / pct-encoded / "*" / "+" pct-encoded = "%" HEXDIG HEXDIG unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
If RQL is used as for to define queries in HTTP URLs, there are several considerations. First, servers that allow publicly initiated requests should enforce proper security measures to protect against excessive resource consumption. Many operators may be understood by the server, but not efficiently executable and servers can therefore reject such queries. Rejections may be indicated by a 403 Forbidden status code response, or if authentication may provide the authorization necessary to perform the query, a 401 Unauthorized status code can be sent.
If the query is not syntactically valid, (does not follow the RQL grammar), the server may return a status code of 400 Bad Request. If the query is syntactically valid, but the operator name is not known, the server may also return a status code of 400 Bad Request.
The proposed MIME media type for Resource Query Language is application/rql
Type name: application
Subtype name: rql
Required parameters: none
Optional parameters: none
|[RFC2119]||Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).|
|[RFC3986]||Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” STD 66, RFC 3986, January 2005 (TXT, HTML, XML).|
|[W3C.REC-html401-19991224]||Hors, A., Raggett, D., and I. Jacobs, “HTML 4.01 Specification,” World Wide Web Consortium Recommendation REC-html401-19991224, December 1999 (HTML).|
|[I-D.nottingham-atompub-fiql]||Nottingham, M., “FIQL: The Feed Item Query Language,” draft-nottingham-atompub-fiql-00 (work in progress), December 2007 (TXT).|
|Kris Zyp (editor)|
|530 Lytton Avenue|
|Palo Alto, CA 94301|
|Phone:||+1 650 968 8787|