org.hibernate.search.query.dsl.BooleanJunction Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of hibernate-search-engine Show documentation
Core of the Object/Lucene mapper, query engine and index management
There is a newer version: 5.11.12.Final
Show newest version
/*
 * Hibernate Search, full-text search for your domain model
 *
 * License: GNU Lesser General Public License (LGPL), version 2.1 or later
 * See the lgpl.txt file in the root directory or .
 */

package org.hibernate.search.query.dsl;

import org.apache.lucene.search.Query;

/**
 * Represents a boolean query that can contains one or more elements to join
 * 
 * 
"minimumShouldMatch" constraints
 * 
 * "minimumShouldMatch" constraints define a minimum number of "should" clauses that have to match
 * in order for the boolean junction to match.
 * 

 * The feature is similar, and will work identically, to
 * "Min Number Should Match"
 * in Solr or
 * {@code 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 junction.
 * 

 * 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).
 * 

 * Examples:
 * 

 *     // Example 1: at least 3 "should" clauses have to match
 *     booleanContext1.minimumShouldMatchNumber( 3 );
 *     // Example 2: at most 2 "should" clauses may not match
 *     booleanContext2.minimumShouldMatchNumber( -2 );
 *     // Example 3: at least 75% of "should" clauses have to match (rounded down)
 *     booleanContext3.minimumShouldMatchPercent( 75 );
 *     // Example 4: at most 25% of "should" clauses may not match (rounded down)
 *     booleanContext4.minimumShouldMatchPercent( -25 );
 * 
 *
 * @author Emmanuel Bernard
 */
public interface BooleanJunction extends QueryCustomization, Termination {
	/**
	 * The boolean query results should match the subquery
	 * @param query the query to match (nulls are ignored)
	 * @return a {@link BooleanJunction}
	 */
	BooleanJunction should(Query query);

	/**
	 * The boolean query results must (or must not) match the subquery
	 * Call the .not() method to ensure results of the boolean query do NOT match the subquery.
	 *
	 * @param query the query to match (nulls are ignored)
	 * @return a {@link MustJunction}
	 */
	MustJunction must(Query query);

	/**
	 * @return true if no restrictions have been applied
	 */
	boolean isEmpty();

	/**
	 * Sets the "minimumShouldMatch" constraint.
	 *
	 * @param matchingClausesNumber A definition of the number of "should" clauses that have to match.
	 * If positive, it is the number of clauses that have to match.
	 * See Definition of the minimum
	 * for details and possible values, in particular negative values.
	 * @return {@code this}, for method chaining.
	 */
	BooleanJunction minimumShouldMatchNumber(int matchingClausesNumber);

	/**
	 * Sets the "minimumShouldMatch" constraint.
	 *
	 * @param matchingClausesPercent A definition of the number of "should" clauses that have to match, as a percentage.
	 * If positive, it is the percentage of the total number of "should" clauses that have to match.
	 * See Definition of the minimum
	 * for details and possible values, in particular negative values.
	 * @return {@code this}, for method chaining.
	 */
	BooleanJunction minimumShouldMatchPercent(int matchingClausesPercent);
}