Package org.elasticsearch.xpack.esql.expression.function.aggregate

Class AggregateFunction

java.lang.Object

org.elasticsearch.xpack.esql.core.tree.Node<Expression>

org.elasticsearch.xpack.esql.core.expression.Expression

org.elasticsearch.xpack.esql.core.expression.function.Function

org.elasticsearch.xpack.esql.expression.function.aggregate.AggregateFunction

All Implemented Interfaces:

NamedWriteable, Writeable, PostAnalysisPlanVerificationAware, Resolvable

Direct Known Subclasses:

Absent, Avg, Count, CountApproximate, CountDistinct, DimensionValues, Earliest, First, FirstDocId, FromPartial, HistogramMerge, Last, Latest, Max, Median, Min, NumericAggregate, Present, Sample, Scalar, Sparkline, SpatialAggregateFunction, StdDev, TimeSeriesAggregateFunction, Top, ToPartial, Values, Variance, WeightedAvg

public abstract class AggregateFunction
extends Function
implements PostAnalysisPlanVerificationAware

A type of Function that takes multiple values and extracts a single value out of them. For example, AVG(). - Aggregate functions can have an optional filter and window, which default to Literal.TRUE and NO_WINDOW. - The aggregation function should be composed as: source, field, filter, window, parameters. Extra parameters should go to the parameters after the filter and window.

These function appear only in special places in the language that expect to take many inputs and produce one output per group key:

• | STATS MAX(a)
• | STATS MAX(a) BY ...

They always process many input rows to produce their values. If they are built without a BY they produce a single value as output. If they are built with a BY they produce one value per group key as output.

See AggregatorMode for important information about their execution lifecycle.

Nested Class Summary

Nested classes/interfaces inherited from class org.elasticsearch.xpack.esql.core.expression.Expression

Expression.TypeResolution

Nested classes/interfaces inherited from class org.elasticsearch.xpack.esql.core.tree.Node

Node.NodeStringFormat

Nested classes/interfaces inherited from interface org.elasticsearch.common.io.stream.Writeable

Writeable.Reader<V>, Writeable.Writer<V>

Field Summary

Fields

Modifier and Type	Field	Description
static final Literal	NO_WINDOW
static final TransportVersion	WINDOW_INTERVAL

Fields inherited from class org.elasticsearch.xpack.esql.core.tree.Node

TO_STRING_MAX_LINES, TO_STRING_MAX_WIDTH

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	AggregateFunction(StreamInput in)
protected	AggregateFunction(Source source, Expression field)
protected	AggregateFunction(Source source, Expression field, List<? extends Expression> parameters)
protected	AggregateFunction(Source source, Expression field, Expression filter, Expression window, List<? extends Expression> parameters)

Method Summary

Modifier and Type	Method	Description
List<Attribute>	aggregateInputReferences(Supplier<List<Attribute>> inputAttributes)	Returns the ordered list of input attributes required by this aggregate function, excluding those referenced by the filter.
boolean	equals(Object obj)
Expression	field()
Expression	filter()
boolean	hasFilter()
int	hashCode()
boolean	hasWindow()	Whether the aggregate function has a window different than NO_WINDOW.
List<? extends Expression>	parameters()
BiConsumer<LogicalPlan,Failures>	postAnalysisPlanVerification()	Allows the implementer to return a consumer that will perform self-validation in the context of the tree structure the implementer is part of.
protected static Expression	readWindow(StreamInput in)
protected Expression.TypeResolution	resolveType()	The implementation of Expression.typeResolved(), which is just a caching wrapper around this method.
Expression	window()	Return the window associated with the aggregate function.
AggregateFunction	withField(Expression newField)
static List<? extends Expression>	withFilter(List<? extends Expression> expression, Expression filter)
abstract AggregateFunction	withFilter(Expression filter)	Attach a filter to the aggregate function.
static Expression	withFilter(Expression expression, Expression filter)
AggregateFunction	withParameters(List<? extends Expression> parameters)
AggregateFunction	withWindow(Expression newWindow)
final void	writeTo(StreamOutput out)

Methods inherited from class org.elasticsearch.xpack.esql.core.expression.function.Function

arguments, functionName, nodeString, nullable

Methods inherited from class org.elasticsearch.xpack.esql.core.expression.Expression

canonical, canonicalize, childrenResolved, dataType, fold, foldable, propertiesToString, references, resolved, semanticEquals, semanticHash, toString, toString, typeResolved

Methods inherited from class org.elasticsearch.xpack.esql.core.tree.Node

allMatch, anyMatch, children, collect, collect, collect, collectFirstChildren, collectLeaves, doCollectFirst, forEachDown, forEachDown, forEachDownMayReturnEarly, forEachProperty, forEachPropertyDown, forEachPropertyOnly, forEachPropertyUp, forEachUp, forEachUp, info, nodeName, nodeProperties, nodeString, replaceChildren, replaceChildrenSameSize, source, sourceLocation, sourceText, transformChildren, transformChildren, transformDown, transformDown, transformDown, transformDown, transformDownSkipBranch, transformNodeProps, transformPropertiesDown, transformPropertiesOnly, transformPropertiesUp, transformUp, transformUp, transformUp

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.elasticsearch.common.io.stream.NamedWriteable

getWriteableName

Field Details

NO_WINDOW

public static final Literal NO_WINDOW

WINDOW_INTERVAL

public static final TransportVersion WINDOW_INTERVAL

Constructor Details

AggregateFunction

protected AggregateFunction(Source source,
 Expression field)

AggregateFunction

protected AggregateFunction(Source source,
 Expression field,
 List<? extends Expression> parameters)

AggregateFunction

protected AggregateFunction(Source source,
 Expression field,
 Expression filter,
 Expression window,
 List<? extends Expression> parameters)

AggregateFunction

protected AggregateFunction(StreamInput in)
                     throws IOException

Throws:

IOException

Method Details

readWindow

protected static Expression readWindow(StreamInput in)
                                throws IOException

Throws:

IOException

writeTo

public final void writeTo(StreamOutput out)
                   throws IOException

Specified by:

writeTo in interface Writeable

Throws:

IOException

field

public Expression field()

parameters

public List<? extends Expression> parameters()

hasFilter

public boolean hasFilter()

filter

public Expression filter()

resolveType

protected Expression.TypeResolution resolveType()

Description copied from class: Expression

The implementation of Expression.typeResolved(), which is just a caching wrapper around this method. See it's javadoc for what this method should return.

Implementations will rarely interact with the Expression.TypeResolution class directly, instead usually calling the utility methods on TypeResolutions.

Implementations should fail if Expression.childrenResolved() returns false.

Overrides:

resolveType in class Expression

withFilter

public abstract AggregateFunction withFilter(Expression filter)

Attach a filter to the aggregate function.

withFilter

public static Expression withFilter(Expression expression,
 Expression filter)

withFilter

public static List<? extends Expression> withFilter(List<? extends Expression> expression,
 Expression filter)

withParameters

public AggregateFunction withParameters(List<? extends Expression> parameters)

window

public Expression window()

Return the window associated with the aggregate function.

hasWindow

public boolean hasWindow()

Whether the aggregate function has a window different than NO_WINDOW.

aggregateInputReferences

public List<Attribute> aggregateInputReferences(Supplier<List<Attribute>> inputAttributes)

Returns the ordered list of input attributes required by this aggregate function, excluding those referenced by the filter. The order must align with the input channels expected by the aggregator.

hashCode

public int hashCode()

Overrides:

hashCode in class Function

equals

public boolean equals(Object obj)

Overrides:

equals in class Function

postAnalysisPlanVerification

public BiConsumer<LogicalPlan,Failures> postAnalysisPlanVerification()

Description copied from interface: PostAnalysisPlanVerificationAware

Allows the implementer to return a consumer that will perform self-validation in the context of the tree structure the implementer is part of. This usually involves checking the type and configuration of the children or that of the parent.

It is often more useful to perform the checks as extended as it makes sense, over stopping at the first failure. This will allow the author to progress faster to a correct query.

Example: a GroupingFunction instance, which models a function to group documents to aggregate over, can only be used in the context of the STATS command, modeled by the Aggregate class. This is how this verification is performed:

     
      @Override
      public BiConsumer<LogicalPlan, Failures> postAnalysisPlanVerification() {
          return (p, failures) -> {
              if (p instanceof Aggregate == false) {
                  p.forEachExpression(
                      GroupingFunction.class,
                      gf -> failures.add(fail(gf, "cannot use grouping function [{}] outside of a STATS command", gf.sourceText()))
                  );
              }
          };
      }
     
     

Specified by:

postAnalysisPlanVerification in interface PostAnalysisPlanVerificationAware

Returns:

a consumer that will receive a tree to check and an accumulator of failures found during inspection.

withField

public AggregateFunction withField(Expression newField)

withWindow

public AggregateFunction withWindow(Expression newWindow)