Query Types in PikaORM

Choosing the Right Query Approach

The Pika ORM provides several querying mechanisms designed for different use cases and levels of abstraction. Pick the one that matches how close to the metal you want to be.

1. PikaClassFinder

Purpose: High-level, convenient finder interface for common query patterns.

• Simple method-based querying
• Built-in methods for common operations (byId, firstWhere, where, all)
• Collection parameter support

// Single record lookup
SampleModel fromDb = orm.find(SampleModel.class).byId(id);

// Collection parameters (IN clauses)
var results = orm.find(SampleModel.class)
    .where("str_val in :strs", Map.of("strs", List.of("foo", "bar")))
    .toList();

2. PikaClassQuery

Purpose: Type-safe, fluent SQL-based querying interface for specific entity classes.

• Strongly typed to a specific model class
• Named parameter support with :paramName syntax
• Query plan analysis with explain()

var query = orm.query(SampleModel.class)
    .where("date_val < :val")
    .withVar("val", new Date(2050, 1, 1));

List<SampleModel> results = query.fetchList();

3. PikaQueryBuilder

Purpose: Fluent SQL query construction with optional result mapping for complex queries.

• Support for JOINs, column selection, ordering, and paging
• Dual result modes: ResultMap (generic) or typed entity mapping

var query = orm.queryBuilder("albums")
    .select("albums.*", "tracks.Name")
    .join("Tracks on albums.AlbumId = tracks.TrackId")
    .where("Title LIKE '%A%'");

var results = query.fetchList();

4. Raw SQL Query Interface

Purpose: Direct SQL execution with flexible result mapping — when you just need to write the query yourself.

var result = orm.select("SELECT * FROM Todos", Todo.class).toList();

One-to-Many Relationships

Declare relationships using loadMany() in the parent entity:

public class FooContainer {
    private long id;

    public PikaORM.PikaManyQuery<Foo> getFoos() {
        // Foo.class being the other side of the 1-N relationship
        return PikaORM.get().loadMany(this, Foo.class);
    }
}

// Loading
List<Foo> foos = fooContainer.getFoos().toList();

// Creating (immediate persistence)
Foo newFoo = new Foo();
fooContainer.getFoos().addAndSave(newFoo);