Chapter 19. Building a Query using the Ickle Query Language
19.1. Building a Query using the Ickle Query Language
Using Ickle, a light and small subset of JP-QL with full-text extensions, it is possible to create relational and full-text queries in both Library and Remote Client-Server mode. Ickle is a string-based querying language, and has the following characteristics:
- Queres Java classes and supports Protocol Buffers.
- Queries can target a single entity type.
- Queries can filter on properties of embedded objects, including collections.
- Supports projections, aggregations, sorting, named parameters.
- Supports indexed and non-indexed execution.
- Supports complex boolean expressions.
- Supports full-text queries.
-
Does not support computations in expressions, such as
user.age > sqrt(user.shoeSize+3). - Does not support joins.
- Does not support subqueries.
-
Is supported across various JBoss Data Grid APIs. Whenever a Query is produced by the
QueryBuilderis accepted, including continuous queries or in event filters for listeners.
To use the API, first obtain a QueryFactory to the cache and then call the .create() method, passing in the string to use in the query. For instance:
QueryFactory qf = Search.getQueryFactory(remoteCache);
Query q = qf.create("from sample_bank_account.Transaction where amount > 20");When using Ickle all fields used with full-text operators must be both Indexed and Analysed.
Ickle is a Technology Preview feature in JBoss Data Grid 7.1.
19.2. Deviations from the Lucene Query Parser Syntax
While Ickle is a subset of JP-QL it does have the following deviations in its query syntax:
- Whitespace is not significant.
- There is no support for wildcards in field names.
- A field name or path must always be specified, as there is no default field.
-
&&and||are accepted instead ofANDorORin both full-text and JPA predicates. -
!may be used instead ofNOT. -
A missing boolean operator is interpreted as
OR. - String terms must be enclosed with either single or double quotes.
- Fuzziness and boosting are not accepted in arbitrary order; fuzziness always comes first.
-
!=is accepted instead of<>. -
Boosting cannot be applied to
>,>=,<,⇐operators. Ranges may be used to achieve the same result.
19.3. Fuzzy Queries
To execute a fuzzy query add ~ along with an integer, representing the distance from the term used, after the term. For instance
Query fuzzyQuery = qf.create("from sample_bank_account.Transaction where description : 'cofee'~2");19.4. Range Queries
To execute a range query define the given boundaries within a pair of braces, as seen in the following example:
Query rangeQuery = qf.create("from sample_bank_account.Transaction where amount : [20 to 50]");19.5. Phrase Queries
A group of words may be searched by surrounding them in quotation marks, as seen in the following example:
Query q = qf.create("from sample_bank_account.Transaction where description : 'bus fare'");19.6. Proximity Queries
To execute a proximity query, finding two terms within a specific distance, add a ~ along with the distance after the phrase. For instance, the following example will find the words canceling and fee provided they are not more than 3 words apart:
Query proximityQuery = qf.create("from sample_bank_account.Transaction where description : 'canceling fee'~3 ");19.7. Wildcard Queries
Both single-character and multi-character wildcard searches may be performed:
- A single-character wildcard search may be used with the ? character.
- A multi-character wildcard search may be used with the * character.
To search for text or test the following single-character wildcard search would be used:
Query wildcardQuery = qf.create("from sample_bank_account.Transaction where description : 'te?t'");To search for test, tests, or tester the following multi-character wildcard search would be useD:
Query wildcardQuery = qf.create("from sample_bank_account.Transaction where description : 'test*'");19.8. Regular Expression Queries
Regular expression queries may be performed by specifing a pattern between /. Ickle uses Lucene’s regular expression syntax, so to search for the words moat or boat the following could be used:
Query regExpQuery = qf.create("from sample_library.Book where title : /[mb]oat/");19.9. Boosting Queries
Terms may be boosted by adding a ^ after the term to increase their relevance in a given query, the higher the boost factor the more relevant the term will be. For instance to search for titles containing beer and wine with a higher relevance on beer, by a factor of 3, the following could be used:
Query boostedQuery = qf.create("from sample_library.Book where title : beer^3 OR wine");