org.apache.lucene.facet.search

## Class TopKFacetResultsHandler

- java.lang.Object
- - org.apache.lucene.facet.search.FacetResultsHandler
  - - org.apache.lucene.facet.partitions.PartitionsFacetResultsHandler
    - - org.apache.lucene.facet.search.TopKFacetResultsHandler

    public class TopKFacetResultsHandler
    extends PartitionsFacetResultsHandler

Generate Top-K results for a particular `FacetRequest`. K is global (among all results) and is defined by `FacetRequest.numResults`.

WARNING: This API is experimental and might change in incompatible ways in the next release.

### Field Summary

### Fields inherited from class org.apache.lucene.facet.search.FacetResultsHandler

`facetArrays, facetRequest, taxonomyReader`

### Constructor Summary

Constructors
Constructor and Description
`TopKFacetResultsHandler(TaxonomyReader taxonomyReader, FacetRequest facetRequest, FacetArrays facetArrays)` Construct top-K results handler.

### Method Summary

Methods
`IntermediateFacetResult` `fetchPartitionResult(int offset)` Fetch results of a single partition, given facet arrays for that partition, and based on the matching documents and faceted search parameters.
`void` `labelResult(FacetResult facetResult)` Label results according to settings in `FacetRequest`, such as `FacetRequest.getNumLabel()`.
`IntermediateFacetResult` `mergeResults(IntermediateFacetResult... tmpResults)` Merge results of several facet partitions.
`FacetResult` `rearrangeFacetResult(FacetResult facetResult)` Perform any rearrangement as required on a facet result that has changed after it was rendered.
`FacetResult` `renderFacetResult(IntermediateFacetResult tmpResult)` Create a facet result from the temporary result.

### Methods inherited from class org.apache.lucene.facet.partitions.PartitionsFacetResultsHandler

`compute, isSelfPartition`

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### TopKFacetResultsHandler

    public TopKFacetResultsHandler(TaxonomyReader taxonomyReader,
                           FacetRequest facetRequest,
                           FacetArrays facetArrays)

Construct top-K results handler.

Parameters:
  `taxonomyReader` - taxonomy reader
  `facetRequest` - facet request being served

### Method Detail

#### fetchPartitionResult

    public IntermediateFacetResult fetchPartitionResult(int offset)
                                                 throws IOException

Description copied from class: `PartitionsFacetResultsHandler`
Fetch results of a single partition, given facet arrays for that partition, and based on the matching documents and faceted search parameters.

Specified by:
  `fetchPartitionResult` in class `PartitionsFacetResultsHandler`
Parameters:
  `offset` - offset in input arrays where partition starts
Returns:
  temporary facet result, potentially, to be passed back to this result handler for merging, or null in case that constructor parameter, `facetRequest`, requests an illegal FacetResult, like, e.g., a root node category path that does not exist in constructor parameter `taxonomyReader` .
Throws:
  `IOException` - on error

#### mergeResults

    public IntermediateFacetResult mergeResults(IntermediateFacetResult... tmpResults)
                                         throws IOException

Description copied from class: `PartitionsFacetResultsHandler`
Merge results of several facet partitions. Logic of the merge is undefined and open for interpretations. For example, a merge implementation could keep top K results. Passed `IntermediateFacetResult` must be ones that were created by this handler otherwise a `ClassCastException` is thrown. In addition, all passed `IntermediateFacetResult` must have the same `FacetRequest` otherwise an `IllegalArgumentException` is thrown.

Specified by:
  `mergeResults` in class `PartitionsFacetResultsHandler`
Parameters:
  `tmpResults` - one or more temporary results created by this handler.
Returns:
  temporary facet result that represents to union, as specified by this handler, of the input temporary facet results.
Throws:
  `IOException` - on error.
See Also:
  `IntermediateFacetResult.getFacetRequest()`

#### renderFacetResult

    public FacetResult renderFacetResult(IntermediateFacetResult tmpResult)

Description copied from class: `PartitionsFacetResultsHandler`
Create a facet result from the temporary result.

Specified by:
  `renderFacetResult` in class `PartitionsFacetResultsHandler`
Parameters:
  `tmpResult` - temporary result to be rendered as a `FacetResult`

#### rearrangeFacetResult

    public FacetResult rearrangeFacetResult(FacetResult facetResult)

Description copied from class: `PartitionsFacetResultsHandler`
Perform any rearrangement as required on a facet result that has changed after it was rendered.

Possible use case: a sampling facets accumulator invoked another other facets accumulator on a sample set of documents, obtained rendered facet results, fixed their counts, and now it is needed to sort the results differently according to the fixed counts.

Specified by:
  `rearrangeFacetResult` in class `PartitionsFacetResultsHandler`
Parameters:
  `facetResult` - result to be rearranged.
See Also:
  `FacetResultNode.value`

#### labelResult

    public void labelResult(FacetResult facetResult)
                     throws IOException

Description copied from class: `PartitionsFacetResultsHandler`
Label results according to settings in `FacetRequest`, such as `FacetRequest.getNumLabel()`. Usually invoked by `StandardFacetsAccumulator.accumulate(ScoredDocIDs)`

Specified by:
  `labelResult` in class `PartitionsFacetResultsHandler`
Parameters:
  `facetResult` - facet result to be labeled.
Throws:
  `IOException` - on error