org.hibernate.search.query.engine.spi

Interface HSQuery

All Superinterfaces:

ProjectionConstants

All Known Implementing Classes:

HSQueryImpl

public interface HSQuery
extends ProjectionConstants

Defines and executes an Hibernate Search query (wrapping a Lucene query). Uses fluent APIs to define the query and offer a few alternatives on how to execute the query. This object is not meant to be thread safe. The typical usage is as follow

   //get query object
 HSQuery query = searchIntegrator.createHSQuery();
 //configure query object
 query
 .luceneQuery( luceneQuery )
 .timeoutExceptionFactory( exceptionFactory )
 .targetedEntities( Arrays.asList( classes ) );

 [...]

 //start timeout counting
 query.getTimeoutManager().start();

 //query execution and use
 List<EntityInfo> entityInfos = query.getEntityInfos();
 [...]

 //done with the core of the query
 query.getTimeoutManager().stop();
 
 

Author:

Emmanuel Bernard

Field Summary

Fields inherited from interface org.hibernate.search.engine.ProjectionConstants

DOCUMENT, DOCUMENT_ID, EXPLANATION, ID, OBJECT_CLASS, SCORE, SPATIAL_DISTANCE, THIS

Method Summary

Modifier and Type	Method and Description
void	afterDeserialise(SearchIntegrator integrator) afterDeserialise.
void	disableFullTextFilter(String name) Disable a given filter by its name.
FullTextFilter	enableFullTextFilter(String name) Enable a given filter by its name.
Explanation	explain(int documentId) Return the Lucene Explanation object describing the score computation for the matching object/document in the current query
HSQuery	filter(Filter filter) Allows to use lucene filters.
HSQuery	firstResult(int firstResult) Set the first element to retrieve.
ExtendedSearchIntegrator	getExtendedSearchIntegrator() Deprecated. should be at most SearchIntegrator, preferably removed altogether
FacetManager	getFacetManager()
Set<Class<?>>	getIndexedTargetedEntities()
Query	getLuceneQuery()
String[]	getProjectedFields()
List<Class<?>>	getTargetedEntities()
TimeoutManager	getTimeoutManager()
HSQuery	luceneQuery(Query query) Defines the underlying Lucene query
HSQuery	maxResults(int maxResults) Set the maximum number of elements to retrieve.
HSQuery	projection(String... fields) Defines the Lucene field names projected and returned in a query result Each field is converted back to it's object representation, an Object[] being returned for each "row" (similar to an HQL or a Criteria API projection).
DocumentExtractor	queryDocumentExtractor() Execute the Lucene query and return a traversable object over the results.
List<EntityInfo>	queryEntityInfos() Execute the Lucene query and return the list of EntityInfos populated with metadata and projection.
int	queryResultSize()
HSQuery	setSpatialParameters(Coordinates center, String fieldName) setSpatialParameters.
HSQuery	sort(Sort sort) Lets Lucene sort the results.
HSQuery	targetedEntities(List<Class<?>> classes) Defines the targeted entities.
HSQuery	tenantIdentifier(String tenantId)
HSQuery	timeoutExceptionFactory(TimeoutExceptionFactory exceptionFactory) Define the timeout exception factory to customize the exception returned by the user.

Method Detail

luceneQuery

HSQuery luceneQuery(Query query)

Defines the underlying Lucene query

Parameters:

query - the Lucene query

Returns:

this to allow method chaining

tenantIdentifier

HSQuery tenantIdentifier(String tenantId)

targetedEntities

HSQuery targetedEntities(List<Class<?>> classes)

Defines the targeted entities. This helps to reduce the number of targeted indexes.

Parameters:

classes - the list of classes (indexes) targeted by this query

Returns:

this to allow for method chaining

sort

HSQuery sort(Sort sort)

Lets Lucene sort the results. This is useful when you have different sort requirements than the default Lucene ranking. Without Lucene sorting you would have to retrieve the full result set and order the Hibernate objects.

Parameters:

sort - The Lucene sort object.

Returns:

this to allow for method chaining

filter

HSQuery filter(Filter filter)

Allows to use lucene filters. Semi-deprecated? a preferred way is to use the @FullTextFilterDef approach

Parameters:

filter - The Lucene filter.

Returns:

this to allow for method chaining

timeoutExceptionFactory

HSQuery timeoutExceptionFactory(TimeoutExceptionFactory exceptionFactory)

Define the timeout exception factory to customize the exception returned by the user. Defaults to returning QueryTimeoutException

Parameters:

exceptionFactory - the timeout exception factory to use

Returns:

this to allow for method chaining

projection

HSQuery projection(String... fields)

Defines the Lucene field names projected and returned in a query result Each field is converted back to it's object representation, an Object[] being returned for each "row" (similar to an HQL or a Criteria API projection).

A projectable field must be stored in the Lucene index and use a TwoWayFieldBridge Unless notified in their JavaDoc, all built-in bridges are two-way. All @DocumentId fields are projectable by design.

If the projected field is not a projectable field, null is returned in the object[]

Parameters:

fields - the projected field names

Returns:

this to allow for method chaining

firstResult

HSQuery firstResult(int firstResult)

Set the first element to retrieve. If not set, elements will be retrieved beginning from element 0.

Parameters:

firstResult - a element number, numbered from 0

Returns:

this to allow for method chaining

maxResults

HSQuery maxResults(int maxResults)

Set the maximum number of elements to retrieve. If not set, there is no limit to the number of elements retrieved.

Parameters:

maxResults - the maximum number of elements

Returns:

this in order to allow method chaining

getTargetedEntities

List<Class<?>> getTargetedEntities()

Returns:

the targeted entity types

getIndexedTargetedEntities

Set<Class<?>> getIndexedTargetedEntities()

Returns:

a set of indexed entities corresponding to the class hierarchy of the targeted entities

getProjectedFields

String[] getProjectedFields()

Returns:

the projected field names

getTimeoutManager

TimeoutManager getTimeoutManager()

Returns:

the timeout manager. Make sure to wrap your HSQuery usage around a timeoutManager.start() and timeoutManager.stop().

getFacetManager

FacetManager getFacetManager()

Returns:

return the manager for all faceting related operations

getLuceneQuery

Query getLuceneQuery()

Returns:

the underlying Lucene query

queryEntityInfos

List<EntityInfo> queryEntityInfos()

Execute the Lucene query and return the list of EntityInfos populated with metadata and projection. ProjectionConstants.THIS if projected is not populated. It is the responsibility of the object source integration.

Returns:

list of EntityInfos populated with metadata and projection

queryDocumentExtractor

DocumentExtractor queryDocumentExtractor()

Execute the Lucene query and return a traversable object over the results. Results are lazily fetched. ProjectionConstants.THIS if projected is not populated. It is the responsibility of the object source integration. The returned DocumentExtractor must be closed by the caller to release Lucene resources.

Returns:

the DocumentExtractor instance

queryResultSize

int queryResultSize()

Returns:

the number of hits for this search

Caution: The number of results might be slightly different from what the object source returns if the index is not in sync with the store at the time of query.

explain

Explanation explain(int documentId)

Return the Lucene Explanation object describing the score computation for the matching object/document in the current query

Parameters:

documentId - Lucene Document id to be explain. This is NOT the object id

Returns:

Lucene Explanation

enableFullTextFilter

FullTextFilter enableFullTextFilter(String name)

Enable a given filter by its name.

Parameters:

name - the name of the filter to enable

Returns:

Returns a FullTextFilter object that allows filter parameter injection

disableFullTextFilter

void disableFullTextFilter(String name)

Disable a given filter by its name.

Parameters:

name - the name of the filter to disable.

getExtendedSearchIntegrator

@Deprecated
ExtendedSearchIntegrator getExtendedSearchIntegrator()

Deprecated. should be at most SearchIntegrator, preferably removed altogether

getExtendedSearchIntegrator.

Returns:

the ExtendedSearchintegrator instance

afterDeserialise

void afterDeserialise(SearchIntegrator integrator)

afterDeserialise.

Parameters:

integrator - a SearchIntegrator object.

setSpatialParameters

HSQuery setSpatialParameters(Coordinates center,
                             String fieldName)

setSpatialParameters.

Parameters:

center - center of the spatial search

fieldName - name ot the spatial field

Returns:

this to allow for method chaining