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

Class UnresolvedExternalRelation

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.UnresolvedExternalRelation
All Implemented Interfaces:
NamedWriteable, Writeable, Resolvable, Unresolvable, UnresolvedSourceRelation
public final class UnresolvedExternalRelation extends LeafPlan implements Unresolvable, UnresolvedSourceRelation
Unresolved external data source reference (Iceberg table or Parquet file). Produced by the parser for inline EXTERNAL commands and by the dataset rewriter for FROM <dataset>; both paths converge here so the downstream resolver/analyzer treat them uniformly.

The config map holds plain configuration values (no Literal wrappers); secret values arrive as SecureString on the dataset path.

See Also:

  • Constructor Details

    • UnresolvedExternalRelation

      public UnresolvedExternalRelation(Source source, Expression tablePath, Map<String,Object> config)
      Creates an unresolved external relation with no METADATA fields. Convenience overload for callers that don't carry standard metadata names (the inline EXTERNAL command path, tests).

    • UnresolvedExternalRelation

      public UnresolvedExternalRelation(Source source, Expression tablePath, Map<String,Object> config, List<NamedExpression> metadataFields)
      Creates an unresolved external relation without a backing dataset name (the inline EXTERNAL command path or tests that exercise the analyzer with a bare path).

    • UnresolvedExternalRelation

      public UnresolvedExternalRelation(Source source, Expression tablePath, Map<String,Object> config, List<NamedExpression> metadataFields, @Nullable String datasetName)
      Creates an unresolved external relation.

      The metadataFields list carries the names from the user's METADATA ... clause verbatim. The analyzer (specifically ResolveExternalRelations) is the binding site: it resolves each name against MetadataAttribute.ATTRIBUTES_MAP and appends an ExternalMetadataAttribute per resolved name to the leaf's output. This constructor does not validate the names — invalid names surface as unresolved attributes downstream with the existing "Unknown column" diagnostic.

      datasetName is the registered dataset identifier when the relation was created by DatasetRewriter from a FROM <dataset> pattern; it is null for the inline EXTERNAL command path where no dataset mapping exists. It flows through to the operator factory so the per-file _index synthesizer can populate the column with the user-facing dataset identifier rather than the raw resource path.

      Parameters:
      source - the source location in the query
      tablePath - the resource path or external table identifier (a Literal or parameter reference)
      config - plain-valued configuration (e.g., credentials, format options) — not wrapped in Literal
      metadataFields - names requested in the METADATA clause, in declaration order; never null
      datasetName - registered dataset name when this leaf came from FROM <dataset>; null otherwise

    • UnresolvedExternalRelation

      public UnresolvedExternalRelation(Source source, Expression tablePath, Map<String,Object> config, List<NamedExpression> metadataFields, @Nullable String datasetName, @Nullable DatasetMapping mapping)
      Full constructor carrying the dataset's user-declared mapping (DatasetMapping), if any. Only the FROM <dataset> path (via DatasetRewriter) supplies a non-null mapping; the inline EXTERNAL path and tests pass null (inference only). The mapping is consumed in pre-analysis by the external-source resolver to drive the strict-skip / non-strict-overlay decision.

  • Method Details

    • 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<UnresolvedExternalRelation> 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>

    • tablePath

      public Expression tablePath()

    • config

      public Map<String,Object> config()

    • metadataFields

      public List<NamedExpression> metadataFields()

    • datasetName

      @Nullable public String datasetName()
      Registered dataset identifier, or null when this relation was produced by the inline EXTERNAL command path (no dataset mapping). Threaded to the operator factory so the _index per-file synthesizer can emit the user-facing dataset name.

    • mapping

      @Nullable public DatasetMapping mapping()
      The dataset's user-declared mapping (the `mappings` block), or null when the dataset has none (inference only) or for the inline EXTERNAL path. Consumed by the external-source resolver.

    • 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>