From 40a0a750e4d2c27134e52c694b25029e6849ca14 Mon Sep 17 00:00:00 2001 From: comphead Date: Tue, 21 Apr 2026 12:52:29 -0700 Subject: [PATCH 1/2] chore: add `array_remove_*` NULL handling changes to `Upgrade Guide` --- .../library-user-guide/upgrading/53.0.0.md | 46 +++++++++++++++++++ 1 file changed, 46 insertions(+) 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 f572b2a3f7cc9..7feb61cb44aca 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,49 @@ 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 + +-- To strip NULLs, use array_filter: +SELECT array_filter(make_array(1, NULL, 2), x -> x IS NOT NULL); +-- Result: [1, 2] +``` + +See [#21011](https://github.com/apache/datafusion/issues/21011) and +[PR #21013](https://github.com/apache/datafusion/pull/21013) for details. From c647634e5958ea65390e18eefc7e381a300d9ba2 Mon Sep 17 00:00:00 2001 From: comphead Date: Tue, 21 Apr 2026 13:09:47 -0700 Subject: [PATCH 2/2] chore: add `array_remove_*` NULL handling changes to `Upgrade Guide` --- docs/source/library-user-guide/upgrading/53.0.0.md | 4 ---- 1 file changed, 4 deletions(-) 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 7feb61cb44aca..a619862e2a153 100644 --- a/docs/source/library-user-guide/upgrading/53.0.0.md +++ b/docs/source/library-user-guide/upgrading/53.0.0.md @@ -545,10 +545,6 @@ SELECT array_remove(make_array(1, NULL, 2), NULL); -- After (returns NULL due to NULL propagation): SELECT array_remove(make_array(1, NULL, 2), NULL); -- New result: NULL - --- To strip NULLs, use array_filter: -SELECT array_filter(make_array(1, NULL, 2), x -> x IS NOT NULL); --- Result: [1, 2] ``` See [#21011](https://github.com/apache/datafusion/issues/21011) and