org.apache.lucene.facet.search

## Class StandardFacetsAccumulator

- java.lang.Object
- - org.apache.lucene.facet.search.FacetsAccumulator
  - - org.apache.lucene.facet.search.StandardFacetsAccumulator

Direct Known Subclasses:
  AdaptiveFacetsAccumulator, SamplingAccumulator, SamplingWrapper

    public class StandardFacetsAccumulator
    extends FacetsAccumulator

Standard implementation for `FacetsAccumulator`, utilizing partitions to save on memory.

Why partitions? Because if there are say 100M categories out of which only top K are required, we must first compute value for all 100M categories (going over all documents) and only then could we select top K. This is made easier on memory by working in partitions of distinct categories: Once a values for a partition are found, we take the top K for that partition and work on the next partition, them merge the top K of both, and so forth, thereby computing top K with RAM needs for the size of a single partition rather than for the size of all the 100M categories.

Decision on partitions size is done at indexing time, and the facet information for each partition is maintained separately.

Implementation detail: Since facets information of each partition is maintained in a separate "category list", we can be more efficient at search time, because only the facet info for a single partition need to be read while processing that partition.

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

### Field Summary

Fields
`static double` `DEFAULT_COMPLEMENT_THRESHOLD` Default threshold for using the complements optimization.
`static double` `DISABLE_COMPLEMENT` Passing this to `setComplementThreshold(double)` will disable using complement optimization.
`static double` `FORCE_COMPLEMENT` Passing this to `setComplementThreshold(double)` will force using complement optimization.
`protected boolean` `isUsingComplements`
`protected int` `maxPartitions`
`protected int` `partitionSize`

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

`facetArrays, indexReader, searchParams, taxonomyReader`

### Constructor Summary

Constructors
Constructor and Description
`StandardFacetsAccumulator(FacetSearchParams searchParams, IndexReader indexReader, TaxonomyReader taxonomyReader)`
`StandardFacetsAccumulator(FacetSearchParams searchParams, IndexReader indexReader, TaxonomyReader taxonomyReader, FacetArrays facetArrays)`

### Method Summary

Methods
`List<FacetResult>` `accumulate(List<FacetsCollector.MatchingDocs> matchingDocs)` Used by `FacetsCollector` to build the list of `facet results` that match the `facet requests` that were given in the constructor.
`List<FacetResult>` `accumulate(ScoredDocIDs docids)`
`protected ScoredDocIDs` `actualDocsToAccumulate(ScoredDocIDs docids)` Set the actual set of documents over which accumulation should take place.
`protected PartitionsFacetResultsHandler` `createFacetResultsHandler(FacetRequest fr)` Creates a `FacetResultsHandler` that matches the given `FacetRequest`.
`protected HashMap<CategoryListIterator,Aggregator>` `getCategoryListMap(FacetArrays facetArrays, int partition)` Create an `Aggregator` and a `CategoryListIterator` for each and every `FacetRequest`.
`double` `getComplementThreshold()` Returns the complement threshold.
`protected double` `getTotalCountsFactor()` Expert: factor by which counts should be multiplied when initializing the count arrays from total counts.
`boolean` `isUsingComplements()` Returns true if complements are enabled.
`protected boolean` `mayComplement()` check if all requests are complementable
`void` `setComplementThreshold(double complementThreshold)` Set the complement threshold.
`protected boolean` `shouldComplement(ScoredDocIDs docids)` Check if it is worth to use complements

### Methods inherited from class org.apache.lucene.facet.search.FacetsAccumulator

`create, getAggregator, getCategoryLists`

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

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

### Field Detail

#### DEFAULT_COMPLEMENT_THRESHOLD

    public static final double DEFAULT_COMPLEMENT_THRESHOLD

Default threshold for using the complements optimization. If accumulating facets for a document set larger than this ratio of the index size than perform the complement optimization.

See Also:
  `for more info on the complements optimization.`, Constant Field Values

#### DISABLE_COMPLEMENT

    public static final double DISABLE_COMPLEMENT

Passing this to `setComplementThreshold(double)` will disable using complement optimization.

See Also:
  Constant Field Values

#### FORCE_COMPLEMENT

    public static final double FORCE_COMPLEMENT

Passing this to `setComplementThreshold(double)` will force using complement optimization.

See Also:
  Constant Field Values

#### partitionSize

    protected int partitionSize

#### maxPartitions

    protected int maxPartitions

#### isUsingComplements

    protected boolean isUsingComplements

### Constructor Detail

#### StandardFacetsAccumulator

    public StandardFacetsAccumulator(FacetSearchParams searchParams,
                             IndexReader indexReader,
                             TaxonomyReader taxonomyReader)

#### StandardFacetsAccumulator

    public StandardFacetsAccumulator(FacetSearchParams searchParams,
                             IndexReader indexReader,
                             TaxonomyReader taxonomyReader,
                             FacetArrays facetArrays)

### Method Detail

#### accumulate

    public List<FacetResult> accumulate(ScoredDocIDs docids)
                                 throws IOException

Throws:
  `IOException`

#### mayComplement

    protected boolean mayComplement()

check if all requests are complementable

#### createFacetResultsHandler

    protected PartitionsFacetResultsHandler createFacetResultsHandler(FacetRequest fr)

Description copied from class: `FacetsAccumulator`
Creates a `FacetResultsHandler` that matches the given `FacetRequest`.

Overrides:
  `createFacetResultsHandler` in class `FacetsAccumulator`

#### actualDocsToAccumulate

    protected ScoredDocIDs actualDocsToAccumulate(ScoredDocIDs docids)
                                           throws IOException

Set the actual set of documents over which accumulation should take place.

Allows to override the set of documents to accumulate for. Invoked just before actual accumulating starts. From this point that set of documents remains unmodified. Default implementation just returns the input unchanged.

Parameters:
  `docids` - candidate documents to accumulate for
Returns:
  actual documents to accumulate for
Throws:
  `IOException`

#### shouldComplement

    protected boolean shouldComplement(ScoredDocIDs docids)

Check if it is worth to use complements

#### getTotalCountsFactor

    protected double getTotalCountsFactor()

Expert: factor by which counts should be multiplied when initializing the count arrays from total counts. Default implementation for this returns 1, which is a no op.

Returns:
  a factor by which total counts should be multiplied

#### getCategoryListMap

    protected HashMap<CategoryListIterator,Aggregator> getCategoryListMap(FacetArrays facetArrays,
                                                              int partition)
                                                                   throws IOException

Create an `Aggregator` and a `CategoryListIterator` for each and every `FacetRequest`. Generating a map, matching each categoryListIterator to its matching aggregator.

If two CategoryListIterators are served by the same aggregator, a single aggregator is returned for both. NOTE: If a given category list iterator is needed with two different aggregators (e.g counting and association) - an exception is thrown as this functionality is not supported at this time.

Throws:
  `IOException`

#### accumulate

    public List<FacetResult> accumulate(List<FacetsCollector.MatchingDocs> matchingDocs)
                                 throws IOException

Description copied from class: `FacetsAccumulator`
Used by `FacetsCollector` to build the list of `facet results` that match the `facet requests` that were given in the constructor.

Overrides:
  `accumulate` in class `FacetsAccumulator`
Parameters:
  `matchingDocs` - the documents that matched the query, per-segment.
Throws:
  `IOException`

#### getComplementThreshold

    public double getComplementThreshold()

Returns the complement threshold.

See Also:
  `setComplementThreshold(double)`

#### setComplementThreshold

    public void setComplementThreshold(double complementThreshold)

Set the complement threshold. This threshold will dictate whether the complements optimization is applied. The optimization is to count for less documents. It is useful when the same FacetSearchParams are used for varying sets of documents. The first time complements is used the "total counts" are computed - counting for all the documents in the collection. Then, only the complementing set of documents is considered, and used to decrement from the overall counts, thereby walking through less documents, which is faster.

For the default settings see `DEFAULT_COMPLEMENT_THRESHOLD`.

To forcing complements in all cases pass `FORCE_COMPLEMENT`. This is mostly useful for testing purposes, as forcing complements when only tiny fraction of available documents match the query does not make sense and would incur performance degradations.

To disable complements pass `DISABLE_COMPLEMENT`.

Parameters:
  `complementThreshold` - the complement threshold to set
See Also:
  `getComplementThreshold()`

#### isUsingComplements

    public boolean isUsingComplements()

Returns true if complements are enabled.