Module storm
Package st.orm.template

Class QueryBuilder<T extends Record,R,ID>

java.lang.Object
st.orm.template.QueryBuilder<T,R,ID>
Type Parameters:
T - the type of the table being queried.
R - the type of the result.
ID - the type of the primary key.
Direct Known Subclasses:
DeleteBuilderImpl, SelectBuilderImpl
public abstract class QueryBuilder<T extends Record,R,ID> extends Object
QueryBuilder relies on preview features of the Java platform:
Programs can only use QueryBuilder when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A query builder that constructs a query from a template.

  • Constructor Details

    • QueryBuilder

      public QueryBuilder()

  • Method Details

    • typed

      public abstract <X> QueryBuilder<T,R,X> typed(@Nonnull Class<X> pkType)
      Returns a typed query builder for the specified primary key type.
      Type Parameters:
      X - the type of the primary key.
      Parameters:
      pkType - the primary key type.
      Returns:
      the typed query builder.
      Throws:
      PersistenceException - if the pk type is not valid.
      Since:
      1.2

    • safe

      public abstract QueryBuilder<T,R,ID> safe()
      Returns a query builder that does not require a WHERE clause for UPDATE and DELETE queries.

      This method is used to prevent accidental updates or deletions of all records in a table when a WHERE clause is not provided.

      Since:
      1.2

    • distinct

      public abstract QueryBuilder<T,R,ID> distinct()
      Marks the current query as a distinct query.
      Returns:
      the query builder.

    • crossJoin

      public abstract QueryBuilder<T,R,ID> crossJoin(@Nonnull Class<? extends Record> relation)
      Adds a cross join to the query.
      Parameters:
      relation - the relation to join.
      Returns:
      the query builder.

    • innerJoin

      public abstract QueryBuilder.TypedJoinBuilder<T,R,ID> innerJoin(@Nonnull Class<? extends Record> relation)
      Adds an inner join to the query.
      Parameters:
      relation - the relation to join.
      Returns:
      the query builder.

    • leftJoin

      public abstract QueryBuilder.TypedJoinBuilder<T,R,ID> leftJoin(@Nonnull Class<? extends Record> relation)
      Adds a left join to the query.
      Parameters:
      relation - the relation to join.
      Returns:
      the query builder.

    • rightJoin

      public abstract QueryBuilder.TypedJoinBuilder<T,R,ID> rightJoin(@Nonnull Class<? extends Record> relation)
      Adds a right join to the query.
      Parameters:
      relation - the relation to join.
      Returns:
      the query builder.

    • join

      public abstract QueryBuilder.TypedJoinBuilder<T,R,ID> join(@Nonnull JoinType type, @Nonnull Class<? extends Record> relation, @Nonnull String alias)
      Adds a join of the specified type to the query.
      Parameters:
      type - the type of the join (e.g., INNER, LEFT, RIGHT).
      relation - the relation to join.
      alias - the alias to use for the joined relation.
      Returns:
      the query builder.

    • crossJoin

      public abstract QueryBuilder<T,R,ID> crossJoin(@Nonnull StringTemplatePREVIEW template)
      Adds a cross join to the query.
      Parameters:
      template - the condition to join.
      Returns:
      the query builder.

    • innerJoin

      public abstract QueryBuilder.JoinBuilder<T,R,ID> innerJoin(@Nonnull StringTemplatePREVIEW template, @Nonnull String alias)
      Adds an inner join to the query.
      Parameters:
      template - the condition to join.
      alias - the alias to use for the joined relation.
      Returns:
      the query builder.

    • leftJoin

      public abstract QueryBuilder.JoinBuilder<T,R,ID> leftJoin(@Nonnull StringTemplatePREVIEW template, @Nonnull String alias)
      Adds a left join to the query.
      Parameters:
      template - the template to join.
      alias - the alias to use for the joined relation.
      Returns:
      the query builder.

    • rightJoin

      public abstract QueryBuilder.JoinBuilder<T,R,ID> rightJoin(@Nonnull StringTemplatePREVIEW template, @Nonnull String alias)
      Adds a right join to the query.
      Parameters:
      template - the template to join.
      alias - the alias to use for the joined relation.
      Returns:
      the query builder.

    • join

      public abstract QueryBuilder.JoinBuilder<T,R,ID> join(@Nonnull JoinType type, @Nonnull StringTemplatePREVIEW template, @Nonnull String alias)
      Adds a join of the specified type to the query using a template.
      Parameters:
      type - the join type.
      template - the template to join.
      alias - the alias to use for the joined relation.
      Returns:
      the query builder.

    • join

      public abstract QueryBuilder.JoinBuilder<T,R,ID> join(@Nonnull JoinType type, @Nonnull QueryBuilder<?,?,?> subquery, @Nonnull String alias)
      Adds a join of the specified type to the query using a subquery.
      Parameters:
      type - the join type.
      subquery - the subquery to join.
      alias - the alias to use for the joined relation.
      Returns:
      the query builder.

    • where

      public final QueryBuilder<T,R,ID> where(@Nonnull ID id)
      Adds a WHERE clause that matches the specified primary key of the table.
      Parameters:
      id - the id to match.
      Returns:
      the query builder.

    • where

      public final QueryBuilder<T,R,ID> where(@Nonnull Ref<T> ref)
      Adds a WHERE clause that matches the specified primary key of the table, expressed by a ref.
      Parameters:
      ref - the ref to match.
      Returns:
      the query builder.
      Since:
      1.3

    • where

      public final QueryBuilder<T,R,ID> where(@Nonnull T record)
      Adds a WHERE clause that matches the specified record.
      Parameters:
      record - the record to match.
      Returns:
      the query builder.

    • whereId

      public final QueryBuilder<T,R,ID> whereId(@Nonnull Iterable<? extends ID> it)
      Adds a WHERE clause that matches the specified primary keys of the table.
      Parameters:
      it - ids to match.
      Returns:
      the query builder.
      Since:
      1.2

    • whereRef

      public final QueryBuilder<T,R,ID> whereRef(@Nonnull Iterable<? extends Ref<T>> it)
      Adds a WHERE clause that matches the specified primary keys of the table, expressed by a ref.
      Parameters:
      it - refs to match.
      Returns:
      the query builder.
      Since:
      1.3

    • where

      public final <V extends Record> QueryBuilder<T,R,ID> where(@Nonnull Metamodel<T,V> path, @Nonnull V record)
      Adds a WHERE clause that matches the specified record. The record can represent any of the related tables in the table graph.
      Parameters:
      path - the path to the object in the table graph.
      record - the records to match.
      Returns:
      the predicate builder.

    • where

      public final <V extends Record> QueryBuilder<T,R,ID> where(@Nonnull Metamodel<T,V> path, @Nonnull Ref<V> ref)
      Adds a WHERE clause that matches the specified ref. The ref can represent any of the related tables in the table graph.
      Parameters:
      path - the path to the object in the table graph.
      ref - the ref to match.
      Returns:
      the predicate builder.
      Since:
      1.3

    • where

      public final <V extends Record> QueryBuilder<T,R,ID> where(@Nonnull Metamodel<T,V> path, @Nonnull Iterable<V> it)
      Adds a WHERE clause that matches the specified records. The records can represent any of the related tables in the table graph.
      Parameters:
      path - the path to the object in the table graph.
      it - the records to match.
      Returns:
      the predicate builder.

    • whereRef

      public final <V extends Record> QueryBuilder<T,R,ID> whereRef(@Nonnull Metamodel<T,V> path, @Nonnull Iterable<? extends Ref<V>> it)
      Adds a WHERE clause that matches the specified records. The records can represent any of the related tables in the table graph.
      Parameters:
      path - the path to the object in the table graph.
      it - the records to match.
      Returns:
      the predicate builder.
      Since:
      1.3

    • where

      public final QueryBuilder<T,R,ID> where(@Nonnull Iterable<? extends T> it)
      Adds a WHERE clause that matches the specified records.
      Parameters:
      it - the records to match.
      Returns:
      the query builder.

    • where

      public final <V> QueryBuilder<T,R,ID> where(@Nonnull Metamodel<T,V> path, @Nonnull Operator operator, @Nonnull Iterable<? extends V> it)
      Adds a WHERE clause that matches the specified objects at the specified path in the table graph.
      Type Parameters:
      V - the type of the object that the metamodel represents.
      Parameters:
      path - the path to the object in the table graph.
      operator - the operator to use for the comparison.
      it - the objects to match, which can be primary keys, records representing the table, or fields in the table graph.
      Returns:
      the query builder.
      Since:
      1.2

    • where

      @SafeVarargs public final <V> QueryBuilder<T,R,ID> where(@Nonnull Metamodel<T,V> path, @Nonnull Operator operator, @Nonnull V... o)
      Adds a WHERE clause that matches the specified objects at the specified path in the table graph.
      Type Parameters:
      V - the type of the object that the metamodel represents.
      Parameters:
      path - the path to the object in the table graph.
      operator - the operator to use for the comparison.
      o - the object(s) to match, which can be primary keys, records representing the table, or fields in the table graph.
      Returns:
      the query builder.
      Since:
      1.2

    • where

      public final QueryBuilder<T,R,ID> where(@Nonnull StringTemplatePREVIEW template)
      Adds a WHERE clause to the query for the specified expression.
      Parameters:
      template - the expression.
      Returns:
      the query builder.

    • where

      public abstract QueryBuilder<T,R,ID> where(@Nonnull Function<QueryBuilder.WhereBuilder<T,R,ID>,QueryBuilder.PredicateBuilder<?,?,?>> predicate)
      Adds a WHERE clause to the query using a QueryBuilder.WhereBuilder.
      Parameters:
      predicate - the predicate to add.
      Returns:
      the query builder.

    • groupBy

      public final QueryBuilder<T,R,ID> groupBy(@Nonnull Metamodel<T,?> path)
      Adds a GROUP BY clause to the query for field at the specified path in the table graph.
      Parameters:
      path - the path to group by.
      Returns:
      the query builder.
      Since:
      1.2

    • groupBy

      @SafeVarargs public final QueryBuilder<T,R,ID> groupBy(@Nonnull Metamodel<T,?>... path)
      Adds a GROUP BY clause to the query for field at the specified path in the table graph. The metamodel can refer to manually added joins.
      Parameters:
      path - the path to group by.
      Returns:
      the query builder.
      Since:
      1.2

    • groupByAny

      public final QueryBuilder<T,R,ID> groupByAny(@Nonnull Metamodel<?,?>... path)
      Adds a GROUP BY clause to the query for field at the specified path in the table graph. The metamodel can refer to manually added joins.
      Parameters:
      path - the path to group by.
      Returns:
      the query builder.
      Since:
      1.2

    • groupBy

      public final QueryBuilder<T,R,ID> groupBy(@Nonnull StringTemplatePREVIEW template)
      Adds a GROUP BY clause to the query using a string template.
      Parameters:
      template - the template to group by.
      Returns:
      the query builder.
      Since:
      1.2

    • having

      @SafeVarargs public final <V> QueryBuilder<T,R,ID> having(@Nonnull Metamodel<T,V> path, @Nonnull Operator operator, @Nonnull V... o)
      Adds a HAVING clause to the query using the specified expression.
      Parameters:
      path - the path to the object in the table graph.
      operator - the operator to use for the comparison.
      o - the object(s) to match, which can be primary keys, records representing the table, or fields in the table graph.
      Returns:
      the query builder.
      Since:
      1.2

    • havingAny

      @SafeVarargs public final <V> QueryBuilder<T,R,ID> havingAny(@Nonnull Metamodel<?,V> path, @Nonnull Operator operator, @Nonnull V... o)
      Adds a HAVING clause to the query using the specified expression. The metamodel can refer to manually added joins.
      Parameters:
      path - the path to the object in the table graph.
      operator - the operator to use for the comparison.
      o - the object(s) to match, which can be primary keys, records representing the table, or fields in the table graph or manually added joins.
      Returns:
      the query builder.
      Since:
      1.2

    • having

      public final QueryBuilder<T,R,ID> having(@Nonnull StringTemplatePREVIEW template)
      Adds a HAVING clause to the query using the specified expression.
      Parameters:
      template - the expression to add.
      Returns:
      the query builder.
      Since:
      1.2

    • orderBy

      public final QueryBuilder<T,R,ID> orderBy(@Nonnull Metamodel<T,?> path)
      Adds an ORDER BY clause to the query for the field at the specified path in the table graph.
      Parameters:
      path - the path to order by.
      Returns:
      the query builder.
      Since:
      1.2

    • orderByDescending

      public final QueryBuilder<T,R,ID> orderByDescending(@Nonnull Metamodel<T,?> path)
      Adds an ORDER BY clause to the query for the field at the specified path in the table graph. The results are sorted in descending order.
      Parameters:
      path - the path to order by.
      Returns:
      the query builder.
      Since:
      1.2

    • orderBy

      @SafeVarargs public final QueryBuilder<T,R,ID> orderBy(@Nonnull Metamodel<T,?>... path)
      Adds an ORDER BY clause to the query for the field at the specified path in the table graph.
      Parameters:
      path - the path to order by.
      Returns:
      the query builder.
      Since:
      1.2

    • orderByAny

      public final QueryBuilder<T,R,ID> orderByAny(@Nonnull Metamodel<?,?>... path)
      Adds an ORDER BY clause to the query for the field at the specified path in the table graph or manually added joins.
      Parameters:
      path - the path to order by.
      Returns:
      the query builder.
      Since:
      1.2

    • orderBy

      public final QueryBuilder<T,R,ID> orderBy(@Nonnull StringTemplatePREVIEW template)
      Adds an ORDER BY clause to the query using a string template.
      Parameters:
      template - the template to order by.
      Returns:
      the query builder.
      Since:
      1.2

    • limit

      public abstract QueryBuilder<T,R,ID> limit(int limit)
      Adds a LIMIT clause to the query.
      Parameters:
      limit - the maximum number of records to return.
      Returns:
      the query builder.
      Since:
      1.2

    • offset

      public abstract QueryBuilder<T,R,ID> offset(int offset)
      Adds an OFFSET clause to the query.
      Parameters:
      offset - the offset.
      Returns:
      the query builder.
      Since:
      1.2

    • append

      public abstract QueryBuilder<T,R,ID> append(@Nonnull StringTemplatePREVIEW template)
      Append the query with a string template.
      Parameters:
      template - the string template to append.
      Returns:
      the query builder.

    • forShare

      public abstract QueryBuilder<T,R,ID> forShare()
      Locks the selected rows for reading.
      Returns:
      the query builder.
      Throws:
      PersistenceException - if the database does not support the specified lock mode, or if the lock mode is not supported for the current query.
      Since:
      1.2

    • forUpdate

      public abstract QueryBuilder<T,R,ID> forUpdate()
      Locks the selected rows for reading.
      Returns:
      the query builder.
      Throws:
      PersistenceException - if the database does not support the specified lock mode, or if the lock mode is not supported for the current query.
      Since:
      1.2

    • forLock

      public abstract QueryBuilder<T,R,ID> forLock(@Nonnull StringTemplatePREVIEW template)
      Locks the selected rows using a custom lock mode.

      Note that this method results in non-portable code, as the lock mode is specific to the underlying database.

      Returns:
      the query builder.
      Throws:
      PersistenceException - if the lock mode is not supported for the current query.
      Since:
      1.2

    • build

      public abstract Query build()
      Builds the query based on the current state of the query builder.
      Returns:
      the constructed query.

    • prepare

      public final PreparedQuery prepare()
      Prepares the query for execution.

      Unlike regular queries, which are constructed lazily, prepared queries are constructed eagerly. Prepared queries allow the use of bind variables and enable reading generated keys after row insertion.

      Note that the prepared query must be closed after usage to prevent resource leaks. As the prepared query is AutoCloseable, it is recommended to use it within a try-with-resources block.

      Returns:
      the prepared query.
      Throws:
      PersistenceException - if the query preparation fails.

    • getResultStream

      public abstract Stream<R> getResultStream()
      Executes the query and returns a stream of results.

      The resulting stream is lazily loaded, meaning that the records are only retrieved from the database as they are consumed by the stream. This approach is efficient and minimizes the memory footprint, especially when dealing with large volumes of records.

      Note that calling this method does trigger the execution of the underlying query, so it should only be invoked when the query is intended to run. Since the stream holds resources open while in use, it must be closed after usage to prevent resource leaks. As the stream is AutoCloseable, it is recommended to use it within a try-with-resources block.

      Returns:
      a stream of results.
      Throws:
      PersistenceException - if the query operation fails due to underlying database issues, such as connectivity.

    • getResult

      public final <X> X getResult(@Nonnull ResultCallback<R,X> callback)
      Executes the query and returns a stream of using the specified callback. This method retrieves the records and applies the provided callback to process them, returning the result produced by the callback.

      This method ensures efficient handling of large data sets by loading entities only as needed. It also manages lifecycle of the callback stream, automatically closing the stream after processing to prevent resource leaks.

      Type Parameters:
      X - the type of result produced by the callback after processing the entities.
      Parameters:
      callback - a ResultCallback defining how to process the stream of records and produce a result.
      Returns:
      the result produced by the callback's processing of the record stream.
      Throws:
      PersistenceException - if the query operation fails due to underlying database issues, such as connectivity.

    • getResultCount

      public final long getResultCount()
      Returns the number of results of this query.
      Returns:
      the total number of results of this query as a long value.
      Throws:
      PersistenceException - if the query operation fails due to underlying database issues, such as connectivity.

    • getResultList

      public final List<R> getResultList()
      Executes the query and returns a list of results.
      Returns:
      the list of results.
      Throws:
      PersistenceException - if the query fails.

    • getSingleResult

      public final R getSingleResult()
      Executes the query and returns a single result.
      Returns:
      the single result.
      Throws:
      NoResultException - if there is no result.
      NonUniqueResultException - if more than one result.
      PersistenceException - if the query fails.

    • getOptionalResult

      public final Optional<R> getOptionalResult()
      Executes the query and returns an optional result.
      Returns:
      the optional result.
      Throws:
      NonUniqueResultException - if more than one result.
      PersistenceException - if the query fails.

    • executeUpdate

      public final int executeUpdate()
      Execute a DELETE statement.
      Returns:
      the number of rows impacted as result of the statement.
      Throws:
      PersistenceException - if the statement fails.

    • slice

      public static <X, Y> Stream<Y> slice(@Nonnull Stream<X> stream, int batchSize, @Nonnull Function<List<X>,Stream<Y>> function)
      Performs the function in multiple batches, each containing up to batchSize elements from the stream.
      Type Parameters:
      X - the type of elements in the stream.
      Y - the type of elements in the result stream.
      Parameters:
      stream - the stream to batch.
      batchSize - the maximum number of elements to include in each batch.
      function - the function to apply to each batch.
      Returns:
      a stream of results from each batch.

    • slice

      public static <X> Stream<List<X>> slice(@Nonnull Stream<X> stream, int size)
      Generates a stream of slices, each containing a subset of elements from the original stream up to a specified size. This method is designed to facilitate batch processing of large streams by dividing the stream into smaller manageable slices, which can be processed independently.

      If the specified size is equal to Integer.MAX_VALUE, this method will return a single slice containing the original stream, effectively bypassing the slicing mechanism. This is useful for operations that can handle all elements at once without the need for batching.

      Type Parameters:
      X - the type of elements in the stream.
      Parameters:
      stream - the original stream of elements to be sliced.
      size - the maximum number of elements to include in each slice. If size is Integer.MAX_VALUE, only one slice will be returned.
      Returns:
      a stream of slices, where each slice contains up to size elements from the original stream.