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
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `Sampler.SampleResult` Result of sample computation

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected SamplingParams` | `samplingParams`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.

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