org.apache.lucene.facet.sampling

## Class Sampler

- java.lang.Object
- - org.apache.lucene.facet.sampling.Sampler

Direct Known Subclasses:
  RandomSampler, RepeatableSampler

    public abstract class Sampler
    extends Object

Sampling definition for facets accumulation

The Sampler uses TAKMI style counting to provide a 'best guess' top-K result set of the facets accumulated.

Note: Sampling accumulation (Accumulation over a sampled-set of the results), does not guarantee accurate values for `FacetResult.getNumValidDescendants()`.

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

### Nested Class Summary

Nested Classes
`static class` `Sampler.SampleResult` Result of sample computation

### Field Summary

Fields
`protected SamplingParams` `samplingParams`

### Constructor Summary

Constructors
Constructor and Description
`Sampler()` Construct with `SamplingParams`
`Sampler(SamplingParams params)` Construct with certain `SamplingParams`

### Method Summary

Methods
`protected abstract Sampler.SampleResult` `createSample(ScoredDocIDs docids, int actualSize, int sampleSetSize)` Create and return a sample of the input set
`SampleFixer` `getSampleFixer(IndexReader indexReader, TaxonomyReader taxonomyReader, FacetSearchParams searchParams)` Get a fixer of sample facet accumulation results.
`Sampler.SampleResult` `getSampleSet(ScoredDocIDs docids)` Compute a sample set out of the input set, based on the `SamplingParams.getSampleRatio()` in effect.
`SamplingParams` `getSamplingParams()` Return the sampling params in effect
`FacetSearchParams` `overSampledSearchParams(FacetSearchParams original)` Over-sampled search params, wrapping each request with an over-sampled one.
`boolean` `shouldSample(ScoredDocIDs docIds)` Check if this sampler would complement for the input docIds
`FacetResult` `trimResult(FacetResult facetResult)` Trim the input facet result. Note: It is only valid to call this method with result obtained for a facet request created through `overSampledSearchParams(FacetSearchParams)`.

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

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

### Field Detail

#### samplingParams

    protected final SamplingParams samplingParams

### Constructor Detail

#### Sampler

    public Sampler()

Construct with `SamplingParams`

#### Sampler

    public Sampler(SamplingParams params)
            throws IllegalArgumentException

Construct with certain `SamplingParams`

Parameters:
  `params` - sampling params in effect
Throws:
  `IllegalArgumentException` - if the provided SamplingParams are not valid

### Method Detail

#### shouldSample

    public boolean shouldSample(ScoredDocIDs docIds)

Check if this sampler would complement for the input docIds

#### getSampleSet

    public Sampler.SampleResult getSampleSet(ScoredDocIDs docids)
                                      throws IOException

Compute a sample set out of the input set, based on the `SamplingParams.getSampleRatio()` in effect. Sub classes can override to alter how the sample set is computed.

If the input set is of size smaller than `SamplingParams.getMinSampleSize()`, the input set is returned (no sampling takes place).

Other than that, the returned set size will not be larger than `SamplingParams.getMaxSampleSize()` nor smaller than `SamplingParams.getMinSampleSize()`.

Parameters:
  `docids` - full set of matching documents out of which a sample is needed.
Throws:
  `IOException`

#### createSample

    protected abstract Sampler.SampleResult createSample(ScoredDocIDs docids,
                                    int actualSize,
                                    int sampleSetSize)
                                                  throws IOException

Create and return a sample of the input set

Parameters:
  `docids` - input set out of which a sample is to be created
  `actualSize` - original size of set, prior to sampling
  `sampleSetSize` - required size of sample set
Returns:
  sample of the input set in the required size
Throws:
  `IOException`

#### getSampleFixer

    public SampleFixer getSampleFixer(IndexReader indexReader,
                             TaxonomyReader taxonomyReader,
                             FacetSearchParams searchParams)

Get a fixer of sample facet accumulation results. Default implementation returns a `TakmiSampleFixer` which is adequate only for counting. For any other accumulator, provide a different fixer.

#### getSamplingParams

    public final SamplingParams getSamplingParams()

Return the sampling params in effect

#### trimResult

    public FacetResult trimResult(FacetResult facetResult)
                           throws IllegalArgumentException

Trim the input facet result.
Note: It is only valid to call this method with result obtained for a facet request created through `overSampledSearchParams(FacetSearchParams)`.

Throws:
  `IllegalArgumentException` - if called with results not obtained for requests created through `overSampledSearchParams(FacetSearchParams)`

#### overSampledSearchParams

    public FacetSearchParams overSampledSearchParams(FacetSearchParams original)

Over-sampled search params, wrapping each request with an over-sampled one.