Chapter 22. Building a Query using the Ickle Query Language

22.1. Building a Query using the Ickle Query Language

Create relational and full-text queries in both Library and Remote Client-Server mode with the Ickle query language.

Ickle is string-based 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 QueryBuilder is 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");
Note

When using Ickle all fields used with full-text operators must be both Indexed and Analysed.

22.2. Ickle Query Language Parser Syntax

The parser syntax for the Ickle query language has some notable rules:

  • Whitespace is not significant.
  • Wildcards are not supported in field names.
  • A field name or path must always be specified, as there is no default field.
  • && and || are accepted instead of AND or OR in both full-text and JPA predicates.
  • ! may be used instead of NOT.
  • 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.

22.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");

22.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]");

22.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'");

22.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 ");

22.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*'");
Note

Full-text wildcard queries match terms as they are stored in the index, which varies depending on the analyzer you use.

You should also be aware that JBoss Data Grid does not analyze arguments in wildcard operators. Use arguments that resemble the output of the analysis for the index.

For example, most analyzers converts text to lowercase before indexing it. In this case, any wildcard searches that use arguments with capital letters return no matches.

In general, wildcard queries are also slower than other types of full-text queries and should be avoided whenever possible.

22.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/");

22.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");