Package org.elasticsearch.xpack.esql.expression.function.scalar.multivalue

Class MvSingleValueOrNull

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.core.expression.function.scalar.ScalarFunction

org.elasticsearch.xpack.esql.expression.function.scalar.EsqlScalarFunction

org.elasticsearch.xpack.esql.expression.function.scalar.UnaryScalarFunction

org.elasticsearch.xpack.esql.expression.function.scalar.multivalue.AbstractMultivalueFunction

org.elasticsearch.xpack.esql.expression.function.scalar.multivalue.MvSingleValueOrNull

All Implemented Interfaces:

NamedWriteable, Writeable, Resolvable, EvaluatorMapper

public class MvSingleValueOrNull
extends AbstractMultivalueFunction

Internal optimizer function that returns an expression's value if it is single-valued, or null if it is multi-valued.

This is not a user-visible function; it is injected by the query planner to enable rewrites such as:

   | STATS s1 = SUM(expr + c1), s2 = SUM(expr + c2)
   →
   | STATS svSum = SUM(SINGLE_VALUE_OR_NULL(expr)), svCount = COUNT(SINGLE_VALUE_OR_NULL(expr))
   | EVAL s1 = svSum + c1 * svCount, s2 = svSum + c2 * svCount
 

which applies when two or more SUM(expr ± c) expressions share the same expr. The wrapped expression is not limited to field references — it can be any expression whose result may be multi-valued.

A single node may carry multiple Source entries in warningSources, one per original expression that the node represents. On encountering a multi-valued position the evaluator emits a separate warning for each source, so callers that share one node across several expressions still get a distinct warning per expression.

Nested Class Summary

Nested classes/interfaces inherited from class org.elasticsearch.xpack.esql.expression.function.scalar.multivalue.AbstractMultivalueFunction

AbstractMultivalueFunction.AbstractEvaluator, AbstractMultivalueFunction.AbstractNullableEvaluator

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.xpack.esql.evaluator.mapper.EvaluatorMapper

EvaluatorMapper.ToEvaluator

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 NamedWriteableRegistry.Entry	ENTRY
static final TransportVersion	MV_SINGLE_VALUE_OR_NULL_TRANSPORT_VERSION

Fields inherited from class org.elasticsearch.xpack.esql.expression.function.scalar.UnaryScalarFunction

field

Fields inherited from class org.elasticsearch.xpack.esql.core.expression.function.scalar.ScalarFunction

MAX_BYTES_REF_RESULT_SIZE

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

TO_STRING_MAX_LINES, TO_STRING_MAX_WIDTH

Constructor Summary

Constructors

Constructor	Description
MvSingleValueOrNull(Source source, Expression field)
MvSingleValueOrNull(Source source, Expression field, List<Source> warningSources)

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object obj)
protected ExpressionEvaluator.Factory	evaluator(ExpressionEvaluator.Factory fieldEval)	Build the evaluator given the evaluator a multivalued field.
String	getWriteableName()
int	hashCode()
protected NodeInfo<? extends Expression>	info()	Normally, you want to use one of the static create methods to implement this.
Expression	replaceChildren(List<Expression> newChildren)
protected Expression.TypeResolution	resolveFieldType()
List<Source>	warningSources()
void	writeTo(StreamOutput out)

Methods inherited from class org.elasticsearch.xpack.esql.expression.function.scalar.multivalue.AbstractMultivalueFunction

resolveType, toEvaluator

Methods inherited from class org.elasticsearch.xpack.esql.expression.function.scalar.UnaryScalarFunction

dataType, field, foldable

Methods inherited from class org.elasticsearch.xpack.esql.expression.function.scalar.EsqlScalarFunction

fold

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, 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, nodeName, nodeProperties, nodeString, replaceChildrenSameSize, source, sourceLocation, sourceText, toString, 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.xpack.esql.evaluator.mapper.EvaluatorMapper

fold

Field Details

MV_SINGLE_VALUE_OR_NULL_TRANSPORT_VERSION

public static final TransportVersion MV_SINGLE_VALUE_OR_NULL_TRANSPORT_VERSION

ENTRY

public static final NamedWriteableRegistry.Entry ENTRY

Constructor Details

MvSingleValueOrNull

public MvSingleValueOrNull(Source source,
 Expression field)

MvSingleValueOrNull

public MvSingleValueOrNull(Source source,
 Expression field,
 List<Source> warningSources)

Method Details

warningSources

public List<Source> warningSources()

writeTo

public void writeTo(StreamOutput out)
             throws IOException

Specified by:

writeTo in interface Writeable

Overrides:

writeTo in class AbstractMultivalueFunction

Throws:

IOException

getWriteableName

public String getWriteableName()

resolveFieldType

protected Expression.TypeResolution resolveFieldType()

Specified by:

resolveFieldType in class AbstractMultivalueFunction

evaluator

protected ExpressionEvaluator.Factory evaluator(ExpressionEvaluator.Factory fieldEval)

Description copied from class: AbstractMultivalueFunction

Build the evaluator given the evaluator a multivalued field.

Specified by:

evaluator in class AbstractMultivalueFunction

replaceChildren

public Expression replaceChildren(List<Expression> newChildren)

Specified by:

replaceChildren in class Node<Expression>

hashCode

public int hashCode()

Overrides:

hashCode in class Function

equals

public boolean equals(Object obj)

Overrides:

equals in class Function

info

protected NodeInfo<? extends Expression> info()

Description copied from class: Node

Normally, you want to use one of the static create methods to implement this.

For QueryPlans, it is very important that the properties contain all of the expressions and references relevant to this node, and that all the properties are used in the provided constructor; otherwise query plan transformations like QueryPlan#transformExpressionsOnly(Function) will not have an effect.

Specified by:

info in class Node<Expression>