Struct TimeSeriesTable 

pub struct TimeSeriesTable { /* private fields */ }

High-level time-series table handle.

This is the main entry point for callers. It bundles:

• where the table is,
• how to talk to the transaction log,
• what the current committed state is,
• and the extracted time index spec.

Implementations

impl TimeSeriesTable

pub async fn append_parquet_segment( &mut self, relative_path: &str, ) -> Result<u64, TableError>

Append a Parquet segment using its canonical relative path as identity.

Rows need not be ordered by the table’s ordered index.

pub async fn append_parquet_from_path( &mut self, parquet_path: &Path, ) -> Result<(u64, String), TableError>

Copy an external Parquet file into the table when needed and append it.

Rows need not be ordered by the table’s ordered index.

A copy created by this operation is removed when append fails before publication. Files already under the table root and copies involved in an ambiguous commit outcome are preserved. Returns the committed version and normalized table-relative segment path.

pub async fn append_parquet_from_path_with_report( &mut self, parquet_path: &Path, ) -> Result<(u64, String, AppendReport), TableError>

Copy and append a Parquet file while collecting a profiling report. Returns the committed version, normalized table-relative path, and report.

pub async fn append_parquet_segment_with_report( &mut self, relative_path: &str, ) -> Result<(u64, AppendReport), TableError>

Append a Parquet segment and return a profiling report.

impl TimeSeriesTable

pub async fn load_table_coverage_snapshot_only( &self, ) -> Result<Coverage, TableError>

Load table coverage using the snapshot pointer only.

• If there is no snapshot pointer:
  • If table has zero segments: returns empty coverage.
  • Else: returns MissingTableCoveragePointer (strict mode).
• If snapshot exists but is missing/corrupt: returns the snapshot read error.

impl TimeSeriesTable

pub async fn coverage_ratio_for_range<S, E>( &self, start: S, end: E, ) -> Result<f64, TableError>

where S: Into<IndexValue>, E: Into<IndexValue>,

Coverage ratio in [0.0, 1.0] for the half-open index range [start, end).

This identity-free query is only valid for tables without configured entity columns. It uses the table-level coverage snapshot, with readonly recovery from segments if needed.

Errors

Returns TableError::InvalidRange when the endpoints do not match the table index or start >= end, TableError::EntityIdentityRequired when the table has entity columns, and contextual coverage errors when the snapshot cannot be loaded or the range cannot be bucketed.

Examples

use chrono::{TimeZone, Utc};
let start = Utc.timestamp_opt(0, 0).single().unwrap();
let end = Utc.timestamp_opt(120, 0).single().unwrap();
let ratio = table.coverage_ratio_for_range(start, end).await?;

pub async fn coverage_ratio_for_entity_range<S, E>( &self, entity: &[(&str, EntityValue)], start: S, end: E, ) -> Result<f64, TableError>

where S: Into<IndexValue>, E: Into<IndexValue>,

Coverage ratio in [0.0, 1.0] for one entity over [start, end).

Entity components are supplied by column name and canonicalized into the configured entity-column order. Coverage from other identities is never included. A complete identity not present in the table has zero coverage.

Errors

Returns a typed entity identity error for missing, duplicate, unexpected, or unconfigured entity columns. Range and sidecar errors retain the same behavior as TimeSeriesTable::coverage_ratio_for_range.

Examples

If entities A and B both have data in the same bucket, their coverage is still queried independently:

use chrono::{TimeZone, Utc};
let start = Utc.timestamp_opt(0, 0).single().unwrap();
let end = Utc.timestamp_opt(120, 0).single().unwrap();
let a = table
    .coverage_ratio_for_entity_range(&[("symbol", EntityValue::from("A"))], start, end)
    .await?;
let b = table
    .coverage_ratio_for_entity_range(&[("symbol", EntityValue::from("B"))], start, end)
    .await?;

pub async fn max_gap_len_for_range<S, E>( &self, start: S, end: E, ) -> Result<u128, TableError>

where S: Into<IndexValue>, E: Into<IndexValue>,

Maximum contiguous missing run length in buckets for [start, end).

This identity-free query is only valid for tables without configured entity columns.

Errors

Returns TableError::InvalidRange when the endpoints do not match the table index or start >= end, TableError::EntityIdentityRequired when the table has entity columns, and contextual coverage errors when the snapshot cannot be loaded or the range cannot be bucketed.

Examples

use chrono::{TimeZone, Utc};
let start = Utc.timestamp_opt(0, 0).single().unwrap();
let end = Utc.timestamp_opt(180, 0).single().unwrap();
let gap = table.max_gap_len_for_range(start, end).await?;

pub async fn max_gap_len_for_entity_range<S, E>( &self, entity: &[(&str, EntityValue)], start: S, end: E, ) -> Result<u128, TableError>

where S: Into<IndexValue>, E: Into<IndexValue>,

Maximum contiguous missing run length for one entity over [start, end).

Entity components are supplied by column name and canonicalized into the configured entity-column order. Other entities never fill this entity’s gaps. A complete identity not present in the table is missing for the entire requested range.

Errors

Returns a typed entity identity error for missing, duplicate, unexpected, or unconfigured entity columns. It returns TableError::InvalidRange for invalid half-open range endpoints and contextual coverage errors when the snapshot cannot be loaded or the range cannot be bucketed.

pub async fn last_fully_covered_window<E>( &self, end: E, window_len_buckets: u64, ) -> Result<Option<RangeInclusive<Bucket>>, TableError>

where E: Into<IndexValue>,

Return the last fully covered contiguous window of window_len_buckets ending before the exclusive ordered-index endpoint.

Notes:

• This returns a bucket-id RangeInclusive in the 64-bit bucket domain.
• Returns None when window_len_buckets == 0 or when no fully covered window is found.
• This identity-free query is only valid for tables without configured entity columns.

Errors

Returns TableError::InvalidRange when end does not match the table index, TableError::EntityIdentityRequired when the table has entity columns, and contextual coverage errors when the endpoint cannot be bucketed or the snapshot cannot be loaded.

Examples

use chrono::{TimeZone, Utc};
let ts_end = Utc.timestamp_opt(360, 0).single().unwrap(); // end of bucket 5
let window = table.last_fully_covered_window(ts_end, 2).await?;

pub async fn last_fully_covered_window_for_entity<E>( &self, entity: &[(&str, EntityValue)], end: E, window_len_buckets: u64, ) -> Result<Option<RangeInclusive<Bucket>>, TableError>

where E: Into<IndexValue>,

Return one entity’s last fully covered contiguous window ending before the exclusive ordered-index endpoint.

Entity components are supplied by column name and canonicalized into the configured entity-column order. Other entities cannot contribute buckets to the window. A complete identity not present in the table returns None, as does a zero-length window.

Errors

Returns a typed entity identity error for missing, duplicate, unexpected, or unconfigured entity columns. It returns TableError::InvalidRange when end does not match the table index and contextual coverage errors when the endpoint cannot be bucketed or the snapshot cannot be loaded.

impl TimeSeriesTable

pub async fn optimize(&mut self) -> Result<OptimizeReport, TableError>

Replace every live mixed-entity segment with verified single-entity Parquet segments in one expected-version commit.

Optimization preserves logical rows, schema, and per-entity coverage, but may change physical row order.

Errors

Returns TableError when optimization is not applicable, staging or validation fails, the commit cannot be confirmed, or rollback fails.

impl TimeSeriesTable

pub async fn scan_range<S, E>( &self, start: S, end: E, ) -> Result<TimeSeriesScan, TableError>

where S: Into<IndexValue>, E: Into<IndexValue>,

Scan the time-series table for record batches overlapping [start, end), returning a stream of filtered batches from the segments covering that range.

Input rows need not be ordered. The returned batches and rows have no ordering guarantee; callers that need ordered results must sort them.

impl TimeSeriesTable

pub fn state(&self) -> &TableState

Return the current committed table state.

pub fn index_spec(&self) -> &IndexSpec

Return the time index specification for this table.

pub fn location(&self) -> &TableLocation

Return the table location.

pub async fn open(location: TableLocation) -> Result<Self, TableError>

Open an existing time-series table at the given location.

Steps:

• Build a TransactionLogStore for the location.
• Rebuild TableState from the transaction log.
• Reject empty tables (version == 0).
• Require TableKind::TimeSeries and extract IndexSpec.

pub async fn create( location: TableLocation, table_meta: TableMeta, ) -> Result<Self, TableError>

Create a new time-series table at the given location.

This:

• Requires table_meta.format_version to match TABLE_FORMAT_VERSION,
• Requires table_meta.kind to be TableKind::TimeSeries,
• Verifies that there are no existing commits (version must be 0),
• Writes an initial commit with UpdateTableMeta(table_meta.clone()),
• Returns a TimeSeriesTable with a fresh TableState.

pub async fn current_version(&self) -> Result<u64, TableError>

Load the current log version from disk without mutating in-memory state.

pub async fn load_latest_state(&self) -> Result<TableState, TableError>

Rebuild and return the latest table state from the transaction log.

pub async fn refresh(&mut self) -> Result<bool, TableError>

Refresh in-memory state if the log has advanced; returns true if updated.

Trait Implementations

impl Clone for TimeSeriesTable

fn clone(&self) -> TimeSeriesTable

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for TimeSeriesTable

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

Formats the value using the given formatter.