{"id":15056561,"url":"https://github.com/jirutka/rsql-parser","last_synced_at":"2025-05-13T22:04:28.255Z","repository":{"id":41156292,"uuid":"2286033","full_name":"jirutka/rsql-parser","owner":"jirutka","description":"Parser for RSQL / FIQL – query language for RESTful APIs","archived":false,"fork":false,"pushed_at":"2025-03-13T21:44:48.000Z","size":146,"stargazers_count":752,"open_issues_count":12,"forks_count":159,"subscribers_count":40,"default_branch":"master","last_synced_at":"2025-04-13T18:44:13.807Z","etag":null,"topics":["fiql","groovy","java","javacc","parser","rest-api","rsql","search"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jirutka.png","metadata":{"files":{"readme":"README.adoc","changelog":"CHANGELOG.adoc","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-08-29T01:02:22.000Z","updated_at":"2025-04-10T12:20:10.000Z","dependencies_parsed_at":"2022-07-14T08:31:24.748Z","dependency_job_id":"a567644e-4f58-4a7c-bff3-811b0248dac7","html_url":"https://github.com/jirutka/rsql-parser","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jirutka%2Frsql-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jirutka%2Frsql-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jirutka%2Frsql-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jirutka%2Frsql-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jirutka","download_url":"https://codeload.github.com/jirutka/rsql-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251338173,"owners_count":21573512,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fiql","groovy","java","javacc","parser","rest-api","rsql","search"],"created_at":"2024-09-24T21:53:16.069Z","updated_at":"2025-04-28T15:28:56.046Z","avatar_url":"https://github.com/jirutka.png","language":"Java","readme":"= RSQL / FIQL parser\nJakub Jirutka \u003chttps://github.com/jirutka[@jirutka]\u003e\n:name: rsql-parser\n:version: 2.1.0\n:mvn-group: cz.jirutka.rsql\n:gh-name: jirutka/{name}\n:gh-branch: master\n:src-base: link:src/main/java/cz/jirutka/rsql/parser\n\nifdef::env-github[]\nimage:https://travis-ci.org/{gh-name}.svg?branch={gh-branch}[\"Build Status\", link=\"https://travis-ci.org/{gh-name}\"]\nimage:https://coveralls.io/repos/{gh-name}/badge.svg?branch={gh-branch}\u0026service=github[\"Coverage Status\", link=\"https://coveralls.io/github/{gh-name}?branch={gh-branch}\"]\nimage:https://api.codacy.com/project/badge/grade/bd2168ab0e424e028ad6df8ff886d81a[\"Codacy code quality\", link=\"https://www.codacy.com/app/{gh-name}\"]\nimage: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}\"]\nendif::env-github[]\n\nRSQL is a query language for parametrized filtering of entries in RESTful APIs.\nIt’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.\nFIQL is great for use in URI; there are no unsafe characters, so URL encoding is not required.\nOn 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.\n\nFor example, you can query your resource like this: `/movies?query=name==\"Kill Bill\";year=gt=2003` or `/movies?query=director.lastName==Nolan and year\u003e=2000`.\nSee \u003c\u003cExamples, examples\u003e\u003e below.\n\nThis is a complete and thoroughly tested parser for RSQL written in https://javacc.github.io/javacc/[JavaCC] and Java.\nSince RSQL is a superset of the FIQL, it can be used for parsing FIQL as well.\n\n\n== Related libraries\n\nRSQL-parser can be used with:\n\n* https://github.com/perplexhub/rsql-jpa-specification[rsql-jpa-specification] to convert RSQL into Spring Data JPA Specification and QueryDSL Predicate,\n* https://manosbatsis.github.io/vaultaire/plugins/rsql-support/[Vaultaire] depends on rsql-parser for URL-friendly queries of https://www.corda.net/[Corda] Vault states,\n* https://github.com/tennaito/rsql-jpa[rsql-jpa] to convert RSQL into JPA2 CriteriaQuery,\n* https://github.com/RutledgePaulV/rsql-mongodb[rsql-mongodb] to convert RSQL into MongoDB query using Spring Data MongoDB,\n* https://github.com/RutledgePaulV/q-builders[q-builders] to build (not only) RSQL query in type-safe manner,\n* _your own library…_\n\nIt’s very easy to write a converter for RSQL using its AST.\nTake a look at very simple and naive converter to JPA2 in less than 100 lines of code https://gist.github.com/jirutka/42a0f9bfea280b3c5dca[here].\nYou 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].\n\n\n== Grammar and semantic\n\n_The following grammar specification is written in EBNF notation (http://www.cl.cam.ac.uk/~mgk25/iso-14977.pdf[ISO 14977])._\n\nRSQL expression is composed of one or more comparisons, related to each other with logical operators:\n\n* Logical AND : `;` or `` and ``\n* Logical OR : `,` or `` or ``\n\nBy default, the AND operator takes precedence (i.e. it’s evaluated before any OR operators are).\nHowever, a parenthesized expression can be used to change the precedence, yielding whatever the contained expression yields.\n\n----\ninput          = or, EOF;\nor             = and, { \",\" , and };\nand            = constraint, { \";\" , constraint };\nconstraint     = ( group | comparison );\ngroup          = \"(\", or, \")\";\n----\n\nComparison is composed of a selector, an operator and an argument.\n\n----\ncomparison     = selector, comparison-op, arguments;\n----\n\nSelector identifies a field (or attribute, element, …) of the resource representation to filter by.\nIt can be any non empty Unicode string that doesn’t contain reserved characters (see below) or a white space.\nThe specific syntax of the selector is not enforced by this parser.\n\n----\nselector       = unreserved-str;\n----\n\nComparison operators are in FIQL notation and some of them has an alternative syntax as well:\n\n* Equal to : `==`\n* Not equal to : `!=`\n* Less than : `=lt=` or `\u003c`\n* Less than or equal to : `=le=` or `\\\u003c=`\n* Greater than operator : `=gt=` or `\u003e`\n* Greater than or equal to : `=ge=` or `\u003e=`\n* In : `=in=`\n* Not in : `=out=`\n\nYou can also simply extend this parser with your own operators (see the \u003c\u003cHow to add custom operators, next section\u003e\u003e).\n\n----\ncomparison-op  = comp-fiql | comp-alt;\ncomp-fiql      = ( ( \"=\", { ALPHA } ) | \"!\" ), \"=\";\ncomp-alt       = ( \"\u003e\" | \"\u003c\" ), [ \"=\" ];\n----\n\nArgument can be a single value, or multiple values in parenthesis separated by comma.\nValue that doesn’t contain any reserved character or a white space can be unquoted, other arguments must be enclosed in single or double quotes.\n\n----\narguments      = ( \"(\", value, { \",\" , value }, \")\" ) | value;\nvalue          = unreserved-str | double-quoted | single-quoted;\n\nunreserved-str = unreserved, { unreserved }\nsingle-quoted  = \"'\", { ( escaped | all-chars - ( \"'\" | \"\\\" ) ) }, \"'\";\ndouble-quoted  = '\"', { ( escaped | all-chars - ( '\"' | \"\\\" ) ) }, '\"';\n\nreserved       = '\"' | \"'\" | \"(\" | \")\" | \";\" | \",\" | \"=\" | \"!\" | \"~\" | \"\u003c\" | \"\u003e\";\nunreserved     = all-chars - reserved - \" \";\nescaped        = \"\\\", all-chars;\nall-chars      = ? all unicode characters ?;\n----\n\nIf you need to use both single and double quotes inside a quoted argument, then you must escape one of them using `\\` (backslash).\nIf you want to use `\\` literally, then double it as `\\\\`.\nBackslash has a special meaning only inside a quoted argument, not in unquoted argument.\n\n\n== Examples\n\nExamples of RSQL expressions in both FIQL-like and alternative notation:\n\n----\n- name==\"Kill Bill\";year=gt=2003\n- name==\"Kill Bill\" and year\u003e2003\n- genres=in=(sci-fi,action);(director=='Christopher Nolan',actor==*Bale);year=ge=2000\n- genres=in=(sci-fi,action) and (director=='Christopher Nolan' or actor==*Bale) and year\u003e=2000\n- director.lastName==Nolan;year=ge=2000;year=lt=2010\n- director.lastName==Nolan and year\u003e=2000 and year\u003c2010\n- genres=in=(sci-fi,action);genres=out=(romance,animated,horror),director==Que*Tarantino\n- genres=in=(sci-fi,action) and genres=out=(romance,animated,horror) or director==Que*Tarantino\n----\n\n== How to use\n\nNodes 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].\n\n[source, java]\n----\nNode rootNode = new RSQLParser().parse(\"name==RSQL;version=ge=2.0\");\n\nrootNode.accept(yourShinyVisitor);\n----\n\n\n== How to add custom operators\n\nNeed more operators?\nThe parser can be simply enhanced by custom FIQL-like comparison operators, so you can add your own.\n\n[source, java]\n----\nSet\u003cComparisonOperator\u003e operators = RSQLOperators.defaultOperators();\noperators.add(new ComparisonOperator(\"=all=\", true));\n\nNode rootNode = new RSQLParser(operators).parse(\"genres=all=('thriller','sci-fi')\");\n----\n\n== Maven\n\nReleased versions are available in The Central Repository.\nJust add this artifact to your project:\n\n[source, xml, subs=\"verbatim, attributes\"]\n----\n\u003cdependency\u003e\n    \u003cgroupId\u003e{mvn-group}\u003c/groupId\u003e\n    \u003cartifactId\u003e{name}\u003c/artifactId\u003e\n    \u003cversion\u003e{version}\u003c/version\u003e\n\u003c/dependency\u003e\n----\n\nHowever if you want to use the last snapshot version, you have to add the JFrog OSS repository:\n\n[source, xml]\n----\n\u003crepository\u003e\n    \u003cid\u003ejfrog-oss-snapshot-local\u003c/id\u003e\n    \u003cname\u003eJFrog OSS repository for snapshots\u003c/name\u003e\n    \u003curl\u003ehttps://oss.jfrog.org/oss-snapshot-local\u003c/url\u003e\n    \u003csnapshots\u003e\n        \u003cenabled\u003etrue\u003c/enabled\u003e\n    \u003c/snapshots\u003e\n\u003c/repository\u003e\n----\n\n\n== License\n\nThis project is licensed under http://opensource.org/licenses/MIT[MIT license].\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjirutka%2Frsql-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjirutka%2Frsql-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjirutka%2Frsql-parser/lists"}