Struct QueryTrace 

pub struct QueryTrace {

    pub scan_mode: ScanMode,
    pub run_count: usize,
    pub memtable_rows: usize,
    pub mutable_run_rows: usize,
    pub overlay_rows: usize,
    pub conditions_pushed: usize,
    pub conditions_residual: usize,
    pub survivor_count: Option<usize>,
    pub index_rebuild: IndexRebuild,
    pub fast_row_id_map: bool,
    pub learned_range_used: bool,
    pub result_cache_hit: bool,
    pub row_materialized: bool,
    pub pages_decoded: usize,
    pub pages_skipped: usize,
    pub join_mode: JoinMode,
    pub planning_nanos: u64,
}

Records which engine path a query took. Filled at decision points via QueryTrace::record; collected via QueryTrace::capture.

All fields are #[derive(Default)], so adding a new field is non-breaking. Fields default to zero / false / None so a trace from an uninstrumented path still reads cleanly.

Fields

scan_mode: ScanMode

The physical scan path that served this query.

run_count: usize

Number of sorted runs in the table at query time. 1 = single-run fast path eligible; >1 = k-way merge; 0 = empty/memtable-only table.

memtable_rows: usize

Rows in the memtable overlay (unflushed puts/updates/deletes).

mutable_run_rows: usize

Rows in the mutable-run tier overlay.

overlay_rows: usize

Rows in the materialized overlay batch yielded by a cursor (memtable + mutable-run combined, post-filter). Non-zero means the query paid overlay materialization cost.

conditions_pushed: usize

How many conditions were translated to native pushdown (index-served).

conditions_residual: usize

How many conditions could not be pushed down (residual / fallback).

survivor_count: Option<usize>

Survivor row count after predicate resolution, if known without decoding data columns (set for index-served and count paths).

index_rebuild: IndexRebuild

Whether ensure_indexes_complete rebuilt indexes during this query.

fast_row_id_map: bool

Whether the fast clean-run row-id→position arithmetic was used (avoids decoding + binary-searching the system row-id column).

learned_range_used: bool

Whether a learned (PGM) range index served a Range/RangeF64 condition (in-memory, no column read).

result_cache_hit: bool

Whether the result cache returned a hit (no re-decode / re-resolve).

row_materialized: bool

Whether rows were materialized as Row { HashMap } (the slow path).

pages_decoded: usize

Number of pages decoded (lazily filled by cursors when capturing).

pages_skipped: usize

Number of pages skipped by page-stat pruning or empty page plans.

join_mode: JoinMode

Which join path served the query (Priority 13). None for non-joins.

planning_nanos: u64

Logical-planning time in nanoseconds (Priority 8: parse + plan, separate from execution). 0 on a result-cache hit (planning was skipped) or when the plan came from the logical-plan cache.

Implementations

impl QueryTrace

pub fn capture<F, T>(f: F) -> (T, QueryTrace)

where F: FnOnce() -> T,

Execute f with path tracing active on the current thread, returning the result and the captured trace. Recording calls inside f (and anything f calls on this thread) fill the returned trace.

Nesting is supported: an inner capture pushes a fresh trace onto the stack and gets its own result; the outer trace is unaffected by inner recordings.

When no capture is active (the normal hot path), QueryTrace::record is a single TLS load + empty-check + return — zero allocation, zero locking, no measurable cost.

pub fn push_scope()

Push a fresh trace onto the thread-local stack, starting a capture scope. Pair with Self::pop_scope to retrieve the trace. This is the async- compatible alternative to Self::capture: push before await, pop after.

Thread affinity: the trace is thread-local, so recordings must happen on the same OS thread as the push/pop pair. This holds for synchronous query paths (the common case) and for single-partition DataFusion scans (physical planning + leaf execution run inline on the polling thread).

pub fn pop_scope() -> QueryTrace

Pop the innermost trace from the thread-local stack, ending a capture scope. Returns the captured trace. Panics if the stack is empty (unpaired pop); see Self::push_scope.

pub fn capturing() -> bool

Whether path tracing is active on this thread (at least one QueryTrace::capture scope is open).

pub fn record<F>(f: F)

where F: FnOnce(&mut QueryTrace),

Record into the innermost active trace via f. No-op when not capturing — the hot path pays only the TLS load to check the stack.

This is the primary recording primitive: call it at every decision point (path selection, index rebuild, fast-path hit/miss). It is cheap enough to call once per query entry point without measurable overhead.

pub fn is_fast(&self) -> bool

Returns true when this trace took a “good” (non-materializing) path: a cursor, a pushdown, a shadow, or a count shortcut — and did not rebuild indexes or materialize rows. Useful as a quick sanity check in path-sensitive tests.

impl QueryTrace

pub fn assert_mode(&self, expected: ScanMode) -> &Self

Assert the scan mode equals expected. Returns &self for chaining.

pub fn assert_no_index_rebuild(&self) -> &Self

Assert no index rebuild happened during this query (Priority 10 guard).

pub fn assert_not_materialized(&self) -> &Self

Assert the query did not materialize Row { HashMap } objects.

pub fn assert_cache_hit(&self) -> &Self

Assert the result cache returned a hit.

pub fn assert_fast_row_id_map(&self) -> &Self

Assert the fast clean-run row-id→position arithmetic was used.

Trait Implementations

impl Clone for QueryTrace

fn clone(&self) -> QueryTrace

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for QueryTrace

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

Formats the value using the given formatter.

impl Default for QueryTrace

fn default() -> QueryTrace

Returns the “default value” for a type.

impl Display for QueryTrace

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

Compact one-line summary for benchmark output and ad-hoc inspection: native-pushdown pushed=2 survivors=12500 runs=1 idx=complete fast-rid.