DeltaTable.merge(): does a type mismatch between source and target raise an error?

[loic-bellinger]

Context

The documentation states:

write_deltalake will raise ValueError if the schema of the data passed to it differs from the existing table's schema.

https://delta-io.github.io/delta-rs/usage/writing/

Observed behavior with DeltaTable.merge()

When merging data whose column type differs from the target table schema (e.g. Int64 source into a String target column), no error is raised. The data is silently cast to match the target schema (seems similiar to that issue).

Minimal repro :

import polars as pl
from deltalake import write_deltalake, DeltaTable

# 1. Create table with 'value' as String
write_deltalake(
    "/tmp/t",
    pl.DataFrame({"id": [1, 2], "value": ["a", "b"]}),
    mode="overwrite",
)

# 2. Merge with 'value' as Int64 - different type, no error raised
(
    DeltaTable("/tmp/t")
    .merge(
        pl.DataFrame({"id": [2, 3], "value": [99, 100]}),  # Int64 source
        predicate="source.id = target.id",
        source_alias="source",
        target_alias="target",
        # error_on_type_mismatch=True  ← default, but has no effect here
    )
    .when_matched_update_all()
    .when_not_matched_insert_all()
    .execute()
)

# 3. Schema unchanged (String), Int64 silently coerced → "99", "100"
print(DeltaTable("/tmp/t").schema())  # value: string
print(pl.read_delta("/tmp/t"))
# shape: (3, 2)
# ┌─────┬───────┐
# │ id  ┆ value │
# │ --- ┆ ---   │
# │ i64 ┆ str   │  ← still String
# ╞═════╪═══════╡
# │ 1   ┆ a     │
# │ 2   ┆ 99    │  ← Int64 silently cast to String
# │ 3   ┆ 100   │  ← idem
# └─────┴───────┘

Note: error_on_type_mismatch=True is the default in .merge() but does not prevent this silent coercion.

Additional finding

An error is raised only when the cast is impossible (e.g. "abc" into an Int64 column):

Exception: Cast error: Cannot cast string 'abc' to value of Int64 type

The exception type is Exception wrapping a cast error — not ValueError.

Question

Is this intentional? Does "schema differs" refer only to structural differences (column added/removed), not type changes on existing columns?

If type coercion is by design, it would be helpful to:

1. Clarify the docs (currently implies any schema difference raises an error)
2. Document error_on_type_mismatch more precisely - the name suggests it should prevent this, but it doesn't for castable types

Silent type coercion can corrupt data without any signal to the user.

[ethan-tyler]

opened issue #4448