## org.apache.lucene.facet.search
Class TopKInEachNodeHandler

    java.lang.Object
      org.apache.lucene.facet.search.FacetResultsHandler
          org.apache.lucene.facet.search.TopKInEachNodeHandler

    public class TopKInEachNodeHandler

extends FacetResultsHandler

Generates `FacetResult` from the count arrays aggregated for a particular `FacetRequest`. The generated `FacetResult` is a subtree of the taxonomy tree. Its root node, `FacetResult.getFacetResultNode()`, is the facet specified by `FacetRequest.getCategoryPath()`, and the enumerated children, `FacetResultNode.getSubResults()`, of each node in that `FacetResult` are the top K ( = `FacetRequest.getNumResults()`) among its children in the taxonomy. Top in the sense `FacetRequest.getSortBy()`, which can be by the values aggregated in the count arrays, or by ordinal numbers; also specified is the sort order, `FacetRequest.getSortOrder()`, ascending or descending, of these values or ordinals before their top K are selected. The depth (number of levels excluding the root) of the `FacetResult` tree is specified by `FacetRequest.getDepth()`.

Because the number of selected children of each node is restricted, and not the overall number of nodes in the `FacetResult`, facets not selected into `FacetResult` might have better values, or ordinals, (typically, higher counts), than facets that are selected into the `FacetResult`.

The generated `FacetResult` also provides with `FacetResult.getNumValidDescendants()`, which returns the total number of facets that are descendants of the root node, no deeper than `FacetRequest.getDepth()`, and which have valid value. The rootnode itself is not counted here. Valid value is determined by the `FacetResultsHandler`. `TopKInEachNodeHandler` defines valid as != 0.

NOTE: this code relies on the assumption that `TaxonomyReader.INVALID_ORDINAL` == -1, a smaller value than any valid ordinal.

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

Nested Class Summary
`static class` `TopKInEachNodeHandler.IntermediateFacetResultWithHash` Intermediate result to hold counts from one or more partitions processed thus far.

Field Summary

Fields inherited from class org.apache.lucene.facet.search.FacetResultsHandler
`facetRequest, taxonomyReader`

Constructor Summary
`TopKInEachNodeHandler(TaxonomyReader taxonomyReader, FacetRequest facetRequest)`

Method Summary
`IntermediateFacetResult` `fetchPartitionResult(FacetArrays arrays, int offset)` Recursively explore all facets that can be potentially included in the `FacetResult` to be generated, and that belong to the given partition, so that values can be examined and collected.
`void` `labelResult(FacetResult facetResult)` Label results according to settings in `FacetRequest`, such as `FacetRequest.getNumLabel()`.
`IntermediateFacetResult` `mergeResults(IntermediateFacetResult... tmpResults)` Merge several partitions' `IntermediateFacetResult`-s into one of the same format
`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.search.FacetResultsHandler
`getFacetRequest, getTaxonomyReader, isSelfPartition`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### TopKInEachNodeHandler

    public TopKInEachNodeHandler(TaxonomyReader taxonomyReader,
                                 FacetRequest facetRequest)

Method Detail

### fetchPartitionResult

    public IntermediateFacetResult fetchPartitionResult(FacetArrays arrays,
                                                        int offset)
                                                 throws IOException

  Recursively explore all facets that can be potentially included in the `FacetResult` to be generated, and that belong to the given partition, so that values can be examined and collected. For each such node, gather its top K (`FacetRequest.getNumResults()`) children among its children that are encountered in the given particular partition (aka current counting list).

  Specified by:
    `fetchPartitionResult` in class `FacetResultsHandler`
  Parameters:
    `arrays` - the already filled in count array, potentially only covering one partition: the ordinals ranging from
    `offset` - to `offset` + the length of the count arrays within `arrays` (exclusive)
  Returns:
    `IntermediateFacetResult` consisting of `IntToObjectMap` that maps potential `FacetResult` nodes to their top K children encountered in the current partition. Note that the mapped potential tree nodes need not belong to the given partition, only the top K children mapped to. The aim is to identify nodes that are certainly excluded from the `FacetResult` to be eventually (after going through all the partitions) returned by this handler, because they have K better siblings, already identified in this partition. For the identified excluded nodes, we only count number of their descendants in the subtree (to be included in `FacetResult.getNumValidDescendants()`), but not bother with selecting top K in these generations, which, by definition, are, too, excluded from the FacetResult tree.
  Throws:
    `IOException` - in case `TaxonomyReader.getOrdinal(org.apache.lucene.facet.taxonomy.CategoryPath)` does.
  See Also:
    `FacetResultsHandler.fetchPartitionResult(FacetArrays, int)`

### mergeResults

    public IntermediateFacetResult mergeResults(IntermediateFacetResult... tmpResults)
                                         throws ClassCastException,
                                                IllegalArgumentException

  Merge several partitions' `IntermediateFacetResult`-s into one of the same format

  Specified by:
    `mergeResults` in class `FacetResultsHandler`
  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:
    `ClassCastException` - if the temporary result passed was not created by this handler
    `IllegalArgumentException` - if passed `facetResults` do not have the same `FacetRequest`
  See Also:
    `FacetResultsHandler.mergeResults(IntermediateFacetResult...)`

### labelResult

    public void labelResult(FacetResult facetResult)
                     throws IOException

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

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

### rearrangeFacetResult

    public FacetResult rearrangeFacetResult(FacetResult facetResult)

  Description copied from class: `FacetResultsHandler`
  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 `FacetResultsHandler`
  Parameters:
    `facetResult` - result to be rearranged.
  See Also:
    `FacetResultNode.setValue(double)`

### renderFacetResult

    public FacetResult renderFacetResult(IntermediateFacetResult tmpResult)
                                  throws IOException

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

  Specified by:
    `renderFacetResult` in class `FacetResultsHandler`
  Parameters:
    `tmpResult` - temporary result to be rendered as a `FacetResult`
  Throws:
    `IOException` - on error.