Struct QuerySnapshot 

pub struct QuerySnapshot {

    pub query_info: QueryInfo,
    pub total_duration: Duration,
    pub time_to_first_chunk: Option<Duration>,
    pub error_kind: Option<&'static str>,
    pub direct_terminal_reason: Option<DirectFetchFailureReason>,
    pub fetch_grpc_requests: u64,
    pub fetch_grpc_bytes: u64,
    pub fetch_direct_requests: u64,
    pub fetch_direct_bytes: u64,
    pub fetch_direct_retries: u64,
    pub fetch_direct_requests_retried: u64,
    pub fetch_direct_retry_sleep: Duration,
    pub fetch_direct_max_attempt: u64,
    pub fetch_direct_original_ranges: u64,
    pub fetch_direct_merged_ranges: u64,
    pub planned_fetch_batches: u64,
    pub planned_segment_waves: u64,
    pub segment_admission_limit: u64,
    pub segment_admission_candidate_limit: u64,
    pub segment_admission_source: &'static str,
    pub segment_admission_candidate_reason: &'static str,
    pub segment_admission_adaptive_enabled: bool,
    pub segment_admission_profile_segment_count: u64,
    pub segment_admission_profile_complete: bool,
    pub segment_admission_p95_segment_bytes: u64,
    pub segment_admission_max_segment_bytes: u64,
    pub segment_admission_largest_window_bytes: u64,
    pub max_segments_per_fetch_batch: u64,
    pub max_segments_per_wave: u64,
    pub peak_active_segments: u64,
    pub pipeline_budget_bytes: u64,
    pub pipeline_peak_decoded_bytes: u64,
    pub pipeline_byte_waits: u64,
    pub segment_admission_waits: u64,
    pub pipeline_stall_breaker_activations: u64,
}

One completed query’s metrics, as seen from the client side.

Built once via build_query_snapshot and consumed by:

• the crate-private analytics::PendingInner::drop when sending the PostHog OTLP span (so the span attributes are guaranteed to match what other readers see),
• each subscribed MetricsCollector at end-of-stream, so Python code can read the metrics back without going through the datafusion_ffi EXPLAIN ANALYZE path that currently strips them.

Fields

query_info: QueryInfo

Plan-time facts about the query, recorded once in scan() before any execution. Embedded as-is so a new QueryInfo field automatically flows through to every snapshot consumer.

total_duration: Duration

Wall-clock time from the start of scan() until the query finished (cleanly or via error). Always populated.

time_to_first_chunk: Option<Duration>

Time from scan_start until the first chunk reached the consumer. None when no chunk was ever delivered (e.g. early error, empty result).

error_kind: Option<&'static str>

None on success. On failure, one of the stable QueryErrorKind string labels ("grpc_fetch", "direct_fetch", "decode", "other").

direct_terminal_reason: Option<DirectFetchFailureReason>

Reason a direct (HTTP Range) fetch hit a terminal failure — i.e. a non-retryable error or retries exhausted. None when no direct fetch terminally failed (this can be None even when error_kind is set, if the failure was on the gRPC or decode path).

fetch_grpc_requests: u64

Number of gRPC fetch calls the scanner issued.

fetch_grpc_bytes: u64

Sum of chunk_byte_length (catalog metadata, compressed on-disk size) over chunks fetched via gRPC. See the section comment above for what this is and isn’t.

fetch_direct_requests: u64

Number of direct (HTTP Range) fetches the scanner issued. Counts each merged request once, regardless of how many byte ranges it carried or how many attempts it took.

fetch_direct_bytes: u64

Sum of chunk_byte_length (catalog metadata, compressed on-disk size) over chunks fetched via direct HTTP. Notably this does not count the filler bytes that range-merging pulls between adjacent chunks in the same object, so actual wire traffic can exceed this value. Includes successful merged-range fetches even when a sibling range makes the overall batch fail.

fetch_direct_retries: u64

Total number of direct-fetch retry attempts across all requests. Each retry of a single request adds 1; a request retried 3 times contributes 3 here.

fetch_direct_requests_retried: u64

Number of distinct direct-fetch requests that needed at least one retry. Always ≤ fetch_direct_retries; the ratio between them is the average retries per retried request.

fetch_direct_retry_sleep: Duration

Total backoff time slept across all direct-fetch retries

fetch_direct_max_attempt: u64

True cross-partition max attempt number (via AtomicU64::fetch_max).

fetch_direct_original_ranges: u64

Number of byte ranges the planner wanted to fetch directly, before adjacent ranges were coalesced. With fetch_direct_merged_ranges, gives the range-merging ratio.

fetch_direct_merged_ranges: u64

Number of combined HTTP Range requests produced by merging adjacent byte ranges. Normally equals fetch_direct_requests after a completed scan, but can differ when cancellation stops only part of the planned work from being issued.

planned_fetch_batches: u64

Transport batches produced before splitting direct and gRPC work.

planned_segment_waves: u64

Segment waves produced by the current admission scheduler.

segment_admission_limit: u64

Maximum number of concurrently admitted segments configured for this query.

segment_admission_candidate_limit: u64

Cap recommended by the adaptive policy, whether or not it was applied.

segment_admission_source: &'static str

Source of the effective cap.

segment_admission_candidate_reason: &'static str

Reason the adaptive candidate was or was not eligible.

segment_admission_adaptive_enabled: bool

Whether adaptive admission was enabled for this query.

segment_admission_profile_segment_count: u64

Number of segments evaluated by the policy.

segment_admission_profile_complete: bool

Whether every segment had complete positive uncompressed-size metadata.

segment_admission_p95_segment_bytes: u64

Nearest-rank p95 queried uncompressed bytes per segment.

segment_admission_max_segment_bytes: u64

Largest queried uncompressed segment size.

segment_admission_largest_window_bytes: u64

Sum of the largest candidate-window segment estimates before decode expansion.

max_segments_per_fetch_batch: u64

Largest distinct-segment count in any planned transport batch.

max_segments_per_wave: u64

Largest distinct-segment count in any planned admission wave.

peak_active_segments: u64

Highest observed number of active segments in the admission gate. May exceed segment_admission_limit when the stall breaker admits bypass segments to restore forward progress.

pipeline_budget_bytes: u64

Total decoded-byte capacity shared across all query partitions.

pipeline_peak_decoded_bytes: u64

Highest observed number of decoded bytes charged to the pipeline budget. May exceed pipeline_budget_bytes on an explicit overcommit path.

pipeline_byte_waits: u64

Number of reservations that first parked because decoded-byte capacity was full.

segment_admission_waits: u64

Number of reservations that first parked because segment admission was full.

pipeline_stall_breaker_activations: u64

Number of times the saturated-pipeline stall breaker activated.

Trait Implementations

impl Clone for QuerySnapshot

fn clone(&self) -> QuerySnapshot

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for QuerySnapshot

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for QuerySnapshot

fn eq(&self, other: &QuerySnapshot) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for QuerySnapshot