Querity

https://queritylib.github.io/
Admin
Querity is a powerful and extensible query builder for Java applications that simplifies database...
Tokens:20,324
Snippets:147
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Basic query examples

Source: https://queritylib.github.io/spring-mvc/query-language.html

Examples of valid queries covering comparisons, logical operators, sorting, pagination, null checks, IN/NOT IN, boolean values, nested properties, and DISTINCT.

```querity
lastName="Skywalker"
lastName!="Skywalker"
lastName starts with "Sky"
lastName ends with "walker"
lastName contains "wal"
and(firstName="Luke", lastName="Skywalker")
age>30
age<30
height>=1.80
height<=1.80
and(lastName="Skywalker", age>30)
and(or(firstName="Luke", firstName="Anakin"), lastName="Skywalker") sort by age desc
and(not(firstName="Luke"), lastName="Skywalker")
lastName="Skywalker" page 2,10
lastName is null
lastName is not null
lastName in ("Skywalker", "Solo")
lastName not in ("Skywalker", "Solo")
deleted=false
address.city="Rome"
distinct and(orders.totalPrice>1000,currency="EUR")
sort by lastName asc, age desc page 1,10
```

--------------------------------

### SELECT, GROUP BY, and HAVING (AdvancedQuery) examples

Source: https://queritylib.github.io/spring-mvc/query-language.html

Examples of advanced queries using projections and grouping. Use QuerityParser.parseAdvancedQuery() for these. String values must be enclosed in double quotes.

```querity
select firstName, lastName, address.city
select id, UPPER(lastName) as upperName
select category, COUNT(id) as itemCount group by category
select category, SUM(amount) as total group by category having SUM(amount)>1000
select region, category, AVG(price) as avgPrice group by region, category sort by avgPrice desc
```

--------------------------------

### Build a query with pagination

Source: https://queritylib.github.io/features/pagination.html

Use Querity.query().pagination(page, pageSize).build() to create a query with pagination. The example sets page to 1 and page size to 5.

```java
Query query = Querity.query()
    .pagination(1, 5)
    .build();

```

--------------------------------

### Optional WHERE keyword examples

Source: https://queritylib.github.io/spring-mvc/query-language.html

Shows that the WHERE keyword is optional and can be used for readability in queries.

```querity
where lastName="Skywalker"
where and(firstName="Luke", lastName="Skywalker") sort by age
distinct where status="ACTIVE" page 1,10
```

--------------------------------

### Querity.query().build()

Source: https://queritylib.github.io/features.html

Static method to build an empty query. Use this as a starting point for building more complex queries.

```APIDOC
## Querity.query().build()

### Description
Builds an empty query. Use this as a starting point for building more complex queries.

### Method
Static method

### Endpoint
Querity.query().build()

### Parameters
None

### Request Example
```java
Querity.query().build()
```

### Response
#### Success Response
Returns a Query object representing an empty query.

#### Response Example
```java
Query query = Querity.query().build();
```
```

--------------------------------

### Function arguments

Source: https://queritylib.github.io/features/functions.html

Explains the valid arguments for function expressions and provides examples of combining and nesting functions.

```APIDOC
## Function arguments

### Description
Function arguments must be either property references or literals. This section provides examples of valid function usage.

### Argument Types
- `prop("fieldName")` - Reference to an entity property (alias for `property()`).
- `lit(value)` - Literal value (String, Number, or Boolean).

### Examples
```java
// Combine functions
coalesce(prop("nickname"), lit("Anonymous"))
mod(prop("quantity"), lit(10))
concat(prop("firstName"), lit(" - "), prop("lastName"))

// Arithmetic functions
add(prop("basePrice"), prop("shippingCost"))          // variadic: 2+ arguments
multiply(prop("quantity"), prop("unitPrice"))         // variadic: 2+ arguments
subtract(prop("price"), lit(10))                      // binary: exactly 2 arguments
divide(prop("total"), prop("count"))                  // binary: exactly 2 arguments
negate(prop("balance"))                               // unary: exactly 1 argument

// SUBTRACT and DIVIDE are strictly binary; express chains by nesting
subtract(subtract(prop("total"), prop("discount")), prop("tax"))  // (total - discount) - tax

// Nested functions
upper(trim(prop("name")))  // UPPER(TRIM(name))
length(lower(prop("email")))  // LENGTH(LOWER(email))

// Nested properties (e.g., address.city)
upper(prop("address.city"))
coalesce(prop("contact.email"), prop("contact.phone"), lit("N/A"))
```

### Notes
- With integer operands, `divide()` follows the backend’s integer-division semantics (e.g. `divide(lit(7), lit(2))` may yield `3`).
```

--------------------------------

### Querity.query().pagination(page, pageSize).build()

Source: https://queritylib.github.io/features/pagination.html

Builds a query with pagination by specifying the page number and page size. The example shows a query for page 1 with 5 items per page.

```APIDOC
## Querity.query().pagination(page, pageSize).build()

### Description
Builds a query with pagination by specifying the page number and page size.

### Method
pagination(page, pageSize)

### Parameters
- **page** (int) - Required - The page number (1-based).
- **pageSize** (int) - Required - The number of items per page.

### Request Example
```java
Query query = Querity.query()
    .pagination(1, 5)
    .build();
```

### Response
Returns a Query object configured with pagination settings.
```

--------------------------------

### curl example for querity-parser textual query

Source: https://queritylib.github.io/available-modules.html

Shows how to use the simple textual query language to parse Querity objects. The query uses 'and' with two conditions on 'lastName' and 'firstName'.

```bash
curl 'http://localhost:8080/people?q=and(lastName="Skywalker",firstName="Luke")'
```

--------------------------------

### Function expressions in query language

Source: https://queritylib.github.io/spring-mvc/query-language.html

Examples of queries using function calls such as UPPER, LENGTH, LOWER, COALESCE, MULTIPLY, ADD, SUBTRACT, and DIVIDE. Note that ADD and MULTIPLY are variadic (2+ args), SUBTRACT and DIVIDE take exactly two, and NEGATE takes one.

```querity
UPPER(lastName)="SKYWALKER"
LENGTH(firstName)>5
LOWER(email) starts with "luke"
and(UPPER(lastName)="SKYWALKER", LENGTH(firstName)>3)
sort by LENGTH(lastName) desc
COALESCE(nickname, firstName)="Luke"
MULTIPLY(quantity, unitPrice)>1000
ADD(basePrice, shippingCost)<=100
SUBTRACT(price, discount)>50
sort by DIVIDE(total, count) desc
```

--------------------------------

### curl invocation of the REST API

Source: https://queritylib.github.io/spring-mvc.html

Example of invoking the REST API with a JSON query string. The query is passed as a request parameter 'q'.

```bash
curl 'http://localhost:8080/people?q={"filter":{"and":[{"propertyName":"lastName","operator":"EQUALS","value":"Skywalker"},{"propertyName":"lastName","operator":"EQUALS","value":"Luke"}]}}'

```

--------------------------------

### Invoke REST API with query language parameter

Source: https://queritylib.github.io/spring-mvc/query-language.html

Example invocation of the REST API using the query language. The q parameter contains the query expression and(lastName="Skywalker",firstName="Luke").

```bash
curl 'http://localhost:8080/people?q=and(lastName="Skywalker",firstName="Luke")'

```

--------------------------------

### curl example for querity-spring-web JSON query

Source: https://queritylib.github.io/available-modules.html

Shows how to pass a JSON Query or Condition object as a request parameter in a Spring @RestController. The query is URL-encoded and uses the 'and' filter with two conditions on 'lastName'.

```bash
curl 'http://localhost:8080/people?q={"filter":{"and":[{"propertyName":"lastName","operator":"EQUALS","value":"Skywalker"},{"propertyName":"lastName","operator":"EQUALS","value":"Luke"}]}}'
```

--------------------------------

### MongoDB native sort with sortByNative

Source: https://queritylib.github.io/features/native-sort.html

Use this MongoDB example to sort by a native Spring Data MongoDB Order, such as ascending by lastName, passed to sortByNative. The query is built with Querity.query() and can be executed with findAll.

```java
// Sort using Spring Data MongoDB's Order
org.springframework.data.domain.Sort.Order order = Sort.Order.asc("lastName");
Query query = Querity.query()
    .sort(sortByNative(order))
    .build();

```

--------------------------------

### JPA native sort with sortByNative

Source: https://queritylib.github.io/features/native-sort.html

Use this JPA example to sort by a database-specific expression, such as the length of a field, by passing an OrderSpecification to sortByNative. The query is built with Querity.query() and executed with findAll.

```java
// Sort by length of lastName using CriteriaBuilder
OrderSpecification<Person> orderSpec = (root, cb) -> cb.asc(cb.length(root.get("lastName")));
Query query = Querity.query()
    .sort(sortByNative(orderSpec))
    .build();
List<Person> results = querity.findAll(Person.class, query);

```

--------------------------------

### Spring MVC REST controller using Query parameter

Source: https://queritylib.github.io/spring-mvc.html

Use a Query object as a controller parameter in a Spring @RestController. Requires the querity-spring-web module for automatic configuration, or manual setup if autoconfiguration is disabled.

```java
import io.github.queritylib.querity.api.Query;

@RestController
public class MyRestController {

  @Autowired
  MyService service;

  @GetMapping(value = "/people", produces = MediaType.APPLICATION_JSON_VALUE)
  Result<Person> getPeople(@RequestParam(required = false) Query q) {
    return service.getPeople(q);
  }
}

```

--------------------------------

### Spring service using Querity to query and count people

Source: https://queritylib.github.io/quick-start.html

Create a Spring service that autowires Querity and uses the static imports to build a query with a NOT filter, sorting, and pagination. The findAll method returns the first page of 10 people not named Luke Skywalker, sorted by last name and birthdate descending. The count method returns the total filtered count excluding pagination. Requires Java 14 for the record keyword.

```java
import static io.github.queritylib.querity.api.Querity.*;
import static io.github.queritylib.querity.api.Operator.*;
import static io.github.queritylib.querity.api.Sort.Direction.*;

@Service
public class MyService {

  @Autowired
  Querity querity;

  public Result<Person> getPeople() {
    Query query = Querity.query()
        .filter(
            not(and(
                filterBy("lastName", EQUALS, "Skywalker"),
                filterBy("firstName", EQUALS, "Luke")
            ))
        )
        .sort(sortBy("lastName"), sortBy("birthDate", DESC))
        .pagination(1, 10)
        .build();
    List<Person> items = querity.findAll(Person.class, query);
    Long totalCount = querity.count(Person.class, query.getFilter());
    return new Result<>(items, totalCount);
  }

  record Result<T>(List<T> items, Long totalCount) {
  }
}

```

--------------------------------

### Querity.findAll(entityClass, query)

Source: https://queritylib.github.io/features.html

Instance method to run a query and retrieve the results. It takes an entity class and a query object, and returns the matching entities.

```APIDOC
## Querity.findAll(entityClass, query)

### Description
Runs the given query against the database and retrieves the results.

### Method
Instance method

### Endpoint
Querity.findAll(entityClass, query)

### Parameters
- **entityClass** (Class) - Required - The class of the entity to query.
- **query** (Query) - Required - The query to execute.

### Request Example
```java
List<MyEntity> results = querity.findAll(MyEntity.class, query);
```

### Response
#### Success Response
Returns a list of entities matching the query.

#### Response Example
```java
List<MyEntity> results = querity.findAll(MyEntity.class, query);
```
```

--------------------------------

### Simple entity query vs projection query

Source: https://queritylib.github.io/features/projections.html

Compare a simple entity query using `Querity.query()` with `findAll()` to retrieve full entities, and a projection query using `Querity.advancedQuery()` with `selectBy` and `findAllProjected()` to retrieve maps with selected fields.

```java
// Simple entity query
Query query = Querity.query()
    .filter(filterBy("lastName", EQUALS, "Skywalker"))
    .build();
List<Person> entities = querity.findAll(Person.class, query);

// Projection query
AdvancedQuery advQuery = Querity.advancedQuery()
    .select(selectBy("firstName", "lastName"))
    .filter(filterBy("lastName", EQUALS, "Skywalker"))
    .build();
List<Map<String, Object>> projections = querity.findAllProjected(Person.class, advQuery);
```

--------------------------------

### Querity.and()

Source: https://queritylib.github.io/features/filters.html

Wraps multiple conditions in a logical AND.

```APIDOC
## Querity.and()

### Description
Wraps multiple conditions in a logical AND.

### Method
Java API method

### Signature
`and(condition1, condition2, ...)`

### Parameters
- **conditions** (FilterCondition...) - Required - One or more conditions to combine with AND.

### Request Example
```java
and(
    filterBy("firstName", EQUALS, "Luke"),
    filterBy("lastName", EQUALS, "Skywalker")
)
```

### Response
Returns a `FilterCondition` object representing the AND combination.

### Notes
- Can be nested to create more complex conditions.

```

--------------------------------

### Using functions in filters

Source: https://queritylib.github.io/features/functions.html

Shows how to use function expressions in filters: uppercase comparison, string length, and arithmetic multiplication. Requires the static import of Querity.*.

```java
import static io.github.queritylib.querity.api.Querity.*;

// Filter by uppercase lastName
Query query = Querity.query()
    .filter(filterBy(upper(prop("lastName")), EQUALS, "SKYWALKER"))
    .build();

// Filter by string length
Query query = Querity.query()
    .filter(filterBy(length(prop("firstName")), GREATER_THAN, 5))
    .build();

// Filter by a computed value (quantity * unitPrice)
Query query = Querity.query()
    .filter(filterBy(multiply(prop("quantity"), prop("unitPrice")), GREATER_THAN, 1000))
    .build();
```

--------------------------------

### Native select expression with AliasedSelectionSpecification (JPA only)

Source: https://queritylib.github.io/features/projections.html

For JPA modules, use native expressions with `CriteriaBuilder` to create custom selections. This example concatenates first and last name into a single field. Note: Native select expressions are only available for JPA.

```java
// Select concatenated full name using native expression
SelectionSpecification<Person> fullNameSpec = AliasedSelectionSpecification.of(
    (root, cb) -> cb.concat(cb.concat(root.get("firstName"), " "), root.get("lastName")),
    "fullName"
);
AdvancedQuery query = Querity.advancedQuery()
    .select(selectByNative(fullNameSpec))
    .build();
List<Map<String, Object>> results = querity.findAllProjected(Person.class, query);
// Each map contains: {fullName: "Luke Skywalker"}
```

--------------------------------

### Build a query with sorting using Querity

Source: https://queritylib.github.io/features/sorting.html

Use `Querity.query().sort(...).build()` to create a query with sorting. The `sortBy` method accepts a property name and an optional direction (e.g., `DESC`).

```java
Query query = Querity.query()
    .sort(sortBy("lastName"), sortBy("birthDate", DESC))
    .build();

```

--------------------------------

### Querity.or()

Source: https://queritylib.github.io/features/filters.html

Wraps multiple conditions in a logical OR.

```APIDOC
## Querity.or()

### Description
Wraps multiple conditions in a logical OR.

### Method
Java API method

### Signature
`or(condition1, condition2, ...)`

### Parameters
- **conditions** (FilterCondition...) - Required - One or more conditions to combine with OR.

### Request Example
```java
or(
    filterBy("lastName", EQUALS, "Skywalker"),
    filterBy("lastName", EQUALS, "Kenobi")
)
```

### Response
Returns a `FilterCondition` object representing the OR combination.

### Notes
- Can be nested to create more complex conditions.

```

--------------------------------

### Querity.query().filter()

Source: https://queritylib.github.io/features/filters.html

Builds a query with a filter condition. The filter can be a simple condition, a logical combination (AND, OR, NOT), or a native condition.

```APIDOC
## Querity.query().filter()

### Description
Builds a query with a filter condition. The filter can be a simple condition, a logical combination (AND, OR, NOT), or a native condition.

### Method
Java API method

### Signature
`Querity.query().filter(condition).build()`

### Parameters
- **condition** (FilterCondition) - Required - The filter condition to apply. Can be a simple condition, a logical combination, or a native condition.

### Request Example
```java
Query query = Querity.query()
    .filter(filterBy("lastName", EQUALS, "Skywalker"))
    .build();
```

### Response
Returns a `Query` object that can be used to execute the query.

### Notes
- Supports nested properties with dot notation (e.g., `address.city`, `visitedPlaces.country`).
- Operators: EQUALS, NOT_EQUALS, STARTS_WITH, ENDS_WITH, CONTAINS, GREATER_THAN, GREATER_THAN_EQUALS, LESSER_THAN, LESSER_THAN_EQUALS, IS_NULL, IS_NOT_NULL, IN, NOT_IN.
- STARTS_WITH, ENDS_WITH, CONTAINS are case-insensitive only if the underlying database supports it.

```

--------------------------------

### Using functions in sorting

Source: https://queritylib.github.io/features/functions.html

Demonstrates how to use function expressions in sort conditions, such as length() and upper().

```APIDOC
## Using functions in sorting

### Description
Use SQL-like functions in sort conditions to sort by transformed property values.

### Usage
```java
// Sort by string length
Query query = Querity.query()
    .sort(sortBy(length(prop("lastName")), DESC))
    .build();

// Sort by uppercase value
Query query = Querity.query()
    .sort(sortBy(upper(prop("firstName"))))
    .build();
```

### Functions Used
- `length(prop("lastName"))` - Sorts by the length of the property value.
- `upper(prop("firstName"))` - Sorts by the uppercase value of the property.

### Notes
- Backend support: JPA supports functions in sorting; MongoDB does not support functions in sorting (throws UnsupportedOperationException); Elasticsearch does not support functions.
```

--------------------------------

### Using functions in projections

Source: https://queritylib.github.io/features/functions.html

Shows how to use function expressions in projections: selecting properties with aliases for uppercase, concatenation, and length.

```java
// Select with function expressions
AdvancedQuery query = Querity.advancedQuery()
    .select(selectBy(
        prop("id"),
        upper(prop("lastName")).as("upperLastName"),
        concat(prop("firstName"), lit(" "), prop("lastName")).as("fullName"),
        length(prop("email")).as("emailLength")
    ))
    .build();
```

--------------------------------

### Querity.query().sort()

Source: https://queritylib.github.io/features/sorting.html

Builds a query with sorting criteria. The sort method accepts one or more sort criteria created with Querity.sortBy().

```APIDOC
## Querity.query().sort()

### Description
Builds a query with sorting criteria. The sort method accepts one or more sort criteria created with Querity.sortBy().

### Method
query().sort(...)

### Parameters
- **sortCriteria** (SortCriteria...) - Required - One or more sort criteria to apply to the query.

### Request Example
```java
Query query = Querity.query()
    .sort(sortBy("lastName"), sortBy("birthDate", DESC))
    .build();
```

### Response
Returns a Query object with the specified sorting applied.
```

--------------------------------

### Backend support for functions

Source: https://queritylib.github.io/features/functions.html

Provides a summary of function support across JPA, MongoDB, and Elasticsearch implementations.

```APIDOC
## Backend support for functions

### Description
Function support varies by backend implementation. This section summarizes which functions are supported in filters, sorting, and projections.

### Support Summary
- **JPA**: Full support for all functions in filters, sorting, and projections.
- **MongoDB**: Functions supported in filters only (via `$expr`). Using functions in sort or select throws `UnsupportedOperationException`.
- **Elasticsearch**: Functions are **not supported**. Using functions throws `UnsupportedOperationException`.

### Function Support by Implementation

| Function | JPA | MongoDB | Elasticsearch |
|----------|-----|---------|---------------|
| `abs()`, `sqrt()`, `mod()` | ✓ Filters, Sort, Select | ✓ Filters only | ✗ |
| `add()`, `subtract()`, `multiply()`, `divide()`, `negate()` | ✓ Filters, Sort, Select | ✓ Filters only | ✗ |
| `concat()`, `substring()`, `trim()`, `ltrim()`, `rtrim()` | ✓ Filters, Sort, Select | ✓ Filters only | ✗ |
| `lower()`, `upper()`, `length()`, `locate()` | ✓ Filters, Sort, Select | ✓ Filters only | ✗ |
| `currentDate()`, `currentTime()`, `currentTimestamp()` | ✓ Filters, Sort, Select | ✓ Filters only | ✗ |
| `coalesce()`, `nullif()` | ✓ Filters, Sort, Select | ✓ Filters only | ✗ |
| `count()`, `sum()`, `avg()`, `min()`, `max()` | ✓ Filters, Sort, Select | ✓ Filters only | ✗ |
```

--------------------------------

### AND condition with Querity.and

Source: https://queritylib.github.io/features/filters.html

Wraps multiple conditions in a logical AND. Can be nested for more complex conditions.

```java
Query query = Querity.query()
    .filter(
        and(
            filterBy("firstName", EQUALS, "Luke"),
            filterBy("lastName", EQUALS, "Skywalker")
        )
    ).build();
```

--------------------------------

### Using functions in sorting

Source: https://queritylib.github.io/features/functions.html

Shows how to use function expressions in sorting: sorting by string length descending and by uppercase value.

```java
// Sort by string length
Query query = Querity.query()
    .sort(sortBy(length(prop("lastName")), DESC))
    .build();

// Sort by uppercase value
Query query = Querity.query()
    .sort(sortBy(upper(prop("firstName"))))
    .build();
```

--------------------------------

### Using functions in projections

Source: https://queritylib.github.io/features/functions.html

Demonstrates how to use function expressions in select projections, such as upper(), concat(), and length().

```APIDOC
## Using functions in projections

### Description
Use SQL-like functions in select projections to compute derived fields.

### Usage
```java
// Select with function expressions
AdvancedQuery query = Querity.advancedQuery()
    .select(selectBy(
        prop("id"),
        upper(prop("lastName")).as("upperLastName"),
        concat(prop("firstName"), lit(" "), prop("lastName")).as("fullName"),
        length(prop("email")).as("emailLength")
    ))
    .build();
```

### Functions Used
- `upper(prop("lastName"))` - Converts the property value to uppercase.
- `concat(prop("firstName"), lit(" "), prop("lastName"))` - Concatenates multiple values.
- `length(prop("email"))` - Returns the length of the property value.

### Notes
- Backend support: JPA supports functions in projections; MongoDB does not support functions in select (throws UnsupportedOperationException); Elasticsearch does not support functions.
```

--------------------------------

### Projection with selectBy

Source: https://queritylib.github.io/features/projections.html

Demonstrates how to use Querity.advancedQuery() with selectBy to retrieve only specific fields from entities.

```APIDOC
## Projection with selectBy

### Description
Use `Querity.advancedQuery()` with `selectBy` to retrieve only specific fields instead of full entities. Supports nested properties with dot notation.

### Method
N/A (SDK method call)

### Endpoint
N/A (SDK method call)

### Parameters
- `selectBy(String... properties)` - Required - The properties to select, supporting dot notation for nested fields.
- `filter(filterBy(...))` - Optional - Filter conditions.

### Request Example
```java
AdvancedQuery query = Querity.advancedQuery()
    .select(selectBy("firstName", "lastName", "address.city"))
    .filter(filterBy("lastName", EQUALS, "Skywalker"))
    .build();
List<Map<String, Object>> results = querity.findAllProjected(Person.class, query);
```

### Response
Returns a list of maps, each containing only the selected fields.

### Response Example
```java
// Each map contains only: {firstName: "...", lastName: "...", city: "..."}
```
```

--------------------------------

### Available functions

Source: https://queritylib.github.io/features/functions.html

Lists all available function categories and their functions.

```APIDOC
## Available functions

### Description
Querity provides a set of SQL-like functions that can be used in filters, sorting, and projections.

### Categories and Functions

| Category | Functions |
|----------|-----------|
| Arithmetic | `abs()`, `sqrt()`, `mod()`, `add()`, `subtract()`, `multiply()`, `divide()`, `negate()` |
| String | `concat()`, `substring()`, `trim()`, `ltrim()`, `rtrim()`, `lower()`, `upper()`, `length()`, `locate()` |
| Date/Time | `currentDate()`, `currentTime()`, `currentTimestamp()` |
| Conditional | `coalesce()`, `nullif()` |
| Aggregate | `count()`, `sum()`, `avg()`, `min()`, `max()` |

### Notes
- Function arguments must be property references (`prop()`) or literals (`lit()`).
- Backend support varies by function and implementation (see backend support section).
```

--------------------------------

### Using functions in filters

Source: https://queritylib.github.io/features/functions.html

Demonstrates how to use function expressions in filter conditions, such as upper(), length(), and multiply().

```APIDOC
## Using functions in filters

### Description
Use SQL-like functions in filter conditions to transform property values before comparison.

### Usage
```java
import static io.github.queritylib.querity.api.Querity.*;

// Filter by uppercase lastName
Query query = Querity.query()
    .filter(filterBy(upper(prop("lastName")), EQUALS, "SKYWALKER"))
    .build();

// Filter by string length
Query query = Querity.query()
    .filter(filterBy(length(prop("firstName")), GREATER_THAN, 5))
    .build();

// Filter by a computed value (quantity * unitPrice)
Query query = Querity.query()
    .filter(filterBy(multiply(prop("quantity"), prop("unitPrice")), GREATER_THAN, 1000))
    .build();
```

### Functions Used
- `upper(prop("lastName"))` - Converts the property value to uppercase.
- `length(prop("firstName"))` - Returns the length of the property value.
- `multiply(prop("quantity"), prop("unitPrice"))` - Multiplies two property values.

### Notes
- Function arguments must be property references (`prop()`) or literals (`lit()`).
- Backend support: JPA supports all functions in filters; MongoDB supports functions in filters only; Elasticsearch does not support functions.
```

--------------------------------

### Query vs AdvancedQuery

Source: https://queritylib.github.io/features/projections.html

Shows the difference between simple entity queries and projection queries.

```APIDOC
## Query vs AdvancedQuery

### Description
Querity provides two query types: `Query` for simple entity queries and `AdvancedQuery` for projection queries with `selectBy`, `groupBy`, `having`.

### Method
N/A (SDK method call)

### Endpoint
N/A (SDK method call)

### Parameters
- `Querity.query()` - For simple entity queries, use with `findAll()` to retrieve full entities.
- `Querity.advancedQuery()` - For projection queries, use with `findAllProjected()` to retrieve `Map<String, Object>` results.

### Request Example
```java
// Simple entity query
Query query = Querity.query()
    .filter(filterBy("lastName", EQUALS, "Skywalker"))
    .build();
List<Person> entities = querity.findAll(Person.class, query);

// Projection query
AdvancedQuery advQuery = Querity.advancedQuery()
    .select(selectBy("firstName", "lastName"))
    .filter(filterBy("lastName", EQUALS, "Skywalker"))
    .build();
List<Map<String, Object>> projections = querity.findAllProjected(Person.class, advQuery);
```

### Response
- `findAll()` returns a list of entity objects.
- `findAllProjected()` returns a list of maps with projected fields.
```

--------------------------------

### Use @WithPreprocessor on Query parameter in REST controller

Source: https://queritylib.github.io/spring-mvc/preprocessors.html

Shows a REST controller method that accepts a Query parameter annotated with @WithPreprocessor("preprocessor1"). The preprocessor bean is applied before the method executes, mapping DTO property names to entity property names.

```java
@RestController
public class MyRestController {

  @Autowired
  MyService service;

  @GetMapping(value = "/people", produces = MediaType.APPLICATION_JSON_VALUE)
  Result<Person> getPeople(@RequestParam(required = false) @WithPreprocessor("preprocessor1") Query q) {
    return service.getPeople(q);
  }
}
```

--------------------------------

### Function arguments and nesting

Source: https://queritylib.github.io/features/functions.html

Shows function argument rules: property references and literals, variadic vs binary vs unary arithmetic, nesting, and nested properties. Note that divide() with integer operands follows backend integer-division semantics.

```java
// Combine functions
coalesce(prop("nickname"), lit("Anonymous"))
mod(prop("quantity"), lit(10))
concat(prop("firstName"), lit(" - "), prop("lastName"))

// Arithmetic functions
add(prop("basePrice"), prop("shippingCost"))          // variadic: 2+ arguments
multiply(prop("quantity"), prop("unitPrice"))         // variadic: 2+ arguments
subtract(prop("price"), lit(10))                      // binary: exactly 2 arguments
divide(prop("total"), prop("count"))                  // binary: exactly 2 arguments
negate(prop("balance"))                               // unary: exactly 1 argument

// SUBTRACT and DIVIDE are strictly binary; express chains by nesting
subtract(subtract(prop("total"), prop("discount")), prop("tax"))  // (total - discount) - tax

// Nested functions
upper(trim(prop("name")))  // UPPER(TRIM(name))
length(lower(prop("email")))  // LENGTH(LOWER(email))

// Nested properties (e.g., address.city)
upper(prop("address.city"))
coalesce(prop("contact.email"), prop("contact.phone"), lit("N/A"))
```

--------------------------------

### Querity.query().distinct(true).build()

Source: https://queritylib.github.io/features/distinct.html

Builds a query with distinct results enabled. This is useful when filtering by nested properties that may produce duplicate results in SQL databases.

```APIDOC
## Querity.query().distinct(true).build()

### Description
Builds a query with distinct results enabled. This is useful when filtering by nested properties that may produce duplicate results in SQL databases.

### Method
build()

### Parameters
- **distinct** (boolean) - Required - Set to true to enable distinct results.

### Request Example
```java
Query query = Querity.query()
    .distinct(true)
    .filter(filterBy("orders.items.quantity", GREATER_THAN, 8))
    .pagination(1, 5)
    .build();
```

### Notes
- The distinct flag is meaningless in NoSQL databases and will be ignored.
```

--------------------------------

### OR condition with Querity.or

Source: https://queritylib.github.io/features/filters.html

Wraps multiple conditions in a logical OR. Can be nested for more complex conditions.

```java
Query query = Querity.query()
    .filter(
        or(
            filterBy("lastName", EQUALS, "Skywalker"),
            filterBy("lastName", EQUALS, "Kenobi")
        )
    ).build();
```

--------------------------------

### Parse query language with QuerityParser.parseQuery()

Source: https://queritylib.github.io/spring-mvc/query-language.html

REST controller that parses a query string parameter using QuerityParser.parseQuery() to build a Query object. Requires the querity-parser module and the querity-spring-web alternative for JSON parsing.

```java
import io.github.queritylib.querity.api.Query;
import io.github.queritylib.querity.parser.QuerityParser;

@RestController
public class MyRestController {

  @Autowired
  MyService service;

  @GetMapping(value = "/people", produces = MediaType.APPLICATION_JSON_VALUE)
  Result<Person> getPeople(@RequestParam(required = false) String q) {
    Query query = QuerityParser.parseQuery(q);
    return service.getPeople(query);
  }
}

```

--------------------------------

### Querity.count(entityClass, condition)

Source: https://queritylib.github.io/features.html

Instance method to count the elements filtered by a condition. It takes an entity class and a condition, and returns the count.

```APIDOC
## Querity.count(entityClass, condition)

### Description
Counts the elements filtered by the given condition.

### Method
Instance method

### Endpoint
Querity.count(entityClass, condition)

### Parameters
- **entityClass** (Class) - Required - The class of the entity to count.
- **condition** (Condition) - Required - The condition to filter by.

### Request Example
```java
long count = querity.count(MyEntity.class, condition);
```

### Response
#### Success Response
Returns the number of entities matching the condition.

#### Response Example
```java
long count = querity.count(MyEntity.class, condition);
```
```

--------------------------------

### Native select expressions (JPA only)

Source: https://queritylib.github.io/features/projections.html

Demonstrates using native JPA expressions with CriteriaBuilder for advanced projections.

```APIDOC
## Native select expressions (JPA only)

### Description
For advanced use cases, JPA modules support native expressions using `CriteriaBuilder`. This allows concatenating fields or other custom expressions.

### Method
N/A (SDK method call)

### Endpoint
N/A (SDK method call)

### Parameters
- `AliasedSelectionSpecification.of(...)` - Required - Defines a native selection with an alias.
- `selectByNative(...)` - Required - Specifies the native selection in the query.

### Request Example
```java
SelectionSpecification<Person> fullNameSpec = AliasedSelectionSpecification.of(
    (root, cb) -> cb.concat(cb.concat(root.get("firstName"), " "), root.get("lastName")),
    "fullName"
);
AdvancedQuery query = Querity.advancedQuery()
    .select(selectByNative(fullNameSpec))
    .build();
List<Map<String, Object>> results = querity.findAllProjected(Person.class, query);
```

### Response
Returns a list of maps with the aliased native expression result.

### Response Example
```java
// Each map contains: {fullName: "Luke Skywalker"}
```

### Notes
Native select expressions are only available for JPA.
```

--------------------------------

### Querity.not()

Source: https://queritylib.github.io/features/filters.html

Wraps a condition in a logical NOT.

```APIDOC
## Querity.not()

### Description
Wraps a condition in a logical NOT.

### Method
Java API method

### Signature
`not(condition)`

### Parameters
- **condition** (FilterCondition) - Required - The condition to negate.

### Request Example
```java
not(filterBy("lastName", EQUALS, "Skywalker"))
```

### Response
Returns a `FilterCondition` object representing the NOT of the given condition.

### Notes
- Can wrap simple or complex conditions.

```

--------------------------------

### Build a Querity query with distinct results

Source: https://queritylib.github.io/features/distinct.html

Use this Java snippet to create a Querity query with distinct results. Set distinct(true) when filtering by nested properties that may produce duplicates in SQL databases. The distinct flag is ignored in NoSQL databases.

```java
Query query = Querity.query()
    .distinct(true)
    .filter(filterBy("orders.items.quantity", GREATER_THAN, 8))
    .pagination(1, 5)
    .build();
```

--------------------------------

### Group by multiple properties

Source: https://queritylib.github.io/features/group-by.html

Groups by two properties (category and region) and selects an average price aggregate.

```java
AdvancedQuery query = Querity.advancedQuery()
    .select(selectBy(
        prop("category"),
        prop("region"),
        avg(prop("price")).as("avgPrice")
    ))
    .groupBy("category", "region")
    .build();
```

--------------------------------

### Group by multiple properties

Source: https://queritylib.github.io/features/group-by.html

Groups results by multiple properties and selects an aggregate function.

```APIDOC
## Group by multiple properties

### Description
Groups results by multiple properties and selects an aggregate function.

### Method
N/A (Java API)

### Endpoint
N/A (Java API)

### Parameters
- `selectBy(prop("category"), prop("region"), avg(prop("price")).as("avgPrice"))` - Selection specification for the grouped fields and aggregate.
- `groupBy("category", "region")` - Properties to group by.

### Request Example
```java
AdvancedQuery query = Querity.advancedQuery()
    .select(selectBy(
        prop("category"),
        prop("region"),
        avg(prop("price")).as("avgPrice")
    ))
    .groupBy("category", "region")
    .build();
```

### Response
Returns a list of maps, each containing the grouped fields and aggregate results.
```

--------------------------------

### Basic GROUP BY with count and sum

Source: https://queritylib.github.io/features/group-by.html

Groups by a single property and selects count and sum aggregates. Returns a list of maps with the grouped results.

```java
import static io.github.queritylib.querity.api.Querity.*;

// Group by single property
AdvancedQuery query = Querity.advancedQuery()
    .select(selectBy(
        prop("category"),
        count(prop("id")).as("itemCount"),
        sum(prop("amount")).as("totalAmount")
    ))
    .groupBy("category")
    .build();
List<Map<String, Object>> results = querity.findAllProjected(Order.class, query);
// Returns: [{category: "Electronics", itemCount: 42, totalAmount: 15000}, ...]
```

--------------------------------

### Configure PropertyNameMappingPreprocessor bean with SimplePropertyNameMapper

Source: https://queritylib.github.io/spring-mvc/preprocessors.html

Defines a Spring bean that returns a QueryPreprocessor using PropertyNameMappingPreprocessor with SimplePropertyNameMapper. The builder sets recursive mapping (default true) and custom mappings (e.g., prop1 to prop2).

```java
@SpringBootApplication
public class MyApplication {
  public static void main(String[] args) {
    SpringApplication.run(MyApplication.class, args);
  }

  @Bean
  public QueryPreprocessor preprocessor1() {
    return new PropertyNameMappingPreprocessor(
        SimplePropertyNameMapper.builder()
            .recursive(true) // default is true
            .mapping("prop1", "prop2") // customize your mappings here
            .build());
  }
}
```

--------------------------------

### Querity.filterBy()

Source: https://queritylib.github.io/features/filters.html

Creates a simple condition with a property name, an operator, and an optional value.

```APIDOC
## Querity.filterBy()

### Description
Creates a simple condition with a property name, an operator, and an optional value.

### Method
Java API method

### Signature
`filterBy(propertyName, operator, value)`

### Parameters
- **propertyName** (String) - Required - The name of the property to filter on. Supports nested properties with dot notation.
- **operator** (Operator) - Required - The operator to apply. See list of operators.
- **value** (Object) - Optional - The value to compare against. Not needed for operators like IS_NULL.

### Request Example
```java
filterBy("lastName", EQUALS, "Skywalker")
```

### Response
Returns a `FilterCondition` object.

### Operators
- EQUALS
- NOT_EQUALS
- STARTS_WITH
- ENDS_WITH
- CONTAINS
- GREATER_THAN
- GREATER_THAN_EQUALS
- LESSER_THAN
- LESSER_THAN_EQUALS
- IS_NULL
- IS_NOT_NULL
- IN
- NOT_IN

```

--------------------------------

### Other Optimizations: batchSize, timeout, cacheable

Source: https://queritylib.github.io/features/query-customizers.html

Apply multiple JPA hints in one customize call: batchSize(50) optimizes JDBC fetch size, timeout(5000) sets query timeout in ms, and cacheable(true) enables L2 query cache. These are backend-specific and only applied with the JPA module.

```java
Query query = Querity.query()
    .customize(
        JPAHints.batchSize(50),      // Optimize JDBC fetch size
        JPAHints.timeout(5000),      // Query timeout in ms
        JPAHints.cacheable(true)     // Enable L2 Query Cache
    )
    .build();

```

--------------------------------

### ANTLR v4 grammar for query language

Source: https://queritylib.github.io/spring-mvc/query-language.html

Defines the complete grammar for the Querity query language, including lexer tokens and parser rules. Use this as the authoritative syntax reference.

```ANTLR
DISTINCT    : 'distinct';
WHERE       : 'where';
AND         : 'and';
OR          : 'or';
NOT         : 'not';
SORT        : 'sort by';
ASC         : 'asc';
DESC        : 'desc';
PAGINATION  : 'page';
SELECT      : 'select';
GROUP_BY    : 'group by';
HAVING      : 'having';
AS          : 'as';
NEQ         : '!=';
LTE         : '<=';
GTE         : '>=';
EQ          : '=';
LT          : '<';
GT          : '>';
STARTS_WITH : 'starts with';
ENDS_WITH   : 'ends with';
CONTAINS    : 'contains';
IS_NULL     : 'is null';
IS_NOT_NULL : 'is not null';
IN          : 'in';
NOT_IN      : 'not in';
LPAREN      : '(';
RPAREN      : ')';
COMMA       : ',';

INT_VALUE     : [0-9]+;
DECIMAL_VALUE : [0-9]+'.'[0-9]+;
BOOLEAN_VALUE : 'true' | 'false';
PROPERTY      : [a-zA-Z_][a-zA-Z0-9_.]*;
STRING_VALUE  : '"' (~["\\] | '\\' .)* '"';
FUNCTION_NAME : 'UPPER' | 'LOWER' | 'LENGTH' | 'TRIM' | 'LTRIM' | 'RTRIM' |
                'ABS' | 'SQRT' | 'MOD' | 'ADD' | 'SUBTRACT' | 'MULTIPLY' |
                'DIVIDE' | 'NEGATE' | 'CONCAT' | 'SUBSTRING' | 'LOCATE' |
                'COALESCE' | 'NULLIF' | 'CURRENT_DATE' | 'CURRENT_TIME' |
                'CURRENT_TIMESTAMP' | 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX';

query            : DISTINCT? (WHERE? condition)? (SORT sortFields)? (PAGINATION paginationParams)? ;
advancedQuery    : (SELECT selectFields)? (WHERE? condition)? (GROUP_BY groupByFields)? (HAVING havingCondition)? (SORT sortFields)? (PAGINATION paginationParams)? ;
condition        : simpleCondition | conditionWrapper | notCondition;
operator         : NEQ | LTE | GTE | EQ | LT | GT | STARTS_WITH | ENDS_WITH | CONTAINS | IS_NULL | IS_NOT_NULL | IN | NOT_IN ;
conditionWrapper : (AND | OR) LPAREN condition (COMMA condition)* RPAREN ;
notCondition     : NOT LPAREN condition RPAREN ;
simpleValue      : INT_VALUE | DECIMAL_VALUE | BOOLEAN_VALUE | STRING_VALUE;
arrayValue       : LPAREN simpleValue (COMMA simpleValue)* RPAREN ;
propertyOrFunction : PROPERTY | functionCall ;
functionCall     : FUNCTION_NAME LPAREN (functionArg (COMMA functionArg)*)? RPAREN ;
functionArg      : PROPERTY | simpleValue | functionCall ;
simpleCondition  : propertyOrFunction operator (simpleValue | arrayValue)? ;
direction        : ASC | DESC ;
sortField        : propertyOrFunction (direction)? ;
sortFields       : sortField (COMMA sortField)* ;
selectField      : propertyOrFunction (AS PROPERTY)? ;
selectFields     : selectField (COMMA selectField)* ;
groupByFields    : propertyOrFunction (COMMA propertyOrFunction)* ;
havingCondition  : condition ;
paginationParams : INT_VALUE COMMA INT_VALUE ;
```

--------------------------------

### Basic GROUP BY

Source: https://queritylib.github.io/features/group-by.html

Groups results by a single property and selects aggregate functions like count and sum.

```APIDOC
## Basic GROUP BY

### Description
Groups results by a single property and selects aggregate functions like count and sum.

### Method
N/A (Java API)

### Endpoint
N/A (Java API)

### Parameters
- `selectBy(prop("category"), count(prop("id")).as("itemCount"), sum(prop("amount")).as("totalAmount"))` - Selection specification for the grouped fields and aggregates.
- `groupBy("category")` - Property to group by.

### Request Example
```java
import static io.github.queritylib.querity.api.Querity.*;

AdvancedQuery query = Querity.advancedQuery()
    .select(selectBy(
        prop("category"),
        count(prop("id")).as("itemCount"),
        sum(prop("amount")).as("totalAmount")
    ))
    .groupBy("category")
    .build();
List<Map<String, Object>> results = querity.findAllProjected(Order.class, query);
```

### Response
Returns a list of maps, each containing the grouped field and aggregate results.

### Response Example
```json
[{category: "Electronics", itemCount: 42, totalAmount: 15000}, ...]
```
```

--------------------------------

### Configure Querity bean without Spring Boot

Source: https://queritylib.github.io/installing.html

Define a Querity bean in a Spring configuration class when not using Spring Boot autoconfiguration. Requires an EntityManager and uses QuerityJpaImpl.

```java
import io.github.queritylib.querity.api.Querity;

@Configuration
public class QuerityConfiguration {
  @Bean
  Querity querity(EntityManager entityManager) {
    return new QuerityJpaImpl(entityManager);
  }
}
```

--------------------------------

### Compare quantity with availableStock using filterByField

Source: https://queritylib.github.io/features/field-comparison.html

Find orders where quantity exceeds available stock. Uses filterByField with GREATER_THAN and field("availableStock").

```java
// Find orders where quantity exceeds available stock
Query query = Querity.query()
    .filter(filterByField("quantity", GREATER_THAN, field("availableStock")))
    .build();
```
Tokens:
Raw