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

Interface SearchPredicateFactoryContext

All Known Implementing Classes:

DelegatingSearchPredicateFactoryContext

public interface SearchPredicateFactoryContext

A context allowing to specify the type of a predicate.

This is the main entry point to the predicate DSL.

Common concepts

Type of predicate parameters

Some predicates, such as the match() predicate or the range() predicate, target an index field and define an Object parameter (MatchPredicateFieldSetContext.matching(Object), RangePredicateFieldSetContext.from(Object), ...). The type of arguments passed to these methods is expected to be consistent with the targeted field: if you want a field "myField" to be between values X and Y, Hibernate Search needs to be able to convert the values X and Y to something comparable to the indexed value of "myField".

Generally the expected type of this argument should be rather obvious: for example if you created a field by mapping an Integer property, then an Integer value will be expected when building a predicate; if you mapped a LocalDate, then a LocalDate will be expected. Note that the type that is actually stored in the index does not matter: if you mapped a custom enum type, then this same enum type will be expected throughout the predicate DSL, even if it is stored as a String in the index.

Note it is possible to skip some of the conversion performed by Hibernate Search and by targeting "raw" fields, and in that case the expected type of arguments will be different; see Raw fields for details.

Sometimes a predicate targets multiple fields, either explicitly (multiple field names passed to the onFields method when defining the predicate) or implicitly (multiple targeted indexes). In that case, the type of the targeted fields must be compatible. For example targeting an Integer field and a LocalDate field in the same match() predicate won't work, because you won't be able to pass a non-null argument that is both an Integer and a LocalDate to the MatchPredicateFieldSetContext.matching(Object) method. Thus you generally cannot target fields with different types in the same predicate. When targeting different fields in the same index, you can, however, define one predicate for each field and combine them using a boolean predicate.

Note that custom bridges have the ability to customize the expected type of arguments in the DSL: for example they could accept String arguments when targeting Integer fields. See the documentation of bridges for more information on custom bridges.

Raw fields

Some predicates allow to target "raw fields" using an onRawField(String) method instead of onField(String). Targeting a raw field means some of the usual conversion will be skipped when Hibernate Search processes predicate arguments such as the value to match.

This is useful when the type of the indexed property is not the same as the type of search arguments. For example one may use a custom bridge implementing ValueBridge<MyType, String> to translate a property from a custom type to a string when indexing. When targeting that field with onField, Hibernate Search will expect predicate arguments to be instances of the custom type; with onRawField, it will expect strings.

For details about conversions applied by built-in bridges, please refer to the reference documentation.

Method Summary

Modifier and Type	Method and Description
BooleanJunctionPredicateContext	bool() Match documents if they match a combination of boolean clauses.
SearchPredicateTerminalContext	bool(Consumer<? super BooleanJunctionPredicateContext> clauseContributor) Match documents if they match a combination of boolean clauses, which will be defined by the given consumer.
SearchPredicateFactoryExtensionContext	extension() Create a context allowing to try to apply multiple extensions one after the other, failing only if none of the extensions is supported.
<T> T	extension(SearchPredicateFactoryContextExtension<T> extension) Extend the current context with the given extension, resulting in an extended context offering different types of predicates.
MatchIdPredicateContext	id() Match documents where the identifier is among the given values.
MatchPredicateContext	match() Match documents where targeted fields have a value that "matches" a given single value.
MatchAllPredicateContext	matchAll() Match all documents.
NestedPredicateContext	nested() Match documents where a nested object matches a given predicate.
PhrasePredicateContext	phrase() Match documents where targeted fields have a value that contains a given phrase.
RangePredicateContext	range() Match documents where targeted fields have a value within lower and upper bounds.
SimpleQueryStringPredicateContext	simpleQueryString() Match documents according to a given query string, with a simple query language adapted to end users.
SpatialPredicateContext	spatial() Access the different types of spatial predicates.
WildcardPredicateContext	wildcard() Match documents where targeted fields contain a term that matches a given pattern, such as inter*on or pa?t.

Method Detail

matchAll

MatchAllPredicateContext matchAll()

Match all documents.

Returns:

A context allowing to define the predicate more precisely and ultimately get the resulting predicate.

See Also:

MatchAllPredicateContext

id

MatchIdPredicateContext id()

Match documents where the identifier is among the given values.

Returns:

A context allowing to define the predicate more precisely and ultimately get the resulting predicate.

See Also:

MatchIdPredicateContext

bool

BooleanJunctionPredicateContext bool()

Match documents if they match a combination of boolean clauses.

Returns:

A context allowing to define the predicate more precisely and ultimately get the resulting predicate.

See Also:

BooleanJunctionPredicateContext

bool

SearchPredicateTerminalContext bool(Consumer<? super BooleanJunctionPredicateContext> clauseContributor)

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 context passed in parameter. Should generally be a lambda expression.

Returns:

The resulting SearchPredicate

See Also:

BooleanJunctionPredicateContext

match

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

A context allowing to define the predicate more precisely and ultimately get the resulting predicate.

See Also:

MatchPredicateContext

range

RangePredicateContext range()

Match documents where targeted fields have a value within lower and upper bounds.

Returns:

A context allowing to define the predicate more precisely and ultimately get the resulting predicate.

See Also:

RangePredicateContext

phrase

PhrasePredicateContext phrase()

Match documents where targeted fields have a value that contains a given phrase.

Returns:

A context allowing to define the predicate more precisely and ultimately get the resulting predicate.

See Also:

PhrasePredicateContext

wildcard

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

A context allowing to define the predicate more precisely and ultimately get the resulting predicate.

See Also:

WildcardPredicateContext

nested

NestedPredicateContext nested()

Match documents where a nested object matches a given predicate.

Returns:

A context allowing to define the predicate more precisely and ultimately get the resulting predicate.

See Also:

NestedPredicateContext

simpleQueryString

SimpleQueryStringPredicateContext 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 SimpleQueryStringPredicateTerminalContext.withAndAsDefaultOperator() to change this behavior.

Returns:

A context allowing to define the predicate more precisely and ultimately get the resulting predicate.

See Also:

SimpleQueryStringPredicateContext

spatial

SpatialPredicateContext spatial()

Access the different types of spatial predicates.

Returns:

A context allowing to define the type of spatial predicate.

See Also:

SpatialPredicateContext

extension

<T> T extension(SearchPredicateFactoryContextExtension<T> extension)

Extend the current context with the given extension, resulting in an extended context offering different types of predicates.

Type Parameters:

T - The type of context provided by the extension.

Parameters:

extension - The extension to the predicate DSL.

Returns:

The extended context.

Throws:

SearchException - If the extension cannot be applied (wrong underlying backend, ...).

extension

SearchPredicateFactoryExtensionContext extension()

Create a context allowing to try to apply multiple 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(SearchPredicateFactoryContextExtension) method instead.

Returns:

A context allowing to define the extensions to attempt, and the corresponding predicates.