Package org.elasticsearch.search.aggregations.bucket.range

Class RangeAggregator

java.lang.Object

org.elasticsearch.search.aggregations.BucketCollector

org.elasticsearch.search.aggregations.Aggregator

org.elasticsearch.search.aggregations.AggregatorBase

org.elasticsearch.search.aggregations.bucket.BucketsAggregator

org.elasticsearch.search.aggregations.bucket.range.RangeAggregator

All Implemented Interfaces:

Closeable, AutoCloseable, org.apache.lucene.search.Collector, org.elasticsearch.core.Releasable

public abstract class RangeAggregator
extends BucketsAggregator

Aggregator for range. There are two known subclasses, RangeAggregator.NoOverlap which is fast but only compatible with ranges that don't have overlaps and RangeAggregator.Overlap which handles overlapping ranges. There is also RangeAggregator.FromFilters which isn't a subclass but is also a functional aggregator for range. build(java.lang.String, org.elasticsearch.search.aggregations.AggregatorFactories, org.elasticsearch.search.aggregations.support.ValuesSourceConfig, org.elasticsearch.search.aggregations.bucket.range.InternalRange.Factory<?, ?>, org.elasticsearch.search.aggregations.bucket.range.RangeAggregator.Range[], boolean, org.elasticsearch.search.aggregations.support.AggregationContext, org.elasticsearch.search.aggregations.Aggregator, org.elasticsearch.search.aggregations.CardinalityUpperBound, java.util.Map<java.lang.String, java.lang.Object>) will build the fastest of the three that is compatible with the requested configuration.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	RangeAggregator.Range
static class	RangeAggregator.Unmapped<R extends RangeAggregator.Range>

Nested classes/interfaces inherited from class org.elasticsearch.search.aggregations.bucket.BucketsAggregator

BucketsAggregator.BucketBuilderForFixedCount<B>, BucketsAggregator.BucketBuilderForVariable<B>, BucketsAggregator.ResultBuilderForVariable<B>, BucketsAggregator.SingleBucketResultBuilder

Nested classes/interfaces inherited from class org.elasticsearch.search.aggregations.Aggregator

Aggregator.BucketComparator, Aggregator.Parser, Aggregator.SubAggCollectionMode

Field Summary

Fields

Modifier and Type	Field	Description
static double	DOCS_PER_RANGE_TO_USE_FILTERS	Minimum number of docs in the index per range before we attempt to use a filter-based collection mechanism.
static org.elasticsearch.common.xcontent.ParseField	KEYED_FIELD
static long	MAX_ACCURATE_BOUND	The maximum long that can accurately fit into the double precision floating point bounds.
protected RangeAggregator.Range[]	ranges
static org.elasticsearch.common.xcontent.ParseField	RANGES_FIELD
protected ValuesSource	valuesSource

Fields inherited from class org.elasticsearch.search.aggregations.bucket.BucketsAggregator

docCountProvider

Fields inherited from class org.elasticsearch.search.aggregations.AggregatorBase

collectableSubAggregators, DEFAULT_WEIGHT, name, parent, subAggregators

Fields inherited from class org.elasticsearch.search.aggregations.BucketCollector

NO_OP_COLLECTOR

Constructor Summary

Constructors

Constructor	Description
RangeAggregator(String name, AggregatorFactories factories, ValuesSource valuesSource, DocValueFormat format, InternalRange.Factory rangeFactory, RangeAggregator.Range[] ranges, double averageDocsPerRange, boolean keyed, AggregationContext context, Aggregator parent, CardinalityUpperBound cardinality, Map<String,Object> metadata)

Method Summary

Modifier and Type	Method	Description
static org.elasticsearch.search.aggregations.bucket.range.RangeAggregator.FromFilters<?>	adaptIntoFiltersOrNull(String name, AggregatorFactories factories, ValuesSourceConfig valuesSourceConfig, InternalRange.Factory<?,?> rangeFactory, RangeAggregator.Range[] ranges, double averageDocsPerRange, boolean keyed, AggregationContext context, Aggregator parent, CardinalityUpperBound cardinality, Map<String,Object> metadata)
static Aggregator	build(String name, AggregatorFactories factories, ValuesSourceConfig valuesSourceConfig, InternalRange.Factory<?,?> rangeFactory, RangeAggregator.Range[] ranges, boolean keyed, AggregationContext context, Aggregator parent, CardinalityUpperBound cardinality, Map<String,Object> metadata)	Build an Aggregator for a range aggregation.
InternalAggregation[]	buildAggregations(long[] owningBucketOrds)	Build the results of this aggregation.
InternalAggregation	buildEmptyAggregation()	Build an empty aggregation.
static Aggregator	buildWithoutAttemptedToAdaptToFilters(String name, AggregatorFactories factories, ValuesSource.Numeric valuesSource, DocValueFormat format, InternalRange.Factory<?,?> rangeFactory, RangeAggregator.Range[] ranges, double averageDocsPerRange, boolean keyed, AggregationContext context, Aggregator parent, CardinalityUpperBound cardinality, Map<String,Object> metadata)
void	collectDebugInfo(BiConsumer<String,Object> add)	Collect debug information to add to the profiling results.
static boolean	hasOverlap(RangeAggregator.Range[] ranges)
org.apache.lucene.search.ScoreMode	scoreMode()	Most aggregators don't need scores, make sure to extend this method if your aggregator needs them.
protected long	subBucketOrdinal(long owningBucketOrdinal, int rangeOrd)

Methods inherited from class org.elasticsearch.search.aggregations.bucket.BucketsAggregator

bucketComparator, bucketDocCount, buildAggregationsForFixedBucketCount, buildAggregationsForSingleBucket, buildAggregationsForVariableBuckets, buildSubAggsForAllBuckets, buildSubAggsForBuckets, buildSubAggsForBuckets, close, collectBucket, collectExistingBucket, descendsFromGlobalAggregator, getDocCounts, grow, incrementBucketDocCount, maxBucketOrd, preGetSubLeafCollectors, prepareSubAggs, resolveSortPath, rewriteBuckets

Methods inherited from class org.elasticsearch.search.aggregations.AggregatorBase

addRequestCircuitBreakerBytes, bigArrays, buildEmptySubAggregations, doClose, doPostCollection, doPreCollection, getLeafCollector, getLeafCollector, metadata, name, parent, pointReaderIfAvailable, postCollection, preCollection, searcher, subAggregator, subAggregators, topLevelQuery, toString

Methods inherited from class org.elasticsearch.search.aggregations.Aggregator

buildTopLevel, resolveSortPathOnValidAgg

Methods inherited from class java.lang.Object

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

Field Details

DOCS_PER_RANGE_TO_USE_FILTERS

public static final double DOCS_PER_RANGE_TO_USE_FILTERS

Minimum number of docs in the index per range before we attempt to use a filter-based collection mechanism. This exists mostly to keep fast range aggregations fast. Each filter has an overhead in the ball park of half a millisecond just to build its ScorerSupplier. If there are only a couple of thousand docs in the range then it tends not to be worth it to kick in the optimization.

The value of this field was experimentally derived but the experiment wasn't particularly rigorous. We had a performance test that collected 123 buckets with an average of 900 documents per bucket that jumped from 35ms to 90ms. I figure that 5000 is fairly close to where the break even point is.

See Also:

Constant Field Values

MAX_ACCURATE_BOUND

public static final long MAX_ACCURATE_BOUND

The maximum long that can accurately fit into the double precision floating point bounds.

See Also:

Constant Field Values

RANGES_FIELD

public static final org.elasticsearch.common.xcontent.ParseField RANGES_FIELD

KEYED_FIELD

public static final org.elasticsearch.common.xcontent.ParseField KEYED_FIELD

valuesSource

protected final ValuesSource valuesSource

ranges

protected final RangeAggregator.Range[] ranges

Constructor Details

RangeAggregator

public RangeAggregator(String name,
 AggregatorFactories factories,
 ValuesSource valuesSource,
 DocValueFormat format,
 InternalRange.Factory rangeFactory,
 RangeAggregator.Range[] ranges,
 double averageDocsPerRange,
 boolean keyed,
 AggregationContext context,
 Aggregator parent,
 CardinalityUpperBound cardinality,
 Map<String,Object> metadata)
                throws IOException

Throws:

IOException

Method Details

build

public static Aggregator build(String name,
 AggregatorFactories factories,
 ValuesSourceConfig valuesSourceConfig,
 InternalRange.Factory<?,?> rangeFactory,
 RangeAggregator.Range[] ranges,
 boolean keyed,
 AggregationContext context,
 Aggregator parent,
 CardinalityUpperBound cardinality,
 Map<String,Object> metadata)
                        throws IOException

Build an Aggregator for a range aggregation. If the ranges can be converted into filters then it builds a FiltersAggregator and uses that to collect the results if that aggregator can run in "filter by filter" collection mode. If it can't then we'll collect the ranges using a native RangeAggregator which is significantly faster than the "compatible" collection mechanism for the filters agg.

Throws:

IOException

adaptIntoFiltersOrNull

public static org.elasticsearch.search.aggregations.bucket.range.RangeAggregator.FromFilters<?> adaptIntoFiltersOrNull(String name,
 AggregatorFactories factories,
 ValuesSourceConfig valuesSourceConfig,
 InternalRange.Factory<?,?> rangeFactory,
 RangeAggregator.Range[] ranges,
 double averageDocsPerRange,
 boolean keyed,
 AggregationContext context,
 Aggregator parent,
 CardinalityUpperBound cardinality,
 Map<String,Object> metadata)
                                                                                                                throws IOException

Throws:

IOException

buildWithoutAttemptedToAdaptToFilters

public static Aggregator buildWithoutAttemptedToAdaptToFilters(String name,
 AggregatorFactories factories,
 ValuesSource.Numeric valuesSource,
 DocValueFormat format,
 InternalRange.Factory<?,?> rangeFactory,
 RangeAggregator.Range[] ranges,
 double averageDocsPerRange,
 boolean keyed,
 AggregationContext context,
 Aggregator parent,
 CardinalityUpperBound cardinality,
 Map<String,Object> metadata)
                                                        throws IOException

Throws:

IOException

scoreMode

public org.apache.lucene.search.ScoreMode scoreMode()

Description copied from class: AggregatorBase

Most aggregators don't need scores, make sure to extend this method if your aggregator needs them.

Specified by:

scoreMode in interface org.apache.lucene.search.Collector

Overrides:

scoreMode in class AggregatorBase

subBucketOrdinal

protected long subBucketOrdinal(long owningBucketOrdinal,
 int rangeOrd)

buildAggregations

public InternalAggregation[] buildAggregations(long[] owningBucketOrds)
                                        throws IOException

Description copied from class: Aggregator

Build the results of this aggregation.

Specified by:

buildAggregations in class Aggregator

Parameters:

owningBucketOrds - the ordinals of the buckets that we want to collect from this aggregation

Returns:

the results for each ordinal, in the same order as the array of ordinals

Throws:

IOException

buildEmptyAggregation

public InternalAggregation buildEmptyAggregation()

Description copied from class: Aggregator

Build an empty aggregation.

Specified by:

buildEmptyAggregation in class Aggregator

collectDebugInfo

public void collectDebugInfo(BiConsumer<String,Object> add)

Description copied from class: Aggregator

Collect debug information to add to the profiling results. This will only be called if the aggregation is being profiled.

Well behaved implementations will always call the superclass implementation just in case it has something interesting. They will also only add objects which can be serialized with StreamOutput.writeGenericValue(Object) and XContentBuilder.value(Object). And they'll have an integration test.

Overrides:

collectDebugInfo in class Aggregator

hasOverlap

public static boolean hasOverlap(RangeAggregator.Range[] ranges)