Package org.elasticsearch.xpack.esql.action

Class EsqlExecutionInfo

java.lang.Object
org.elasticsearch.xpack.esql.action.EsqlExecutionInfo
All Implemented Interfaces:
Writeable, ChunkedToXContent, ChunkedToXContentObject
public class EsqlExecutionInfo extends Object implements ChunkedToXContentObject, Writeable
Holds execution metadata about ES|QL queries for cross-cluster searches in order to display this information in ES|QL JSON responses. Patterned after the SearchResponse.Clusters and SearchResponse.Cluster classes.

  • Field Details

    • LOCAL_CLUSTER_NAME_REPRESENTATION

      public static final String LOCAL_CLUSTER_NAME_REPRESENTATION
      See Also:

    • ORIGIN_CLUSTER_NAME_REPRESENTATION

      public static final String ORIGIN_CLUSTER_NAME_REPRESENTATION
      See Also:

    • TOTAL_FIELD

      public static final ParseField TOTAL_FIELD

    • SUCCESSFUL_FIELD

      public static final ParseField SUCCESSFUL_FIELD

    • SKIPPED_FIELD

      public static final ParseField SKIPPED_FIELD

    • RUNNING_FIELD

      public static final ParseField RUNNING_FIELD

    • PARTIAL_FIELD

      public static final ParseField PARTIAL_FIELD

    • FAILED_FIELD

      public static final ParseField FAILED_FIELD

    • DETAILS_FIELD

      public static final ParseField DETAILS_FIELD

    • TOOK

      public static final ParseField TOOK

    • IS_PARTIAL_FIELD

      public static final ParseField IS_PARTIAL_FIELD

    • EXECUTION_METADATA_VERSION

      public static final TransportVersion EXECUTION_METADATA_VERSION

    • EXECUTION_CLUSTER_NAME_VERSION

      public static final TransportVersion EXECUTION_CLUSTER_NAME_VERSION

    • EXECUTION_PROFILE_FORMAT_VERSION

      public static final TransportVersion EXECUTION_PROFILE_FORMAT_VERSION

    • clusterInfo

      public final ConcurrentMap<String,EsqlExecutionInfo.Cluster> clusterInfo

  • Constructor Details

    • EsqlExecutionInfo

      public EsqlExecutionInfo(Predicate<String> skipOnPlanTimeFailurePredicate, EsqlExecutionInfo.IncludeExecutionMetadata includeExecutionMetadata)
      Parameters:
      skipOnPlanTimeFailurePredicate - Decides whether we should skip the cluster that fails during planning phase.
      includeExecutionMetadata - (user defined setting) whether to include the execution/CCS metadata in the HTTP response

    • EsqlExecutionInfo

      public EsqlExecutionInfo(StreamInput in) throws IOException
      Throws:
      IOException

  • Method Details

    • writeTo

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

    • includeCCSMetadata

      public boolean includeCCSMetadata()

    • includeExecutionMetadata

      public EsqlExecutionInfo.IncludeExecutionMetadata includeExecutionMetadata()

    • markEndQuery

      public void markEndQuery()
      Call when ES|QL execution is complete in order to set the overall took time for an ES|QL query.

    • overallTook

      public TimeValue overallTook()

    • clusterAliases

      public Set<String> clusterAliases()

    • queryProfile

      public EsqlQueryProfile queryProfile()

    • shouldSkipOnFailure

      public boolean shouldSkipOnFailure(String clusterAlias)
      Parameters:
      clusterAlias - to check if we should skip this cluster on failure
      Returns:
      whether it's OK to skip the cluster on failure.
      Throws:
      NoSuchRemoteClusterException - if clusterAlias is unknown to this node's RemoteClusterService

    • isCrossClusterSearch

      public boolean isCrossClusterSearch()

    • hasMetadataToReport

      public boolean hasMetadataToReport()
      Is there any metadata to report in the response? This is true on cross-cluster search with includeCCSMetadata=true or when there are partial failures.

    • getCluster

      public EsqlExecutionInfo.Cluster getCluster(String clusterAlias)

    • getClusters

      public Map<String,EsqlExecutionInfo.Cluster> getClusters()

    • initCluster

      public void initCluster(String clusterAlias, String localCusterName, String indexExpression)
      This creates an initial Cluster object with indexExpression and skipUnavailable.

    • swapCluster

      public EsqlExecutionInfo.Cluster swapCluster(String clusterAlias, BiFunction<String,EsqlExecutionInfo.Cluster,EsqlExecutionInfo.Cluster> remappingFunction)
      Utility to swap a Cluster object. Guidelines for the remapping function:
      • The remapping function should return a new Cluster object to swap it for the existing one.
      • If in the remapping function you decide to abort the swap you must return the original Cluster object to keep the map unchanged.
      • Do not return null. If the remapping function returns null, the mapping is removed (or remains absent if initially absent).
      • If the remapping function itself throws an (unchecked) exception, the exception is rethrown, and the current mapping is left unchanged. Throwing exception therefore is OK, but it is generally discouraged.
      • The remapping function may be called multiple times in a CAS fashion underneath, make sure that is safe to do so.
      Parameters:
      clusterAlias - key with which the specified value is associated
      remappingFunction - function to swap the oldCluster to a newCluster
      Returns:
      the new Cluster object

    • toXContentChunked

      public Iterator<? extends ToXContent> toXContentChunked(ToXContent.Params params)
      Specified by:
      toXContentChunked in interface ChunkedToXContent

    • getClusterStates

      public Stream<EsqlExecutionInfo.Cluster> getClusterStates(EsqlExecutionInfo.Cluster.Status status)
      Parameters:
      status - the status you want to access
      Returns:
      a stream of clusters with that status

    • getRunningClusterAliases

      public Stream<String> getRunningClusterAliases()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • isPartial

      public boolean isPartial()

    • markPartial

      public void markPartial()
      Marks the overall result as partial directly, independent of the per-cluster status path used for shard/node failures. This is required for pure external-source queries (e.g. EXTERNAL "file://..."), which carry no clusterInfo entry to drive swapCluster(java.lang.String, java.util.function.BiFunction<java.lang.String, org.elasticsearch.xpack.esql.action.EsqlExecutionInfo.Cluster, org.elasticsearch.xpack.esql.action.EsqlExecutionInfo.Cluster>) — so a lenient external read that drops data (e.g. a max_record_size truncation under a non-strict error_mode) has no cluster to flip. Sticky like the cluster-driven path: once partial, always partial.

    • markAsStopped

      public void markAsStopped()

    • isStopped

      public boolean isStopped()

    • addStopHook

      public void addStopHook(BooleanSupplier hook)
      Registers a hook that runStopHooks() fires when the user requests async STOP for this query. The hook should return true only on the transition from running to finishing — see stopHooks for the rationale.

    • removeStopHook

      public void removeStopHook(BooleanSupplier hook)
      Removes a previously-registered stop hook. Callers register per-phase hooks (e.g. one per driver in a ComputeService.runCompute invocation) and must invoke this on phase completion so the async task's stop-hook list doesn't retain references to closed drivers/contexts for the whole task lifetime — coordinator reductions and subplans invoke runCompute multiple times under the same task, and cleared hooks would otherwise no-op but keep the driver-graph reachable. Uses reference equality via List.remove(Object), so callers must pass the exact same BooleanSupplier instance previously registered.

    • runStopHooks

      public boolean runStopHooks()
      Fires all registered stop hooks and returns true if at least one hook reported that it cut a live unit of work. Callers can use this to decide whether STOP truncated the query (and therefore the response should be flagged is_partial=true) or whether STOP merely raced with natural completion (in which case the response is honestly complete).

      No wrapping try/catch here: today's hooks are Driver::runStopHooks which delegates to DriverContext.runStopHooks(), and that already isolates per-hook failures so one misbehaving operator can't sink the STOP response. Any exception escaping this loop is a bug in a caller (added a hook that doesn't respect the contract) and should surface loudly.

    • clusterInfoInitializing

      public void clusterInfoInitializing(boolean clusterInfoInitializing)

    • isMainPlan

      public boolean isMainPlan()

    • startSubPlans

      public void startSubPlans(boolean isSubqueryJoin)

    • isSubqueryJoinSubPlan

      public boolean isSubqueryJoinSubPlan()

    • finishSubPlans

      public void finishSubPlans()