Package org.elasticsearch.xpack.esql.datasources

Class PhysicalNames

java.lang.Object
org.elasticsearch.xpack.esql.datasources.PhysicalNames
public final class PhysicalNames extends Object
Single source of truth for the declared-schema logical→physical column rename (path).

The whole external-read stack — plan, reconciliation (SchemaReconciliation / ColumnMapping / FilterAdaptation), projection intersection — works in logical names. A path rename is applied only at the last mile, on the names handed to a format reader or its pushdown SPI, so readers are fully rename-agnostic and reconciliation is never disturbed. Every reader-facing name surface (projection, read schema, pushed filter, TopN threshold, aggregate-stats refs, deferred field-extraction column names) routes its names through this class — including the deferred columns, which are extracted from the file by name after the eager projection and so need the same physicalization (LocalExecutionPlanner#planExternalFieldExtract).

Names are treated as opaque whole strings: a dotted name (a.b.c) is a single flat column name in this model and is never split here (a reader that navigates dots does so on the physical name it receives).

  • Method Details

    • translate

      public static String translate(String logicalName, Map<String,String> renames)
      The physical (file) name for a logical column, or the name unchanged when it is not renamed / no renames apply.

    • translateNames

      public static List<String> translateNames(List<String> logicalNames, Map<String,String> renames)
      Physicalize a list of projected column names (order and cardinality preserved). Returns the input if no renames.

    • translateSchema

      public static List<Attribute> translateSchema(List<Attribute> logicalSchema, Map<String,String> renames)
      Physicalize a read schema, renaming each attribute to its physical name via Attribute.withName(String) (type and attribute kind preserved). Non-renamed attributes are returned as-is. Returns the input if no renames.

    • translateExpressionNames

      public static List<Expression> translateExpressionNames(List<Expression> expressions, Map<String,String> renames)
      Rewrite the column names referenced by each expression through renames (via Attribute.withName(java.lang.String), which preserves the attribute's NameId — so a physical→ logical round-trip restores the original attribute identity). Used to physicalize the conjuncts handed to a format's filter-pushdown mint (the opaque predicate then references file columns), and — with inverse(java.util.Map<java.lang.String, java.lang.String>) — to map the mint's returned pushed/remainder expressions back to logical for the plan and reconciliation.

    • inverse

      public static Map<String,String> inverse(Map<String,String> renames)
      The physical→logical inverse of a logical→physical rename map (renames are 1:1, so the inverse is well-defined).

    • noLogicalNamesRemain

      public static boolean noLogicalNamesRemain(Collection<String> readerFacingNames, Map<String,String> renames)
      Invariant guard: true iff no logical rename-source name survives in a reader-facing name set — i.e. the surface was physicalized. A leaked logical name would make a reader look up a column the file does not have (a silently mis-pushed predicate on the pushdown path). Wired as an assert at the pushed-filter mint (PushFiltersToSource), the correctness-critical surface where a mistranslation is silent; the projection and aggregate surfaces are covered instead by the per-format rename ITs. Cheap set-membership scan; no cost with assertions off.