Query Builder

Volt provides a fluent query builder API for constructing complex database queries in a type-safe manner.

Building Queries

Queries start with Query.where() and chain conditions using .and():

Query query = Query.where("status").eq("active")
    .and("age").gte(18);

Operators

Equality

// Equal
Query.where("username").eq("john")

// Not equal
Query.where("status").notEq("deleted")

Comparison

// Greater than
Query.where("price").gt(100)

// Greater than or equal
Query.where("age").gte(18)

// Less than
Query.where("stock").lt(10)

// Less than or equal
Query.where("priority").lte(5)

Pattern Matching

// LIKE
Query.where("email").like("%@gmail.com")

// NOT LIKE
Query.where("name").notLike("test%")

IN Clauses

// IN with varargs
Query.where("status").in("active", "pending", "review")

// IN with List
List<String> statuses = List.of("active", "pending");
Query.where("status").in(statuses)

// NOT IN
Query.where("category").notIn("archived", "deleted")

Range Queries

// BETWEEN
Query.where("price").between(10.00, 50.00)

Query.where("createdAt").between(startDate, endDate)

Null Checks

// IS NULL
Query.where("deletedAt").isNull()

// IS NOT NULL
Query.where("email").notNull()

Chaining Conditions

Chain multiple conditions with .and():

Query query = Query.where("status").eq("active")
    .and("price").gte(100)
    .and("price").lte(500)
    .and("category").in("electronics", "computers")
    .and("deletedAt").isNull();

Query Internals

The query builder generates SQL WHERE clauses and collects parameter values:

Query query = Query.where("status").eq("active")
    .and("price").between(10, 100);

// Get the WHERE clause
String whereClause = query.toWhereClause();
// Returns: "status = ? AND price BETWEEN ? AND ?"

// Get parameter values
List<Object> values = query.collectValues();
// Returns: ["active", 10, 100]

Complete Example

// Find active products in a price range, excluding certain categories
Query query = Query.where("status").eq("active")
    .and("price").gte(25.00)
    .and("price").lte(200.00)
    .and("category").notIn("clearance", "discontinued")
    .and("stock").gt(0)
    .and("deletedAt").isNull();

// Use with Volt
List<Product> products = volt.find(Product.class, query);

Operator Reference

Method	SQL	Example
eq(value)	= ?	where("name").eq("John")
notEq(value)	<> ?	where("status").notEq("deleted")
gt(value)	> ?	where("age").gt(18)
gte(value)	>= ?	where("price").gte(100)
lt(value)	< ?	where("stock").lt(10)
lte(value)	<= ?	where("priority").lte(5)
like(pattern)	LIKE ?	where("email").like("%@gmail.com")
notLike(pattern)	NOT LIKE ?	where("name").notLike("test%")
in(values...)	IN (?, ...)	where("status").in("a", "b")
notIn(values...)	NOT IN (?, ...)	where("type").notIn("x", "y")
between(low, high)	BETWEEN ? AND ?	where("price").between(10, 50)
isNull()	IS NULL	where("deletedAt").isNull()
notNull()	IS NOT NULL	where("email").notNull()