@loradb/lora-node 0.35.1 → 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.
Files changed (57) hide show
  1. package/README.md +5 -0
  2. package/dist/types.d.ts +2 -1
  3. package/dist/types.d.ts.map +1 -1
  4. package/dist/types.js +1 -0
  5. package/dist/types.js.map +1 -1
  6. package/docs/README.md +86 -0
  7. package/docs/concepts/graph-model.md +270 -0
  8. package/docs/concepts/nodes.md +285 -0
  9. package/docs/concepts/properties.md +348 -0
  10. package/docs/concepts/relationships.md +325 -0
  11. package/docs/concepts/result-formats.md +183 -0
  12. package/docs/concepts/schema-free.md +183 -0
  13. package/docs/cookbook.md +1081 -0
  14. package/docs/data-types/lists-and-maps.md +406 -0
  15. package/docs/data-types/overview.md +210 -0
  16. package/docs/data-types/scalars.md +376 -0
  17. package/docs/data-types/spatial.md +291 -0
  18. package/docs/data-types/temporal.md +349 -0
  19. package/docs/data-types/vectors.md +563 -0
  20. package/docs/errors.md +183 -0
  21. package/docs/functions/aggregation.md +372 -0
  22. package/docs/functions/list.md +522 -0
  23. package/docs/functions/map.md +207 -0
  24. package/docs/functions/math.md +421 -0
  25. package/docs/functions/number.md +197 -0
  26. package/docs/functions/overview.md +545 -0
  27. package/docs/functions/spatial.md +384 -0
  28. package/docs/functions/string.md +502 -0
  29. package/docs/functions/temporal.md +590 -0
  30. package/docs/functions/utility.md +137 -0
  31. package/docs/functions/vectors.md +772 -0
  32. package/docs/getting-started/installation.md +204 -0
  33. package/docs/getting-started/node.md +582 -0
  34. package/docs/getting-started/tutorial.md +334 -0
  35. package/docs/index.md +203 -0
  36. package/docs/limitations.md +291 -0
  37. package/docs/performance.md +219 -0
  38. package/docs/queries/aggregation.md +520 -0
  39. package/docs/queries/cheat-sheet.md +302 -0
  40. package/docs/queries/constraints.md +239 -0
  41. package/docs/queries/create.md +331 -0
  42. package/docs/queries/examples.md +453 -0
  43. package/docs/queries/index.md +169 -0
  44. package/docs/queries/indexes.md +538 -0
  45. package/docs/queries/match.md +429 -0
  46. package/docs/queries/ordering.md +359 -0
  47. package/docs/queries/parameters.md +328 -0
  48. package/docs/queries/paths.md +462 -0
  49. package/docs/queries/return-with.md +500 -0
  50. package/docs/queries/set-delete.md +369 -0
  51. package/docs/queries/unwind-merge.md +358 -0
  52. package/docs/queries/where.md +416 -0
  53. package/docs/snapshot.md +545 -0
  54. package/docs/troubleshooting.md +1158 -0
  55. package/docs/wal.md +570 -0
  56. package/docs/why.md +273 -0
  57. 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).