Package org.elasticsearch.search.aggregations

Class AggregatorBase

java.lang.Object
org.elasticsearch.search.aggregations.BucketCollector
org.elasticsearch.search.aggregations.Aggregator
org.elasticsearch.search.aggregations.AggregatorBase
All Implemented Interfaces:
Closeable, AutoCloseable, org.apache.lucene.search.Collector, Releasable
Direct Known Subclasses:
BucketsAggregator, MetricsAggregator, NonCollectingAggregator
public abstract class AggregatorBase extends Aggregator
Base implementation for concrete aggregators.

  • Field Details

    • DEFAULT_WEIGHT

      public static final int DEFAULT_WEIGHT
      The default "weight" that a bucket takes when performing an aggregation
      See Also:

    • name

      protected final String name

    • parent

      protected final Aggregator parent

    • subAggregators

      protected final Aggregator[] subAggregators

    • collectableSubAggregators

      protected BucketCollector collectableSubAggregators

  • Constructor Details

    • AggregatorBase

      protected AggregatorBase(String name, AggregatorFactories factories, AggregationContext context, Aggregator parent, CardinalityUpperBound subAggregatorCardinality, Map<String,Object> metadata) throws IOException
      Constructs a new Aggregator.
      Parameters:
      name - The name of the aggregation
      factories - The factories for all the sub-aggregators under this aggregator
      context - The aggregation context
      parent - The parent aggregator (may be null for top level aggregators)
      subAggregatorCardinality - Upper bound of the number of buckets that sub aggregations will collect
      metadata - The metadata associated with this aggregator
      Throws:
      IOException

  • Method Details

    • pointReaderIfAvailable

      public final Function<byte[],Number> pointReaderIfAvailable(ValuesSourceConfig config)
      Returns a converter for point values if it's safe to use the indexed data instead of doc values. Generally, this means that the query has no filters or scripts, the aggregation is top level, and the underlying field is indexed, and the index is sorted in the right order. If those conditions aren't met, return null to indicate a point reader cannot be used in this case.
      Parameters:
      config - The config for the values source metric.

    • addRequestCircuitBreakerBytes

      protected long addRequestCircuitBreakerBytes(long bytes)
      Increment or decrement the number of bytes that have been allocated to service this request and potentially trigger a CircuitBreakingException. The number of bytes allocated is automatically decremented with the circuit breaker service on closure of this aggregator. If memory has been returned, decrement it without tripping the breaker. For performance reasons subclasses should not call this millions of times each with small increments and instead batch up into larger allocations.
      Parameters:
      bytes - the number of bytes to register or negative to deregister the bytes
      Returns:
      the cumulative size in bytes allocated by this aggregator to service this request

    • scoreMode

      public org.apache.lucene.search.ScoreMode scoreMode()
      Most aggregators don't need scores, make sure to extend this method if your aggregator needs them.

    • metadata

      public Map<String,Object> metadata()

    • getLeafCollector

      protected abstract LeafBucketCollector getLeafCollector(org.apache.lucene.index.LeafReaderContext ctx, LeafBucketCollector sub) throws IOException
      Collect results for this leaf.

      Most Aggregators will return a custom LeafBucketCollector that collects document information for every hit. Callers of this method will make sure to call collect for every hit. So any Aggregator that returns a customer LeafBucketCollector from this method runs at best O(hits) time. See the sum Aggregator for a fairly strait forward example of this.

      Some Aggregators are able to correctly collect results on their own, without being iterated by the top level query or the rest of the aggregations framework. These aggregations collect what they need by calling methods on LeafReaderContext and then they return LeafBucketCollector.NO_OP_COLLECTOR to signal that they've done their own collection. These aggregations can do better than O(hits). See the min Aggregator for an example of an aggregation that does this. It happens to run in constant time in some cases.

      In other cases MinAggregator can't get correct results by taking the constant time path so instead it returns a custom LeafBucketCollector. This is fairly common for aggregations that have these fast paths because most of these fast paths are only possible when the aggregation is at the root of the tree.

      Its also useful to look at the filters Aggregator chooses whether or not it can use the fast path before building the Aggregator rather than on each leaf. Either is fine.

      Throws:
      IOException

    • getLeafCollector

      public final LeafBucketCollector getLeafCollector(org.apache.lucene.index.LeafReaderContext ctx) throws IOException
      Collect results for this leaf.

      Implemented by the Aggregator base class to correctly set up sub Aggregators. See the abstract delegate for more details on what this does.

      Specified by:
      getLeafCollector in interface org.apache.lucene.search.Collector
      Specified by:
      getLeafCollector in class BucketCollector
      Throws:
      IOException

    • preGetSubLeafCollectors

      protected void preGetSubLeafCollectors(org.apache.lucene.index.LeafReaderContext ctx) throws IOException
      Can be overridden by aggregator implementations that like the perform an operation before the leaf collectors of children aggregators are instantiated for the next segment.
      Throws:
      IOException

    • doPreCollection

      protected void doPreCollection() throws IOException
      Can be overridden by aggregator implementation to be called back when the collection phase starts.
      Throws:
      IOException

    • preCollection

      public final void preCollection() throws IOException
      Description copied from class: BucketCollector
      Pre collection callback.
      Specified by:
      preCollection in class BucketCollector
      Throws:
      IOException

    • name

      public String name()
      Description copied from class: Aggregator
      Return the name of this aggregator.
      Specified by:
      name in class Aggregator
      Returns:
      The name of the aggregation.

    • parent

      public Aggregator parent()
      Description copied from class: Aggregator
      Return the parent aggregator.
      Specified by:
      parent in class Aggregator
      Returns:
      The parent aggregator of this aggregator. The addAggregation are hierarchical in the sense that some can be composed out of others (more specifically, bucket addAggregation can define other addAggregation that will be aggregated per bucket). This method returns the direct parent aggregator that contains this aggregator, or null if there is none (meaning, this aggregator is a top level one)

    • subAggregators

      public Aggregator[] subAggregators()
      Description copied from class: Aggregator
      Get the aggregators running under this one.
      Specified by:
      subAggregators in class Aggregator

    • subAggregator

      public Aggregator subAggregator(String aggName)
      Description copied from class: Aggregator
      Return the sub aggregator with the provided name.
      Specified by:
      subAggregator in class Aggregator

    • postCollection

      public void postCollection() throws IOException
      Called after collection of all document is done.

      Warning: this is not final only to allow the parent join aggregator to delay this until building buckets.

      Specified by:
      postCollection in class BucketCollector
      Throws:
      IOException

    • close

      public void close()
      Called upon release of the aggregator.

    • doClose

      protected void doClose()
      Release instance-specific data.

    • doPostCollection

      protected void doPostCollection() throws IOException
      Can be overridden by aggregator implementation to be called back when the collection phase ends.
      Throws:
      IOException

    • buildEmptySubAggregations

      protected final InternalAggregations buildEmptySubAggregations()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • bigArrays

      protected final BigArrays bigArrays()
      Utilities for sharing large primitive arrays and tracking their usage. Used by all subclasses.

    • topLevelQuery

      protected final org.apache.lucene.search.Query topLevelQuery()
      The "top level" query that will filter the results sent to this Aggregator. Used by all Aggregators that perform extra collection phases in addition to the one done in getLeafCollector(LeafReaderContext, LeafBucketCollector).

    • searcher

      protected final org.apache.lucene.search.IndexSearcher searcher()
      The searcher for the shard this Aggregator is running against. Used by all Aggregators that perform extra collection phases in addition to the one done in getLeafCollector(LeafReaderContext, LeafBucketCollector) and by to look up extra "background" information about contents of the shard itself.