Package org.hibernate.search.engine.search.predicate.dsl

Interface SearchPredicateFactory

All Known Subinterfaces:
ElasticsearchSearchPredicateFactory, ExtendedSearchPredicateFactory<S>, LuceneSearchPredicateFactory
All Known Implementing Classes:
AbstractSearchPredicateFactory
public interface SearchPredicateFactory
A factory for search predicates.

This is the main entry point to the predicate DSL.

Field paths

By default, field paths passed to this DSL are interpreted as absolute, i.e. relative to the index root.

However, a new, "relative" factory can be created with withRoot(String): the new factory interprets paths as relative to the object field passed as argument to the method.

This can be useful when calling reusable methods that can apply the same predicate on different object fields that have same structure (same sub-fields).

Such a factory can also transform relative paths into absolute paths using toAbsolutePath(String); this can be useful for native predicates in particular.

  • Method Details

    • matchAll

      MatchAllPredicateOptionsStep<?> matchAll()
      Match all documents.
      Returns:
      The initial step of a DSL where the "match all" predicate can be defined.
      See Also:

    • matchNone

      MatchNonePredicateFinalStep matchNone()
      Match none of the documents.
      Returns:
      The initial step of a DSL where the "match none" predicate can be defined.
      See Also:

    • id

      MatchIdPredicateMatchingStep<?> id()
      Match documents where the identifier is among the given values.
      Returns:
      The initial step of a DSL allowing the definition of an "id" predicate.
      See Also:

    • bool

      BooleanPredicateClausesStep<?> bool()
      Match documents if they match a combination of boolean clauses.
      Returns:
      The initial step of a DSL where the "boolean" predicate can be defined.
      See Also:

    • bool

      @Deprecated PredicateFinalStep bool(Consumer<? super BooleanPredicateClausesStep<?>> clauseContributor)
      Deprecated.
      Use .bool().with(...) instead.
      Match documents if they match a combination of boolean clauses, which will be defined by the given consumer.

      Best used with lambda expressions.

      Parameters:
      clauseContributor - A consumer that will add clauses to the step passed in parameter. Should generally be a lambda expression.
      Returns:
      The final step of the boolean predicate definition.
      See Also:

    • and

      SimpleBooleanPredicateClausesStep<?> and()
      Match documents if they match all inner clauses.
      Returns:
      The initial step of a DSL where predicates that must match can be added and options can be set.
      See Also:

    • and

      SimpleBooleanPredicateOptionsStep<?> and(SearchPredicate firstSearchPredicate, SearchPredicate... otherSearchPredicates)
      Match documents if they match all previously-built SearchPredicate.
      Returns:
      The step of a DSL where options can be set.

    • and

      SimpleBooleanPredicateOptionsStep<?> and(PredicateFinalStep firstSearchPredicate, PredicateFinalStep... otherSearchPredicates)
      Match documents if they match all clauses.
      Returns:
      The step of a DSL where options can be set.

    • or

      SimpleBooleanPredicateClausesStep<?> or()
      Match documents if they match any inner clause.
      Returns:
      The initial step of a DSL where predicates that should match can be added and options can be set.
      See Also:

    • or

      SimpleBooleanPredicateOptionsStep<?> or(SearchPredicate firstSearchPredicate, SearchPredicate... otherSearchPredicates)
      Match documents if they match any previously-built SearchPredicate.
      Returns:
      The step of a DSL where options can be set.

    • or

      SimpleBooleanPredicateOptionsStep<?> or(PredicateFinalStep firstSearchPredicate, PredicateFinalStep... otherSearchPredicates)
      Match documents if they match any clause.
      Returns:
      The step of a DSL where options can be set.

    • not

      NotPredicateFinalStep not(SearchPredicate searchPredicate)
      Match documents that do not satisfy the passed in previously-built SearchPredicate.

      Can be used to negate a predicate.

      Returns:
      The initial and final step of a DSL where the "not" predicate can be defined.
      See Also:

    • not

      NotPredicateFinalStep not(PredicateFinalStep searchPredicate)
      Match documents that do not satisfy the passed in predicate.

      Can be used to negate a predicate.

      Returns:
      The initial and final step of a DSL where the "not" predicate can be defined.
      See Also:

    • match

      MatchPredicateFieldStep<?> match()
      Match documents where targeted fields have a value that "matches" a given single value.

      Note that "value matching" may be exact or approximate depending on the type of the targeted fields: numeric fields in particular imply exact matches, while analyzed, full-text fields imply approximate matches depending on how they are analyzed.

      Returns:
      The initial step of a DSL where the "match" predicate can be defined.
      See Also:

    • range

      RangePredicateFieldStep<?> range()
      Match documents where targeted fields have a value within lower and upper bounds.
      Returns:
      The initial step of a DSL where the "range" predicate can be defined.
      See Also:

    • phrase

      PhrasePredicateFieldStep<?> phrase()
      Match documents where targeted fields have a value that contains a given phrase.
      Returns:
      The initial step of a DSL where the "phrase" predicate can be defined.
      See Also:

    • wildcard

      WildcardPredicateFieldStep<?> wildcard()
      Match documents where targeted fields contain a term that matches a given pattern, such as inter*on or pa?t.

      Note that such patterns are not analyzed, thus any character that is not a wildcard must match exactly the content of the index (including uppercase letters, diacritics, ...).

      Returns:
      The initial step of a DSL where the "wildcard" predicate can be defined.
      See Also:

    • prefix

      PrefixPredicateFieldStep<?> prefix()
      Match documents where targeted fields have a value that starts with a given string.
      Returns:
      The initial step of a DSL where the "prefix" predicate can be defined.
      See Also:

    • regexp

      RegexpPredicateFieldStep<?> regexp()
      Match documents where targeted fields contain a term that matches a given regular expression.
      Returns:
      The initial step of a DSL where the "regexp" predicate can be defined.
      See Also:

    • terms

      TermsPredicateFieldStep<?> terms()
      Match documents where targeted fields contain a term that matches some terms of a given series of terms.
      Returns:
      The initial step of a DSL where the "terms" predicate can be defined.
      See Also:

    • nested

      @Deprecated NestedPredicateFieldStep<?> nested()
      Deprecated.
      Use nested(String) instead.
      Match documents where a nested object matches a given predicate.
      Returns:
      The initial step of a DSL where the "nested" predicate can be defined.
      See Also:

    • nested

      NestedPredicateClausesStep<?> nested(String objectFieldPath)
      Match documents where a nested object matches inner predicates to be defined in the next steps.

      The resulting nested predicate must match all inner clauses, similarly to an "and" predicate.

      Parameters:
      objectFieldPath - The path to the (nested) object field that must match.
      Returns:
      The initial step of a DSL where the "nested" predicate can be defined.
      See Also:

    • simpleQueryString

      SimpleQueryStringPredicateFieldStep<?> simpleQueryString()
      Match documents according to a given query string, with a simple query language adapted to end users.

      Note that by default, unless the query string contains explicit operators, documents will match if any term mentioned in the query string is present in the document (OR operator). This makes sense when sorting results by relevance, but is not ideal otherwise. See CommonQueryStringPredicateOptionsStep.defaultOperator(BooleanOperator) to change this behavior.

      Returns:
      The initial step of a DSL where the "simple query string" predicate can be defined.
      See Also:

    • queryString

      QueryStringPredicateFieldStep<?> queryString()
      Match documents according to a given query string, using the Lucene's query language.

      Note that by default, unless the query string contains explicit operators, documents will match if any term mentioned in the query string is present in the document (OR operator). This makes sense when sorting results by relevance, but is not ideal otherwise. See CommonQueryStringPredicateOptionsStep.defaultOperator(BooleanOperator) to change this behavior.

      Returns:
      The initial step of a DSL where the "query string" predicate can be defined.
      See Also:

    • exists

      ExistsPredicateFieldStep<?> exists()
      Match documents where a given field exists.

      Fields are considered to exist in a document when they have at least one non-null value in this document.

      Returns:
      The initial step of a DSL where the "exists" predicate can be defined.
      See Also:

    • spatial

      SpatialPredicateInitialStep spatial()
      Access the different types of spatial predicates.
      Returns:
      The initial step of a DSL where spatial predicates can be defined.
      See Also:

    • named

      @Incubating NamedPredicateOptionsStep named(String path)
      Match documents if they match a combination of defined named predicate clauses.
      Parameters:
      path - The path to the named predicate, formatted as <object field path>.<predicate name>, or just <predicate name> if the predicate was declared at the root.
      Returns:
      The initial step of a DSL where named predicate predicates can be defined.
      See Also:

    • knn

      KnnPredicateFieldStep knn(int k)
      Match k documents whose vector field value is nearest to the given vector.

      "knn" stands for "K-Nearest Neighbors"; it is a form of vector search.

      Parameters:
      k - The number of nearest neighbors to look for.
      Returns:
      The initial step of a DSL where knn predicate options can be defined.
      See Also:

    • withParameters

      @Incubating PredicateFinalStep withParameters(Function<? super NamedValues,? extends PredicateFinalStep> predicateCreator)
      Delegating predicate that creates the actual predicate at query create time and provides access to query parameters.

      Which predicate exactly to create is defined by a function passed to the arguments of this predicate.

      Parameters:
      predicateCreator - The function defining an actual predicate to apply.
      Returns:
      A final DSL step in a parameterized predicate definition.

    • extension

      <T> T extension(SearchPredicateFactoryExtension<T> extension)
      Extend the current factory with the given extension, resulting in an extended factory offering different types of predicates.
      Type Parameters:
      T - The type of factory provided by the extension.
      Parameters:
      extension - The extension to the predicate DSL.
      Returns:
      The extended factory.
      Throws:
      SearchException - If the extension cannot be applied (wrong underlying backend, ...).

    • extension

      SearchPredicateFactoryExtensionIfSupportedStep extension()
      Create a DSL step allowing multiple attempts to apply extensions one after the other, failing only if none of the extensions is supported.

      If you only need to apply a single extension and fail if it is not supported, use the simpler extension(SearchPredicateFactoryExtension) method instead.

      Returns:
      A DSL step.

    • withRoot

      @Incubating SearchPredicateFactory withRoot(String objectFieldPath)
      Create a new predicate factory whose root for all paths passed to the DSL will be the given object field.

      This is used to call reusable methods that apply the same predicate on different object fields that have same structure (same sub-fields).

      Parameters:
      objectFieldPath - The path from the current root to an object field that will become the new root.
      Returns:
      A new predicate factory using the given object field as root.

    • toAbsolutePath

      @Incubating String toAbsolutePath(String relativeFieldPath)
      Parameters:
      relativeFieldPath - The path to a field, relative to the root of this factory.
      Returns:
      The absolute path of the field, for use in native predicates for example. Note the path is returned even if the field doesn't exist.