nodedb_sql/temporal.rs
1// SPDX-License-Identifier: Apache-2.0
2
3//! Bitemporal scope types threaded through the SQL planner.
4//!
5//! A `TemporalScope` captures the user-facing `FOR SYSTEM_TIME AS OF <ms>` /
6//! `FOR VALID_TIME CONTAINS <ms>` / `FOR VALID_TIME FROM <ms> TO <ms>`
7//! qualifiers. It is extracted from raw SQL by
8//! [`crate::parser::preprocess::temporal`] before sqlparser-rs sees the
9//! statement, threaded through `plan_sql` into each `SqlPlan::Scan`, and
10//! finally honored by the engine's Data Plane handler.
11//!
12//! All timestamps are **milliseconds since Unix epoch**. The edge store
13//! converts to HLC ordinal via `nodedb_types::ms_to_ordinal_upper`. A
14//! `TemporalScope::default()` value is equivalent to "current state"
15//! (no temporal qualifier) — every scan site must construct one even when
16//! the query is not temporal.
17
18/// Valid-time qualifier attached to a scan.
19#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
20pub enum ValidTime {
21 /// No `FOR VALID_TIME` clause — every version qualifies.
22 #[default]
23 Any,
24 /// `FOR VALID_TIME CONTAINS <ms>` — version must satisfy
25 /// `valid_from_ms <= ms < valid_until_ms`.
26 At(i64),
27 /// `FOR VALID_TIME FROM <lo_ms> TO <hi_ms>` — version's valid
28 /// interval must overlap `[lo_ms, hi_ms)`.
29 Range(i64, i64),
30}
31
32/// Combined bitemporal qualifier for a scan.
33#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
34pub struct TemporalScope {
35 /// `FOR SYSTEM_TIME AS OF <ms>` cutoff, milliseconds. `None` means
36 /// current (latest) system-time version.
37 pub system_as_of_ms: Option<i64>,
38 /// Valid-time qualifier.
39 pub valid_time: ValidTime,
40}
41
42impl TemporalScope {
43 /// True when either temporal axis is qualified.
44 pub fn is_temporal(&self) -> bool {
45 self.system_as_of_ms.is_some() || !matches!(self.valid_time, ValidTime::Any)
46 }
47}