evitaDB - Fast e-commerce database
logo
page-background

Query API design

The article introduces the basics of querying EvitaDB using its query API, including constructing queries, making requests, and handling responses, with Java code examples.

The evitaQL (evitaDB Query Language) entry point is represented by , and it looks like a Lisp flavoured language. It always starts with the name of the function, followed by a set of arguments in brackets. You can even use other functions in these arguments.
evitaQL is represented by a simple String that is parsed to an abstract syntax tree, which consists of constraints ( encapsulated in We design the evitaQL String representation to look similar to a query defined in the Java notation.
Developers should create their queries in their code by using the static query methods in and then composing internal constraints from the static methods in . When this class is statically imported, the Java query definition looks like the string form of the query.

Conversion of evitaQL from String to AST and back

There is also which allows for parsing the query from the String. The string notation can be created anytime by calling the toString() method on the object.
The parser supports passing values by reference copying the proven approach from a JDBC prepared statement allowing the use of the character ? in the query and providing an array of correctly sorted input parameters. It also supports the so-called named queries, which are widely used in the Spring framework, using variables in the query with the :name format and providing a Map with the named input parameters.
In the opposite direction, it offers the toStringWithParameterExtraction method on the object which allows for the creating of the string format for evitaQL in the form of a prepared statement and extracting all parameters in separate array.

Defining queries in Java code

This is an example how the query is composed and evitaDB requested. The example statically imports two classes: and

The query can also contain "dirty" parts - i.e. null constraints and unnecessary parts:

The query is automatically cleaned and unnecessary constraints are purged before being processed by the evitaDB engine.

There are several handy visitors (more will be added) that allow you to work with the query. They are placed in the package , and some have quick methods in the class.
The query can be "pretty-printed" by using the prettyPrint method on the class.

Author: Ing. Jan Novotný

Date updated: 15.12.2022

Documentation Source