diff --git a/docs/source/library-user-guide/upgrading/53.0.0.md b/docs/source/library-user-guide/upgrading/53.0.0.md index f572b2a3f7cc..a619862e2a15 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.