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

Class DatasetShadowRelation

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.DatasetShadowRelation

All Implemented Interfaces:

NamedWriteable, Writeable, Resolvable, Unresolvable

public class DatasetShadowRelation
extends LeafPlan
implements Unresolvable

Marker leaf node that represents an exact dataset name being looked up on linked projects (CPS) as a potential remote index with the same name as a local dataset. The dataset analog of ViewShadowRelation: it rides next to the dataset's UnresolvedExternalRelation inside the plain UnionAll the DatasetRewriter builds.

Motivation: FROM ds where ds is BOTH a local dataset AND a remote dataset/index. The local dataset is consumed before field-caps, and DatasetRewriter.crossProjectPatternsToPreserve only re-emits a sibling for wildcards — an exact name returns nothing, so without this shadow the remote half of the exact name never reaches field-caps.

Lifecycle, mirroring ViewShadowRelation:

1. Emitted during dataset rewriting (DatasetRewriter.rewriteOne) alongside the dataset's external relation, only under CPS for an exact (non-wildcard, flat) pattern.
2. PreAnalyzer collects the pattern into the same linked-indices set ViewShadowRelation lands in, keyed by linkedIndexPattern().
3. EsqlSession.preAnalyzeLinkedIndices issues a lenient flat field-caps request per pattern; a linked index of the same name resolves, a linked dataset/view fails on the detect rail. Results land in AnalyzerContext.linkedResolution, keyed by linkedIndexPattern().
4. The ResolveDatasetShadow analyzer rule (sibling of ResolveViewShadow) replaces the shadow with an EsRelation on a valid resolution, else leaves it unresolved.
5. StripDatasetShadowRelations removes any still-unresolved shadow; a single-survivor union collapses to its lone child.

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.common.io.stream.Writeable

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

Field Summary

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

TO_STRING_MAX_LINES, TO_STRING_MAX_WIDTH

Fields inherited from interface org.elasticsearch.xpack.esql.core.capabilities.Unresolvable

UNRESOLVED_PREFIX

Constructor Summary

Constructors

Constructor	Description
DatasetShadowRelation(Source source, String datasetName, LinkedIndexPattern.Kind kind, String pattern)

Method Summary

Modifier and Type	Method	Description
String	datasetName()
boolean	equals(Object obj)
boolean	expressionsResolved()
String	getWriteableName()
int	hashCode()
protected NodeInfo<DatasetShadowRelation>	info()	Normally, you want to use one of the static create methods to implement this.
LinkedIndexPattern	linkedIndexPattern()
List<Object>	nodeProperties()	The values of all the properties that are important to this Node.
List<Attribute>	output()	The ordered list of attributes (i.e.
boolean	resolved()
String	toString()
String	unresolvedMessage()	NOTE: Any non-null return value from this method indicates that the item in question could not be resolved.
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, 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, 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

Constructor Details

DatasetShadowRelation

public DatasetShadowRelation(Source source,
 String datasetName,
 LinkedIndexPattern.Kind kind,
 String pattern)

Method Details

datasetName

public String datasetName()

linkedIndexPattern

public LinkedIndexPattern linkedIndexPattern()

writeTo

public void writeTo(StreamOutput out)

Specified by:

writeTo in interface Writeable

getWriteableName

public String getWriteableName()

Specified by:

getWriteableName in interface NamedWriteable

info

protected NodeInfo<DatasetShadowRelation> 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>

resolved

public boolean resolved()

Specified by:

resolved in interface Resolvable

Specified by:

resolved in interface Unresolvable

Overrides:

resolved in class LogicalPlan

expressionsResolved

public boolean expressionsResolved()

Specified by:

expressionsResolved in class LogicalPlan

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>

unresolvedMessage

public String unresolvedMessage()

Description copied from interface: Unresolvable

NOTE: Any non-null return value from this method indicates that the item in question could not be resolved.

Specified by:

unresolvedMessage in interface Unresolvable

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>

toString

public String toString()

Overrides:

toString in class Node<LogicalPlan>