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

Class PromqlCommand

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.UnaryPlan
org.elasticsearch.xpack.esql.plan.logical.promql.PromqlCommand
All Implemented Interfaces:
NamedWriteable, Writeable, PostAnalysisVerificationAware, TelemetryAware, Resolvable, TimestampAware, TimestampBoundsAware<LogicalPlan>, TimestampBoundsAware.OfLogicalPlan
public class PromqlCommand extends UnaryPlan implements TelemetryAware, TimestampAware, TimestampBoundsAware.OfLogicalPlan
Container plan for embedded PromQL queries. Gets eliminated by the analyzer once the query is validated.

  • Field Details

  • Constructor Details

  • Method Details

    • info

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

    • replaceChild

      public PromqlCommand replaceChild(LogicalPlan newChild)
      Specified by:
      replaceChild in class UnaryPlan

    • withPromqlPlan

      public PromqlCommand withPromqlPlan(LogicalPlan newPromqlPlan)

    • needsTimestampBounds

      public boolean needsTimestampBounds()
      Bounds are only needed when buckets is specified without an explicit time range. When step alone is set, the query can proceed without start/end because the step directly defines the bucket size; postAnalysisVerification(org.elasticsearch.xpack.esql.common.Failures) validates that case.
      Specified by:
      needsTimestampBounds in interface TimestampBoundsAware<LogicalPlan>

    • withTimestampBounds

      public PromqlCommand withTimestampBounds(Literal start, Literal end)
      Description copied from interface: TimestampBoundsAware
      Returns a copy of this node with the given timestamp bounds applied.
      Specified by:
      withTimestampBounds in interface TimestampBoundsAware<LogicalPlan>

    • expressionsResolved

      public boolean expressionsResolved()
      Specified by:
      expressionsResolved in class LogicalPlan

    • telemetryLabel

      public String telemetryLabel()
      Specified by:
      telemetryLabel in interface TelemetryAware
      Returns:
      the label reported in the telemetry data. Only needs to be overwritten if the label doesn't match the class name.

    • getWriteableName

      public String getWriteableName()
      Specified by:
      getWriteableName in interface NamedWriteable

    • writeTo

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

    • promqlPlan

      public LogicalPlan promqlPlan()

    • start

      public Literal start()

    • end

      public Literal end()

    • step

      public Literal step()

    • buckets

      public Literal buckets()
      Number of buckets for auto-derived range-query bucket size.

    • scrapeInterval

      public Literal scrapeInterval()
      The expected scrape interval used to derive implicit range selector windows.

    • hasTimeRange

      public boolean hasTimeRange()

    • isInstantQuery

      public boolean isInstantQuery()

    • isRangeQuery

      public boolean isRangeQuery()

    • valueColumnName

      public String valueColumnName()

    • stepColumnName

      public String stepColumnName()

    • branchColumnName

      public String branchColumnName()
      Name of the synthetic column tagging each union branch with its position, used for left-preferring dedup.

    • timestampColumnName

      public String timestampColumnName()
      Name of the synthetic column materialising the offset-shifted @timestamp + offset evaluation time.

    • valueId

      public NameId valueId()

    • stepId

      public NameId stepId()

    • valueAttribute

      public ReferenceAttribute valueAttribute()

    • stepAttribute

      public ReferenceAttribute stepAttribute()

    • timestamp

      public Expression timestamp()
      Specified by:
      timestamp in interface TimestampAware

    • 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.
      Overrides:
      output in class UnaryPlan

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class UnaryPlan

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class UnaryPlan

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

    • computeReferences

      protected AttributeSet computeReferences()
      Description copied from class: QueryPlan
      This very likely needs to be overridden for QueryPlan.references() to be correct when inheriting. This can be called on unresolved plans and therefore must not rely on calls to QueryPlan.output().
      Overrides:
      computeReferences in class QueryPlan<LogicalPlan>

    • postAnalysisVerification

      public void postAnalysisVerification(Failures failures)
      Description copied from interface: PostAnalysisVerificationAware
      Allows the implementer to validate itself. This usually involves checking its internal setup, which often means checking the parameters it received on construction: their data or syntactic type, class, their count, expressions' structure etc. The discovered failures are added to the given Failures object.

      It is often more useful to perform the checks as extended as it makes sense, over stopping at the first failure. This will allow the author to progress faster to a correct query.

      Example: the Filter class, which models the WHERE command, checks that the expression it filters on - condition - is of a Boolean or NULL type: 

           
     @Override
     void postAnalysisVerification(Failures failures) {
          if (condition.dataType() != NULL && condition.dataType() != BOOLEAN) {
              failures.add(fail(condition, "Condition expression needs to be boolean, found [{}]", condition.dataType()));
          }
     }
      Specified by:
      postAnalysisVerification in interface PostAnalysisVerificationAware
      Parameters:
      failures - the object to add failures to.

    • verify

      public void verify(Failures failures)

    • offset

      public Duration offset(LogicalPlan branch)
      The signed offset shared by the source-backed selectors in branch, as a constant time shift to add to @timestamp. The verifier guarantees a merged branch is offset-uniform (heterogeneous offsets in a binary expression are rejected), so the first source-backed selector's offset is representative. Duration.ZERO when there is none.

    • sourceFilterWindow

      public Duration sourceFilterWindow()
      Returns the source-side timestamp lookback window. Explicit and implicit range selectors contribute their requested window. Instant queries extend that window to at least the Prometheus lookback delta.

    • timestamp

      public Expression timestamp(LogicalPlan fragment)
      Returns the local evaluation timestamp for the current selector branch.

      Unlike timestamp(), which returns the global evaluation timestamp, this function returns the plan fragment timestamp and includes any applied offset.

    • resolveInstantQueryWindow

      public Duration resolveInstantQueryWindow()
      Returns the TSTEP bucket step for instant queries: the max range-selector window, falling back to DEFAULT_LOOKBACK only when no range selectors are present. Unlike sourceFilterWindow(), this does not floor explicit windows up to DEFAULT_LOOKBACK.

    • resolveImplicitRangeWindow

      public Literal resolveImplicitRangeWindow()
      Resolves the implicit range placeholder to a concrete duration based on step and scrape interval. The implicit window is calculated as max(step, scrape_interval).

    • resolveTimeBucketSize

      public Expression resolveTimeBucketSize()