org.hibernate.search.query.engine.spi

## Interface HSQuery

- All Superinterfaces:
    ProjectionConstants
  All Known Implementing Classes:
    AbstractHSQuery, ElasticsearchHSQueryImpl, LuceneHSQuery

      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

    All Methods Instance Methods Abstract Methods Deprecated Methods
    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)` Deprecated. use the `FullTextFilterDef` approach, or handle filtering when building the query (see `BooleanJunction.must(Query)` and `MustJunction.disableScoring()`).
    `HSQuery` | `firstResult(int firstResult)` Set the first element to retrieve.
    `ExtendedSearchIntegrator` | `getExtendedSearchIntegrator()` Deprecated. should be at most SearchIntegrator, preferably removed altogether
    `FacetManager` | `getFacetManager()`
    `IndexedTypeSet` | `getIndexedTargetedEntities()`
    `Query` | `getLuceneQuery()`
    `String[]` | `getProjectedFields()`
    `String` | `getQueryString()`
    `IndexedTypeSet` | `getTargetedEntities()`
    `TimeoutManager` | `getTimeoutManager()`
    `boolean` | `hasThisProjection()`
    `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 `EntityInfo`s populated with metadata and projection.
    `int` | `queryResultSize()`
    `HSQuery` | `setSpatialParameters(Coordinates center, String fieldName)` setSpatialParameters.
    `HSQuery` | `sort(Sort sort)` Lets Lucene sort the results.
    `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)

    - #### 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

          @Deprecated
          HSQuery filter(Filter filter)

      Deprecated. use the `FullTextFilterDef` approach, or handle filtering when building the query (see `BooleanJunction.must(Query)` and `MustJunction.disableScoring()`).
      Allows to use lucene filters.
      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

          IndexedTypeSet getTargetedEntities()

      Returns:
        the targeted entity types

    - #### getIndexedTargetedEntities

          IndexedTypeSet getIndexedTargetedEntities()

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

    - #### getProjectedFields

          String[] getProjectedFields()

      Returns:
        the projected field names

    - #### hasThisProjection

          boolean hasThisProjection()

      Returns:
        `true` if the projected field names contain the `ProjectionConstants.THIS` constant.

    - #### 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 (if any)

    - #### getQueryString

          String getQueryString()

      Returns:
        a String representation of the underlying query

    - #### queryEntityInfos

          List<EntityInfo> queryEntityInfos()

      Execute the Lucene query and return the list of `EntityInfo`s populated with metadata and projection. `ProjectionConstants.THIS` if projected is not populated. It is the responsibility of the object source integration.
      Returns:
        list of `EntityInfo`s 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

Copyright © 2006-2017 Red Hat, Inc. All Rights Reserved