Module storm.foundation
Package st.orm

Interface Match<T extends Data>

Type Parameters:
T - the root table type of the column.
All Known Implementing Classes:
Match.Anywhere, Match.Exact, Match.Prefix, Match.WordStart
public sealed interface Match<T extends Data> permits Match.Anywhere<T>, Match.WordStart<T>, Match.Prefix<T>, Match.Exact<T>
A text column of a search or suggest with the form a typed word matches it in. A word matches anywhere in the value, at the start of any word in it, as a prefix of the value, or the whole value; every form compares ignoring case, and each finds the same rows on every database. The default form of search is anywhere, that of suggest is wordStart; a call that states the form states it for every column.

prefix and exact leave the column bare and lower the word, so an ordinary index over the column serves them; the column is then one that compares case-insensitively on its own, through its collation or as a stored lowered column. prefixIgnoreCase and exactIgnoreCase lower the column too, on any column, served by an index over LOWER(column), as a match anywhere or at a word start is.


 import static st.orm.Match.*;

 owners.select()
         .where(it -> it.suggest(input, wordStart(Owner_.lastName), wordStart(Owner_.firstName)))
         .limit(8)
         .getResultList();

A match states the shortest word by which its column takes the words of the input in its form, its minLength. A match anywhere or at a word start takes words of 3<T extends Data> characters by default, since a shorter word matches too large a share of a table there, and until a word of the input reaches the length, the column takes the whole input in its fallback, the start of the value, ignoring case. A match at the start of the value or of the whole value is narrow on its own, so it takes words of 2<T extends Data> characters by default, without a fallback. withFallback(BiFunction) states another form on the same column, withFallback(Match) a match on another column, and withoutFallback() keeps the column out of the statement until a word reaches the length, as for a column of a related table whose matches rank low.

A match composes with a SqlFunction: wordStart(foldAccents.apply(Owner_.lastName)) matches the folded name. The match is not a path, so only search and suggest take it.

Since:
1.16

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    Match.Anywhere<T extends Data>
    A word matches anywhere in the value: LOWER(column) LIKE LOWER('%word%').
    static final record 
    Match.Exact<T extends Data>
    A word matches the whole value.
    static final record 
    Match.Prefix<T extends Data>
    A word matches at the start of the value.
    static final record 
    Match.WordStart<T extends Data>
    A word matches at the start of any word in the value: the value's start, or the text after a space or one of the punctuation characters that join or separate the words of a name, a hyphen, an apostrophe, an opening parenthesis, a slash, a colon, a period or a comma, so marie matches "Anne-Marie" and brien "O'Brien".

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_MIN_LENGTH
    The shortest word, in characters, by which a match anywhere or at a word start takes the words in its form by default.
    static final int
    DEFAULT_VALUE_MIN_LENGTH
    The shortest word, in characters, a match at the start of the value or of the whole value takes by default, and the shortest input the default fallback takes: a one-character input matches too many rows.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T extends Data>
    Match<T>
    anywhere(Navigable<T,String> path)
    Returns a match of a word anywhere in the value, the default of search.
    static <T extends Data>
    Match<T>
    anywhere(Navigable<T,String> path, int minLength)
    Returns a anywhere match that takes the words in its form once one reaches the given length, and the whole input as the start of the value, ignoring case, before: a longer length keeps a column whose matches rank low, such as one of a related table, in its fallback until a word is long enough to match few rows, and 0 takes every word in its form.
    static <T extends Data>
    Match<T>
    exact(Navigable<T,String> path)
    Returns a match of a word as the whole value, with the column bare and the word lowered, which an ordinary index over a column that compares case-insensitively serves.
    static <T extends Data>
    Match<T>
    exact(Navigable<T,String> path, int minLength)
    Returns a exact match that takes words of at least the given length.
    static <T extends Data>
    Match<T>
    exactIgnoreCase(Navigable<T,String> path)
    Returns a match of a word as the whole value, ignoring case: the column lowered as well as the word, on any column, which an index over LOWER(column) serves, the index of a match anywhere or at a word start included.
    static <T extends Data>
    Match<T>
    exactIgnoreCase(Navigable<T,String> path, int minLength)
    Returns a exactIgnoreCase match that takes words of at least the given length.
    @Nullable Match<T>
    fallback()
    Returns how the column matches the whole input, its words joined by one space, while no word reaches the match's minLength(), or null where the column then takes no part.
    int
    minLength()
    Returns the shortest word, in characters, by which the column takes the words of the input in its form.
    Metamodel<T,String>
    path()
    Returns the text column, as a path.
    static <T extends Data>
    Match<T>
    prefix(Navigable<T,String> path)
    Returns a match of a word as a prefix of the value, with the column bare and the word lowered, which an ordinary index over a column that compares case-insensitively serves.
    static <T extends Data>
    Match<T>
    prefix(Navigable<T,String> path, int minLength)
    Returns a prefix match that takes words of at least the given length.
    static <T extends Data>
    Match<T>
    prefixIgnoreCase(Navigable<T,String> path)
    Returns a match of a word as a prefix of the value, ignoring case: the column lowered as well as the word, on any column, which an index over LOWER(column) serves, the index of a match anywhere or at a word start included.
    static <T extends Data>
    Match<T>
    prefixIgnoreCase(Navigable<T,String> path, int minLength)
    Returns a prefixIgnoreCase match that takes words of at least the given length.
    default Match<T>
    withFallback(BiFunction<? super Navigable<T,String>,Integer,? extends Match<T>> form)
    Returns this match with a fallback in another form on the same column, such as wordStart(Owner_.lastName).withFallback(Match::wordStart), which matches a short input at every word start.
    default Match<T>
    withFallback(Match<T> fallback)
    Returns this match with a fallback on any column of the row, such as a prefix match on a stored lowered column.
    default Match<T>
    withoutFallback()
    Returns this match without a fallback: the column takes no part in the statement until a word reaches its minLength(), its related table and a semi-join declared for it included, so a column of a related table whose matches rank low is not read for a short input.
    static <T extends Data>
    Match<T>
    wordStart(Navigable<T,String> path)
    Returns a match of a word at the start of any word in the value, the default of suggest: the value's start, or the text after a space or a punctuation character that joins or separates words.
    static <T extends Data>
    Match<T>
    wordStart(Navigable<T,String> path, int minLength)
    Returns a wordStart match that takes the words in its form once one reaches the given length, and the whole input as the start of the value, ignoring case, before: a longer length keeps a column whose matches rank low, such as one of a related table, in its fallback until a word is long enough to match few rows, and 0 takes every word in its form.

  • Field Details

    • DEFAULT_MIN_LENGTH

      static final int DEFAULT_MIN_LENGTH
      The shortest word, in characters, by which a match anywhere or at a word start takes the words in its form by default.
      See Also:

    • DEFAULT_VALUE_MIN_LENGTH

      static final int DEFAULT_VALUE_MIN_LENGTH
      The shortest word, in characters, a match at the start of the value or of the whole value takes by default, and the shortest input the default fallback takes: a one-character input matches too many rows.
      See Also:

  • Method Details

    • path

      Metamodel<T,String> path()
      Returns the text column, as a path.
      Returns:
      the column.

    • minLength

      int minLength()
      Returns the shortest word, in characters, by which the column takes the words of the input in its form. Once a word reaches it, the column takes every word, a shorter one tested only on the rows the longer word found; until then, the column takes the whole input in its fallback, or takes no part in the statement, its related table included, and a semi-join declared for it with its condition too. 0 takes every word in its form.
      Returns:
      the length.

    • fallback

      @Nullable Match<T> fallback()
      Returns how the column matches the whole input, its words joined by one space, while no word reaches the match's minLength(), or null where the column then takes no part. The fallback's own minLength() applies to the whole input, and its own fallback takes no part.

      The default of a match anywhere or at a word start is the start of the value, ignoring case, prefixIgnoreCase on the same column, taking an input of 2<T extends Data> characters or more: a short word matches too large a share of a table inside words or at their starts, and the index that serves the match serves its fallback. A match at the start of the value or of the whole value has none, being narrow on its own.

      Returns:
      the fallback, or null.

    • withFallback

      default Match<T> withFallback(BiFunction<? super Navigable<T,String>,Integer,? extends Match<T>> form)
      Returns this match with a fallback in another form on the same column, such as wordStart(Owner_.lastName).withFallback(Match::wordStart), which matches a short input at every word start. The factory receives the column and the shortest input the default fallback takes, 2<T extends Data> characters.
      Parameters:
      form - the factory of the fallback, such as Match::wordStart.
      Returns:
      the match.

    • withFallback

      default Match<T> withFallback(Match<T> fallback)
      Returns this match with a fallback on any column of the row, such as a prefix match on a stored lowered column. The fallback takes an input of its own minLength().
      Parameters:
      fallback - the match of the whole input; its own fallback takes no part.
      Returns:
      the match.

    • withoutFallback

      default Match<T> withoutFallback()
      Returns this match without a fallback: the column takes no part in the statement until a word reaches its minLength(), its related table and a semi-join declared for it included, so a column of a related table whose matches rank low is not read for a short input.
      Returns:
      the match.

    • anywhere

      static <T extends Data> Match<T> anywhere(Navigable<T,String> path)
      Returns a match of a word anywhere in the value, the default of search. It takes the words in its form once one reaches 3<T extends Data> characters, and the whole input as the start of the value, ignoring case, before.
      Type Parameters:
      T - the root table type of the column.
      Parameters:
      path - the text column.
      Returns:
      the match.

    • anywhere

      static <T extends Data> Match<T> anywhere(Navigable<T,String> path, int minLength)
      Returns a anywhere match that takes the words in its form once one reaches the given length, and the whole input as the start of the value, ignoring case, before: a longer length keeps a column whose matches rank low, such as one of a related table, in its fallback until a word is long enough to match few rows, and 0 takes every word in its form.
      Type Parameters:
      T - the root table type of the column.
      Parameters:
      path - the text column.
      minLength - the shortest word, in characters, by which the column takes the words in its form.
      Returns:
      the match.

    • wordStart

      static <T extends Data> Match<T> wordStart(Navigable<T,String> path)
      Returns a match of a word at the start of any word in the value, the default of suggest: the value's start, or the text after a space or a punctuation character that joins or separates words. It does not match inside a compound, so son does not find "Davidson"; anywhere does. It takes the words in its form once one reaches 3<T extends Data> characters, and the whole input as the start of the value, ignoring case, before.
      Type Parameters:
      T - the root table type of the column.
      Parameters:
      path - the text column.
      Returns:
      the match.

    • wordStart

      static <T extends Data> Match<T> wordStart(Navigable<T,String> path, int minLength)
      Returns a wordStart match that takes the words in its form once one reaches the given length, and the whole input as the start of the value, ignoring case, before: a longer length keeps a column whose matches rank low, such as one of a related table, in its fallback until a word is long enough to match few rows, and 0 takes every word in its form.
      Type Parameters:
      T - the root table type of the column.
      Parameters:
      path - the text column.
      minLength - the shortest word, in characters, by which the column takes the words in its form.
      Returns:
      the match.

    • prefix

      static <T extends Data> Match<T> prefix(Navigable<T,String> path)
      Returns a match of a word as a prefix of the value, with the column bare and the word lowered, which an ordinary index over a column that compares case-insensitively serves. It takes words of 2<T extends Data> characters or more.
      Type Parameters:
      T - the root table type of the column.
      Parameters:
      path - the text column.
      Returns:
      the match.

    • prefix

      static <T extends Data> Match<T> prefix(Navigable<T,String> path, int minLength)
      Returns a prefix match that takes words of at least the given length.
      Type Parameters:
      T - the root table type of the column.
      Parameters:
      path - the text column.
      minLength - the shortest word, in characters, the column takes.
      Returns:
      the match.

    • prefixIgnoreCase

      static <T extends Data> Match<T> prefixIgnoreCase(Navigable<T,String> path)
      Returns a match of a word as a prefix of the value, ignoring case: the column lowered as well as the word, on any column, which an index over LOWER(column) serves, the index of a match anywhere or at a word start included. It takes words of 2<T extends Data> characters or more.
      Type Parameters:
      T - the root table type of the column.
      Parameters:
      path - the text column.
      Returns:
      the match.

    • prefixIgnoreCase

      static <T extends Data> Match<T> prefixIgnoreCase(Navigable<T,String> path, int minLength)
      Returns a prefixIgnoreCase match that takes words of at least the given length.
      Type Parameters:
      T - the root table type of the column.
      Parameters:
      path - the text column.
      minLength - the shortest word, in characters, the column takes.
      Returns:
      the match.

    • exact

      static <T extends Data> Match<T> exact(Navigable<T,String> path)
      Returns a match of a word as the whole value, with the column bare and the word lowered, which an ordinary index over a column that compares case-insensitively serves. It takes words of 2<T extends Data> characters or more.
      Type Parameters:
      T - the root table type of the column.
      Parameters:
      path - the text column.
      Returns:
      the match.

    • exact

      static <T extends Data> Match<T> exact(Navigable<T,String> path, int minLength)
      Returns a exact match that takes words of at least the given length.
      Type Parameters:
      T - the root table type of the column.
      Parameters:
      path - the text column.
      minLength - the shortest word, in characters, the column takes.
      Returns:
      the match.

    • exactIgnoreCase

      static <T extends Data> Match<T> exactIgnoreCase(Navigable<T,String> path)
      Returns a match of a word as the whole value, ignoring case: the column lowered as well as the word, on any column, which an index over LOWER(column) serves, the index of a match anywhere or at a word start included. It takes words of 2<T extends Data> characters or more.
      Type Parameters:
      T - the root table type of the column.
      Parameters:
      path - the text column.
      Returns:
      the match.

    • exactIgnoreCase

      static <T extends Data> Match<T> exactIgnoreCase(Navigable<T,String> path, int minLength)
      Returns a exactIgnoreCase match that takes words of at least the given length.
      Type Parameters:
      T - the root table type of the column.
      Parameters:
      path - the text column.
      minLength - the shortest word, in characters, the column takes.
      Returns:
      the match.