= RSQL / FIQL parser
Jakub Jirutka https://github.com/jirutka[@jirutka]
:name: rsql-parser
:version: 2.1.0
:mvn-group: cz.jirutka.rsql
:gh-name: jirutka/{name}
:gh-branch: master
:src-base: link:src/main/java/cz/jirutka/rsql/parser
ifdef::env-github[]
image:https://travis-ci.org/{gh-name}.svg?branch={gh-branch}["Build Status", link="https://travis-ci.org/{gh-name}"]
image:https://coveralls.io/repos/{gh-name}/badge.svg?branch={gh-branch}&service=github["Coverage Status", link="https://coveralls.io/github/{gh-name}?branch={gh-branch}"]
image:https://api.codacy.com/project/badge/grade/bd2168ab0e424e028ad6df8ff886d81a["Codacy code quality", link="https://www.codacy.com/app/{gh-name}"]
image:https://maven-badges.herokuapp.com/maven-central/{mvn-group}/{name}/badge.svg["Maven Central", link="https://maven-badges.herokuapp.com/maven-central/{mvn-group}/{name}"]
endif::env-github[]
RSQL is a query language for parametrized filtering of entries in RESTful APIs.
It’s based on http://tools.ietf.org/html/draft-nottingham-atompub-fiql-00[FIQL] (Feed Item Query Language) – an URI-friendly syntax for expressing filters across the entries in an Atom Feed.
FIQL is great for use in URI; there are no unsafe characters, so URL encoding is not required.
On the other side, FIQL’s syntax is not very intuitive and URL encoding isn’t always that big deal, so RSQL also provides a friendlier syntax for logical operators and some of the comparison operators.
For example, you can query your resource like this: /movies?query=name=="Kill Bill";year=gt=2003 or /movies?query=director.lastName==Nolan and year>=2000.
See <<Examples, examples>> below.
This is a complete and thoroughly tested parser for RSQL written in http://javacc.java.net[JavaCC] and Java.
Since RSQL is a superset of the FIQL, it can be used for parsing FIQL as well.
== Related libraries
RSQL-parser can be used with:
- https://github.com/tennaito/rsql-jpa[rsql-jpa] to convert RSQL into JPA2 CriteriaQuery,
- https://github.com/RutledgePaulV/rsql-mongodb[rsql-mongodb] to convert RSQL into MongoDB query using Spring Data MongoDB,
- https://github.com/RutledgePaulV/q-builders[q-builders] to build (not only) RSQL query in type-safe manner,
- your own library…
It’s very easy to write a converter for RSQL using its AST.
Take a look at very simple and naive converter to JPA2 in less than 100 lines of code https://gist.github.com/jirutka/42a0f9bfea280b3c5dca[here].
You may also read a http://www.baeldung.com/rest-api-search-language-rsql-fiql[blog article about RSQL] by https://github.com/eugenp[Eugen Paraschiv].
== Grammar and semantic
The following grammar specification is written in EBNF notation (http://www.cl.cam.ac.uk/~mgk25/iso-14977.pdf[ISO 14977]).
RSQL expression is composed of one or more comparisons, related to each other with logical operators:
- Logical AND :
;orand - Logical OR :
,oror
By default, the AND operator takes precedence (i.e. it’s evaluated before any OR operators are).
However, a parenthesized expression can be used to change the precedence, yielding whatever the contained expression yields.
input = or, EOF;
or = and, { "," , and };
and = constraint, { ";" , constraint };
constraint = ( group, comparison );
group = "(", or, ")";
Comparison is composed of a selector, an operator and an argument.
comparison = selector, comparison-op, arguments;
Selector identifies a field (or attribute, element, …) of the resource representation to filter by.
It can be any non empty Unicode string that doesn’t contain reserved characters (see below) or a white space.
The specific syntax of the selector is not enforced by this parser.
selector = unreserved-str;
Comparison operators are in FIQL notation and some of them has an alternative syntax as well:
- Equal to :
== - Not equal to :
!= - Less than :
=lt=or< - Less than or equal to :
=le=or<= - Greater than operator :
=gt=or> - Greater than or equal to :
=ge=or>= - In :
=in= - Not in :
=out=
You can also simply extend this parser with your own operators (see the <<How to add custom operators, next section>>).
comparison-op = comp-fiql, comp-alt;
comp-fiql = ( ( "=", { ALPHA } ), "!" ), "=";
comp-alt = ( ">", "<" ), [ "=" ];
Argument can be a single value, or multiple values in parenthesis separated by comma.
Value that doesn’t contain any reserved character or a white space can be unquoted, other arguments must be enclosed in single or double quotes.
arguments = ( "(", value, { "," , value }, ")" ), value;
value = unreserved-str, double-quoted, single-quoted;
unreserved-str = unreserved, { unreserved }
single-quoted = "'", { ( escaped, all-chars - ( "'", "" ) ) }, "'";
double-quoted = '"', { ( escaped, all-chars - ( '"', "" ) ) }, '"';
reserved = '"', "'", "(", ")", ";", ",", "=", "!", "~", "<", ">";
unreserved = all-chars - reserved - " ";
escaped = "", all-chars;
all-chars = ? all unicode characters ?;
If you need to use both single and double quotes inside a quoted argument, then you must escape one of them using \ (backslash).
If you want to use \ literally, then double it as \\.
Backslash has a special meaning only inside a quoted argument, not in unquoted argument.
== Examples
Examples of RSQL expressions in both FIQL-like and alternative notation:
- name=="Kill Bill";year=gt=2003
- name=="Kill Bill" and year>2003
- genres=in=(sci-fi,action);(director=='Christopher Nolan',actor==*Bale);year=ge=2000
- genres=in=(sci-fi,action) and (director=='Christopher Nolan' or actor==*Bale) and year>=2000
- director.lastName==Nolan;year=ge=2000;year=lt=2010
- director.lastName==Nolan and year>=2000 and year<2010
- genres=in=(sci-fi,action);genres=out=(romance,animated,horror),director==Que*Tarantino
- genres=in=(sci-fi,action) and genres=out=(romance,animated,horror) or director==Que*Tarantino
== How to use
Nodes are http://en.wikipedia.org/wiki/Visitor_pattern[visitable], so to traverse the parsed AST (and convert it to SQL query maybe), you can implement the provided {src-base}/ast/RSQLVisitor.java[RSQLVisitor] interface or simplified {src-base}/ast/NoArgRSQLVisitorAdapter.java[NoArgRSQLVisitorAdapter].
[source, java]
Node rootNode = new RSQLParser().parse("name==RSQL;version=ge=2.0");
rootNode.accept(yourShinyVisitor);
== How to add custom operators
Need more operators?
The parser can be simply enhanced by custom FIQL-like comparison operators, so you can add your own.
[source, java]
Set operators = RSQLOperators.defaultOperators();
operators.add(new ComparisonOperator("=all=", true));
Node rootNode = new RSQLParser(operators).parse("genres=all=('thriller','sci-fi')");
== Maven
Released versions are available in The Central Repository.
Just add this artifact to your project:
[source, xml, subs="verbatim, attributes"]
However if you want to use the last snapshot version, you have to add the JFrog OSS repository:
[source, xml]
== License
This project is licensed under http://opensource.org/licenses/MIT[MIT license].