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 FormatReader.filterPushdownSupport().

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:

• ExternalSchema 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, FileList fileList, Map<StoragePath,SchemaReconciliation.FileSchemaInfo> schemaMap)
ExternalRelation(Source source, String sourcePath, SourceMetadata metadata, List<Attribute> output, FileList fileList, Map<StoragePath,SchemaReconciliation.FileSchemaInfo> schemaMap, String datasetName)
ExternalRelation(Source source, String sourcePath, SourceMetadata metadata, List<Attribute> output, FileList fileList, Map<StoragePath,SchemaReconciliation.FileSchemaInfo> schemaMap, String datasetName, List<? extends NamedExpression> metadataFields, DeclaredReadSpec declaredReadSpec)

Method Summary

Modifier and Type	Method	Description
String	datasetName()	Registered dataset identifier, or null when this relation was produced by the inline EXTERNAL command path.
DeclaredReadSpec	declaredReadSpec()	The declared mapping's read-instructions (renames, _id.path, per-column date formats), or DeclaredReadSpec.NONE.
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()
List<? extends NamedExpression>	metadataFields()	METADATA clause expressions threaded through from the parser.
List<Object>	nodeProperties()	The values of all the properties that are important to this Node.
void	nodeString(StringBuilder sb, Node.NodeStringFormat format, NodeStringMapper mapper)	Append this Node's string representation to sb.
List<Attribute>	output()	The ordered list of attributes (i.e.
Map<StoragePath,SchemaReconciliation.FileSchemaInfo>	schemaMap()
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, nodeString, propertiesToString, replaceChildrenSameSize, source, sourceLocation, sourceText, toString, 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,
 Map<StoragePath,SchemaReconciliation.FileSchemaInfo> schemaMap)

ExternalRelation

public ExternalRelation(Source source,
 String sourcePath,
 SourceMetadata metadata,
 List<Attribute> output,
 FileList fileList,
 Map<StoragePath,SchemaReconciliation.FileSchemaInfo> schemaMap,
 @Nullable
 String datasetName)

ExternalRelation

public ExternalRelation(Source source,
 String sourcePath,
 SourceMetadata metadata,
 List<Attribute> output,
 FileList fileList,
 Map<StoragePath,SchemaReconciliation.FileSchemaInfo> schemaMap,
 @Nullable
 String datasetName,
 List<? extends NamedExpression> metadataFields,
 DeclaredReadSpec declaredReadSpec)

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()

schemaMap

public Map<StoragePath,SchemaReconciliation.FileSchemaInfo> schemaMap()

datasetName

@Nullable
public String datasetName()

Registered dataset identifier, or null when this relation was produced by the inline EXTERNAL command path. Carried to ExternalSourceExec via toPhysicalExec().

declaredReadSpec

public DeclaredReadSpec declaredReadSpec()

The declared mapping's read-instructions (renames, _id.path, per-column date formats), or DeclaredReadSpec.NONE. Carried to ExternalSourceExec via toPhysicalExec().

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

metadataFields

public List<? extends NamedExpression> metadataFields()

METADATA clause expressions threaded through from the parser. Resolved entries are bound into output; unresolved entries (typo'd or unknown names) stay here so the verifier's checkUnresolvedAttributes walk picks them up and reports the indexed-equivalent "Unresolved metadata pattern [...]" error.

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

nodeProperties

public List<Object> nodeProperties()

Description copied from class: Node

The values of all the properties that are important to this Node.

Overrides:

nodeProperties in class Node<LogicalPlan>

nodeString

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

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 - output-shape configuration (width / lines / property count)

mapper - identifier-mapping strategy (raw via NodeStringMapper.IDENTITY, anonymized via the failure-path anonymizer, etc.)

withAttributes

public ExternalRelation withAttributes(List<Attribute> newAttributes)