Sync Modes

Yoda supports two strategies for applying CDC events from the OLTP log to the OLAP mirror. Choose Destructive when you only need the current state of your data, or Temporal when you need a full history of changes for point-in-time queries and audit trails.

Configure the mode in HtapConfig before starting the engine. It cannot be changed at runtime without dropping and recreating the OLAP tables.

use yoda::{HtapConfig, SyncMode};

let config = HtapConfig {
    sync_mode: SyncMode::Temporal,
    ..HtapConfig::default()
};

SyncMode::Destructive (default)

The OLAP table is a current-state mirror of the OLTP table.

OLTP operation	OLAP effect
INSERT	Row inserted into OLAP.
UPDATE	Existing OLAP row overwritten in place.
DELETE	Row removed from OLAP.

This is the simplest mode and uses the least storage. It is ideal when you only need up-to-date analytics and have no requirement to query historical states.

SyncMode::Temporal (SCD Type 2)

Every CDC event appends a new row — no row is ever modified or deleted. The OLAP table grows as a time-ordered history, with three metadata columns (_yoda_valid_from, _yoda_valid_to, _yoda_operation) tracking version validity.

A point-in-time query reads the table as it existed at timestamp T:

SELECT *
FROM   users
WHERE  _yoda_valid_from <= T
  AND  (_yoda_valid_to IS NULL OR _yoda_valid_to > T)

For the full mechanics — how UPDATE and DELETE events translate to close-and-append SQL pairs, atomicity guarantees per backend, the worked schema, current-state and history queries, and a complete CLI walkthrough — see Advanced → Temporal Mode (SCD-2).

Choosing a Mode

Consideration	Destructive	Temporal
Storage growth	Bounded (current rows only)	Unbounded (full history)
Point-in-time queries	No	Yes
Audit / compliance	No	Yes
Query complexity	Simple	Requires _yoda_valid_from/to filter
DuckDB atomicity	N/A	Fully atomic close + insert
DataFusion atomicity	N/A	Best-effort (sequence-number recovery)

Start with Destructive and switch to Temporal only when you have a concrete need for history. Migrating an existing deployment requires recreating the OLAP tables.

Next Steps

• Temporal Mode (SCD-2) — full mechanics, point-in-time queries, atomicity
• Configuration Reference — set sync_mode and related fields
• OLAP Backends — DuckDB vs. DataFusion trade-offs
• Sidecar Mode — use temporal sync with an external Postgres source