Package org.elasticsearch.xpack.esql.datasources.cache

Class ExternalStatsCapture

java.lang.Object
org.elasticsearch.xpack.esql.datasources.cache.ExternalStatsCapture
public final class ExternalStatsCapture extends Object
Thread-bound sink for captured per-file source statistics. The text-format readers' close hooks call record(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>) with one flat _stats.* map per contribution; whichever operator drove the iteration binds a sink ahead of time so the contributions end up on the operator's Status and ride back to the coordinator via DriverCompletionInfo.

In the orthogonal stripe model the READER owns stripe addressing: it attributes each record to its canonical stripe (ordinal = floor(recordStartOffset / stripeSize), using the base offset and grid passed via FormatReadContext) and emits one record(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>) call per stripe it touched, each map already carrying the _stats.stripe_* addressing keys. This sink no longer stamps coverage — there is nothing for the coordinator to add, because only the reader knows where each record sits relative to the grid.

Sinks must be bound on the same thread that subsequently invokes the reader's close(). For the synchronous operator the operator owns the iteration thread; for the async path the coordinator binds on the reader/worker thread that runs the iterator.

  • Method Details

    • record

      public static void record(String filePath, Map<String,Object> stats)
      Appends a flat _stats.* contribution for filePath. Multiple contributions per path accumulate (one per stripe a chunk touched, one per whole-file read); the coordinator-side reconciler routes them by their marker keys. No-op if no sink is bound on the current thread, if the path is null, or if the map is null/empty.

      The sink is typed as ConcurrentMap because parallel-parsing workers concurrently invoke computeIfAbsent on the outer map; only the ConcurrentMap contract makes that lookup-or-insert atomic.

    • bind

      public static ExternalStatsCapture.Handle bind(ConcurrentMap<String,List<Map<String,Object>>> sink)
      Binds sink as the active capture target on the current thread; returns a handle the caller must close (try-with-resources) to restore the previous sink. The same sink instance can also be polled directly by the binding owner — record(java.lang.String, java.util.Map<java.lang.String, java.lang.Object>) only writes.

    • newSink

      public static ConcurrentMap<String,List<Map<String,Object>>> newSink()
      Convenience factory for a fresh thread-safe sink.