Struct TimeSeriesTable 

pub struct TimeSeriesTable { /* private fields */ }

High-level time-series table handle.

This is the main entry point for callers. It bundles the table location, transaction log, current committed state, and ordered-index specification.

Implementations

impl TimeSeriesTable

pub fn ensure_append_supported(&self) -> Result<(), TableError>

Check whether this client supports appending to the current table.

Higher-level wrappers can call this before inspecting or converting an append input. Self::append repeats the check before writing.

pub async fn append<S, SourceKind>( &mut self, source: S, ) -> Result<u64, TableError>

where S: IntoRecordBatchReader<SourceKind>,

Append Arrow record batches into one table-managed Parquet segment.

Rows need not be ordered by the table’s ordered index. The source is consumed incrementally and is never collected by this method. When a registered schema exists, incoming fields are matched by name and written in registered order. Exact types and these lossless scalar widenings are accepted: Int8 -> Int32/Int64, Int16 -> Int32/Int64, Int32 -> Int64, UInt8/UInt16/UInt32 -> UInt64, and Float32 -> Float64. New segments use Zstandard compression and row groups bounded by 1,048,576 rows and 128 MiB estimated encoded bytes. Wrap the source in AppendRequest to override those physical settings for only this append.

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::CoverageQuery containing CoverageQueryError::InvalidRange when the endpoints do not match the table index or start >= end, or CoverageQueryError::EntityIdentityRequired when the table has entity columns. Snapshot and interval mapping failures retain their typed sources in the same operation error.

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 interval, 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 index intervals for [start, end).

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

Errors

Returns TableError::CoverageQuery containing CoverageQueryError::InvalidRange when the endpoints do not match the table index or start >= end, or CoverageQueryError::EntityIdentityRequired when the table has entity columns. Snapshot and interval mapping failures retain their typed sources in the same operation error.

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 CoverageQueryError::InvalidRange inside TableError::CoverageQuery for invalid half-open range endpoints and retains typed snapshot and interval mapping sources in the same operation error.

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

where E: Into<IndexValue>,

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

Notes:

• This returns inclusive index interval IDs in their 64-bit domain.
• Returns None for a zero-length window or when no complete window exists.
• This identity-free query is only valid for tables without configured entity columns.

Errors

Returns TableError::CoverageQuery containing CoverageQueryError::InvalidRange when end does not match the table index or CoverageQueryError::EntityIdentityRequired when the table has entity columns. Endpoint mapping and snapshot failures retain their typed sources in the same operation error.

Examples

use chrono::{TimeZone, Utc};
let ts_end = Utc.timestamp_opt(360, 0).single().unwrap(); // end of interval 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_intervals: u64, ) -> Result<Option<RangeInclusive<IndexIntervalId>>, 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 intervals 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 CoverageQueryError::InvalidRange inside TableError::CoverageQuery when end does not match the table index and retains typed endpoint mapping and snapshot sources in the same operation error.

impl TimeSeriesTable

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

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

This validates the requested metadata, verifies that the target has no commits, publishes the initial metadata commit, and rebuilds the state returned to the caller.

impl TimeSeriesTable

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

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

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 async fn current_version(&self) -> Result<u64, TableError>

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

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

Rebuild and return the latest time-series table state.

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

Refresh in-memory state if the transaction log has advanced.

impl TimeSeriesTable

pub fn state(&self) -> &TableState

Return the current committed table state.

pub fn index_spec(&self) -> &IndexSpec

Return the ordered-index specification for this table.

pub fn location(&self) -> &TableLocation

Return the table location.

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.