loom-kernel 1.2.1__tar.gz → 1.3.0__tar.gz

{loom_kernel-1.2.1 → loom_kernel-1.3.0}/CHANGELOG.md

@@ -1,3 +1,110 @@
+# 🚀 Release 1.3.0 ([#127](https://github.com/the-reacher-data/loom-py/pull/127)) ([`1fcaa1c`](https://github.com/the-reacher-data/loom-py/commit/1fcaa1ca1520db435d1ba4974284a96a35d2734f))
+
+
+## ✨ Features
+### etl
+- **etl:** update() — matched-only MERGE, the insert-less sibling of upsert<br>
+  > IntoTable(...).update(keys=..., include=/exclude=) issues the upsert
+  > MERGE WITHOUT when_not_matched_insert: source rows whose keys match are
+  > updated, rows without a match are IGNORED — nothing is ever inserted,
+  > by construction. This is the mode for repairing columns of an existing
+  > table (re-attribution), where an insert would be a bug that until now
+  > had to be guarded with row-count assertions outside the write.
+  > UpdateSpec keeps neutral public field names (keys/exclude/include) and
+  > exposes upsert_* read-only aliases that satisfy the shared _UpsertLike
+  > merge protocol, so the MERGE plan, the partition pre-filter and the
+  > compile-time key/exclude/include validators are reused untouched;
+  > compilation errors name update() instead of upsert(). A new compile
+  > guard rejects an include= fully absorbed by keys/partition_cols — in
+  > update() that write is a guaranteed no-op. At write time there is no
+  > creation path: a missing table is an error, never a create. Implemented
+  > in the Polars and Spark writers by factoring the shared merge up to
+  > when_matched_update.
+  > Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+  > Claude-Session: https://claude.ai/code/session_01U65Md2FMcEaEgpZCKkYqGL
+
+- **etl:** IntoHistory joins the declared target union of ETLStep<br>
+  > It worked at runtime but mypy rejected the assignment on every step
+  > with a historified target. One line in the ClassVar (mirrored in
+  > ClientStep, which redeclares the same union — pyright requires the
+  > override to be identical) and a test pinning union membership via
+  > get_type_hints.
+  > Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+  > Claude-Session: https://claude.ai/code/session_01U65Md2FMcEaEgpZCKkYqGL
+
+- **etl:** param exprs and path templates accept read-only params properties<br>
+  > A computed @property (e.g. partition_day) resolves at runtime through
+  > the same getattr chain as a struct field, but compile-time validation
+  > only looked at msgspec.structs.fields — forcing the filter down to
+  > runtime and losing the declarative pushdown. Now names resolving to a
+  > property on the CLASS (public properties only — no methods, no private
+  > names) count as known fields, symmetrically in validate_param_exprs and
+  > validate_file_path_templates; an unknown name still fails with the same
+  > error.
+  > Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+  > Claude-Session: https://claude.ai/code/session_01U65Md2FMcEaEgpZCKkYqGL
+
+
+### prefect
+- **prefect:** "year" chunk in backfill_flow for overhead-dominated backfills<br>
+  > When backfill cost is dominated by per-chunk overhead rather than data
+  > volume (real case: 135 monthly chunks x ~2.5 min ≈ 6 h for a fact that
+  > resolves each chunk in seconds), a multi-year window drops to a handful
+  > of calendar-year chunks. Same algebra as month: floor to January 1,
+  > calendar-year advance, %Y label for correlation/run ids, and start_from
+  > resume intact. The docstrings call out that both documented window
+  > edges — the start floor and the finalize window_end pin — operate at
+  > year scale at this granularity.
+  > Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+  > Claude-Session: https://claude.ai/code/session_01U65Md2FMcEaEgpZCKkYqGL
+  > --------
+  > Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
+
+
+
+
+
+
+
+
+
+
+# 🚀 Release 1.2.2 ([#124](https://github.com/the-reacher-data/loom-py/pull/124)) ([`ced8b6a`](https://github.com/the-reacher-data/loom-py/commit/ced8b6ab8bba62b7d34e57ad334d26f29af1e0c2))
+
+
+## ✨ Features
+### etl
+- **etl:** replace_matching, el alias que dice lo que replace_partitions hace<br>
+  > replace_partitions nunca ha exigido particion fisica: colecta los VALORES de
+  > las columnas presentes en el frame y emite un replaceWhere de Delta sobre
+  > ellos. El nombre ha causado confusion real en tablas de model sin particionar
+  > (facts por dia, colas por fecha de snapshot). replace_matching(*cols) es el
+  > mismo spec con la semantica en el nombre; replace_partitions queda intacto
+  > (en uso) y su docstring apunta al alias.
+  > Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+
+- **etl:** replace_physical_partitions — el replace de particiones DE VERDAD<br>
+  > La familia queda completa y cada nombre dice lo que hace:
+  > replace_matching(*cols): replaceWhere por los VALORES del frame; tablas sin
+  > particionar (facts por dia, colas por fecha).
+  > replace_physical_partitions(*cols): mismo predicado MAS un check en escritura
+  > contra el metadata Delta — si la tabla no esta fisicamente particionada por
+  > esas columnas, rechaza en alto en vez de degradar a rewrite por filas. Un
+  > backend sin metadata de particiones (spark hoy) tambien rechaza, no adivina.
+  > replace_partitions(*cols): intacto (en uso), su docstring dirige a los dos.
+  > Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
+  > --------
+  > Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
+
+
+
+
+
+
+
+
+
+
 # 🚀 Release 1.2.1 ([#122](https://github.com/the-reacher-data/loom-py/pull/122)) ([`797f134`](https://github.com/the-reacher-data/loom-py/commit/797f134ebf64378a0af54f89d8fbac10e033553c))
 
 

{loom_kernel-1.2.1 → loom_kernel-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 1.2.1
+Version: 1.3.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Typing :: Typed

{loom_kernel-1.2.1 → loom_kernel-1.3.0}/docs/etl/pipelines.md

@@ -269,6 +269,21 @@ target = IntoTable("events.orders").upsert(
 `partition_cols` is optional but strongly recommended — without it every MERGE
 forces a full table scan.
 
+### update
+
+Matched-only MERGE. Rows whose keys match are updated; source rows without a
+match are ignored — nothing is ever inserted. Use it when an insert would be
+a bug, e.g. repairing columns of an existing table. The target table must
+already exist: a missing table is a write error, not a create.
+
+```python
+target = IntoTable("events.orders").update(
+    keys=("order_id",),
+    partition_cols=("year", "month"),  # strongly recommended for large tables
+    include=("status",),               # only these columns are updated
+)
+```
+
 ---
 
 ## Running only selected stages

{loom_kernel-1.2.1 → loom_kernel-1.3.0}/docs/getting-started/etl.md

@@ -71,6 +71,7 @@ Every `IntoTable` target declares exactly one write mode by chaining a method.
 | `replace_partition` | Overwrite a single known partition | `IntoTable("staging.orders").replace_partition(year=params.run_date.year)` |
 | `replace_where` | Overwrite rows matching a predicate | `IntoTable("staging.orders").replace_where(col("date") == params.run_date)` |
 | `upsert` | Merge on key columns | `IntoTable("staging.orders").upsert(keys=("order_id",))` |
+| `update` | Update matching rows only — never inserts | `IntoTable("staging.orders").update(keys=("order_id",))` |
 
 See the [ETL pipelines guide](../etl/pipelines.md) for the full write-mode reference.
 

{loom_kernel-1.2.1 → loom_kernel-1.3.0}/docs/guides/etl.md

@@ -269,6 +269,21 @@ target = IntoTable("events.orders").upsert(
 `partition_cols` is optional but strongly recommended — without it every MERGE
 forces a full table scan.
 
+### update
+
+Matched-only MERGE. Rows whose keys match are updated; source rows without a
+match are ignored — nothing is ever inserted. Use it when an insert would be
+a bug, e.g. repairing columns of an existing table. The target table must
+already exist: a missing table is a write error, not a create.
+
+```python
+target = IntoTable("events.orders").update(
+    keys=("order_id",),
+    partition_cols=("year", "month"),  # strongly recommended for large tables
+    include=("status",),               # only these columns are updated
+)
+```
+
 ### historify
 
 For SCD Type 2 history tracking use `IntoHistory` instead of `IntoTable`.
@@ -283,6 +298,7 @@ SNAPSHOT vs LOG mode, and configuration of boundary columns.
 | `IntoTable(...).replace_partition(...)` | Replace known partition | Above |
 | `IntoTable(...).replace_where(...)` | Predicate-based overwrite | Above |
 | `IntoTable(...).upsert(...)` | Merge by key | Above |
+| `IntoTable(...).update(...)` | Update matches only, never insert | Above |
 | `IntoHistory(...)` | SCD Type 2 historification | [Below](#historify) |
 
 ---

{loom_kernel-1.2.1 → loom_kernel-1.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "loom-kernel"
-version = "1.2.1"
+version = "1.3.0"
 description = "Loom Python project"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -278,7 +278,7 @@ markers = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "1.2.1"
+version = "1.3.0"
 tag_format = "v$version"
 version_files = [
     "pyproject.toml:project.version",

{loom_kernel-1.2.1 → loom_kernel-1.3.0}/src/loom/etl/backends/_merge.py

@@ -35,7 +35,7 @@ TARGET_ALIAS = "t"
 
 
 class _UpsertLike(Protocol):
-    """Structural protocol satisfied by both ``UpsertSpec`` and ``UpsertOp``.
+    """Structural protocol satisfied by the merge specs (``UpsertSpec``, ``UpdateSpec``).
 
     Declared as read-only properties so frozen dataclasses satisfy it.
     """
@@ -214,7 +214,7 @@ def _build_merge_plan(
 
 
 def _warn_no_partition_cols(table_ref: str) -> None:
-    """Emit a WARNING when no partition columns are declared on an UPSERT.
+    """Emit a WARNING when no partition columns are declared on a MERGE write.
 
     Without partition columns the MERGE predicate cannot prune Delta log files,
     forcing a full table scan.  For large tables this can be very expensive.
@@ -223,7 +223,7 @@ def _warn_no_partition_cols(table_ref: str) -> None:
         table_ref: Logical table reference string (for the log message).
     """
     _log.warning(
-        "upsert table=%s has no partition_cols — full table scan on MERGE. "
+        "merge table=%s has no partition_cols — full table scan on MERGE. "
         "Declare partition_cols= to enable Delta log file pruning.",
         table_ref,
     )
@@ -239,7 +239,7 @@ def _log_partition_combos(
         combos:    List of partition combination dicts collected from the frame.
         table_ref: Logical table reference string.
     """
-    _log.debug("upsert table=%s partition_combos=%d", table_ref, len(combos))
+    _log.debug("merge table=%s partition_combos=%d", table_ref, len(combos))
 
 
 def _build_partition_predicate(

{loom_kernel-1.2.1 → loom_kernel-1.3.0}/src/loom/etl/backends/_write_policy.py

@@ -23,6 +23,7 @@ from loom.etl.declarative.target import (
     TargetSpec,
     TempFanInSpec,
     TempSpec,
+    UpdateSpec,
     UpsertSpec,
 )
 from loom.etl.declarative.target._history import HistorifyRepairReport, HistorifySpec
@@ -158,6 +159,7 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
             ReplacePartitionsSpec: self._dispatch_replace_partitions,
             ReplaceWhereSpec: self._dispatch_replace_where,
             UpsertSpec: self._dispatch_upsert,
+            UpdateSpec: self._dispatch_update,
             HistorifySpec: self._dispatch_historify,
         }
 
@@ -213,6 +215,16 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
     ) -> None:
         self._do_upsert(frame, target, cast(UpsertSpec, spec), streaming)
 
+    def _dispatch_update(
+        self,
+        frame: InputFrameT,
+        target: ResolvedTarget,
+        spec: TargetSpec,
+        _params_instance: Any,
+        streaming: bool,
+    ) -> None:
+        self._do_update(frame, target, cast(UpdateSpec, spec), streaming)
+
     def _dispatch_historify(
         self,
         frame: InputFrameT,
@@ -294,6 +306,8 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
                 partition_cols=spec.partition_cols,
             )
             return
+        if spec.require_physical:
+            self._require_physical_partitions(target, spec.partition_cols)
         aligned = self._align(frame, existing, spec.schema_mode)
         materialized = self._materialize_checked(aligned, target, streaming)
         self._replace_partitions(
@@ -303,6 +317,30 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
             schema_mode=spec.schema_mode,
         )
 
+    def _physical_partition_columns(self, target: ResolvedTarget) -> tuple[str, ...] | None:
+        """The table's physical partition columns, or ``None`` when the backend
+        cannot tell — which makes ``require_physical`` refuse rather than guess."""
+        return None
+
+    def _require_physical_partitions(
+        self, target: ResolvedTarget, partition_cols: tuple[str, ...]
+    ) -> None:
+        physical = self._physical_partition_columns(target)
+        if physical is None:
+            raise ValueError(
+                f"replace_physical_partitions: backend cannot verify the physical "
+                f"partitioning of {target}. Use replace_partitions/replace_matching, "
+                f"or a backend that exposes partition metadata."
+            )
+        missing = [col for col in partition_cols if col not in physical]
+        if missing:
+            raise ValueError(
+                f"replace_physical_partitions: table {target} is partitioned by "
+                f"{list(physical) or 'nothing'} but the write asked for {list(partition_cols)} "
+                f"(missing: {missing}). For value-based replacement on these columns "
+                f"use replace_matching instead."
+            )
+
     def _do_replace_where(
         self,
         frame: InputFrameT,
@@ -364,6 +402,36 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
             existing_schema=existing,
         )
 
+    def _do_update(
+        self,
+        frame: InputFrameT,
+        target: ResolvedTarget,
+        spec: UpdateSpec,
+        streaming: bool,
+    ) -> None:
+        """Update policy: require exists → align+write.
+
+        Unlike :meth:`_do_upsert` there is no creation path: an update-only
+        MERGE against a missing table has nothing to update, and creating the
+        table from the frame would insert every row — exactly what this mode
+        exists to prevent.
+        """
+        existing = self._physical_schema(target)
+        if existing is None:
+            raise SchemaNotFoundError(
+                f"Destination table does not exist: {target}. "
+                "update() never inserts, so it cannot create the table — "
+                "create it first with append/replace/upsert."
+            )
+        aligned = self._align(frame, existing, spec.schema_mode)
+        materialized = self._materialize_checked(aligned, target, streaming=False)
+        self._update(
+            materialized,
+            target,
+            spec=spec,
+            existing_schema=existing,
+        )
+
     def _do_historify(
         self,
         frame: InputFrameT,
@@ -564,6 +632,17 @@ class _WritePolicy(TargetWriter, Generic[InputFrameT, WriteFrameT, PhysicalSchem
     ) -> None:
         """Upsert/merge into existing table."""
 
+    @abstractmethod
+    def _update(
+        self,
+        frame: WriteFrameT,
+        target: ResolvedTarget,
+        *,
+        spec: UpdateSpec,
+        existing_schema: PhysicalSchemaT,
+    ) -> None:
+        """Matched-only merge into existing table — never inserts."""
+
     @abstractmethod
     def _historify(
         self,

{loom_kernel-1.2.1 → loom_kernel-1.3.0}/src/loom/etl/backends/polars/_writer.py

@@ -7,6 +7,7 @@ from typing import Any, Literal
 
 import polars as pl
 from deltalake import CommitProperties, DeltaTable, WriterProperties, write_deltalake
+from deltalake.table import TableMerger
 
 from loom.core.logger import get_logger
 from loom.etl.backends._historify._transform import scd2_transform
@@ -16,6 +17,7 @@ from loom.etl.backends._merge import (
     _build_merge_plan,
     _build_partition_predicate,
     _log_partition_combos,
+    _MergePlan,
     _warn_no_partition_cols,
 )
 from loom.etl.backends._path_template import resolve_file_uri
@@ -33,6 +35,7 @@ from loom.etl.declarative.target._history import HistorifyRepairReport, Historif
 from loom.etl.declarative.target._table import (
     AppendSpec,
     ReplacePartitionsSpec,
+    UpdateSpec,
     UpsertSpec,
 )
 from loom.etl.lineage._records import LineageRecord, WriteContext, get_lineage_schema
@@ -405,6 +408,11 @@ class PolarsTargetWriter(_WritePolicy[pl.LazyFrame, pl.DataFrame, PolarsPhysical
         )
         _log_write_commit("replace", location)
 
+    def _physical_partition_columns(self, target: ResolvedTarget) -> tuple[str, ...] | None:
+        location = self._as_path_target(target).location
+        dt = DeltaTable(location.uri, storage_options=location.storage_options or {})
+        return tuple(dt.metadata().partition_columns)
+
     def _replace_partitions(
         self,
         frame: pl.DataFrame,
@@ -485,9 +493,55 @@ class PolarsTargetWriter(_WritePolicy[pl.LazyFrame, pl.DataFrame, PolarsPhysical
         spec: UpsertSpec,
         existing_schema: PolarsPhysicalSchema,
     ) -> None:
-        """Merge frame into target using Delta MERGE."""
-        path_target = self._as_path_target(target)
+        """Merge frame into target using Delta MERGE (update + insert)."""
         _ = existing_schema
+        merger, plan, location = self._matched_update_merger(frame, target, spec, mode="upsert")
+        merger.when_not_matched_insert(updates=plan.insert_values).execute()
+        _log_write_commit("upsert", location)
+
+    def _update(
+        self,
+        frame: pl.DataFrame,
+        target: ResolvedTarget,
+        *,
+        spec: UpdateSpec,
+        existing_schema: PolarsPhysicalSchema,
+    ) -> None:
+        """Merge frame into target using a matched-only Delta MERGE.
+
+        No ``when_not_matched_insert`` clause is emitted, so unmatched source
+        rows are ignored and the MERGE inserts zero rows by construction.
+        """
+        _ = existing_schema
+        merger, _plan, location = self._matched_update_merger(frame, target, spec, mode="update")
+        merger.execute()
+        _log_write_commit("update", location)
+
+    def _matched_update_merger(
+        self,
+        frame: pl.DataFrame,
+        target: ResolvedTarget,
+        spec: UpsertSpec | UpdateSpec,
+        *,
+        mode: str,
+    ) -> tuple[TableMerger, _MergePlan, TableLocation]:
+        """Build the Delta MERGE up to the shared ``when_matched_update`` clause.
+
+        Both :meth:`_upsert` and :meth:`_update` start from the same merge:
+        partition-combo pre-filter, ON predicate, and the matched-update
+        column map.  The caller chains its remaining clauses and executes.
+
+        Args:
+            frame:  Materialised source frame.
+            target: Resolved path target.
+            spec:   Upsert or update spec (identical merge fields).
+            mode:   Write-mode label for logging.
+
+        Returns:
+            Tuple of the prepared merger, the merge plan, and the target
+            location (for commit logging).
+        """
+        path_target = self._as_path_target(target)
         location = path_target.location
 
         # Collect partition combinations for pre-filter
@@ -507,24 +561,19 @@ class PolarsTargetWriter(_WritePolicy[pl.LazyFrame, pl.DataFrame, PolarsPhysical
 
         dt = DeltaTable(location.uri, storage_options=location.storage_options or {})
         _log_write_start(
-            "upsert",
+            mode,
             location,
             frame,
             partition_cols=spec.partition_cols,
             predicate=merge_plan.predicate,
         )
-        (
-            dt.merge(
-                source=frame,
-                predicate=merge_plan.predicate,
-                source_alias=SOURCE_ALIAS,
-                target_alias=TARGET_ALIAS,
-            )
-            .when_matched_update(updates=merge_plan.update_set)
-            .when_not_matched_insert(updates=merge_plan.insert_values)
-            .execute()
-        )
-        _log_write_commit("upsert", location)
+        merger = dt.merge(
+            source=frame,
+            predicate=merge_plan.predicate,
+            source_alias=SOURCE_ALIAS,
+            target_alias=TARGET_ALIAS,
+        ).when_matched_update(updates=merge_plan.update_set)
+        return merger, merge_plan, location
 
     def _read_existing_data(
         self,

{loom_kernel-1.2.1 → loom_kernel-1.3.0}/src/loom/etl/backends/spark/_writer.py

@@ -7,7 +7,7 @@ import logging
 from collections.abc import Callable, Sequence
 from typing import Any, cast
 
-from delta.tables import DeltaTable
+from delta.tables import DeltaMergeBuilder, DeltaTable
 from pyspark.errors.exceptions.base import AnalysisException
 from pyspark.sql import DataFrame, SparkSession
 from pyspark.sql import types as T
@@ -20,6 +20,7 @@ from loom.etl.backends._merge import (
     TARGET_ALIAS,
     _build_merge_plan,
     _log_partition_combos,
+    _MergePlan,
     _warn_no_partition_cols,
 )
 from loom.etl.backends._path_template import resolve_file_uri
@@ -37,7 +38,7 @@ from loom.etl.declarative._write_options import (
 from loom.etl.declarative.target import SchemaMode
 from loom.etl.declarative.target._file import FileSpec
 from loom.etl.declarative.target._history import HistorifyRepairReport, HistorifySpec
-from loom.etl.declarative.target._table import AppendSpec, UpsertSpec
+from loom.etl.declarative.target._table import AppendSpec, UpdateSpec, UpsertSpec
 from loom.etl.lineage._records import LineageRecord, get_lineage_schema
 from loom.etl.storage._config import MissingTablePolicy
 from loom.etl.storage._file_locator import FileLocator
@@ -250,7 +251,40 @@ class SparkTargetWriter(_WritePolicy[DataFrame, DataFrame, SparkPhysicalSchema])
     ) -> None:
         """Merge frame into target using Delta MERGE (delta-spark)."""
         _ = existing_schema
+        merger, plan = self._matched_update_merger(frame, target, spec)
+        merger.whenNotMatchedInsert(
+            values=cast(dict[str, str | Column], plan.insert_values)
+        ).execute()
 
+    def _update(
+        self,
+        frame: DataFrame,
+        target: ResolvedTarget,
+        *,
+        spec: UpdateSpec,
+        existing_schema: SparkPhysicalSchema,
+    ) -> None:
+        """Merge frame into target using a matched-only Delta MERGE.
+
+        No ``whenNotMatchedInsert`` clause is emitted, so unmatched source
+        rows are ignored and the MERGE inserts zero rows by construction.
+        """
+        _ = existing_schema
+        merger, _plan = self._matched_update_merger(frame, target, spec)
+        merger.execute()
+
+    def _matched_update_merger(
+        self,
+        frame: DataFrame,
+        target: ResolvedTarget,
+        spec: UpsertSpec | UpdateSpec,
+    ) -> tuple[DeltaMergeBuilder, _MergePlan]:
+        """Build the Delta MERGE up to the shared ``whenMatchedUpdate`` clause.
+
+        Both :meth:`_upsert` and :meth:`_update` start from the same merge:
+        partition-combo pre-filter, ON predicate, and the matched-update
+        column map.  The caller chains its remaining clauses and executes.
+        """
         if isinstance(target, CatalogTarget):
             dt = DeltaTable.forName(self._spark, target.catalog_ref.ref)
         else:
@@ -265,13 +299,12 @@ class SparkTargetWriter(_WritePolicy[DataFrame, DataFrame, SparkPhysicalSchema])
             source_alias=SOURCE_ALIAS,
         )
 
-        (
+        merger = (
             dt.alias(TARGET_ALIAS)
             .merge(frame.alias(SOURCE_ALIAS), merge_plan.predicate)
             .whenMatchedUpdate(set=cast(dict[str, str | Column], merge_plan.update_set))
-            .whenNotMatchedInsert(values=cast(dict[str, str | Column], merge_plan.insert_values))
-            .execute()
         )
+        return merger, merge_plan
 
     def _read_existing_data(
         self,

{loom_kernel-1.2.1 → loom_kernel-1.3.0}/src/loom/etl/compiler/_errors.py

@@ -28,6 +28,7 @@ class ETLErrorCode(StrEnum):
     UPSERT_NO_KEYS = "UPSERT_NO_KEYS"
     UPSERT_EXCLUDE_INCLUDE_CONFLICT = "UPSERT_EXCLUDE_INCLUDE_CONFLICT"
     UPSERT_KEY_IN_EXCLUDE = "UPSERT_KEY_IN_EXCLUDE"
+    UPDATE_EMPTY_UPDATE_SET = "UPDATE_EMPTY_UPDATE_SET"
     MISSING_GENERIC_PARAM = "MISSING_GENERIC_PARAM"
     MISSING_TARGET = "MISSING_TARGET"
     INVALID_TARGET_TYPE = "INVALID_TARGET_TYPE"
@@ -171,38 +172,56 @@ class ETLCompilationError(Exception):
         )
 
     @classmethod
-    def upsert_no_keys(cls, step: type) -> ETLCompilationError:
-        """upsert() declared with no key columns."""
+    def upsert_no_keys(cls, step: type, method: str = "upsert") -> ETLCompilationError:
+        """upsert()/update() declared with no key columns."""
         return cls(
             code=ETLErrorCode.UPSERT_NO_KEYS,
             component=step.__qualname__,
             message=(
-                f"{step.__qualname__}: upsert() requires at least one key column. "
+                f"{step.__qualname__}: {method}() requires at least one key column. "
                 'Pass keys=("col",) to identify rows uniquely.'
             ),
         )
 
     @classmethod
-    def upsert_exclude_include_conflict(cls, step: type) -> ETLCompilationError:
-        """upsert() has both exclude= and include= set."""
+    def upsert_exclude_include_conflict(
+        cls, step: type, method: str = "upsert"
+    ) -> ETLCompilationError:
+        """upsert()/update() has both exclude= and include= set."""
         return cls(
             code=ETLErrorCode.UPSERT_EXCLUDE_INCLUDE_CONFLICT,
             component=step.__qualname__,
             message=(
-                f"{step.__qualname__}: upsert() exclude= and include= are mutually exclusive. "
+                f"{step.__qualname__}: {method}() exclude= and include= are mutually exclusive. "
                 "Use one or the other, not both."
             ),
         )
 
     @classmethod
-    def upsert_key_in_exclude(cls, step: type, overlap: frozenset[str]) -> ETLCompilationError:
-        """upsert() exclude= contains columns that are also upsert keys."""
+    def upsert_key_in_exclude(
+        cls, step: type, overlap: frozenset[str], method: str = "upsert"
+    ) -> ETLCompilationError:
+        """upsert()/update() exclude= contains columns that are also merge keys."""
         return cls(
             code=ETLErrorCode.UPSERT_KEY_IN_EXCLUDE,
             component=step.__qualname__,
             message=(
-                f"{step.__qualname__}: upsert() exclude={sorted(overlap)} overlaps with "
-                "upsert keys — key columns are always excluded from UPDATE SET."
+                f"{step.__qualname__}: {method}() exclude={sorted(overlap)} overlaps with "
+                f"{method} keys — key columns are always excluded from UPDATE SET."
+            ),
+        )
+
+    @classmethod
+    def update_empty_update_set(cls, step: type, include: tuple[str, ...]) -> ETLCompilationError:
+        """update() include= is fully absorbed by keys and partition columns."""
+        return cls(
+            code=ETLErrorCode.UPDATE_EMPTY_UPDATE_SET,
+            component=step.__qualname__,
+            message=(
+                f"{step.__qualname__}: update() include={sorted(include)} is fully covered "
+                "by keys/partition_cols, which are always excluded from UPDATE SET — "
+                "the MERGE would update no columns and the write would be a guaranteed "
+                "no-op. List at least one non-key, non-partition column."
             ),
         )