Add upgrade notes for change

Author: neilconway

docs/source/library-user-guide/upgrading/53.0.0.md

@@ -440,6 +440,68 @@ let sort_proto = serialize_physical_sort_expr(
 );
 ```
 
+### String/numeric comparison coercion now prefers numeric types
+
+Previously, comparing a numeric column with a string value (e.g.,
+`WHERE int_col > '100'`) coerced both sides to strings and performed a
+lexicographic comparison. This produced incorrect results — for example,
+`325 > '100'` was `false` under string comparison because `'3' < '1'` is
+`false` lexicographically.
+
+DataFusion now coerces the string side to the numeric type in comparison
+contexts (`=`, `<`, `>`, `<=`, `>=`, `<>`, `IN`, `BETWEEN`, `CASE .. WHEN`).
+
+**Who is affected:**
+
+- Queries that compare numeric values with string values
+- Queries that use `IN` lists with mixed string and numeric types
+- Queries that use `CASE expr WHEN` with mixed string and numeric types
+
+**Behavioral changes (old → new):**
+
+| Expression | Old behavior | New behavior |
+|---|---|---|
+| `int_col > '100'` | Lexicographic (incorrect) | Numeric (correct) |
+| `float_col = '5'` | String `'5' != '5.0'` (incorrect) | Numeric `5.0 = 5.0` (correct) |
+| `int_col = 'hello'` | String comparison, always false | Cast error |
+| `str_col IN ('a', 1)` | Coerce to Utf8 | Cast error (`'a'` cannot be cast to Int64) |
+| `float_col IN ('1.0')` | String `'1.0' != '1'` (incorrect) | Numeric `1.0 = 1.0` (correct) |
+| `CASE str_col WHEN 1.0` | Coerce to Utf8 | Coerce to Float64 |
+| `SELECT 1 UNION SELECT 'a'` | Coerce to Utf8 | Coerce to Utf8 (unchanged) |
+
+**Migration guide:**
+
+Most queries will produce more correct results with no changes needed.
+However, queries that relied on the old string-comparison behavior may need
+adjustment:
+
+- **Queries comparing numeric columns with non-numeric strings** (e.g.,
+  `int_col = 'hello'` or `int_col > text_col` where `text_col` contains
+  non-numeric values) will now produce a cast error instead of silently
+  returning no rows.
+- **Mixed-type `IN` lists** (e.g., `str_col IN ('a', 1)`) are now rejected. Use
+  consistent types in the list, or add an explicit `CAST`.
+- **Queries comparing integer columns with decimal strings** (e.g.,
+  `int_col = '99.99'`) will now produce a cast error because `'99.99'`
+  cannot be cast to an integer. Use a float column or adjust the literal.
+
+See [#15161](https://github.com/apache/datafusion/issues/15161) and
+[PR #20426](https://github.com/apache/datafusion/pull/20426) for details.
+
+### `comparison_coercion_numeric` removed, replaced by `comparison_coercion`
+
+The `comparison_coercion_numeric` function has been removed. Its behavior
+(preferring numeric types for string/numeric comparisons) is now the default in
+`comparison_coercion`. A new function, `type_union_coercion`, handles contexts
+where string types are preferred (`UNION`, `CASE THEN/ELSE`, `NVL2`).
+
+**Who is affected:**
+
+- Crates that call `comparison_coercion_numeric` directly
+- Crates that call `comparison_coercion` and relied on its old
+  string-preferring behavior
+- Crates that call `get_coerce_type_for_case_expression`
+
 ### `generate_series` and `range` table functions changed
 
 The `generate_series` and `range` table functions now return an empty set when the interval is invalid, instead of an error.