Getting Started

This guide shows how to set up Qubit and write your first type-safe query.

Quick Start with Code Start

Create a new project with the Qubit extension pre-configured:

quarkus create app com.example:my-app --extension=qubit

This generates a project with a sample entity and REST resource demonstrating Qubit queries.

Manual Installation

Add the Qubit dependency to your pom.xml:

<dependency>
    <groupId>io.quarkiverse.qubit</groupId>
    <artifactId>quarkus-qubit</artifactId>
    <version>${quarkus-qubit.version}</version>
</dependency>

Choose Your Pattern

Qubit supports two patterns for defining queryable entities.

ActiveRecord Pattern

Extend QubitEntity in your entity class:

@Entity
public class Person extends QubitEntity {
    public String firstName;
    public String lastName;
    public int age;
    public boolean active;
}

Call static methods directly on the entity. The explicit type annotation (Person p) is required due to Java’s static method type inference:

List<Person> adults = Person
    .where((Person p) -> p.age >= 18)
    .toList();

Repository Pattern

Create a repository interface that extends QubitRepository:

@ApplicationScoped
public class PersonRepository implements QubitRepository<Person, Long> {
}

Inject and use the repository. The repository is typed, so lambda parameters are inferred automatically:

@Inject
PersonRepository personRepository;

// No explicit type needed — p is inferred as Person
List<Person> adults = personRepository
    .where(p -> p.age >= 18)
    .toList();

Your First Query

Here is a complete example showing filtering, projection, and aggregation:

// Filter and sort (repository — type inferred)
List<Person> activeAdults = personRepository
    .where(p -> p.age >= 18 && p.active)
    .sortedBy(p -> p.lastName)
    .toList();

// Project to DTO
List<PersonDTO> dtos = personRepository
    .where(p -> p.active)
    .select(p -> new PersonDTO(p.firstName, p.lastName))
    .toList();

// Aggregate
Double avgSalary = personRepository
    .avg(p -> p.salary)
    .getSingleResult();

// Ternary expressions in projections
List<String> labels = personRepository
    .select(p -> p.age >= 18 ? "adult" : "minor")
    .toList();

What’s Next