Resource Query Language
draft-zyp-rql-00

Abstract

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:

category=toy&sort(+price)

Status of This Memo

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 Notice

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.

Table of Contents

1.  Introduction
2.  Conventions
3.  Overview
4.  Operators
5.  Values
6.  Arrays
7.  Nested Operators
8.  Defined Operators
    8.1.  sort
    8.2.  select
    8.3.  aggregate
    8.4.  distinct
    8.5.  in
    8.6.  contains
    8.7.  limit
    8.8.  and
    8.9.  or
    8.10.  eq
    8.11.  lt
    8.12.  le
    8.13.  gt
    8.14.  ge
    8.15.  ne
    8.16.  sum
    8.17.  mean
    8.18.  max
    8.19.  min
    8.20.  recurse
9.  Comparison Syntax
10.  Typed Values
11.  ABNF for RQL
12.  HTTP
13.  IANA Considerations
14.  References
    14.1.  Normative References
    14.2.  Informative References
Appendix A.  Change Log
Appendix B.  Open Issues

1.  Introduction

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).

2.  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 RFC 2119.

3.  Overview

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.

4.  Operators

An operator consists of an operator name followed by a list of comma-delimited arguments within paranthesis:

name(args,...)

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:

eq(foo,3)

5.  Values

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.

6.  Arrays

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:

in(category,(toy,food))

7.  Nested Operators

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:

or(eq(category,toy),eq(category,food))

8.  Defined Operators

RQL defines the following semantics for these operators:

8.1.  sort

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:

sort(+foo)

One can also do multiple property sorts. To sort by price in ascending order and rating in descending order:

sort(+price,-rating)

8.2.  select

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

8.3.  aggregate

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:

aggregate(departmentId,sum(sales))

8.4.  distinct

distinct() - Returns a result set with duplicates removed

8.5.  in

in(<property>,<array-of-values>) - Filters for objects where the specified property's value is in the provided array

8.6.  contains

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

8.7.  limit

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.

8.8.  and

and(<query>,<query>,...) - Returns a query result set applying all the given operators to constrain the query

8.9.  or

or(<query>,<query>,...) - Returns a union result set of the given operators

8.10.  eq

eq(<property>,<value>) - Filters for objects where the specified property's value is equal to the provided value

8.11.  lt

lt(<property>,<value>) - Filters for objects where the specified property's value is less than the provided value

8.12.  le

le(<property>,<value>) - Filters for objects where the specified property's value is less than or equal to the provided value

8.13.  gt

gt(<property>,<value>) - Filters for objects where the specified property's value is greater than the provided value

8.14.  ge

ge(<property>,<value>) - Filters for objects where the specified property's value is greater than or equal to the provided value

8.15.  ne

ne(<property>,<value>) - Filters for objects where the specified property's value is not equal to the provided value

8.16.  sum

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

8.17.  mean

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

8.18.  max

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

8.19.  min

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

8.20.  recurse

recurse(<property?>) - Recursively searches, looking in children of the object as objects in arrays in the given property value

9.  Comparison Syntax

RQL provides a semantically equivelant syntactic alternate to operator syntax with comparison syntax. A comparison operator may be written in the form:

name=value

As shorthand for:

eq(name,value)

RQL also supports provides sugar for the "and" operator with ampersand delimited operators. The following form:

operator&operator

As shorthand for:

and(operator,operator)

With these transformations, one can write queries of the form:

foo=3&bar=text

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:

foo=3&(bar=text|bar=string)

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:

name=comparator=value

Which is shorthand for:

comparator(name,value)

For example, to find resources with a "price" less than 10:

price=lt=10

10.  Typed Values

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:

type:value

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:

foo=number:4

11.  ABNF for RQL

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 / "-" / "." / "_" / "~"

12.  HTTP

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.

13.  IANA Considerations

The proposed MIME media type for Resource Query Language is application/rql

Type name: application

Subtype name: rql

Required parameters: none

Optional parameters: none

14.  References

14.1. Normative References

14.2. Informative References

Appendix A.  Change Log

-00

• Initial draft

Appendix B.  Open Issues

Author's Address