org.apache.lucene.facet.search.sampling
Class Sampler

java.lang.Object
  org.apache.lucene.facet.search.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() & FacetResultNode.getResidue().

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

Nested Class Summary

static class

Sampler.SampleResult Result of sample computation

Field Summary

protected SamplingParams

samplingParams

Constructor Summary

Sampler()
Construct with SamplingParams

Sampler(SamplingParams params)
Construct with certain SamplingParams

Method Summary

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.