Module storm.java
Package st.orm.template

Class WhereBuilder<T extends Data,R,ID>

java.lang.Object
st.orm.template.WhereBuilder<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.
All Implemented Interfaces:
SubqueryTemplate
public abstract class WhereBuilder<T extends Data,R,ID> extends Object implements SubqueryTemplate
WhereBuilder relies on preview features of the Java platform:
Programs can only use WhereBuilder when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A builder for constructing the WHERE clause of a query, providing type-safe predicate construction.

The WhereBuilder is passed to the lambda argument of QueryBuilder.where(java.util.function.Function) and offers methods for matching by primary key, record, ref, metamodel path, or custom string template expressions. Each method returns a PredicateBuilder that can be further composed using and() and or() combinators.

The where methods are type-safe and restrict metamodel paths to the root table's entity graph. A join widens the query root, after which the where methods accept paths from any entity in the query; a path on an entity outside the query fails when the query is built.

Example


 List<User> users = userRepository
         .select()
         .where(predicate -> predicate
             .where(User_.email, LIKE, "%@example.com")
             .and(predicate.where(User_.address.city.name, EQUALS, "Sunnyvale")))
         .getResultList();
See Also:

  • Constructor Details

    • WhereBuilder

      public WhereBuilder()

  • Method Details

    • TRUE

      public final PredicateBuilder<T,R,ID> TRUE()
      A predicate that always evaluates to true.

      It renders as 1 = 1, a comparison every database reads as a condition, where a boolean literal is not one on SQL Server or on Oracle before 23.

    • FALSE

      public final PredicateBuilder<T,R,ID> FALSE()
      A predicate that always evaluates to false.

      It renders as 1 <> 1, a comparison every database reads as a condition, where a boolean literal is not one on SQL Server or on Oracle before 23.

    • exists

      public abstract PredicateBuilder<T,R,ID> exists(QueryBuilder<?,?,?> subquery)
      Adds an EXISTS condition to the WHERE clause using the specified subquery.

      This method appends an EXISTS clause to the current query's WHERE condition. It checks whether the provided subquery returns any rows, allowing you to filter results based on the existence of related data. This is particularly useful for constructing queries that need to verify the presence of certain records in a related table or subquery.

      Parameters:
      subquery - the subquery to check for existence.
      Returns:
      the updated PredicateBuilder with the EXISTS condition applied.

    • notExists

      public abstract PredicateBuilder<T,R,ID> notExists(QueryBuilder<?,?,?> subquery)
      Adds an NOT EXISTS condition to the WHERE clause using the specified subquery.

      This method appends an NOT EXISTS clause to the current query's WHERE condition. It checks whether the provided subquery returns any rows, allowing you to filter results based on the existence of related data. This is particularly useful for constructing queries that need to verify the absence of certain records in a related table or subquery.

      Parameters:
      subquery - the subquery to check for existence.
      Returns:
      the updated PredicateBuilder with the NOT EXISTS condition applied.

    • whereId

      public abstract PredicateBuilder<T,R,ID> whereId(ID id)
      Adds a condition to the WHERE clause that matches the specified primary key of the table.
      Parameters:
      id - the id to match.
      Returns:
      the predicate builder.

    • whereRef

      public abstract PredicateBuilder<T,R,ID> whereRef(Ref<T> ref)
      Adds a condition to the WHERE clause that matches the specified primary key of the table, expressed by a ref.
      Parameters:
      ref - the ref to match.
      Returns:
      the predicate builder.
      Since:
      1.3

    • where

      public abstract PredicateBuilder<T,R,ID> where(T record)
      Adds a condition to the WHERE clause that matches the specified record.
      Parameters:
      record - the record to match.
      Returns:
      the predicate builder.

    • whereId

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

    • whereRef

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

    • where

      public abstract PredicateBuilder<T,R,ID> where(Iterable<? extends T> it)
      Adds a condition to the WHERE clause that matches the specified records.
      Parameters:
      it - the records to match.
      Returns:
      the predicate builder.

    • where

      public final <V extends Data> PredicateBuilder<T,R,ID> where(Navigable<? extends T,V> path, V record)
      Adds a condition to the 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 abstract <V extends Data> PredicateBuilder<T,R,ID> where(Navigable<? extends T,V> path, Ref<V> ref)
      Adds a condition to the WHERE clause that matches the specified ref. The record 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

    • whereRef

      public abstract <V extends Data> PredicateBuilder<T,R,ID> whereRef(Navigable<? extends T,V> path, Iterable<? extends Ref<V>> it)
      Adds a condition to the WHERE clause that matches the specified refs. The refs can represent any of the related tables in the table graph.
      Parameters:
      path - the path to the ref in the table graph.
      it - the refs to match.
      Returns:
      the predicate builder.
      Since:
      1.3

    • where

      public final <V extends Data> PredicateBuilder<T,R,ID> where(Navigable<? extends T,V> path, Iterable<V> it)
      Adds a condition to the 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.

    • where

      public abstract <V> PredicateBuilder<T,R,ID> where(Navigable<? extends T,V> path, Operator operator, Iterable<? extends V> it)
      Adds a condition to the 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> PredicateBuilder<T,R,ID> where(Navigable<? extends T,V> path, Operator operator, V... o)
      Adds a condition to the 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 abstract <V> PredicateBuilder<T,R,ID> where(Navigable<? extends T,V> path, Operator operator, Navigable<?,V> other)
      Adds a condition to the WHERE clause that compares the column at the specified path with the column at another path of the query, such as a foreign key with a foreign key to the same table. Both paths resolve as they do in a value comparison: to a table of the query, or to a path joined on demand; a path on a table outside the query is refused when the query is built. A multi-column path compares component-wise with a path of as many columns.
      Type Parameters:
      V - the type of the value both columns hold.
      Parameters:
      path - the path to the column on the left of the operator.
      operator - the operator to use for the comparison.
      other - the path to the column on the right of the operator.
      Returns:
      the predicate builder.
      Since:
      1.16

    • search

      @SafeVarargs public final PredicateBuilder<T,R,ID> search(String input, Navigable<? extends T,String> path, Navigable<? extends T,String>... more)
      Matches the words of a search input against one or more text columns. Every word must occur in at least one of the paths, ignoring case and matched as literal text, as Operator.CONTAINS_IGNORE_CASE matches it, so search("davis madison", Owner_.lastName, Owner_.address.city.name) finds Harold Davis of Madison. Whitespace separates the words, and a quote at the start of a word opens a phrase such as "the good", one word that runs to the next quote or to the end of the input; a quote inside a word is an ordinary character. An input without words, such as an empty search box, matches every row. search(String, Match, Match[]) states another match form per column.

      A path through a relation joins its table as any other path does, and a path may start at a table the query joins. A path may also start at a semi-joined table, which searches the rows related to each row; each word is matched on its own, so the words may match different related rows. Accents compare as the column's collation compares them.

      Until a word reaches three characters, the whole input matches as the start of the value, ignoring case, and an input of one character matches no rows; a shorter word next to a longer one is tested only on the rows the longer word found, so it reads no table in full. A search box that queries as the user types, such as an auto-complete, uses suggest(String, Navigable, Navigable[]) instead.

      Parameters:
      input - the search input, as a search box receives it.
      path - the first text column to search.
      more - further text columns to search.
      Returns:
      the predicate builder.
      Since:
      1.15

    • search

      @SafeVarargs public final PredicateBuilder<T,R,ID> search(String input, Set<String> ignore, Navigable<? extends T,String> path, Navigable<? extends T,String>... more)
      Matches the words of a search input against one or more text columns, as search(String, Navigable, Navigable[]) does, ignoring the given words as well. A word that equals one of them, ignoring case, takes no part in the predicate, so an input of ignored words alone matches every row, as an empty input does; a quoted word is never ignored. The whole input, ignored words included, still matches as the start of the value while no word reaches three characters. A search names the words that occur in a large share of its rows, such as "van" in a list of last names: matched anywhere, such a word narrows almost nothing, and a row without it is not found. search("van berg", Set.of("van", "de", "der"), Owner_.lastName) matches on "berg" alone.
      Parameters:
      input - the search input, as a search box receives it.
      ignore - the words to ignore, compared ignoring case.
      path - the first text column to search.
      more - further text columns to search.
      Returns:
      the predicate builder.
      Since:
      1.16

    • search

      @SafeVarargs public final PredicateBuilder<T,R,ID> search(String input, Match<? extends T> field, Match<? extends T>... more)
      Matches the words of a search input against text columns, each in its stated match form, as search(String, Navigable, Navigable[]) matches them anywhere in the value. A field states its form through the factories of Match: anywhere, wordStart, prefix, prefixIgnoreCase, exact or exactIgnoreCase; search("van berg", wordStart(Owner_.lastName), exact(Owner_.telephone)) matches each word at the start of a word of the last name or as the whole telephone number.
      Parameters:
      input - the search input, as a search box receives it.
      field - the first text column to search, with its match form.
      more - further text columns to search, with their match forms.
      Returns:
      the predicate builder.
      Since:
      1.16

    • search

      @SafeVarargs public final PredicateBuilder<T,R,ID> search(String input, Set<String> ignore, Match<? extends T> field, Match<? extends T>... more)
      Matches the words of a search input against text columns, each in its stated match form, as search(String, Match, Match[]) does, ignoring the given words as well, as search(String, Set, Navigable, Navigable[]) ignores them. A quoted word is never ignored.
      Parameters:
      input - the search input, as a search box receives it.
      ignore - the words to ignore, compared ignoring case.
      field - the first text column to search, with its match form.
      more - further text columns to search, with their match forms.
      Returns:
      the predicate builder.
      Since:
      1.16

    • suggest

      @SafeVarargs public final PredicateBuilder<T,R,ID> suggest(String input, Navigable<? extends T,String> path, Navigable<? extends T,String>... more)
      Matches the words of a search box that queries as the user types, such as an auto-complete, against one or more text columns. Every word matches at the start of a word in one of the columns, the same rows on every database: suggest("van b", Owner_.lastName) finds "Van den Berg" and not "Sullivan". The input is read as search(String, Navigable, Navigable[]) reads it. An input without a word of three characters matches as the start of the value, ignoring case, and a shorter word next to one that reaches the length is tested only on the rows the longer word found. An empty input, or one of a single character, matches no rows, so the box never fetches and sorts a whole table on the first keystroke. suggest(String, Match, Match[]) states another match form per column.
      Parameters:
      input - the search input, as a search box receives it.
      path - the first text column to search.
      more - further text columns to search.
      Returns:
      the predicate builder.
      Since:
      1.16

    • suggest

      @SafeVarargs public final PredicateBuilder<T,R,ID> suggest(String input, Set<String> ignore, Navigable<? extends T,String> path, Navigable<? extends T,String>... more)
      Matches the words of a search box that queries as the user types against one or more text columns, as suggest(String, Navigable, Navigable[]) does, ignoring the given words as well. A word that equals one of them, ignoring case, takes no part in the predicate, so an input of ignored words alone matches no rows; a quoted word is never ignored. A search box names the words that occur in a large share of its rows, such as "van" in a list of last names, which narrow nothing: suggest("van berg", Set.of("van", "de", "der"), Owner_.lastName) matches on "berg" alone.
      Parameters:
      input - the search input, as a search box receives it.
      ignore - the words to ignore, compared ignoring case.
      path - the first text column to search.
      more - further text columns to search.
      Returns:
      the predicate builder.
      Since:
      1.16

    • suggest

      @SafeVarargs public final PredicateBuilder<T,R,ID> suggest(String input, Match<? extends T> field, Match<? extends T>... more)
      Matches the words of a search box that queries as the user types against text columns, each in its stated match form, as suggest(String, Navigable, Navigable[]) matches them at the start of a word. A field states its form through the factories of Match: anywhere, wordStart, prefix, prefixIgnoreCase, exact or exactIgnoreCase; suggest(input, wordStart(Owner_.lastName), prefix(OwnerNameSuffix_.suffix)) matches each word at the start of a word of the name, or as a prefix of a suffix row, which an ordinary index serves. Until a word reaches a field's minLength, the field matches the whole input in its fallback.
      Parameters:
      input - the search input, as a search box receives it.
      field - the first text column to search, with its match form.
      more - further text columns to search, with their match forms.
      Returns:
      the predicate builder.
      Since:
      1.16

    • suggest

      @SafeVarargs public final PredicateBuilder<T,R,ID> suggest(String input, Set<String> ignore, Match<? extends T> field, Match<? extends T>... more)
      Matches the words of a search box that queries as the user types against text columns, each in its stated match form, as suggest(String, Match, Match[]) does, ignoring the given words as well, as suggest(String, Set, Navigable, Navigable[]) ignores them. A quoted word is never ignored.
      Parameters:
      input - the search input, as a search box receives it.
      ignore - the words to ignore, compared ignoring case.
      field - the first text column to search, with its match form.
      more - further text columns to search, with their match forms.
      Returns:
      the predicate builder.
      Since:
      1.16

    • where

      public abstract PredicateBuilder<T,R,ID> where(StringTemplatePREVIEW template)
      Appends a custom expression to the WHERE clause.
      Parameters:
      template - the expression to add.
      Returns:
      the predicate builder.