Struct HypertableRegistry 

pub struct HypertableRegistry { /* private fields */ }

In-memory catalog of hypertables and their chunks. Thread-safe because INSERTs can land from multiple writers simultaneously.

Implementations

impl HypertableRegistry

pub fn new() -> Self

pub fn register(&self, spec: HypertableSpec)

Register a new hypertable. Replaces the previous spec if one existed with the same name; chunks for that name are kept — the operator is assumed to know what they’re doing when they redefine (e.g. widening chunk_interval_ns).

pub fn get(&self, name: &str) -> Option<HypertableSpec>

pub fn list(&self) -> Vec<HypertableSpec>

pub fn unregister(&self, name: &str) -> Option<HypertableSpec>

Drop a hypertable from the registry. Returns the removed spec when present, or None for unknown names. Callers drop the backing collection separately — this is registry housekeeping only.

pub fn route(&self, hypertable: &str, timestamp_ns: u64) -> Option<ChunkId>

Route a write: returns the ChunkId the row belongs in, allocating the chunk on first write. None when the hypertable is unknown.

pub fn show_chunks(&self, hypertable: &str) -> Vec<ChunkMeta>

Return every chunk for hypertable, oldest-first.

pub fn drop_chunks_before( &self, hypertable: &str, cutoff_ns: u64, ) -> Vec<ChunkMeta>

Drop every chunk of hypertable whose max_ts_ns is at or below cutoff_ns. Returns the count dropped — the physical storage release is the caller’s responsibility (this module only owns the metadata).

pub fn sweep_expired(&self, hypertable: &str, now_ns: u64) -> Vec<ChunkMeta>

Sweep chunks whose effective TTL has fired. A chunk is droppable when now_ns ≥ max_ts_ns + effective_ttl_ns — the registry hands back every removed ChunkMeta so the physical-storage callback can release bytes + indexes. Chunks without an effective TTL (neither per-chunk override nor hypertable default) are never touched.

This is the “TTL applied at the partition level” primitive: one O(1) metadata sweep reclaims every row of every expired chunk, instead of scanning rows individually like an entity-level TTL would. Empty hypertables stay empty.

pub fn sweep_all_expired(&self, now_ns: u64) -> Vec<(String, ChunkMeta)>

Sweep every registered hypertable in one shot — the loop the retention daemon runs every cycle. Returns a flat list of (hypertable_name, chunk_dropped) pairs.

pub fn set_default_ttl_ns(&self, hypertable: &str, ttl_ns: Option<u64>) -> bool

Install / replace the hypertable-wide default TTL. None disables automatic expiry — chunks live until explicit drop_chunks / per-chunk override fires.

pub fn set_chunk_ttl_ns(&self, id: &ChunkId, ttl_ns: Option<u64>) -> bool

Override the TTL for a single chunk. Useful for “keep this specific chunk longer because it contains an incident replay” or “expire this one faster because it was filled from a backfill we’re about to redo”. None removes the override and falls back to the hypertable default.

pub fn chunks_expiring_within( &self, hypertable: &str, now_ns: u64, horizon_ns: u64, ) -> Vec<ChunkMeta>

Inspect the list of chunks that are about to expire within horizon_ns. Powers preview endpoints (“what will the next sweep drop?”) without actually dropping anything.

pub fn seal_chunk(&self, id: &ChunkId) -> bool

Seal a chunk — future writes to the same start_ns bucket will still land (open-ended), but the sealed flag signals the maintenance layer that the chunk can now be compressed / uploaded / migrated. Returns true if the chunk existed.

pub fn seal_chunk_columnar( &self, id: &ChunkId, page: PageLocation, bytes: Vec<u8>, ) -> bool

Seal a chunk columnar (PRD #850, #911): mark it sealed, record where its RDCC ColumnBlock lives in ChunkMeta.columnar_page, and stash the block bytes so the columnar read path can decode them. The columnar counterpart of seal_chunk — the production caller (seal_chunk_with_config’s columnar arm) hands the sealed bytes here. Returns true if the chunk existed.

pub fn columnar_block(&self, id: &ChunkId) -> Option<Vec<u8>>

Fetch the RDCC ColumnBlock bytes recorded for a columnar-sealed chunk by seal_chunk_columnar. None for row-sealed chunks or chunks whose bytes are not RAM-resident (e.g. after a restart, pending the durable page-write bridge).

pub fn total_rows(&self, hypertable: &str) -> u64

Total row count across every chunk of hypertable. Used by catalog views + benchmark harnesses.

pub fn names(&self) -> Vec<String>

List the hypertables the retention daemon should sweep.

pub fn is_empty(&self) -> bool

True when no hypertable is registered and no chunk is tracked. Lets the durability layer skip the persist step entirely for workloads that never declared a hypertable (zero overhead).

pub fn snapshot_chunks(&self) -> Vec<ChunkMeta>

Snapshot every chunk across all hypertables, ordered by (hypertable, start_ns) so the persisted form is deterministic. Pairs with [restore_chunk] on boot. Specs are snapshotted via [list].

pub fn restore_chunk(&self, meta: ChunkMeta)

Reinstate a chunk verbatim during recovery. Overwrites any existing entry for the same (hypertable, start_ns).

Unlike [route], this does not observe a timestamp — it restores the persisted counters (row_count, min_ts_ns, max_ts_ns, sealed, ttl_override_ns) exactly so the post-restart registry is identical to the pre-restart one. The caller is expected to [register] the owning spec first; a chunk whose hypertable has no spec is still tracked (routing falls back to the spec once it is registered), matching the pre-restart invariant that chunks outlive a missing spec only transiently.

pub fn drop_hypertable(&self, name: &str) -> usize

Drop the whole hypertable (spec + every chunk). Returns the number of chunks removed.

pub fn select_compaction_candidates( &self, hypertable: &str, max_rows_per_group: u64, min_chunks: usize, ) -> Vec<Vec<ChunkId>>

Select groups of small sealed columnar chunks that are candidates for compaction. Returns a list of groups; each group is a list of ChunkIds that together hold at most max_rows_total rows. Groups with fewer than min_chunks chunks are not returned (no-op merges).

Chunks are considered in oldest-first order within each hypertable. The caller decides the merge policy (threshold sizes, timing).

pub fn compact_columnar_chunks( &self, hypertable: &str, source_ids: &[ChunkId], merged_chunk_id: u64, schema_ref: u64, granule_size: u32, ) -> Result<ChunkId, CompactionError>

Merge N sealed columnar chunks into one larger sealed columnar chunk.

Crash safety

The merge is computed entirely in memory before any registry state is touched. The final registry update (insert merged entry + remove source entries) happens atomically under one Mutex lock acquisition. If the process is killed before the lock is taken, all source chunks remain intact — no committed data is lost. A torn merge (crash mid-computation, before the atomic commit) is safe because the registry never saw the partial output.

Arguments

• hypertable — name of the owning hypertable.
• source_ids — the ChunkIds of the chunks to merge (must all be sealed, columnar, and have their blocks RAM-resident).
• merged_chunk_id — the chunk_id header field for the output RDCC block; the caller assigns this (e.g. min(source start_ns) cast).
• schema_ref — the catalog schema id written into the output header.
• granule_size — sparse-granule-index stride for the merged block. Pass DEFAULT_GRANULE_SIZE for the standard 8 192-row marks.

Returns the ChunkId of the newly inserted merged chunk on success.

Trait Implementations

impl Clone for HypertableRegistry

fn clone(&self) -> HypertableRegistry

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for HypertableRegistry

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

Formats the value using the given formatter.

impl Default for HypertableRegistry

fn default() -> HypertableRegistry

Returns the “default value” for a type.