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,
    pub authorization_nanos: u64,
    pub rls_cache_hit: bool,
    pub rls_rows_evaluated: usize,
    pub rls_policy_columns_decoded: usize,
    pub authorization_retries: usize,
    pub hard_filter_nanos: u64,
    pub ann_algorithm: Option<AnnAlgorithm>,
    pub ann_quantization: Option<AnnQuantization>,
    pub ann_backend: Option<&'static str>,
    pub ann_candidate_nanos: u64,
    pub ann_candidate_cap_hit: bool,
    pub sparse_candidate_nanos: u64,
    pub minhash_candidate_nanos: u64,
    pub candidate_count: usize,
    pub union_size: usize,
    pub fusion_nanos: u64,
    pub exact_vector_gather_nanos: u64,
    pub exact_vector_score_nanos: u64,
    pub exact_set_gather_nanos: u64,
    pub exact_set_parse_nanos: u64,
    pub exact_set_score_nanos: u64,
    pub projection_nanos: u64,
    pub projection_rows: usize,
    pub projection_cells: usize,
    pub work_consumed: usize,
    pub total_nanos: u64,
    pub directory_complete: bool,
    pub directory_candidates: usize,
    pub run_range_rejects: usize,
    pub membership_filter_rejects: usize,
    pub run_readers_opened: usize,
    pub early_stop: bool,
    pub point_cache_hits: usize,
    pub controlled_scan_versions_examined: usize,
    pub controlled_scan_rows_emitted: usize,
    pub controlled_scan_source_refills: usize,
    pub controlled_scan_peak_source_buffer_rows: usize,
    pub controlled_scan_peak_same_row_versions: usize,
    pub controlled_scan_checkpoints: usize,
    pub controlled_scan_time_to_first_row_us: u64,
    pub controlled_scan_cancel_latency_us: u64,
    pub controlled_scan_setup_time_us: u64,
    pub hot_lookup_attempted: bool,
    pub hot_lookup_hit: bool,
    pub hot_fallback_reason: Option<&'static str>,
    pub hot_fallback_overlay_versions: usize,
    pub hot_fallback_runs_considered: usize,
    pub hot_fallback_runs_opened: usize,
    pub hot_fallback_pages_decoded: usize,
    pub hot_fallback_rows_materialized: usize,
    pub hot_lookup_nanos: u64,
    pub hot_fallback_nanos: u64,
    pub raw_candidates: usize,
    pub unique_candidates: usize,
    pub duplicate_candidates: usize,
    pub visibility_rejected: usize,
    pub tombstone_rejected: usize,
    pub ttl_rejected: usize,
    pub authorization_rejected: usize,
    pub hard_filter_rejected: usize,
    pub candidate_cap: usize,
    pub candidate_cap_hit: bool,
    pub final_hits: usize,
    pub underfill_reason: Option<&'static str>,
}

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.

authorization_nanos: u64

Authorization/RLS candidate-cache work for the query.

rls_cache_hit: bool

rls_rows_evaluated: usize

rls_policy_columns_decoded: usize

authorization_retries: usize

hard_filter_nanos: u64

AI retrieval stage timings and bounded cardinalities.

ann_algorithm: Option<AnnAlgorithm>

ANN backend selected by the authoritative index schema.

ann_quantization: Option<AnnQuantization>

ANN representation selected by the authoritative index schema.

ann_backend: Option<&'static str>

Concrete backend executing the ANN candidate search.

ann_candidate_nanos: u64

ann_candidate_cap_hit: bool

sparse_candidate_nanos: u64

minhash_candidate_nanos: u64

candidate_count: usize

union_size: usize

fusion_nanos: u64

exact_vector_gather_nanos: u64

exact_vector_score_nanos: u64

exact_set_gather_nanos: u64

exact_set_parse_nanos: u64

exact_set_score_nanos: u64

projection_nanos: u64

projection_rows: usize

projection_cells: usize

work_consumed: usize

total_nanos: u64

directory_complete: bool

Whether the RunLookupDirectory was consulted and produced a complete candidate set for this get. false means the legacy range-scan fallback ran (which is acceptable but not optimal).

directory_candidates: usize

Number of run locators the directory returned for the queried RowId.

run_range_rejects: usize

Number of runs rejected by the header-derived run_row_id_ranges filter.

membership_filter_rejects: usize

Number of runs rejected by membership / predicate filters before open.

run_readers_opened: usize

How many immutable run readers were actually opened.

early_stop: bool

Set when the lookup short-circuited because the best candidate was provably newer than every remaining locator’s upper bound.

point_cache_hits: usize

Point cache hits (replay of a recent in-process lookup result).

controlled_scan_versions_examined: usize

Total versions examined across all segments during the scan.

controlled_scan_rows_emitted: usize

Rows emitted by the scan (post-filter).

controlled_scan_source_refills: usize

Number of times a segment cursor was refilled.

controlled_scan_peak_source_buffer_rows: usize

Peak number of buffered rows held by the streaming merge at any moment.

controlled_scan_peak_same_row_versions: usize

Peak number of versions seen for any single RowId during the scan.

controlled_scan_checkpoints: usize

Number of ExecutionControl::checkpoint calls issued during the scan.

controlled_scan_time_to_first_row_us: u64

Wall-clock time to produce the first row, in microseconds.

controlled_scan_cancel_latency_us: u64

Time from cancel to the scan actually observing cancellation, in µs.

controlled_scan_setup_time_us: u64

Wall-clock time spent constructing the controlled-scan sources, in µs.

hot_lookup_attempted: bool

Whether a HOT lookup was attempted for this query.

hot_lookup_hit: bool

Whether the HOT lookup was a hit (no fallback).

hot_fallback_reason: Option<&'static str>

Stable reason label when the HOT lookup fell back. None on hit.

hot_fallback_overlay_versions: usize

Overlay versions examined during the fallback path.

hot_fallback_runs_considered: usize

Sorted runs considered during the fallback path.

hot_fallback_runs_opened: usize

Sorted run readers actually opened during the fallback path.

hot_fallback_pages_decoded: usize

Pages decoded during the fallback path.

hot_fallback_rows_materialized: usize

Rows materialized during the fallback path.

hot_lookup_nanos: u64

Wall-clock time spent on the HOT fast-path lookup, in nanoseconds.

hot_fallback_nanos: u64

Wall-clock time spent on the fallback path, in nanoseconds.

raw_candidates: usize

Raw candidates produced by the index backend before dedup.

unique_candidates: usize

Unique candidates after (RowId) dedup.

duplicate_candidates: usize

Duplicate candidates dropped during dedup.

visibility_rejected: usize

Candidates rejected by Snapshot::observes_row.

tombstone_rejected: usize

Candidates rejected as tombstones.

ttl_rejected: usize

Candidates rejected by TTL.

authorization_rejected: usize

Candidates rejected by authorization (RLS / allowed set).

hard_filter_rejected: usize

Candidates rejected by hard filter.

candidate_cap: usize

Configured candidate cap for the retrieval.

candidate_cap_hit: bool

Whether the candidate cap was hit.

final_hits: usize

Final number of hits returned to the caller.

underfill_reason: Option<&'static str>

Stable explanation when a top-k retrieval legally returns fewer than k.

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.