org.apache.lucene.facet (Lucene 10.5.1 facet API)
Description: declaration: package: org.apache.lucene.facet

# Package org.apache.lucene.facet

package org.apache.lucene.facet
Faceted search.

This module provides multiple methods for computing facet counts and value aggregations:

- Taxonomy-based methods rely on a separate taxonomy index to map hierarchical facet paths to global int ordinals for fast counting at search time; these methods can compute counts ((`FastTaxonomyFacetCounts`) aggregate long or double values `TaxonomyFacetIntAssociations`, `TaxonomyFacetFloatAssociations`. Add `FacetField` or `AssociationFacetField` to your documents at index time to use taxonomy-based methods.
- Sorted-set doc values method does not require a separate taxonomy index, and computes counts based on sorted set doc values fields (`SortedSetDocValuesFacetCounts`). Add `SortedSetDocValuesFacetField` to your documents at index time to use sorted set facet counts.
- Range faceting `LongRangeFacetCounts`, `DoubleRangeFacetCounts` compute counts for a dynamic numeric range from a provided `LongValuesSource` (previously indexed numeric field, or a dynamic expression such as distance).

At search time you first run your search, but pass a `FacetsCollector` to gather all hits (and optionally, scores for each hit). Then, instantiate whichever facet methods you'd like to use to compute aggregates. Finally, all methods implement a common `Facets` base API that you use to obtain specific facet counts.

The various `FacetsCollectorManager.search(org.apache.lucene.search.IndexSearcher, org.apache.lucene.search.Query, int, org.apache.lucene.facet.FacetsCollectorManager)` utility methods are useful for doing an "ordinary" search (sorting by score, or by a specified Sort) but also collecting into a `FacetsCollectorManager` for subsequent faceting.

- Related Packages
  Package
  Description
  org.apache.lucene.facet.facetset
  Provides FacetSets faceting capabilities which allows users to facet on high dimensional field values.
  org.apache.lucene.facet.range
  Provides range faceting capabilities.
  org.apache.lucene.facet.rangeonrange
  Provides range on range faceting capabilities.
  org.apache.lucene.facet.sortedset
  Provides faceting capabilities over facets that were indexed with `SortedSetDocValuesFacetField`.
  org.apache.lucene.facet.taxonomy
  Taxonomy of Categories.
- Class
  Description
  DrillDownQuery
  A `Query` for drill-down over facet categories.
  DrillSideways
  Computes drill down and sideways counts for the provided `DrillDownQuery`.
  DrillSideways.ConcurrentDrillSidewaysResult<R>
  Result of a concurrent drill sideways search, including the `Facets` and `TopDocs`.
  DrillSideways.DrillSidewaysResult
  Result of a drill sideways search, including the `Facets` and `TopDocs`.
  DrillSideways.Result<T,R>
  `DrillSideways.search(DrillDownQuery, CollectorManager, List)` result.
  FacetCountsWithFilterQuery
  Base class for facet counts.
  FacetField
  Add an instance of this to your `Document` for every facet label.
  FacetQuery
  A term `Query` over a `FacetField`.
  FacetResult
  Counts or aggregates for a single dimension.
  Facets
  Common base class for all facets implementations.
  FacetsCollector
  Collects hits for subsequent faceting.
  FacetsCollector.MatchingDocs
  Holds the documents that were matched in the `LeafReaderContext`.
  FacetsCollectorManager
  A `CollectorManager` implementation which produces FacetsCollector and produces a merged FacetsCollector.
  FacetsCollectorManager.FacetsResult
  Holds results of a search run via static utility methods exposed by this class.
  FacetsConfig
  Records per-dimension configuration.
  FacetsConfig.DimConfig
  Holds the configuration for one dimension
  FacetsConfig.DrillDownTermsIndexing
  Drill down terms indexing option to control whether dimension and sub-path terms should be indexed.
  FacetUtils
  Utility class with a single method for getting a DocIdSetIterator that skips deleted docs
  LabelAndValue
  Single label and its value, usually contained in a `FacetResult`.
  LongValueFacetCounts
  `Facets` implementation that computes counts for all unique long values, more efficiently counting small values (0-1023) using an int array, and switching to a `HashMap` for values above 1023.
  MultiDoubleValues
  Per-segment, per-document double values, which can be calculated at search-time.
  MultiDoubleValuesSource
  Base class for producing `MultiDoubleValues`.
  MultiFacetQuery
  A multi-terms `Query` over a `FacetField`.
  MultiFacets
  Maps specified dims to provided Facets impls; else, uses the default Facets impl.
  MultiLongValues
  Per-segment, per-document long values, which can be calculated at search-time.
  MultiLongValuesSource
  Base class for producing `MultiLongValues`.
  RandomSamplingFacetsCollector
  Collects hits for subsequent faceting, using sampling if needed.
  StringDocValuesReaderState
  Stores an `OrdinalMap` created for a specific `IndexReader` (`reader`) + `field`.
  StringValueFacetCounts
  Compute facet counts from a previously indexed `SortedSetDocValues` or `SortedDocValues` field.
  TopOrdAndFloatQueue
  Keeps highest results, first by largest float value, then tie-break by smallest ord.
  TopOrdAndFloatQueue.OrdAndFloat
  Holds an ordinal and a float value.
  TopOrdAndIntQueue
  Keeps highest results, first by largest int value, then tie-break by smallest ord.
  TopOrdAndIntQueue.OrdAndInt
  Holds an ordinal and an int value.
  TopOrdAndNumberQueue
  Keeps highest results, first by largest value, then tie-break by smallest ord.
  TopOrdAndNumberQueue.OrdAndValue
  Holds a single entry.