Package org.elasticsearch.xpack.esql.plan.logical

Class ExternalRelation

java.lang.Object

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

org.elasticsearch.xpack.esql.plan.QueryPlan<LogicalPlan>

org.elasticsearch.xpack.esql.plan.logical.LogicalPlan

org.elasticsearch.xpack.esql.plan.logical.LeafPlan

org.elasticsearch.xpack.esql.plan.logical.ExternalRelation

All Implemented Interfaces:

NamedWriteable, Writeable, Resolvable, ExecutesOn, ExecutesOn.Coordinator

public class ExternalRelation
extends LeafPlan
implements ExecutesOn.Coordinator

Logical plan node for external data source relations (e.g., Iceberg table, Parquet file).

Like EsRelation, the Mapper wraps this into a FragmentExec so that pipeline breakers (Aggregate, Limit, TopN) above it are distributed to data nodes via ExchangeExec. On data nodes, localPlan() expands the FragmentExec through LocalMapper into ExternalSourceExec, enabling local optimizations such as filter pushdown via FilterPushdownRegistry.

The ExecutesOn.Coordinator marker is retained for logical plan validation (e.g., Enrich/Join hoist rules that inspect whether a relation executes on the coordinator).

The source-specific metadata is stored in the SourceMetadata interface, which provides:

• Schema attributes via SourceMetadata.schema()
• Source type via SourceMetadata.sourceType()
• Configuration via SourceMetadata.config()
• Opaque source metadata via SourceMetadata.sourceMetadata()

The toPhysicalExec() method creates a generic ExternalSourceExec that carries all necessary information for the operator factory to create the appropriate source operator via the SPI.

Nested Class Summary

Nested classes/interfaces inherited from class org.elasticsearch.xpack.esql.plan.logical.LogicalPlan

LogicalPlan.Stage

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.plan.logical.ExecutesOn

ExecutesOn.Coordinator, ExecutesOn.ExecuteLocation, ExecutesOn.Remote

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

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

TO_STRING_MAX_LINES, TO_STRING_MAX_WIDTH

Constructor Summary

Constructors

Constructor	Description
ExternalRelation(Source source, String sourcePath, SourceMetadata metadata, List<Attribute> output)
ExternalRelation(Source source, String sourcePath, SourceMetadata metadata, List<Attribute> output, FileList fileList)

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object obj)
boolean	expressionsResolved()
FileList	fileList()
String	getWriteableName()
int	hashCode()
protected NodeInfo<ExternalRelation>	info()	Normally, you want to use one of the static create methods to implement this.
SourceMetadata	metadata()
void	nodeString(StringBuilder sb, Node.NodeStringFormat format)	Append this Node's string representation to sb.
List<Attribute>	output()	The ordered list of attributes (i.e.
String	sourcePath()
String	sourceType()
ExternalSourceExec	toPhysicalExec()
ExternalRelation	withAttributes(List<Attribute> newAttributes)
void	writeTo(StreamOutput out)

Methods inherited from class org.elasticsearch.xpack.esql.plan.logical.LeafPlan

computeReferences, replaceChildren

Methods inherited from class org.elasticsearch.xpack.esql.plan.logical.LogicalPlan

analyzed, childrenResolved, optimized, preAnalyzed, preOptimized, resolved, setAnalyzed, setOptimized, setPreAnalyzed, setPreOptimized

Methods inherited from class org.elasticsearch.xpack.esql.plan.QueryPlan

computeExpressions, expressions, forEachExpression, forEachExpression, forEachExpressionDown, forEachExpressionUp, inputSet, outputSet, references, transformExpressionsDown, transformExpressionsDown, transformExpressionsOnly, transformExpressionsOnly, transformExpressionsOnlyUp, transformExpressionsUp, transformExpressionsUp

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, propertiesToString, replaceChildrenSameSize, source, sourceLocation, sourceText, toString, 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.plan.logical.ExecutesOn.Coordinator

executesOn

Field Details

ENTRY

public static final NamedWriteableRegistry.Entry ENTRY

Constructor Details

ExternalRelation

public ExternalRelation(Source source,
 String sourcePath,
 SourceMetadata metadata,
 List<Attribute> output,
 FileList fileList)

ExternalRelation

public ExternalRelation(Source source,
 String sourcePath,
 SourceMetadata metadata,
 List<Attribute> output)

Method Details

writeTo

public void writeTo(StreamOutput out)
             throws IOException

Specified by:

writeTo in interface Writeable

Throws:

IOException

getWriteableName

public String getWriteableName()

Specified by:

getWriteableName in interface NamedWriteable

info

protected NodeInfo<ExternalRelation> 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<LogicalPlan>

sourcePath

public String sourcePath()

metadata

public SourceMetadata metadata()

fileList

public FileList fileList()

output

public List<Attribute> output()

Description copied from class: QueryPlan

The ordered list of attributes (i.e. columns) this plan produces when executed. Must be called only on resolved plans, otherwise may throw an exception or return wrong results.

Specified by:

output in class QueryPlan<LogicalPlan>

expressionsResolved

public boolean expressionsResolved()

Specified by:

expressionsResolved in class LogicalPlan

sourceType

public String sourceType()

toPhysicalExec

public ExternalSourceExec toPhysicalExec()

hashCode

public int hashCode()

Specified by:

hashCode in class LogicalPlan

equals

public boolean equals(Object obj)

Specified by:

equals in class LogicalPlan

nodeString

public void nodeString(StringBuilder sb,
 Node.NodeStringFormat format)

Description copied from class: Node

Append this Node's string representation to sb. This does not include this node's Node.children().

Overrides:

nodeString in class Node<LogicalPlan>

Parameters:

sb - target for the string

format - configuration for rendering the string representation

withAttributes

public ExternalRelation withAttributes(List<Attribute> newAttributes)