Struct TableReadGeneration 

pub struct TableReadGeneration { /* private fields */ }

Immutable, structurally shared snapshot used by scored readers.

Methods from Deref<Target = Table>

pub const AUTO_COMPACT_RUN_THRESHOLD: usize = 8

pub fn should_compact(&self) -> bool

Whether this table would benefit from compaction right now — the query-cost signal for §5.9. Pure run-count topology (no per-query bookkeeping): once runs have accumulated past the threshold, scans and pushdown queries are paying multi-run fallback cost, so compaction is worthwhile. A daemon (or any long-lived holder) polls this.

pub fn require_select(&self) -> Result<()>

Check Select permission on this table. Public so that read entry points that don’t go through Table::query (e.g. MongrelProvider::scan, Table::count) can enforce before reading. On a credentialless database this is a no-op.

pub fn apply_defaults(&self, columns: &mut Vec<(u16, Value)>) -> Result<()>

Apply column default expressions to columns at stage time (before NOT NULL validation). For each column carrying a default_value, if the column is omitted or explicitly Null, the default is applied. Explicit values are never overridden. Called after fill_auto_inc and before validate_not_null.

pub fn mutable_run_len(&self) -> usize

Number of versions currently held in the mutable-run tier.

pub fn get(&self, row_id: RowId, snapshot: Snapshot) -> Option<Row>

Read the row at row_id visible to snapshot, merging the newest version across the memtable and all sorted runs.

pub fn visible_rows(&self, snapshot: Snapshot) -> Result<Vec<Row>>

All rows visible at snapshot (newest version per RowId, tombstones dropped), merged across the memtable, the mutable-run tier, and all runs. Ascending RowId.

pub fn visible_columns( &self, snapshot: Snapshot, ) -> Result<Vec<(u16, Vec<Value>)>>

Visible data as columns (column_id → values) rather than rows — the vectorized scan path. Fast path: when the memtable is empty and there is exactly one run (the common post-flush analytical case), it computes the visible index set once and gathers each column, with no per-row HashMap/Row materialization. Falls back to Self::visible_rows pivoted to columns when the memtable is live or runs overlap.

pub fn lookup_pk(&self, key: &[u8]) -> Option<RowId>

Resolve a primary-key value to a row id (latest version).

pub fn rows_for_rids( &self, rids: &[u64], snapshot: Snapshot, ) -> Result<Vec<Row>>

Materialize the MVCC-visible, non-deleted rows for rids at snapshot, preserving the input order. Rows whose newest visible version is a tombstone, or that no longer exist, are omitted. Shared by index-served [query] and the Phase 8.1 FK-join path.

pub fn rows_for_rids_with_context( &self, rids: &[u64], snapshot: Snapshot, context: &AiExecutionContext, ) -> Result<Vec<Row>>

pub fn indexes_complete(&self) -> bool

Resolve the referencing (FK) side of a primary-key ↔ foreign-key join as a row-id set (Phase 8.1): union the roaring-bitmap entries of fk_column_id for every value in pk_values — the surviving primary-key values — then intersect with fk_conditions, i.e. any FK-side predicates (ann_search ∩ fm_contains, bitmap equality, range, …). Returns the survivor row-ids ascending. Requires a bitmap index on fk_column_id; returns an empty set when there is none. Whether live indexes are complete (Phase 14.7 + 17.2: the broadcast join path checks this before using the HOT index).

pub fn index_build_policy(&self) -> IndexBuildPolicy

Where bulk loads put the index-build cost (see IndexBuildPolicy).

pub fn broadcast_join_values( &self, column_id: u16, pk_db: &Table, ) -> Option<Vec<Vec<u8>>>

Phase 17.2: broadcast join — return the distinct values in this table’s bitmap index for column_id that also exist as a key in pk_db’s HOT index. Avoids loading the entire PK table when the FK column has low cardinality. Returns None if no bitmap index exists for the column.

pub fn fk_join_row_ids( &self, fk_column_id: u16, pk_values: &[Vec<u8>], fk_conditions: &[Condition], snapshot: Snapshot, ) -> Result<Vec<u64>>

pub fn fk_join_count( &self, fk_column_id: u16, pk_values: &[Vec<u8>], fk_conditions: &[Condition], snapshot: Snapshot, ) -> Result<u64>

Like [fk_join_row_ids] but returns only the cardinality of the FK survivor set — without materializing or sorting it. For a bare COUNT(*) join with no FK-side filter this is O(1) on the bitmap union (Phase 17.4): the prior path built a HashSet<u64> + Vec<u64> + sort_unstable over up to N rows only to read .len().

pub fn snapshot(&self) -> Snapshot

pub fn data_generation(&self) -> u64

Generation of this table’s row contents for table-local caches.

pub fn ttl(&self) -> Option<TtlPolicy>

pub fn current_epoch(&self) -> Epoch

pub fn memtable_len(&self) -> usize

pub fn count(&self) -> u64

Live row count. O(1) without TTL; TTL tables scan because wall-clock expiry can change without a commit epoch.

pub fn visible_columns_native( &self, snapshot: Snapshot, projection: Option<&[u16]>, ) -> Result<Vec<(u16, NativeColumn)>>

no Value). Fast path: empty memtable + single run decodes columns directly and gathers visible indices; falls back to the Value path pivoted to native columns otherwise. projection (a set of column ids) limits decoding to the requested columns — None ⇒ all user columns.

pub fn visible_columns_native_with_control( &self, snapshot: Snapshot, projection: Option<&[u16]>, control: &ExecutionControl, ) -> Result<Vec<(u16, NativeColumn)>>

pub fn run_count(&self) -> usize

pub fn memtable_is_empty(&self) -> bool

Whether the memtable is empty (no unflushed puts).

pub fn page_cache_stats(&self) -> CacheStats

Cumulative raw-page-cache hit/miss counts (Priority 14: hit visibility). Useful for confirming a repeat scan is served from cache or measuring a query’s locality after reset_page_cache_stats.

pub fn reset_page_cache_stats(&self)

Zero the raw-page-cache hit/miss counters.

pub fn run_ids(&self) -> Vec<u128>

The run IDs in level order (Phase 15.5: used by the Arrow IPC shadow to key shadow files and detect stale shadows).

pub fn single_run_is_clean(&self) -> bool

Whether the single run (if exactly one) is clean — i.e. has RUN_FLAG_CLEAN set (Phase 15.5: the shadow is zero-copy only for clean runs).

pub fn native_page_cursor_traced( &self, snapshot: Snapshot, projection: Vec<(u16, TypeId)>, conditions: &[Condition], ) -> Result<(Option<NativePageCursor>, QueryTrace)>

Self::native_page_cursor with a captured crate::trace::QueryTrace.

pub fn native_multi_run_cursor_traced( &self, snapshot: Snapshot, projection: Vec<(u16, TypeId)>, conditions: &[Condition], ) -> Result<(Option<MultiRunCursor>, QueryTrace)>

Self::native_multi_run_cursor with a captured crate::trace::QueryTrace.

pub fn native_page_cursor( &self, snapshot: Snapshot, projection: Vec<(u16, TypeId)>, conditions: &[Condition], ) -> Result<Option<NativePageCursor>>

Build a lazy, page-aware NativePageCursor for the single-run fast path. MVCC visibility and predicate survivor resolution are settled up front (so they see the live indexes under the DB lock); the cursor then owns the reader and decodes only the projected columns of pages that contain survivors, lazily. This is the fused-predicate + page-skip + late-materialization scan.

Phase 13.1: the memtable / mutable-run overlay is now handled. Rows with a newer version in the overlay are excluded from the run’s page plans (their run version is stale); the overlay rows are pre-materialized and appended as a final batch via NativePageCursor::new_with_overlay.

Returns None only for multiple sorted runs; the caller falls back to the materialize-then-stream scan for that layout.

pub fn native_multi_run_cursor( &self, snapshot: Snapshot, projection: Vec<(u16, TypeId)>, conditions: &[Condition], ) -> Result<Option<MultiRunCursor>>

Generalizes Self::native_page_cursor (single-run) to arbitrary run counts via a k-way merge by RowId. Cross-run MVCC resolution (newest visible version per RowId) and predicate survivor resolution are settled up front from the cheap system columns + global indexes; the cursor then lazily decodes the projected data columns of just the pages that own survivors, each page at most once. The memtable / mutable-run overlay is materialized and yielded as a final batch (mirroring the single-run path).

Returns None only when there are no runs at all (caller falls back).

pub fn scan_cursor( &self, snapshot: Snapshot, projection: Vec<(u16, TypeId)>, conditions: &[Condition], ) -> Result<Option<Box<dyn Cursor>>>

Native vectorized aggregate over a (possibly filtered) column on the single-run fast path (Phase 7.2). Resolves survivors via the same page-pruned cursor as the scan, then accumulates the aggregate in one pass over the typed buffer — no Value, no Arrow RecordBatch.

column is None for COUNT(*). Returns Ok(None) when the fast path does not apply (multi-run / non-empty memtable); the caller scans. Open the streaming Cursor matching the current run layout: the single-run page cursor when there is exactly one sorted run, otherwise the multi-run k-way merge cursor. Both fuse the predicate, skip non-surviving pages, and fold the memtable / mutable-run overlay, so callers stay columnar end-to-end and never materialize Rows. Returns None when no cursor applies (e.g. an overlay-only table with no sorted run), leaving the caller to fall back.

This is the single source of truth for layout-aware cursor selection, shared by the column scan (Self::query_columns_native / the SQL provider) and the aggregate path (Self::aggregate_native). New streaming consumers should build on this rather than re-deciding the cursor by run count.

pub fn aggregate_native( &self, snapshot: Snapshot, column: Option<u16>, conditions: &[Condition], agg: NativeAgg, ) -> Result<Option<NativeAggResult>>

Native vectorized aggregate over a (possibly filtered) column, in one pass over the typed buffers — no Value, no Arrow batch. Layout-agnostic: survivors stream through Self::scan_cursor (single- or multi-run, overlay-folded), so the same path serves every sorted-run layout.

column is None for COUNT(*). Order of attempts:

1. Single clean run + no WHERE ⇒ MIN/MAX/COUNT(col) straight from page min/max/null_count (no decode).
2. COUNT(*) ⇒ survivor cardinality from the cursor’s page plans.
3. Otherwise accumulate the projected column over the cursor.

Returns Ok(None) (caller scans) when no native path applies: an overlay-only table with no sorted run, or a non-numeric column.

pub fn aggregate_native_with_control( &self, snapshot: Snapshot, column: Option<u16>, conditions: &[Condition], agg: NativeAgg, control: &ExecutionControl, ) -> Result<Option<NativeAggResult>>

pub fn exact_column_stats( &self, _snapshot: Snapshot, projection: &[u16], ) -> Result<Option<HashMap<u16, ColumnStat>>>

Exact per-column statistics for the analytical aggregate fast path (Phase 7.1: MIN/MAX/COUNT(col) from page stats). Returns None unless the table is effectively insert-only at snapshot — empty memtable, a single sorted run, and live_count == run.row_count() — so the run’s page min/max/null_count are exact (no tombstoned or superseded versions skew them). Under deletes/updates the caller falls back to scanning.

pub fn dir(&self) -> &Path

pub fn schema(&self) -> &Schema

pub fn page_cache_flush(&self)

Flush all live page-cache entries to the persistent _cache/ backing directory (best-effort). Useful before a clean shutdown so hot pages survive restart.

pub fn page_cache_len(&self) -> usize

Number of entries currently in the shared page cache (diagnostic).

pub fn decoded_cache_len(&self) -> usize

Number of entries currently in the shared decoded-page cache (Phase 15.4 diagnostic).

pub fn gc(&self) -> Result<GcReport>

Remove orphan run files (not in the manifest) and all but the active WAL segment. Safe to run any time; readers pin snapshots, not files.

pub fn check(&self) -> Result<CheckReport>

Verify every manifest-referenced run’s footer checksum.

Trait Implementations

impl Deref for TableReadGeneration

type Target = Table

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Drop for TableReadGeneration

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.