org.apache.lucene.facet.search

## Class TopKInEachNodeHandler

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

-     public class TopKInEachNodeHandler
      extends PartitionsFacetResultsHandler

  Generates `FacetResult` from the `FacetArrays` 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.categoryPath`, and the enumerated children, `FacetResultNode.subResults`, of each node in that `FacetResult` are the top K ( = `FacetRequest.numResults`) among its children in the taxonomy. 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

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `TopKInEachNodeHandler.AACO` Maintains an array of `AggregatedCategory`.
    `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

      `facetArrays, facetRequest, taxonomyReader`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TopKInEachNodeHandler(TaxonomyReader taxonomyReader, FacetRequest facetRequest, FacetArrays facetArrays)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `IntermediateFacetResult` | `fetchPartitionResult(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.partitions.PartitionsFacetResultsHandler

      `compute, 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,
                               FacetArrays facetArrays)

  - ### Method Detail

    - #### fetchPartitionResult

          public IntermediateFacetResult fetchPartitionResult(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.numResults`) children among its children that are encountered in the given particular partition (aka current counting list).
      Specified by:
        `fetchPartitionResult` in class `PartitionsFacetResultsHandler`
      Parameters:
        `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:
        `fetchPartitionResult(int)`

    - #### mergeResults

          public IntermediateFacetResult mergeResults(IntermediateFacetResult... tmpResults)

      Merge several partitions' `IntermediateFacetResult`-s into one of the same format
      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.
      See Also:
        `mergeResults(IntermediateFacetResult...)`

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

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

    - #### renderFacetResult

          public FacetResult renderFacetResult(IntermediateFacetResult tmpResult)
                                        throws IOException

      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`
      Throws:
        `IOException` - on error.

Copyright © 2000-2013 Apache Software Foundation. All Rights Reserved.