Skip to content
Draft
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions pages/advanced-algorithms/available-algorithms/collections.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,44 @@ uncomparable. <br />
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
Expand Down