Package org.apache.lucene.facet

# Class DrillSideways

java.lang.Object
org.apache.lucene.facet.DrillSideways

public class DrillSideways extends Object
Computes drill down and sideways counts for the provided `DrillDownQuery`. Drill sideways counts include alternative values/aggregates for the drill-down dimensions so that a dimension does not disappear after the user drills down into it.

Use one of the static search methods to do the search, and then get the hits and facet results from the returned `DrillSideways.DrillSidewaysResult`.

There is both a "standard" and "concurrent" implementation for drill sideways. The concurrent approach is enabled by providing an `ExecutorService` to the ctor. The concurrent implementation may be a little faster but does duplicate work (which grows linearly with the number of drill down dimensions specified on the provided `DrillDownQuery`). The duplicate work may impact the overall throughput of a system. The standard approach may be a little slower but avoids duplicate computations and query processing. Note that both approaches are compatible with concurrent searching across segments (i.e., if using an `IndexSearcher` constructed with an `Executor`).

NOTE: this allocates one `FacetsCollector` for each drill-down, plus one. If your index has high number of facet labels then this will multiply your memory usage.

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

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`static class`
`DrillSideways.ConcurrentDrillSidewaysResult<R>`
Result of a concurrent drill sideways search, including the `Facets` and `TopDocs`.
`static class`
`DrillSideways.DrillSidewaysResult`
Result of a drill sideways search, including the `Facets` and `TopDocs`.
`static final record`
`DrillSideways.Result<T,R>`
`search(DrillDownQuery, CollectorManager, List)` result.

## Field Summary

Fields
Modifier and Type
Field
Description
`protected final FacetsConfig`
`config`
`FacetsConfig` passed to constructor.
`protected final IndexSearcher`
`searcher`
`IndexSearcher` passed to constructor.
`protected final SortedSetDocValuesReaderState`
`state`
`SortedSetDocValuesReaderState` passed to constructor; can be null.
`protected final TaxonomyReader`
`taxoReader`
`TaxonomyReader` passed to constructor.

## Constructor Summary

Constructors
Constructor
Description
`DrillSideways(IndexSearcher searcher, FacetsConfig config, SortedSetDocValuesReaderState state)`
Create a new `DrillSideways` instance, assuming the categories were indexed with `SortedSetDocValuesFacetField`.
`DrillSideways(IndexSearcher searcher, FacetsConfig config, TaxonomyReader taxoReader)`
Create a new `DrillSideways` instance.
`DrillSideways(IndexSearcher searcher, FacetsConfig config, TaxonomyReader taxoReader, SortedSetDocValuesReaderState state)`
Create a new `DrillSideways` instance, where some dimensions were indexed with `SortedSetDocValuesFacetField` and others were indexed with `FacetField`.
`DrillSideways(IndexSearcher searcher, FacetsConfig config, TaxonomyReader taxoReader, SortedSetDocValuesReaderState state, ExecutorService executor)`
Create a new `DrillSideways` instance, where some dimensions were indexed with `SortedSetDocValuesFacetField` and others were indexed with `FacetField`.

## Method Summary

Modifier and Type
Method
Description
`protected Facets`
`buildFacetsResult(FacetsCollector drillDowns, FacetsCollector[] drillSideways, String[] drillSidewaysDims)`
Subclass can override to customize per-dim Facets impl.
`protected FacetsCollectorManager`
`createDrillDownFacetsCollectorManager()`
Subclass can override to customize drill down facets collector.
`protected FacetsCollectorManager`
`createDrillSidewaysFacetsCollectorManager()`
Subclass can override to customize drill sideways facets collector.
`protected boolean`
`scoreSubDocsAtOnce()`
Override this and return true if your collector (e.g., `ToParentBlockJoinCollector`) expects all sub-scorers to be positioned on the document being collected.
`DrillSideways.DrillSidewaysResult`
`search(DrillDownQuery query, int topN)`
Search, sorting by score, and computing drill down and sideways counts.
`<R> DrillSideways.ConcurrentDrillSidewaysResult<R>`
`search(DrillDownQuery query, CollectorManager<?,R> hitCollectorManager)`
Runs a search, using a `CollectorManager` to gather and merge search results
`<C extends Collector, T, K extends Collector, R>
DrillSideways.Result<T,R>`
`search(DrillDownQuery query, CollectorManager<C,T> drillDownCollectorManager, List<? extends CollectorManager<K,R>> drillSidewaysCollectorManagers)`
Search using DrillDownQuery with custom collectors.
`DrillSideways.DrillSidewaysResult`
`search(DrillDownQuery query, Query filter, FieldDoc after, int topN, Sort sort, boolean doDocScores)`
Search, sorting by `Sort`, and computing drill down and sideways counts.
`DrillSideways.DrillSidewaysResult`
`search(ScoreDoc after, DrillDownQuery query, int topN)`
Search, sorting by score, and computing drill down and sideways counts.

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

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

## Field Details

### searcher

protected final IndexSearcher searcher
`IndexSearcher` passed to constructor.

### taxoReader

protected final TaxonomyReader taxoReader
`TaxonomyReader` passed to constructor.

### state

protected final SortedSetDocValuesReaderState state
`SortedSetDocValuesReaderState` passed to constructor; can be null.

### config

protected final FacetsConfig config
`FacetsConfig` passed to constructor.

## Constructor Details

### DrillSideways

public DrillSideways(IndexSearcher searcher, FacetsConfig config, TaxonomyReader taxoReader)
Create a new `DrillSideways` instance.

### DrillSideways

public DrillSideways(IndexSearcher searcher, FacetsConfig config, SortedSetDocValuesReaderState state)
Create a new `DrillSideways` instance, assuming the categories were indexed with `SortedSetDocValuesFacetField`.

### DrillSideways

public DrillSideways(IndexSearcher searcher, FacetsConfig config, TaxonomyReader taxoReader, SortedSetDocValuesReaderState state)
Create a new `DrillSideways` instance, where some dimensions were indexed with `SortedSetDocValuesFacetField` and others were indexed with `FacetField`.

### DrillSideways

public DrillSideways(IndexSearcher searcher, FacetsConfig config, TaxonomyReader taxoReader, SortedSetDocValuesReaderState state, ExecutorService executor)
Create a new `DrillSideways` instance, where some dimensions were indexed with `SortedSetDocValuesFacetField` and others were indexed with `FacetField`.

Use this constructor to use the concurrent implementation

## Method Details

### createDrillDownFacetsCollectorManager

protected FacetsCollectorManager createDrillDownFacetsCollectorManager()
Subclass can override to customize drill down facets collector. Returning `null` is valid if no drill down facet collection is needed.

### createDrillSidewaysFacetsCollectorManager

protected FacetsCollectorManager createDrillSidewaysFacetsCollectorManager()
Subclass can override to customize drill sideways facets collector. This should not return `null` as we assume drill sideways is being used to collect "sideways" hits:

### buildFacetsResult

protected Facets buildFacetsResult(FacetsCollector drillDowns, FacetsCollector[] drillSideways, String[] drillSidewaysDims) throws IOException
Subclass can override to customize per-dim Facets impl.

Throws:
  `IOException`

### search

public DrillSideways.DrillSidewaysResult search(DrillDownQuery query, Query filter, FieldDoc after, int topN, Sort sort, boolean doDocScores) throws IOException
Search, sorting by `Sort`, and computing drill down and sideways counts.

Throws:
  `IOException`

### search

public DrillSideways.DrillSidewaysResult search(DrillDownQuery query, int topN) throws IOException
Search, sorting by score, and computing drill down and sideways counts.

Throws:
  `IOException`

### search

public DrillSideways.DrillSidewaysResult search(ScoreDoc after, DrillDownQuery query, int topN) throws IOException
Search, sorting by score, and computing drill down and sideways counts.

Throws:
  `IOException`

### scoreSubDocsAtOnce

protected boolean scoreSubDocsAtOnce()
Override this and return true if your collector (e.g., `ToParentBlockJoinCollector`) expects all sub-scorers to be positioned on the document being collected. This will cause some performance loss; default is false.

### search

public <R> DrillSideways.ConcurrentDrillSidewaysResult<R> search(DrillDownQuery query, CollectorManager<?,R> hitCollectorManager) throws IOException
Runs a search, using a `CollectorManager` to gather and merge search results

Throws:
  `IOException`

### search

public <C extends Collector, T, K extends Collector, R> DrillSideways.Result<T,R> search(DrillDownQuery query, CollectorManager<C,T> drillDownCollectorManager, List<? extends CollectorManager<K,R>> drillSidewaysCollectorManagers) throws IOException
Search using DrillDownQuery with custom collectors. This method can be used with any `CollectorManager`s.

Note: Use `MultiCollectorManager` to collect both hits and facets for the entire query and/or for drill-sideways dimensions. You can also use it to wrap different types of `CollectorManager` for drill-sideways dimensions.

Throws:
  `IOException`