Apache DataFusion SQL Query Engine
chore: add `array_remove_*` NULL handling changes to `Upgrade Guide` (#21769)
Oleks Vcfafce4d96ec
diff --git a/docs/source/library-user-guide/upgrading/53.0.0.md b/docs/source/library-user-guide/upgrading/53.0.0.mdindex f572b2a3f7..a619862e2a 100644--- a/docs/source/library-user-guide/upgrading/53.0.0.md+++ b/docs/source/library-user-guide/upgrading/53.0.0.md@@ -507,3 +507,45 @@ Now:+-------+0 row(s) fetched.```++### `array_remove`, `array_remove_n`, `array_remove_all` now return NULL when the element argument is NULL++Previously, calling `array_remove(array, NULL)` would attempt to match and+remove NULL entries from the array, returning the array with NULLs stripped.+Now, passing NULL as the element to remove causes the function to return NULL,+which is consistent with standard SQL NULL propagation semantics.++The same change applies to `array_remove_n` (aliases: `list_remove_n`) and+`array_remove_all` (aliases: `list_remove_all`).++**Who is affected:**++- Queries that call `array_remove`, `array_remove_n`, or `array_remove_all`+ with a NULL element argument (literal or column-derived).++**Behavioral changes:**++| Expression | Old result | New result |+| ---------------------------------------------------- | ----------------- | ---------- |+| `array_remove(make_array(1, NULL, 2), NULL)` | `[1, 2]` | `NULL` |+| `array_remove(make_array(1, NULL, 2, NULL), NULL)` | `[1, 2, NULL]` | `NULL` |+| `array_remove_n(make_array(1, 2, 2, 1, 1), NULL, 2)` | `[1, 2, 2, 1, 1]` | `NULL` |+| `array_remove_all(make_array(1, 2, 2, 1, 1), NULL)` | `[1, 2, 2, 1, 1]` | `NULL` |++**Migration guide:**++If your queries relied on the old behavior to strip NULLs from arrays, use+`array_remove_all` with a non-NULL sentinel or use `array_filter` instead:++```sql+-- Before (removed NULLs from array):+SELECT array_remove(make_array(1, NULL, 2), NULL);+-- Old result: [1, 2]++-- After (returns NULL due to NULL propagation):+SELECT array_remove(make_array(1, NULL, 2), NULL);+-- New result: NULL+```++See [#21011](https://github.com/apache/datafusion/issues/21011) and+[PR #21013](https://github.com/apache/datafusion/pull/21013) for details.