diff --git a/pages/advanced-algorithms/available-algorithms/collections.mdx b/pages/advanced-algorithms/available-algorithms/collections.mdx index 339874be6..b2d6449da 100644 --- a/pages/advanced-algorithms/available-algorithms/collections.mdx +++ b/pages/advanced-algorithms/available-algorithms/collections.mdx @@ -39,6 +39,44 @@ uncomparable.
Only `Numeric` data types can be used in `sum()` and `avg()` functions, so only `Int` and `Double` data types are allowed. +### Handling `NULL` values + +Passing `NULL` as a whole list (or scalar) argument no longer raises an +argument-validation error. Each function returns a defined result: + +| Function | Result when a list argument is `NULL` | +| --- | --- | +| `sum()`, `sum_longs()`, `avg()`, `min()`, `max()`, `to_set()`, `pairs()` | `null` | +| `union()`, `union_all()` | the other list; `null` when both are `NULL` | +| `remove_all()` | `null` when the first list is `NULL`; the first list when the second is `NULL` | +| `intersection()`, `sort()`, `flatten()` | empty list `[]` | +| `contains()`, `contains_all()`, `contains_sorted()` | `false` | +| `frequencies_as_map()` | empty map `{}` | +| `split()`, `partition()` | no rows | + +`NULL` elements inside a list are handled per function: + +- `min()` and `max()` skip `NULL` elements; a list containing only `NULL` values returns `null`. +- `contains()` and `contains_all()` never match a `NULL` search value (`NULL = NULL` is not true), so searching for `NULL` returns `false`. +- `split()` treats a `NULL` delimiter as matching nothing and returns the whole list as a single part; `NULL` list elements are kept. +- `frequencies_as_map()` counts `NULL` elements under the `"NO_VALUE"` key. +- `flatten()`, `pairs()`, `to_set()`, `union()`, `union_all()`, `remove_all()` and `intersection()` keep `NULL` elements as ordinary values. +- `sum()`, `sum_longs()`, `avg()`, `sort()` and `contains_sorted()` still reject a list that contains a `NULL` element; `contains_sorted()` also rejects a `NULL` search value, and `partition()` still rejects a `NULL` size. + +For example, a `NULL` argument returns the defined result instead of erroring: + +```cypher +RETURN collections.sum(null) AS sum, collections.sort(null) AS sorted; +``` + +```plaintext ++----------------------------+ +| sum | sorted | ++----------------------------+ +| null | [] | ++----------------------------+ +``` + ### `sort()` Sorts the elements of an input list if they are of the same data type. For the input