Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 220 lines (152 sloc) 9.12 kb
5cb24aef »
2010-07-07 Added docs
1 Resource Query Language (RQL) is a query language designed for use in URIs with object
2 style data structures. This project includes the RQL specification and
3 provides a JavaScript implementation of query
d339bd97 »
2011-07-26 Make a note about supported module formats
4 parsing and query execution implementation for JavaScript arrays. The JavaScript library
5 supports AMD and NodeJS/CommonJS module format so it can be run in the browser or
6 in the server. RQL can be thought as basically a set of
5cb24aef »
2010-07-07 Added docs
7 nestable named operators which each have a set of arguments. RQL is designed to
8 have an extremely simple, but extensible grammar that can be written in a URL friendly query string. A simple RQL
9 query with a single operator that indicates a search for any resources with a property of
10 "foo" that has value of 3 could be written:
11
12 eq(foo,3)
13
14 RQL is a compatible superset of standard HTML form URL encoding. The following query
15 is identical to the query (it is sugar for the query above):
16
17 foo=3
18
19 Such that this can be used in URIs like:
20
21 http://example.org/data?foo=3
22
c37d09be »
2011-12-28 Updated docs to better organized and reflect latest installation inst…
23 # JavaScript Library
5cb24aef »
2010-07-07 Added docs
24
25 Using the JavaScript library we can construct queries
c37d09be »
2011-12-28 Updated docs to better organized and reflect latest installation inst…
26 using chained operator calls in JavaScript. We could execute the query above like this:
5cb24aef »
2010-07-07 Added docs
27
28 var Query = require("rql/query").Query;
c37d09be »
2011-12-28 Updated docs to better organized and reflect latest installation inst…
29 var fooEq3Query = new Query().eq("foo",3);
cb1bafac »
2010-11-29 Updated docs
30
c37d09be »
2011-12-28 Updated docs to better organized and reflect latest installation inst…
31 # RQL Rules
5cb24aef »
2010-07-07 Added docs
32
33 The RQL grammar is based around standard URI delimiters. The standard rules for
34 encoding strings with URL encoding (%xx) are observed. RQL also supersets FIQL.
35 Therefore we can write a query that finds resources with a "price" property below
36 10 with a "lt" operator using FIQL syntax:
37
38 price=lt=10
39
40 Which is identical (and sugar for call operator syntax known as the normalized form):
41
42 lt(price,10)
43
44 One can combine conditions with multiple operators with "&":
45
46 foo=3&price=lt=10
47
48 Is the same as:
49
50 eq(foo,3)&lt(price,10)
51
52 Which is also the same as:
53
54 and(eq(foo,3),lt(price,10))
55
56 We can execute a query against a JavaScript array:
57
58 require("rql/js-array").executeQuery("foo=3&price=lt=10", {}, data)...
59
60 The | operator can be used to indicate an "or" operation. We can also use paranthesis
61 to group expressions. For example:
62
63 (foo=3|foo=bar)&price=lt=10
64
65 Which is the same as:
66
67 and(or(eq(foo,3),eq(foo,bar)),lt(price,10))
68
69 Values in queries can be strings (using URL encoding), numbers, booleans, null, undefined,
70 and dates (in ISO UTC format without colon encoding). We can also denote arrays
71 with paranthesis enclosed, comma separated values. For example to find the objects
72 where foo can be the number 3, the string bar, the boolean true, or the date for the
73 first day of the century we could write an array with the "in" operator:
74
75 foo=in=(3,bar,true,2000-01-01T00:00:00Z)
76
77 We can also explicitly specify primitive types in queries. To explicitly specify a string "3",
78 we can do:
79
80 foo=string:3
81
cb1bafac »
2010-11-29 Updated docs
82 Any property can be nested by using an array of properties. To search by the bar property of
5cb24aef »
2010-07-07 Added docs
83 the object in the foo property we can do:
84
cb1bafac »
2010-11-29 Updated docs
85 (foo,bar)=3
5cb24aef »
2010-07-07 Added docs
86
cb1bafac »
2010-11-29 Updated docs
87 We can also use slashes as shorthand for arrays, so we could equivalently write the nested
88 query:
89
90 foo/bar=3
91
5cb24aef »
2010-07-07 Added docs
92 Another common operator is sort. We can use the sort operator to sort by a specified property.
93 To sort by foo in ascending order:
94
95 price=lt=10&sort(+foo)
96
97 We can also do multiple property sorts. To sort by price in ascending order and rating in descending order:
98
99 sort(+price,-rating)
100
101 The aggregate function can be used for aggregation. To calculate the sum of sales for
102 each department:
103
104 aggregate(departmentId,sum(sales))
105
106 Here is a definition of the common operators (individual stores may have support
107 for more less operators):
108
109 * sort(<+|-><property) - Sorts by the given property in order specified by the prefix (+ for ascending, - for descending)
110 * select(<property>,<property>,...) - Trims each object down to the set of properties defined in the arguments
111 * values(<property>) - Returns an array of the given property value for each object
112 * aggregate(<property|function>,...) - Aggregates the array, grouping by objects that are distinct for the provided properties, and then reduces the remaining other property values using the provided functions
113 * distinct() - Returns a result set with duplicates removed
114 * in(<property>,<array-of-values>) - Filters for objects where the specified property's value is in the provided array
dffb85e7 »
2010-11-30 Eliminate not() in lieu of excludes() and out()
115 * out(<property>,<array-of-values>) - Filters for objects where the specified property's value is not in the provided array
116 * contains(<property>,<value | expression>) - Filters for objects where the specified property's value is an array and the array contains any value that equals the provided value or satisfies the provided expression.
117 * excludes(<property>,<value | expression>) - Filters for objects where the specified property's value is an array and the array does not contain any of value that equals the provided value or satisfies the provided expression.
5cb24aef »
2010-07-07 Added docs
118 * limit(count,start,maxCount) - Returns the given range of objects from the result set
119 * and(<query>,<query>,...) - Applies all the given queries
120 * or(<query>,<query>,...) - The union of the given queries
121 * eq(<property>,<value>) - Filters for objects where the specified property's value is equal to the provided value
122 * lt(<property>,<value>) - Filters for objects where the specified property's value is less than the provided value
123 * le(<property>,<value>) - Filters for objects where the specified property's value is less than or equal to the provided value
124 * gt(<property>,<value>) - Filters for objects where the specified property's value is greater than the provided value
125 * ge(<property>,<value>) - Filters for objects where the specified property's value is greater than or equal to the provided value
126 * ne(<property>,<value>) - Filters for objects where the specified property's value is not equal to the provided value
ba5f2008 »
2010-09-28 Switch from contains() to any() and all().
127 * rel(<relation name?>,<query>) - Applies the provided query against the linked data of the provided relation name.
5cb24aef »
2010-07-07 Added docs
128 * 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
129 * 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
130 * 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
131 * 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
132 * recurse(<property?>) - Recursively searches, looking in children of the object as objects in arrays in the given property value
133 * first() - Returns the first record of the query's result set
134 * one() - Returns the first and only record of the query's result set, or produces an error if the query's result set has more or less than one record in it.
135 * count() - Returns the count of the number of records in the query's result set
136
c37d09be »
2011-12-28 Updated docs to better organized and reflect latest installation inst…
137 # JavaScript Modules
138
139 ## rql/query
140
141 var newQuery = require("rql/query").Query();
142
143 This module allows us to construct queries. With the query object, we could execute
144 RQL operators as methods against the query object. For example:
145
146 var Query = require("rql/query").Query;
147 var fooBetween3And10Query = new Query().lt("foo",3).gt("foo",10);
148
149 ## rql/parser
150
151 var parsedQueryObject = require("rql/parser").parseQuery(rqlString);
152
5cb24aef »
2010-07-07 Added docs
153 If you are writing an implementation of RQL for a database or other storage endpoint, or want to introspect queries, you can use the parsed query data
5acbf466 »
2010-10-28 Upgrade to latest AMD API, and tolerate missing options on js-array q…
154 structures. You can parse string queries with parser module's parseQuery function.
5cb24aef »
2010-07-07 Added docs
155 Query objects have a "name" property and an "args" with an array of the arguments.
156 For example:
157
158 require("rql/parser").parseQuery("(foo=3|foo=bar)&price=lt=10") ->
159 {
160 name: "and",
161 args: [
162 {
163 name:"or",
164 args:[
165 {
166 name:"eq",
167 args:["foo",3]
168 },
169 {
170 name:"eq",
171 args:["foo","bar"]
172 }
173 ]
174 },
175 {
176 name:"lt",
177 args:["price",10]
178 }
179 ]
180 }
181
ec9c8530 »
2010-11-26 Add installation instructions
182 Installation
183 ========
184
c37d09be »
2011-12-28 Updated docs to better organized and reflect latest installation inst…
185 RQL can be installed using any standard package manager, for example with NPM:
186
187 npm install rql
ec9c8530 »
2010-11-26 Add installation instructions
188
c37d09be »
2011-12-28 Updated docs to better organized and reflect latest installation inst…
189 or CPM:
ec9c8530 »
2010-11-26 Add installation instructions
190
c37d09be »
2011-12-28 Updated docs to better organized and reflect latest installation inst…
191 cpm install rql
192
193 or RingoJS:
194
195 ringo-admin install persvr/rql
5acbf466 »
2010-10-28 Upgrade to latest AMD API, and tolerate missing options on js-array q…
196
197
5cb24aef »
2010-07-07 Added docs
198 Licensing
199 --------
200
201 The RQL implementation is part of the Persevere project, and therefore is licensed under the
202 AFL or BSD license. The Persevere project is administered under the Dojo foundation,
203 and all contributions require a Dojo CLA.
204
205 Project Links
206 ------------
207
208 See the main Persevere project for more information:
209
210 ### Homepage:
211
212 * [http://persvr.org/](http://persvr.org/)
213
214 ### Mailing list:
215
c37d09be »
2011-12-28 Updated docs to better organized and reflect latest installation inst…
216 * [http://groups.google.com/group/json-query](http://groups.google.com/group/json-query)
5cb24aef »
2010-07-07 Added docs
217
218 ### IRC:
219
220 * [\#persevere on irc.freenode.net](http://webchat.freenode.net/?channels=persevere)
Something went wrong with that request. Please try again.