Module storm.java
Package st.orm.template

Interface Query

All Known Subinterfaces:
PreparedQuery
public interface Query
Represents a constructed SQL statement that is ready for execution.

Query is the result of building a query via the QueryBuilder or the QueryTemplate.query(StringTemplate)PREVIEW method. It supports both DQL (Data Query Language) statements such as SELECT, and DML (Data Manipulation Language) statements such as INSERT, UPDATE, and DELETE.

For SELECT statements, results can be retrieved as streams, lists, single results, or optional results. The result type can be raw Object[] arrays (columns in order) or mapped to a specific record type.

For DML statements (INSERT, UPDATE, DELETE), use executeUpdate() to execute the statement and obtain the number of affected rows. For batch operations, use executeBatch().

A query can also be converted to a PreparedQuery via prepare(), which enables bind variable usage, batch processing, and retrieval of generated keys.

Example: Execute a raw query


 List<User> users = orm.query(RAW."""
         SELECT \{User.class}
         FROM \{User.class}
         WHERE \{User_.name} = \{"Alice"}""")
     .getResultList(User.class);
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    int[]
    executeBatch()
    Execute a batch of commands.
    int
    executeUpdate()
    Execute a command, such as an INSERT, UPDATE, or DELETE statement.
    default Optional<Object[]>
    getOptionalResult()
    Execute a SELECT query and returns a single row, where the columns of the row corresponds to the order of values in the list.
    default <T> Optional<T>
    getOptionalResult(Class<T> type)
    Execute a SELECT query and returns a single row, where the columns of the row are mapped to the constructor arguments of the specified type.
    default <T extends Data>
    List<Ref<T>>
    getRefList(Class<T> type, Class<?> pkType)
    Execute a SELECT query and return the resulting rows as a list of ref instances.
    <T extends Data>
    Stream<Ref<T>>
    getRefStream(Class<T> type, Class<?> pkType)
    Execute a SELECT query and return the resulting rows as a stream of ref instances.
    default long
    getResultCount()
    Returns the number of results of this query.
    default List<Object[]>
    getResultList()
    Execute a SELECT query and return the resulting rows as a list of row instances.
    default <T> List<T>
    getResultList(Class<T> type)
    Execute a SELECT query and return the resulting rows as a list of row instances.
    Stream<Object[]>
    getResultStream()
    Execute a SELECT query and return the resulting rows as a stream of row instances.
    <T> Stream<T>
    getResultStream(Class<T> type)
    Execute a SELECT query and return the resulting rows as a stream of row instances.
    default Object[]
    getSingleResult()
    Execute a SELECT query and returns a single row, where the columns of the row corresponds to the order of values in the list.
    default <T> T
    getSingleResult(Class<T> type)
    Execute a SELECT query and returns a single row, where the columns of the row are mapped to the constructor arguments of the specified type.
    boolean
    isVersionAware()
    Returns true if the query is version aware, false otherwise.
    PreparedQuery
    prepare()
    Prepares the query for execution.
    Query
    unsafe()
    Returns a new query that allows dangerous operations, such as DELETE and UPDATE without a WHERE clause.

  • Method Details

    • prepare

      PreparedQuery prepare()
      Prepares the query for execution.

      Queries are normally constructed in a lazy fashion, unlike prepared queries which are constructed eagerly. Prepared queries allow the use of bind variables and enable reading generated keys after row insertion.

      Note: 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.

    • unsafe

      Query unsafe()
      Returns a new query that allows dangerous operations, such as DELETE and UPDATE without a WHERE clause.
      Returns:
      a new query that allows dangerous operations.
      Since:
      1.2

    • getSingleResult

      default Object[] getSingleResult()
      Execute a SELECT query and returns a single row, where the columns of the row corresponds to the order of values in the list.
      Returns:
      a single row, where the columns of the row corresponds to the order of values the list.
      Throws:
      NoResultException - if there is no result.
      NonUniqueResultException - if more than one result.
      PersistenceException - if the query fails.

    • getOptionalResult

      default Optional<Object[]> getOptionalResult()
      Execute a SELECT query and returns a single row, where the columns of the row corresponds to the order of values in the list.
      Returns:
      a single row, where the columns of the row corresponds to the order of values the list, or an empty optional if there is no result.
      Throws:
      NonUniqueResultException - if more than one result.
      PersistenceException - if the query fails.

    • getResultCount

      default 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.

    • getSingleResult

      default <T> T getSingleResult(@Nonnull Class<T> type)
      Execute a SELECT query and returns a single row, where the columns of the row are mapped to the constructor arguments of the specified type.
      Parameters:
      type - the type of the result.
      Returns:
      a single row, where the columns of the row corresponds to the order of values the list.
      Throws:
      NoResultException - if there is no result.
      NonUniqueResultException - if more than one result.
      PersistenceException - if the query fails.

    • getOptionalResult

      default <T> Optional<T> getOptionalResult(@Nonnull Class<T> type)
      Execute a SELECT query and returns a single row, where the columns of the row are mapped to the constructor arguments of the specified type.
      Parameters:
      type - the type of the result.
      Returns:
      a single row, where the columns of the row corresponds to the order of values the list, or an empty optional if there is no result.
      Throws:
      NonUniqueResultException - if more than one result.
      PersistenceException - if the query fails.

    • getResultList

      default List<Object[]> getResultList()
      Execute a SELECT query and return the resulting rows as a list of row instances.

      Each element in the list represents a row in the result, where the columns of the row corresponds to the order of values in the row array.

      Returns:
      the result list.
      Throws:
      PersistenceException - if the query fails.

    • getResultList

      default <T> List<T> getResultList(@Nonnull Class<T> type)
      Execute a SELECT query and return the resulting rows as a list of row instances.

      Each element in the list represents a row in the result, where the columns of the row are mapped to the constructor arguments of the specified type.

      Parameters:
      type - the type of the result.
      Returns:
      the result list.
      Throws:
      PersistenceException - if the query fails.

    • getRefList

      default <T extends Data> List<Ref<T>> getRefList(@Nonnull Class<T> type, @Nonnull Class<?> pkType)
      Execute a SELECT query and return the resulting rows as a list of ref instances.

      Each element in the list represents a row in the result, where the columns of the row are mapped to the constructor arguments primary key type.

      Parameters:
      type - the type of the results that are being referenced.
      pkType - the primary key type.
      Returns:
      the result list.
      Throws:
      PersistenceException - if the query fails.
      Since:
      1.3

    • getResultStream

      Stream<Object[]> getResultStream()
      Execute a SELECT query and return the resulting rows as a stream of row instances.

      Each element in the stream represents a row in the result, where the columns of the row corresponds to the order of values in the row array.

      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: 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.

    • getResultStream

      <T> Stream<T> getResultStream(@Nonnull Class<T> type)
      Execute a SELECT query and return the resulting rows as a stream of row instances.

      Each element in the stream represents a row in the result, where the columns of the row are mapped to the constructor arguments of the specified type.

      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: 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.

    • getRefStream

      <T extends Data> Stream<Ref<T>> getRefStream(@Nonnull Class<T> type, @Nonnull Class<?> pkType)
      Execute a SELECT query and return the resulting rows as a stream of ref instances.

      Each element in the stream represents a row in the result, where the columns of the row are mapped to the constructor arguments primary key type.

      Note: 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.

      Parameters:
      type - the type of the results that are being referenced.
      pkType - the primary key type.
      Returns:
      a stream of ref instances.
      Throws:
      PersistenceException - if the query fails.
      Since:
      1.3

    • isVersionAware

      boolean isVersionAware()
      Returns true if the query is version aware, false otherwise.
      Returns:
      true if the query is version aware, false otherwise.

    • executeUpdate

      int executeUpdate()
      Execute a command, such as an INSERT, UPDATE, or DELETE statement.
      Returns:
      the number of rows impacted as result of the statement.
      Throws:
      PersistenceException - if the statement fails.

    • executeBatch

      int[] executeBatch()
      Execute a batch of commands.
      Returns:
      an array of update counts containing one element for each command in the batch. The elements of the array are ordered according to the order in which commands were added to the batch, following Statement.executeBatch semantics.
      Throws:
      PersistenceException - if the batch fails.