Skip to content

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.md
index 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.