Interface Query

All Known Subinterfaces:
TypedQuery<T>
public interface Query
Query represents a string-based query execution interface used in Jakarta NoSQL. It provides a consistent mechanism for dynamically executing queries using either named or positional parameters, and supports core query operations such as SELECT, UPDATE, and DELETE. This API is based on Jakarta Query and supports the Jakarta Common Query Language (JCQL), including clauses such as SELECT, WHERE, ORDER BY, UPDATE SET, and DELETE FROM.

This class is mutable and therefore not thread-safe. It is intended to be used in a single-threaded or scoped manner per operation or request.

Usage constraints:

Example usage for SELECT:

  List<Person> people = template.query("SELECT * FROM Person WHERE active = true").result();

Example usage for DELETE:

template.query("DELETE FROM Person WHERE active = false")
        .executeUpdate();

Example usage for UPDATE:

template.query("UPDATE Person SET active = true WHERE name = 'Ada'")
        .executeUpdate();
Since:
1.1.0

  • Method Summary

    Modifier and Type
    Method
    Description
    Query
    bind(int position, Object value)
    Binds a positional parameter to the query.
    Query
    bind(String name, Object value)
    Binds a named parameter to the query.
    void
    executeUpdate()
    Executes a write operation query (such as UPDATE or DELETE).
    <T> List<T>
    result()
    Executes a SELECT query and returns the result as a List.
    <T> Optional<T>
    singleResult()
    Executes a SELECT query and returns a single result wrapped in an Optional.
    <T> Stream<T>
    stream()
    Executes a SELECT query and returns the result as a Stream.

  • Method Details

    • executeUpdate

      void executeUpdate()
      Executes a write operation query (such as UPDATE or DELETE).

      This method performs non-select operations. If the query is a SELECT, it will throw an UnsupportedOperationException.

      Note: Since some NoSQL databases use eventual consistency or append-only write models, the effects of this operation may not be immediately visible. The propagation of the update or delete may vary depending on the database implementation and its consistency guarantees.

      If required parameters (named or positional) are not bound, this operation will fail, and the provider may throw an exception. 

      template.query("DELETE FROM Person WHERE age < :minAge")
        .bind("minAge", 18)
        .executeUpdate();
      Throws:
      UnsupportedOperationException - if the query is a SELECT, or the operation is not supported by the provider

    • result

      <T> List<T> result()
      Executes a SELECT query and returns the result as a List.

      This method must only be used for queries that begin with SELECT. If the query is an UPDATE or DELETE, an UnsupportedOperationException will be thrown.

      If required parameters are not bound before execution, the query will fail and the provider will raise an exception or error. 

      List<Person> adults = template.query("SELECT * FROM Person WHERE age >= :minAge")
                              .bind("minAge", 18)
                              .result();
      Type Parameters:
      T - the type of the entity
      Returns:
      list of results or an empty list
      Throws:
      UnsupportedOperationException - if the query is not a SELECT

    • stream

      <T> Stream<T> stream()
      Executes a SELECT query and returns the result as a Stream.

      This method must only be used for queries that begin with SELECT. If the query is an UPDATE or DELETE, an UnsupportedOperationException will be thrown.

      If required parameters are not bound before execution, the query will fail and the provider will raise an exception or error. 

      Stream<Person> stream = template.query("SELECT * FROM Person WHERE active = true")
                                 .stream();
      Type Parameters:
      T - the type of the entity
      Returns:
      a stream of results
      Throws:
      UnsupportedOperationException - if the query is not a SELECT

    • singleResult

      <T> Optional<T> singleResult()
      Executes a SELECT query and returns a single result wrapped in an Optional.

      If no result is found, returns Optional.empty(). If more than one result is found, the behavior is provider-specific and may throw an exception.

      This method must only be used for queries that begin with SELECT. If the query is an UPDATE or DELETE, an UnsupportedOperationException will be thrown.

      If required parameters are not bound before execution, the query will fail and the provider will raise an exception or error. 

      Optional<Person> person = template.query("SELECT * FROM Person WHERE id = :id")
                                  .bind("id", "p-001")
                                  .singleResult();
      Type Parameters:
      T - the type of the entity
      Returns:
      optional result
      Throws:
      UnsupportedOperationException - if the query is not a SELECT
      Since:
      1.1.0

    • bind

      Query bind(String name, Object value)
      Binds a named parameter to the query. 
      Query query = template.query("SELECT * FROM Book WHERE title = :title")
                      .bind("title", "Effective Java");
      Parameters:
      name - the parameter name (without :)
      value - the value to bind
      Returns:
      this query instance for fluent chaining
      Throws:
      NullPointerException - if the name is null

    • bind

      Query bind(int position, Object value)
      Binds a positional parameter to the query. Positions are 1-based. 
      Query query = template.query("SELECT * FROM Person WHERE age > ?1")
                      .bind(1, 30);
      Parameters:
      position - the parameter position (starting at 1)
      value - the value to bind
      Returns:
      this query instance for fluent chaining
      Throws:
      IllegalArgumentException - if position is less than 1