Package org.elasticsearch.xpack.esql.datasources

Record Class DeclaredReadSpec

java.lang.Object
java.lang.Record
org.elasticsearch.xpack.esql.datasources.DeclaredReadSpec
All Implemented Interfaces:
Writeable
public record DeclaredReadSpec(Map<String,String> renames, String idPath, Map<String,String> dateFormats, Set<String> declaredTypeColumns) extends Record implements Writeable
The read-instructions a declared dataset mapping derives for the data node. Carried as a first-class field along the resolution → plan → operator seam (ExternalSourceResolution.ResolvedSource → ExternalRelation → ExternalSourceExec → SourceOperatorContext → the operator factory), so a new declared read-instruction is one typed field rather than another string key fenced and sniffed out of the config map.
  • renames — the declared logical→physical column renames a path move produces. Consumed at the reader-facing boundary via PhysicalNames (projection + read schema physicalization) and by the pushdown planner rules. Empty when the mapping renames nothing.
  • idPath — the declared mappings._id.path (a single logical column name), or null. When present the data node stamps _id from that column instead of the synthetic (file+row-position) identity (VirtualColumnIterator).
  • dateFormats — per-column date parse-patterns, keyed by logical column name. The text readers parse that column's timestamps with the given pattern (via the ES DateFormatter) instead of the ISO default / file-level datetime_format. Physicalized to file-column names at the reader boundary (FileSourceFactory). Empty when no column declares a format.
  • declaredTypeColumns — the logical names of the columns whose target type came from an explicit declaration (as opposed to inference). A declared type licenses a lossy read-time coercion toward it — e.g. a declared integer over an int64 file column narrows per value (null on overflow). An inferred target must never narrow: a cross-file clash widens-or-nulls. The by-name columnar readers (Parquet/ORC) key their whole-column incompatibility null-fill on this set — a declared column keeps the coercion escape, an inferred one null-fills whenever the file type is not widening-compatible. Physicalized to file-column names at the reader boundary (FileSourceFactory); the text readers ignore it (they parse straight into the target). Empty when the mapping declares no column types.
A plain Writeable: its wire gate lives on the enclosing plan nodes, which only read/write it when the dataset_declared_schema transport version is supported (mirrors how DatasetMapping.Mappings is gated by its container rather than self-gating).

  • Field Details

    • NONE

      public static final DeclaredReadSpec NONE
      The empty spec — nothing declared. The default carried on every non-declared read.

  • Constructor Details

    • DeclaredReadSpec

      public DeclaredReadSpec(Map<String,String> renames, @Nullable String idPath, Map<String,String> dateFormats, Set<String> declaredTypeColumns)
      Creates an instance of a DeclaredReadSpec record class.
      Parameters:
      renames - the value for the renames record component
      idPath - the value for the idPath record component
      dateFormats - the value for the dateFormats record component
      declaredTypeColumns - the value for the declaredTypeColumns record component

  • Method Details

    • of

      public static DeclaredReadSpec of(@Nullable Map<String,String> renames, @Nullable String idPath, @Nullable Map<String,String> dateFormats, @Nullable Set<String> declaredTypeColumns)
      Canonical factory: collapses an all-empty spec to the NONE singleton so an absent declaration always serializes identically. The emptiness test is delegated to isEmpty() (the single source of truth), so a future field added to this record only has to update isEmpty() for the collapse to stay correct.

    • of

      public static DeclaredReadSpec of(@Nullable Map<String,String> renames, @Nullable String idPath)
      Convenience for a spec with no declared date formats and no declared column types.

    • isEmpty

      public boolean isEmpty()
      True when the mapping declared nothing for the data node to apply — no rename, _id.path, format, or type.

    • writeTo

      public void writeTo(StreamOutput out) throws IOException
      Specified by:
      writeTo in interface Writeable
      Throws:
      IOException

    • readFrom

      public static DeclaredReadSpec readFrom(StreamInput in) throws IOException
      Throws:
      IOException

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • renames

      public Map<String,String> renames()
      Returns the value of the renames record component.
      Returns:
      the value of the renames record component

    • idPath

      @Nullable public String idPath()
      Returns the value of the idPath record component.
      Returns:
      the value of the idPath record component

    • dateFormats

      public Map<String,String> dateFormats()
      Returns the value of the dateFormats record component.
      Returns:
      the value of the dateFormats record component

    • declaredTypeColumns

      public Set<String> declaredTypeColumns()
      Returns the value of the declaredTypeColumns record component.
      Returns:
      the value of the declaredTypeColumns record component