@loradb/lora-node 0.36.0 → 0.36.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -0
- package/docs/README.md +86 -0
- package/docs/concepts/graph-model.md +270 -0
- package/docs/concepts/nodes.md +285 -0
- package/docs/concepts/properties.md +348 -0
- package/docs/concepts/relationships.md +325 -0
- package/docs/concepts/result-formats.md +183 -0
- package/docs/concepts/schema-free.md +183 -0
- package/docs/cookbook.md +1081 -0
- package/docs/data-types/lists-and-maps.md +406 -0
- package/docs/data-types/overview.md +210 -0
- package/docs/data-types/scalars.md +376 -0
- package/docs/data-types/spatial.md +291 -0
- package/docs/data-types/temporal.md +349 -0
- package/docs/data-types/vectors.md +563 -0
- package/docs/errors.md +183 -0
- package/docs/functions/aggregation.md +372 -0
- package/docs/functions/list.md +522 -0
- package/docs/functions/map.md +207 -0
- package/docs/functions/math.md +421 -0
- package/docs/functions/number.md +197 -0
- package/docs/functions/overview.md +545 -0
- package/docs/functions/spatial.md +384 -0
- package/docs/functions/string.md +502 -0
- package/docs/functions/temporal.md +590 -0
- package/docs/functions/utility.md +137 -0
- package/docs/functions/vectors.md +772 -0
- package/docs/getting-started/installation.md +204 -0
- package/docs/getting-started/node.md +582 -0
- package/docs/getting-started/tutorial.md +334 -0
- package/docs/index.md +203 -0
- package/docs/limitations.md +291 -0
- package/docs/performance.md +219 -0
- package/docs/queries/aggregation.md +520 -0
- package/docs/queries/cheat-sheet.md +302 -0
- package/docs/queries/constraints.md +239 -0
- package/docs/queries/create.md +331 -0
- package/docs/queries/examples.md +453 -0
- package/docs/queries/index.md +169 -0
- package/docs/queries/indexes.md +538 -0
- package/docs/queries/match.md +429 -0
- package/docs/queries/ordering.md +359 -0
- package/docs/queries/parameters.md +328 -0
- package/docs/queries/paths.md +462 -0
- package/docs/queries/return-with.md +500 -0
- package/docs/queries/set-delete.md +369 -0
- package/docs/queries/unwind-merge.md +358 -0
- package/docs/queries/where.md +416 -0
- package/docs/snapshot.md +545 -0
- package/docs/troubleshooting.md +1158 -0
- package/docs/wal.md +570 -0
- package/docs/why.md +273 -0
- package/package.json +13 -14
|
@@ -0,0 +1,522 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "List Functions"
|
|
3
|
+
description: "List functions in LoraDB — value.size, list.first, list.rest, list.last, list.range, value.reverse, reduce, and friends — with 0-based indexing, negative indices, and null-propagation semantics."
|
|
4
|
+
online: "https://loradb.com/docs/functions/list"
|
|
5
|
+
package: "@loradb/lora-node@0.36.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# List Functions
|
|
9
|
+
|
|
10
|
+
[Lists](../data-types/lists-and-maps.md#lists) are first-class values.
|
|
11
|
+
Indexing is 0-based and supports negative indices counted from the end.
|
|
12
|
+
List functions generally return `null` on `null` input.
|
|
13
|
+
|
|
14
|
+
## Overview
|
|
15
|
+
|
|
16
|
+
| Goal | Function / Syntax |
|
|
17
|
+
|---|---|
|
|
18
|
+
| Size | [`value.size(list)`](#size--head--tail--last) |
|
|
19
|
+
| First, rest, last | [`list.first`, `list.rest`, `list.last`](#size--head--tail--last) |
|
|
20
|
+
| Safe index / slice | [`list.at(list, i)`, `list.slice(list, from[, to])`](#function-indexing-and-slicing) |
|
|
21
|
+
| Reverse | [`value.reverse(list)`](#reverse) |
|
|
22
|
+
| Range | [`list.range(start, end[, step])`](#range) |
|
|
23
|
+
| Take / drop | [`list.take`, `list.drop`, `list.take_last`, `list.drop_last`](#selection-and-reshaping) |
|
|
24
|
+
| Append / prepend / concat | [`list.append`, `list.prepend`, `list.concat`](#functional-concatenation) |
|
|
25
|
+
| Deduplicate | [`list.unique(list)`](#deduplicate-and-set-operations) |
|
|
26
|
+
| Per-list numeric summaries | [`list.sum`, `list.avg`, `list.median`](#numeric-summaries) |
|
|
27
|
+
| Fold | [`reduce(acc, x IN list | …)`](#reduce) |
|
|
28
|
+
| Index / slice | [`list[i]`, `list[a..b]`](#indexing-and-slicing) |
|
|
29
|
+
| Concat | [`list + list`, `list + x`, `x + list`](#concatenation) |
|
|
30
|
+
| Filter / map | [`[x IN list WHERE … | …]`](#list-comprehension) |
|
|
31
|
+
| Attach related entities | [Pattern comprehension](#pattern-comprehension) |
|
|
32
|
+
| Quantify | [`all`, `any`, `none`, `single`](#predicates-in-where) |
|
|
33
|
+
| Collect rows | [`collect(expr)`](./aggregation.md#collect) |
|
|
34
|
+
| Unwind rows | [`UNWIND list AS row`](../queries/unwind-merge.md#unwind) |
|
|
35
|
+
|
|
36
|
+
## value.size / list.first / list.rest / list.last {#size--head--tail--last}
|
|
37
|
+
|
|
38
|
+
| Function | Behaviour |
|
|
39
|
+
|---|---|
|
|
40
|
+
| `value.size(list)` | Number of elements; `null` → `null` |
|
|
41
|
+
| `list.first(list)` | First element; empty list → `null` |
|
|
42
|
+
| `list.rest(list)` | All but first; empty list → `null` |
|
|
43
|
+
| `list.last(list)` | Last element; empty list → `null` |
|
|
44
|
+
|
|
45
|
+
```cypher
|
|
46
|
+
RETURN value.size([1, 2, 3]); // 3
|
|
47
|
+
RETURN list.first([1, 2, 3]); // 1
|
|
48
|
+
RETURN list.rest([1, 2, 3]); // [2, 3]
|
|
49
|
+
RETURN list.last([1, 2, 3]); // 3
|
|
50
|
+
RETURN list.first([]); // null
|
|
51
|
+
RETURN value.size([]) // 0
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`value.size` also works on strings — see
|
|
55
|
+
[`String Functions → size`](./string.md#stringlength--valuesize).
|
|
56
|
+
|
|
57
|
+
## reverse
|
|
58
|
+
|
|
59
|
+
Works on lists and strings.
|
|
60
|
+
|
|
61
|
+
```cypher
|
|
62
|
+
RETURN value.reverse([1, 2, 3]); // [3, 2, 1]
|
|
63
|
+
RETURN value.reverse('abc') // 'cba'
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## range
|
|
67
|
+
|
|
68
|
+
`list.range(start, end[, step])` — inclusive, integers only.
|
|
69
|
+
|
|
70
|
+
```cypher
|
|
71
|
+
RETURN list.range(1, 5); // [1, 2, 3, 4, 5]
|
|
72
|
+
RETURN list.range(0, 10, 2); // [0, 2, 4, 6, 8, 10]
|
|
73
|
+
RETURN list.range(10, 1, -1); // [10, 9, 8, …, 1]
|
|
74
|
+
RETURN list.range(1, 5, 0) // null (zero step)
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Common uses
|
|
78
|
+
|
|
79
|
+
```cypher
|
|
80
|
+
// Pagination helper: generate page numbers
|
|
81
|
+
RETURN list.range(1, toInteger(math.ceil($total / $size))) AS pages
|
|
82
|
+
|
|
83
|
+
;// Simple synthetic data
|
|
84
|
+
UNWIND list.range(1, 100) AS i
|
|
85
|
+
CREATE (:Point {id: i, x: math.random() * 100, y: math.random() * 100})
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Selection and Reshaping
|
|
89
|
+
|
|
90
|
+
These functions transform one list value inside a row. They do not
|
|
91
|
+
change row cardinality; use `UNWIND` when you want one output row per
|
|
92
|
+
element.
|
|
93
|
+
|
|
94
|
+
| Function | Behaviour |
|
|
95
|
+
|---|---|
|
|
96
|
+
| `list.take(xs, n)` | First `n` items; negative or zero `n` returns `[]` |
|
|
97
|
+
| `list.drop(xs, n)` | Everything after the first `n` items; negative or zero `n` returns the original list |
|
|
98
|
+
| `list.take_last(xs, n)` | Last `n` items; negative or zero `n` returns `[]` |
|
|
99
|
+
| `list.drop_last(xs, n)` | Everything except the last `n` items; negative or zero `n` returns the original list |
|
|
100
|
+
| `list.flatten(xs[, depth])` | Flattens nested lists to the given depth; default `1` |
|
|
101
|
+
| `list.compact(xs)` | Removes `null` elements |
|
|
102
|
+
| `list.chunks(xs, size)` | Consecutive fixed-size chunks; the last chunk may be shorter |
|
|
103
|
+
| `list.windows(xs, size[, step])` | Sliding fixed-size windows |
|
|
104
|
+
| `list.zip(a, b)` | Pairs elements until the shorter list is exhausted |
|
|
105
|
+
| `list.append(xs, value)` | Returns a new list with `value` added at the end |
|
|
106
|
+
| `list.prepend(xs, value)` | Returns a new list with `value` added at the beginning |
|
|
107
|
+
| `list.concat(a, b, ...)` | Concatenates two or more lists |
|
|
108
|
+
|
|
109
|
+
```cypher
|
|
110
|
+
RETURN list.take([1, 2, 3, 4], 2); // [1, 2]
|
|
111
|
+
RETURN list.drop([1, 2, 3, 4], 2); // [3, 4]
|
|
112
|
+
RETURN list.take_last([1, 2, 3, 4], 2); // [3, 4]
|
|
113
|
+
RETURN list.drop_last([1, 2, 3, 4], 1); // [1, 2, 3]
|
|
114
|
+
RETURN list.flatten([[1, 2], [3, [4]]], 2); // [1, 2, 3, 4]
|
|
115
|
+
RETURN list.chunks([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
|
|
116
|
+
RETURN list.windows([1, 2, 3, 4], 2); // [[1, 2], [2, 3], [3, 4]]
|
|
117
|
+
RETURN list.zip(['a', 'b'], [1, 2, 3]); // [['a', 1], ['b', 2]]
|
|
118
|
+
RETURN list.append(['a', 'b'], 'c'); // ['a', 'b', 'c']
|
|
119
|
+
RETURN list.prepend(['b', 'c'], 'a'); // ['a', 'b', 'c']
|
|
120
|
+
RETURN list.concat([1, 2], [3], [4, 5]) // [1, 2, 3, 4, 5]
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
Use `list.sample(xs[, n])` or `list.shuffle(xs)` for lightweight random
|
|
124
|
+
sampling. They are not cryptographically secure and are intended for
|
|
125
|
+
exploration, demos, and approximate picks.
|
|
126
|
+
|
|
127
|
+
## reduce
|
|
128
|
+
|
|
129
|
+
Fold over a list, carrying an accumulator.
|
|
130
|
+
|
|
131
|
+
```cypher
|
|
132
|
+
RETURN reduce(total = 0, x IN [1, 2, 3, 4] | total + x); // 10
|
|
133
|
+
RETURN reduce(pairs = [], x IN [1, 2, 3] | pairs + [x * 2]) // [2, 4, 6]
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### Word frequency
|
|
137
|
+
|
|
138
|
+
```cypher
|
|
139
|
+
UNWIND ['red', 'red', 'blue', 'green'] AS word
|
|
140
|
+
RETURN word, count(*) AS n
|
|
141
|
+
ORDER BY n DESC
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`UNWIND` turns each list item into a row. The aggregate groups by
|
|
145
|
+
`word`, so repeated values collapse into counts without needing dynamic
|
|
146
|
+
map keys.
|
|
147
|
+
|
|
148
|
+
### Nested / layered lists
|
|
149
|
+
|
|
150
|
+
```cypher
|
|
151
|
+
// Flatten a list-of-lists
|
|
152
|
+
RETURN reduce(out = [], xs IN [[1, 2], [3, 4], [5]] | out + xs)
|
|
153
|
+
// [1, 2, 3, 4, 5]
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
`reduce` has no short-circuit — the whole list is visited even if the
|
|
157
|
+
accumulator could stop early. Use
|
|
158
|
+
[`any` / `all`](#predicates-in-where) for short-circuit boolean
|
|
159
|
+
questions.
|
|
160
|
+
|
|
161
|
+
## Indexing and slicing
|
|
162
|
+
|
|
163
|
+
```cypher
|
|
164
|
+
RETURN [10, 20, 30][0]; // 10
|
|
165
|
+
RETURN [10, 20, 30][-1]; // 30
|
|
166
|
+
RETURN [10, 20, 30][5]; // null (out of range)
|
|
167
|
+
|
|
168
|
+
RETURN [1, 2, 3, 4, 5][1..3]; // [2, 3] (end-exclusive)
|
|
169
|
+
RETURN [1, 2, 3, 4, 5][..2]; // [1, 2]
|
|
170
|
+
RETURN [1, 2, 3, 4, 5][3..]; // [4, 5]
|
|
171
|
+
RETURN [1, 2, 3, 4, 5][-2..] // [4, 5]
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## Function Indexing And Slicing
|
|
175
|
+
|
|
176
|
+
Use `list.at(list, index)` and `list.slice(list, from[, to])` when a
|
|
177
|
+
query builder needs regular function calls instead of postfix syntax.
|
|
178
|
+
Both use the same 0-based, negative-from-end convention as list
|
|
179
|
+
indexing.
|
|
180
|
+
|
|
181
|
+
```cypher
|
|
182
|
+
RETURN list.at([10, 20, 30], 1); // 20
|
|
183
|
+
RETURN list.at([10, 20, 30], -1); // 30
|
|
184
|
+
RETURN list.at([10, 20, 30], 99); // null
|
|
185
|
+
|
|
186
|
+
RETURN list.slice([10, 20, 30, 40], 1, 3); // [20, 30]
|
|
187
|
+
RETURN list.slice([10, 20, 30, 40], -3, -1); // [20, 30]
|
|
188
|
+
RETURN list.slice([10, 20, 30], 2, 1) // []
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
## Numeric Summaries
|
|
192
|
+
|
|
193
|
+
The `list.*` summary helpers work inside a single row. They skip
|
|
194
|
+
`null` values and return `null` if a non-numeric value appears where a
|
|
195
|
+
number is required.
|
|
196
|
+
|
|
197
|
+
| Function | Behaviour |
|
|
198
|
+
|---|---|
|
|
199
|
+
| `list.sum(list)` | Sum of numeric items; empty/all-null list returns `0` |
|
|
200
|
+
| `list.avg(list)` | Average of numeric items; empty/all-null list returns `null` |
|
|
201
|
+
| `list.min(list)` / `list.max(list)` | Smallest/largest comparable value |
|
|
202
|
+
| `list.product(list)` | Product of numeric items; empty/all-null list returns `1` |
|
|
203
|
+
| `list.stdev(list)` | Sample standard deviation; fewer than two values returns `null` |
|
|
204
|
+
| `list.median(list)` | Median numeric value as a float |
|
|
205
|
+
|
|
206
|
+
```cypher
|
|
207
|
+
RETURN list.sum([1, 2, 3]); // 6
|
|
208
|
+
RETURN list.avg([1, 2, null, 5]); // 2.6666…
|
|
209
|
+
RETURN list.median([1, 10, 20]); // 10.0
|
|
210
|
+
RETURN list.product([2, 3, 4]) // 24
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
### Slicing recipes
|
|
214
|
+
|
|
215
|
+
```cypher
|
|
216
|
+
// Top 3
|
|
217
|
+
RETURN collect(x)[..3]
|
|
218
|
+
|
|
219
|
+
;// Last 3
|
|
220
|
+
RETURN collect(x)[-3..]
|
|
221
|
+
|
|
222
|
+
;// Second-to-fifth
|
|
223
|
+
RETURN collect(x)[1..5]
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
## Concatenation
|
|
227
|
+
|
|
228
|
+
```cypher
|
|
229
|
+
RETURN [1, 2] + [3, 4]; // [1, 2, 3, 4]
|
|
230
|
+
RETURN 0 + [1, 2]; // [0, 1, 2]
|
|
231
|
+
RETURN [1, 2] + 3 // [1, 2, 3]
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
## Functional Concatenation
|
|
235
|
+
|
|
236
|
+
Use the function forms when generated queries or nested expressions are
|
|
237
|
+
easier to build with regular calls than with `+`.
|
|
238
|
+
|
|
239
|
+
```cypher
|
|
240
|
+
RETURN list.concat([1, 2], [3], [4, 5]); // [1, 2, 3, 4, 5]
|
|
241
|
+
RETURN list.append([1, 2], 3); // [1, 2, 3]
|
|
242
|
+
RETURN list.prepend([2, 3], 1) // [1, 2, 3]
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
`list.append` and `list.prepend` can add any value, including `null`.
|
|
246
|
+
`list.concat` requires every argument to be a list; a non-list argument
|
|
247
|
+
returns `null`.
|
|
248
|
+
|
|
249
|
+
## List comprehension
|
|
250
|
+
|
|
251
|
+
```cypher
|
|
252
|
+
// Filter
|
|
253
|
+
RETURN [x IN [1, 2, 3, 4] WHERE x > 2] // [3, 4]
|
|
254
|
+
|
|
255
|
+
;// Map
|
|
256
|
+
RETURN [x IN [1, 2, 3] | x * 10] // [10, 20, 30]
|
|
257
|
+
|
|
258
|
+
;// Filter + map
|
|
259
|
+
RETURN [x IN [1, 2, 3, 4] WHERE x > 2 | x * 10] // [30, 40]
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
### On node properties
|
|
263
|
+
|
|
264
|
+
```cypher
|
|
265
|
+
MATCH (u:User)
|
|
266
|
+
RETURN u.name,
|
|
267
|
+
[t IN u.tags WHERE value.size(t) > 3] AS long_tags
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
### Nested comprehension
|
|
271
|
+
|
|
272
|
+
```cypher
|
|
273
|
+
UNWIND [[1, 2], [3, 4], [5, 6]] AS pair
|
|
274
|
+
RETURN [x IN pair WHERE x % 2 = 0 | x * 10]
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
## Pattern comprehension
|
|
278
|
+
|
|
279
|
+
Bind a pattern and collect one value per match — inline.
|
|
280
|
+
|
|
281
|
+
```cypher
|
|
282
|
+
MATCH (p:Person)
|
|
283
|
+
RETURN p.name,
|
|
284
|
+
[(p)-[:KNOWS]->(f) | f.name] AS friends
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
With a filter:
|
|
288
|
+
|
|
289
|
+
```cypher
|
|
290
|
+
MATCH (p:Person)
|
|
291
|
+
RETURN p.name,
|
|
292
|
+
[(p)-[:WROTE]->(post:Post) WHERE post.published | post.title] AS posts
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
Returns a list per matched `p` — ideal when you'd otherwise add a new
|
|
296
|
+
`MATCH` stage and an aggregation just to assemble "each owner's
|
|
297
|
+
items".
|
|
298
|
+
|
|
299
|
+
A pattern comprehension whose start node is not bound by the outer row
|
|
300
|
+
runs its pattern once per row. Put the lookup key in an inline property
|
|
301
|
+
map, as in `[(v:Person {subject: $s}) WHERE v.verified | v.name]`
|
|
302
|
+
(the key is `subject`), and LoraDB seeks it through an index like
|
|
303
|
+
`MATCH` does, rather than scanning the label for every row. See
|
|
304
|
+
[Performance → Query shape notes](../performance.md#unbound-start-nodes-in-pattern-subqueries).
|
|
305
|
+
|
|
306
|
+
### Take top-N inline
|
|
307
|
+
|
|
308
|
+
```cypher
|
|
309
|
+
MATCH (u:User)
|
|
310
|
+
RETURN u.name,
|
|
311
|
+
[(u)-[:WROTE]->(p) | p.title][..3] AS recent_titles
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
### Pattern comprehension vs OPTIONAL MATCH
|
|
315
|
+
|
|
316
|
+
| Want | Use |
|
|
317
|
+
|---|---|
|
|
318
|
+
| A list per outer row, even if empty | Pattern comprehension |
|
|
319
|
+
| A row per match, with nulls for no-match | `OPTIONAL MATCH` |
|
|
320
|
+
| Existence only, no values | [`EXISTS { … }`](../queries/where.md#pattern-existence) |
|
|
321
|
+
|
|
322
|
+
## Predicates (in [`WHERE`](../queries/where.md))
|
|
323
|
+
|
|
324
|
+
These are part of `WHERE` but operate over lists — included here as a
|
|
325
|
+
cross-reference.
|
|
326
|
+
|
|
327
|
+
| Predicate | Description |
|
|
328
|
+
|---|---|
|
|
329
|
+
| `all(x IN list WHERE pred)` | `true` if `pred` holds for every element |
|
|
330
|
+
| `any(x IN list WHERE pred)` | `true` if `pred` holds for at least one |
|
|
331
|
+
| `none(x IN list WHERE pred)` | `true` if `pred` holds for none |
|
|
332
|
+
| `single(x IN list WHERE pred)` | `true` if `pred` holds for exactly one |
|
|
333
|
+
|
|
334
|
+
```cypher
|
|
335
|
+
MATCH (n)
|
|
336
|
+
WHERE all(x IN n.scores WHERE x >= 0)
|
|
337
|
+
RETURN n;
|
|
338
|
+
|
|
339
|
+
MATCH (n)
|
|
340
|
+
WHERE any(x IN n.tags WHERE x = 'featured')
|
|
341
|
+
RETURN n;
|
|
342
|
+
|
|
343
|
+
MATCH (n)
|
|
344
|
+
WHERE single(x IN n.roles WHERE x = 'owner')
|
|
345
|
+
RETURN n
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
### Predicates on paths
|
|
349
|
+
|
|
350
|
+
`path.nodes(p)` and `path.edges(p)` are lists, so path predicates work
|
|
351
|
+
too:
|
|
352
|
+
|
|
353
|
+
```cypher
|
|
354
|
+
MATCH p = (a)-[:FOLLOWS*1..3]->(b)
|
|
355
|
+
WHERE all(r IN path.edges(p) WHERE r.active)
|
|
356
|
+
RETURN p
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
See [Paths](../queries/paths.md#path-functions).
|
|
360
|
+
|
|
361
|
+
## Common patterns
|
|
362
|
+
|
|
363
|
+
### Deduplicate And Set Operations
|
|
364
|
+
|
|
365
|
+
Use `list.unique(list)` to keep the first occurrence of each value
|
|
366
|
+
inside one row. A list of integers, such as node ids from `id(n)`,
|
|
367
|
+
dedupes in linear time; other values are compared pair by pair. Use set-style helpers when comparing two lists.
|
|
368
|
+
|
|
369
|
+
```cypher
|
|
370
|
+
RETURN list.unique([1, 2, 2, 3, 3, 3]); // [1, 2, 3]
|
|
371
|
+
RETURN list.union([1, 2], [2, 3]); // [1, 2, 3]
|
|
372
|
+
RETURN list.intersect([1, 2, 3], [2, 3, 4]); // [2, 3]
|
|
373
|
+
RETURN list.diff([1, 2, 3], [2]) // [1, 3]
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
### Sort a list
|
|
377
|
+
|
|
378
|
+
Use `list.sort(list[, 'desc'])` for scalar lists in a single row. For
|
|
379
|
+
row-level ordering, sort rows before collecting.
|
|
380
|
+
|
|
381
|
+
```cypher
|
|
382
|
+
RETURN list.sort([3, 1, 4, 1, 5, 9, 2, 6])
|
|
383
|
+
// [1, 1, 2, 3, 4, 5, 6, 9]
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
### Zip two lists
|
|
387
|
+
|
|
388
|
+
```cypher
|
|
389
|
+
RETURN list.zip(['a', 'b', 'c'], [1, 2, 3])
|
|
390
|
+
// [['a', 1], ['b', 2], ['c', 3]]
|
|
391
|
+
```
|
|
392
|
+
|
|
393
|
+
### Reduce to a single value
|
|
394
|
+
|
|
395
|
+
```cypher
|
|
396
|
+
WITH [{k: 'a', v: 1}, {k: 'b', v: 2}] AS kvs
|
|
397
|
+
RETURN reduce(total = 0, kv IN kvs | total + kv.v) AS total
|
|
398
|
+
// 3
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
### Running totals
|
|
402
|
+
|
|
403
|
+
```cypher
|
|
404
|
+
WITH [10, 20, 30, 40] AS xs
|
|
405
|
+
RETURN reduce(
|
|
406
|
+
acc = {total: 0, running: []},
|
|
407
|
+
x IN xs |
|
|
408
|
+
{
|
|
409
|
+
total: acc.total + x,
|
|
410
|
+
running: acc.running + [acc.total + x]
|
|
411
|
+
}
|
|
412
|
+
).running AS running_totals
|
|
413
|
+
// [10, 30, 60, 100]
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
The accumulator is a map with two fields: `total` keeps the running
|
|
417
|
+
sum between steps, `running` appends the new total on each step.
|
|
418
|
+
The trailing `.running` picks that second field off the final map
|
|
419
|
+
so the caller gets the sequence of totals, not the map wrapper.
|
|
420
|
+
`reduce` has no short-circuit, so the full list is always visited —
|
|
421
|
+
use it when you genuinely need every step.
|
|
422
|
+
|
|
423
|
+
### Min-by on objects
|
|
424
|
+
|
|
425
|
+
`min()` is an aggregate — for "pick the list element with the
|
|
426
|
+
smallest key" within a single row, use `reduce`:
|
|
427
|
+
|
|
428
|
+
```cypher
|
|
429
|
+
WITH [{name: 'a', score: 9},
|
|
430
|
+
{name: 'b', score: 3},
|
|
431
|
+
{name: 'c', score: 7}] AS rows
|
|
432
|
+
RETURN reduce(
|
|
433
|
+
best = rows[0],
|
|
434
|
+
r IN list.rest(rows) |
|
|
435
|
+
CASE WHEN r.score < best.score THEN r ELSE best END
|
|
436
|
+
) AS winner
|
|
437
|
+
// {name: 'b', score: 3}
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
Start with the first element as `best`, walk `list.rest(rows)`, and on
|
|
441
|
+
each step keep whichever of `best` vs. `r` has the smaller `score`.
|
|
442
|
+
The [`CASE`](../queries/return-with.md#case-expressions) expression
|
|
443
|
+
returns a whole map — the same shape as `best` — so the accumulator
|
|
444
|
+
type is stable. Swap `<` for `>` to turn this into a max-by.
|
|
445
|
+
|
|
446
|
+
### Bucket counts
|
|
447
|
+
|
|
448
|
+
```cypher
|
|
449
|
+
WITH [1, 7, 12, 3, 45, 9, 22] AS xs
|
|
450
|
+
RETURN reduce(
|
|
451
|
+
buckets = {small: 0, medium: 0, large: 0},
|
|
452
|
+
x IN xs |
|
|
453
|
+
CASE
|
|
454
|
+
WHEN x < 10 THEN buckets + {small: buckets.small + 1}
|
|
455
|
+
WHEN x < 30 THEN buckets + {medium: buckets.medium + 1}
|
|
456
|
+
ELSE buckets + {large: buckets.large + 1}
|
|
457
|
+
END
|
|
458
|
+
) AS histogram
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
### Slice the first N of each group
|
|
462
|
+
|
|
463
|
+
```cypher
|
|
464
|
+
MATCH (u:User)-[:WROTE]->(p:Post)
|
|
465
|
+
WITH u, p ORDER BY p.published_at DESC
|
|
466
|
+
WITH u, collect(p)[..3] AS recent_three
|
|
467
|
+
RETURN u.name, [p IN recent_three | p.title]
|
|
468
|
+
```
|
|
469
|
+
|
|
470
|
+
## Edge cases
|
|
471
|
+
|
|
472
|
+
### Out-of-range index
|
|
473
|
+
|
|
474
|
+
```cypher
|
|
475
|
+
RETURN [1, 2, 3][99]; // null
|
|
476
|
+
RETURN [1, 2, 3][-99] // null
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
### Slice with reversed bounds
|
|
480
|
+
|
|
481
|
+
```cypher
|
|
482
|
+
RETURN [1, 2, 3, 4][3..1] // [] (empty, not null, not an error)
|
|
483
|
+
```
|
|
484
|
+
|
|
485
|
+
### Operations on null lists
|
|
486
|
+
|
|
487
|
+
Every list function returns `null` on a `null` input, including `value.size`.
|
|
488
|
+
|
|
489
|
+
```cypher
|
|
490
|
+
RETURN value.size(null), list.first(null), list.rest(null) // null, null, null
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
### Heterogeneous lists
|
|
494
|
+
|
|
495
|
+
Nothing enforces element-type uniformity.
|
|
496
|
+
|
|
497
|
+
```cypher
|
|
498
|
+
RETURN [1, 'two', true, null]
|
|
499
|
+
```
|
|
500
|
+
|
|
501
|
+
Use a [`type.of`](./overview.md#type-conversion-and-checking) check in
|
|
502
|
+
`all(… WHERE …)` if you need a guarantee.
|
|
503
|
+
|
|
504
|
+
## Limitations
|
|
505
|
+
|
|
506
|
+
- List element types are not enforced — `[1, 'two', true]` is a
|
|
507
|
+
perfectly valid list. Use
|
|
508
|
+
`all(x IN list WHERE type.of(x) = 'INTEGER')` if you need
|
|
509
|
+
homogeneity.
|
|
510
|
+
- `reduce` has no short-circuit — the whole list is visited even if a
|
|
511
|
+
condition could stop it early.
|
|
512
|
+
- `list.sort` only sorts directly comparable scalar values. For maps,
|
|
513
|
+
nodes, or custom sort keys, sort rows with `ORDER BY` before
|
|
514
|
+
collecting.
|
|
515
|
+
|
|
516
|
+
## See also
|
|
517
|
+
|
|
518
|
+
- [**Lists & Maps**](../data-types/lists-and-maps.md) — the data-type side.
|
|
519
|
+
- [**Aggregation → collect**](./aggregation.md#collect) — produce lists from rows.
|
|
520
|
+
- [**UNWIND**](../queries/unwind-merge.md#unwind) — lists back into rows.
|
|
521
|
+
- [**Paths**](../queries/paths.md) — `path.nodes()` / `path.edges()` produce lists.
|
|
522
|
+
- [**WHERE → list predicates**](../queries/where.md#list-predicates).
|