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

Interface MinimumShouldMatchConditionStep<N>

Type Parameters:
N - The type of the next step (returned by MinimumShouldMatchMoreStep.end()).
All Known Subinterfaces:
MinimumShouldMatchMoreStep<N>
public interface MinimumShouldMatchConditionStep<N>
The step in a "minimum should match" constraint definition where a condition can be defined as necessary for the following requirements to be enforced.

"minimumShouldMatch" constraints

"minimumShouldMatch" constraints define a minimum number of "should" clauses that have to match in order for the boolean predicate to match.

The feature is similar, and will work identically, to "Min Number Should Match" in Solr or minimum_should_match in Elasticsearch.

Definition of the minimum

The minimum may be defined either directly as a positive number, or indirectly as a negative number or positive or negative percentage representing a ratio of the total number of "should" clauses in this boolean predicate.

Here is how each type of input is interpreted:

Positive number
The value is interpreted directly as the minimum number of "should" clauses that have to match.
Negative number
The absolute value is interpreted as the maximum number of "should" clauses that may not match: the absolute value is subtracted from the total number of "should" clauses.
Positive percentage
The value is interpreted as the minimum percentage of the total number of "should" clauses that have to match: the percentage is applied to the total number of "should" clauses, then rounded down.
Negative percentage
The absolute value is interpreted as the maximum percentage of the total number of "should" clauses that may not match: the absolute value of the percentage is applied to the total number of "should" clauses, then rounded down, then subtracted from the total number of "should" clauses.

In any case, if the computed minimum is 0 or less, or higher than the total number of "should" clauses, behavior is backend-specific (it may throw an exception, or produce unpredictable results, or fall back to some default behavior).

Conditional constraints

Multiple conditional constraints may be defined, only one of them being applied depending on the total number of "should" clauses.

Each constraint is attributed a minimum number of "should" clauses that have to match, and an additional number. The additional number is unique to each constraint.

The additional number will be compared to the total number of "should" clauses, and the one closest while still strictly lower will be picked: its associated constraint will be applied. If no number matches, the minimum number of matching "should" clauses will be set to the total number of "should" clauses.

Examples: 


     // Example 1: at least 3 "should" clauses have to match
     f.bool().[...].minimumShouldMatchNumber( 3 );
     // Example 2: at most 2 "should" clauses may not match
     f.bool().[...].minimumShouldMatchNumber( -2 );
     // Example 3: at least 75% of "should" clauses have to match (rounded down)
     f.bool().[...].minimumShouldMatchPercent( 75 );
     // Example 4: at most 25% of "should" clauses may not match (rounded down)
     f.bool().[...].minimumShouldMatchPercent( -25 );
     // Example 5: if there are 3 "should" clauses or less, all "should" clauses have to match.
     // If there are 4 "should" clauses or more, at least 90% of "should" clauses have to match (rounded down).
     f.bool().[...].minimumShouldMatchPercent( 3, 90 );
     // Example 6: if there are 4 "should" clauses or less, all "should" clauses have to match.
     // If there are 5 to 9 "should" clauses, at most 25% of "should" clauses may not match (rounded down).
     // If there are 10 "should" clauses or more, at most 3 "should" clauses may not match.
     f.bool().[...].minimumShouldMatch()
             .ifMoreThan( 4 ).thenRequirePercent( 25 )
             .ifMoreThan( 9 ).thenRequireNumber( -3 )
             .end();

  • Method Details

    • ifMoreThan

      MinimumShouldMatchRequireStep<N> ifMoreThan(int ignoreConstraintCeiling)
      Start adding a "minimumShouldMatch" constraint that will be applied if (and only if) there are strictly more than ignoreConstraintCeiling "should" clauses.

      See Conditional constraints for the detailed rules defining whether a constraint is applied or not.

      Parameters:
      ignoreConstraintCeiling - The number of "should" clauses above which the constraint will cease to be ignored.
      Returns:
      The next step, where the minimum required number or percentage of should clauses to match can be set. This requirement will only be taken into account when there are strictly more than ignoreConstraintCeiling "should" clauses.