Module temporal_join 

Temporal Join Operators

Join streaming events with versioned tables using point-in-time lookups. Temporal joins return the table value that was valid at the event’s timestamp, enabling consistent enrichment with time-varying dimension data.

Use Cases

• Currency rate lookup at transaction time
• Product price lookup at order time
• User tier lookup at event time
• Regulatory compliance (audit trail)

Join Types

• Event-Time: Deterministic lookup based on event timestamp (FOR SYSTEM_TIME AS OF)
• Process-Time: Non-deterministic lookup based on processing time (latest value)

Table Characteristics

• Append-Only: Only inserts, no updates/deletes. Optimized: no stream-side state needed.
• Non-Append-Only: Has updates/deletes. Requires state to track join results for retractions.

Example

use laminar_core::operator::temporal_join::{
    TemporalJoinOperator, TemporalJoinConfig, TemporalJoinSemantics,
    TableCharacteristics, TemporalJoinType,
};

// Join orders with currency rates valid at order time
let config = TemporalJoinConfig::builder()
    .stream_key_column("currency".to_string())
    .table_key_column("currency".to_string())
    .table_version_column("valid_from".to_string())
    .semantics(TemporalJoinSemantics::EventTime)
    .table_characteristics(TableCharacteristics::AppendOnly)
    .join_type(TemporalJoinType::Inner)
    .build()
    .unwrap();

let operator = TemporalJoinOperator::new(config);

SQL Syntax (Future)

-- Event-time temporal join
SELECT o.*, r.rate
FROM orders o
JOIN currency_rates FOR SYSTEM_TIME AS OF o.order_time r
    ON o.currency = r.currency;

-- Process-time temporal join (latest value)
SELECT o.*, c.tier
FROM orders o
JOIN customers FOR SYSTEM_TIME AS OF PROCTIME() c
    ON o.customer_id = c.id;

Structs

ArchivedJoinedEventRecord

An archived JoinedEventRecord

ArchivedTableRow

An archived TableRow

JoinedEventRecord

Record of a joined event for retraction tracking (non-append-only tables).

JoinedEventRecordResolver

The resolver for an archived JoinedEventRecord

TableRow

A stored table row for temporal joining.

TableRowResolver

The resolver for an archived TableRow

TemporalJoinConfig

Configuration for a temporal join operator.

TemporalJoinConfigBuilder

Builder for TemporalJoinConfig.

TemporalJoinMetrics

Metrics for tracking temporal join operations.

TemporalJoinOperator

Temporal join operator.

VersionedKeyState

Per-key versioned table state.

Enums

TableChange

Table change event for non-append-only tables.

TableCharacteristics

Table update characteristics.

TemporalJoinSemantics

Type of temporal join semantics.

TemporalJoinType

Type of temporal join to perform.