loom.etl.backends._historify¶

Backend-agnostic SCD Type 2 transform and HistorifyBackend Protocol.

loom.etl.backends._historify.eval_param_expr(expr, params_instance)[source]¶

Walk the ParamExpr attribute path and return the resolved value.

Parameters:

expr (ParamExpr)
params_instance (object)

Return type:

Any

class loom.etl.backends._historify.HistorifyBackend(*args, **kwargs)[source]¶

Bases: Protocol[F]

Backend-specific frame operations used by SCD2Transform.

history_dtype(spec)[source]¶

Return the native dtype for valid_from / valid_to columns.

Parameters:: spec (HistorifySpec)
Return type:: Any

stamp_col(frame, name, value, dtype)[source]¶

Add or overwrite column with literal value.

Parameters:

frame (F)
name (str)
value (Any)
dtype (Any)

Return type:

null_col(frame, name, dtype)[source]¶

Add null column with given dtype.

Parameters:

frame (F)
name (str)
dtype (Any)

Return type:

rename(frame, rename_map)[source]¶

Rename columns according to mapping.

Parameters:

frame (F)
rename_map (dict[str, str])

Return type:

drop(frame, cols)[source]¶

Drop columns.

Parameters:

frame (F)
cols (list[str])

Return type:

dedup_last(frame, subset)[source]¶

Deduplicate keeping last occurrence.

Parameters:

frame (F)
subset (list[str])

Return type:

apply_overwrite_cols(unchanged, incoming, join_key, overwrite)[source]¶

Replace overwrite columns in unchanged rows with values from incoming.

Drops the overwrite columns from unchanged then joins the fresh values from incoming on join_key. The open row is refreshed in-place; no new history row is created.

Parameters:

unchanged (F)
incoming (F)
join_key (list[str])
overwrite (tuple[str, ...])

Return type:

rollback_same_day_run(frame, spec, eff_date, join_key)[source]¶

Undo a previous run on the same eff_date (SNAPSHOT idempotency).

Parameters:

frame (F)
spec (HistorifySpec)
eff_date (Any)
join_key (list[str])

Return type:

build_log_boundaries(frame, spec)[source]¶

Compute valid_from / valid_to from sorted event frame (LOG mode).

Parameters:

frame (F)
spec (HistorifySpec)

Return type:

temporal_conflict_min_date(existing, spec, eff_date)[source]¶

Return min conflicting valid_from or None if no conflict.

Parameters:

existing (F)
spec (HistorifySpec)
eff_date (Any)

Return type:

Any | None

loom.etl.backends._historify.scd2_transform(ops, frame, existing, spec, params_instance)[source]¶

Apply SCD Type 2 logic and return the transformed frame.

Parameters:

ops (HistorifyBackend[F]) – Backend-specific frame operations.
frame (F) – Incoming data frame.
existing (F | None) – Current target frame, or None for first run.
spec (HistorifySpec) – Compiled HistorifySpec.
params_instance (object) – Runtime params for ParamExpr resolution.

Returns:

Transformed frame ready to be written to Delta.

Raises:

HistorifyKeyConflictError – Duplicate entity state vectors.
HistorifyDateCollisionError – Same-date collisions in LOG mode.
HistorifyTemporalConflictError – Future-open records, re-weave off.

Return type:

loom.etl.backends._historify.prev_period_value(eff_date, spec)[source]¶

Return one unit before eff_date (one day or one microsecond).

Parameters:

eff_date (Any)
spec (HistorifySpec)

Return type:

Any

loom.etl.backends._historify.resolve_effective_date(spec, params_instance)[source]¶

Resolve effective date to a scalar (SNAPSHOT) or column name (LOG).

Parameters:

spec (HistorifySpec)
params_instance (object)

Return type:

Any

loom.etl.backends._historify.resolve_track_cols(spec, frame_cols)[source]¶

Return tracked columns — explicit or all non-key, non-history columns.

Parameters:

spec (HistorifySpec)
frame_cols (list[str])

Return type:

tuple[str, …]