@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,520 @@
1
+ ---
2
+ title: "Aggregating Query Results"
3
+ description: "How aggregation works as a clause in LoraDB — implicit GROUP BY from non-aggregated columns, HAVING-style filtering via WITH, and distinct aggregation."
4
+ online: "https://loradb.com/docs/queries/aggregation"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # Aggregating Query Results
9
+
10
+ Aggregations collapse input rows into fewer rows. Non-aggregated
11
+ columns in the same [`RETURN`](./return-with.md) or
12
+ [`WITH`](./return-with.md#with) act as an **implicit group-by** —
13
+ Cypher has no explicit `GROUP BY` keyword.
14
+
15
+ > This page covers clause-level semantics. For each function's exact
16
+ > behaviour (empty input, null handling, return type) see
17
+ > [Aggregation Functions](../functions/aggregation.md).
18
+
19
+ ## Overview
20
+
21
+ | Goal | Clause |
22
+ |---|---|
23
+ | Count rows | `count(*)` |
24
+ | Count non-nulls | `count(expr)` |
25
+ | Sum a property | `sum(expr)` |
26
+ | Mean | `avg(expr)` |
27
+ | Extremes | `min(expr)`, `max(expr)` |
28
+ | Collect into a list | `collect(expr)` |
29
+ | Distinct values | `collect(DISTINCT expr)` |
30
+ | Standard deviation | `stdev(expr)`, `stdevp(expr)` |
31
+ | Percentiles | `percentileCont(expr, p)`, `percentileDisc(expr, p)` |
32
+ | Group by | Any non-aggregated column in the same `RETURN` |
33
+ | HAVING-style filter | [`WITH … WHERE`](./return-with.md#having-style-filtering-with) |
34
+
35
+ ## A five-step walkthrough
36
+
37
+ Rather than list functions first, let's build up an aggregation query
38
+ in stages. Assume a graph seeded with:
39
+
40
+ ```cypher
41
+ UNWIND [
42
+ {region: 'EU', amount: 50, status: 'paid'},
43
+ {region: 'EU', amount: 75, status: 'paid'},
44
+ {region: 'EU', amount: 20, status: 'cancelled'},
45
+ {region: 'US', amount: 200, status: 'paid'},
46
+ {region: 'US', amount: 120, status: 'paid'},
47
+ {region: 'APAC', amount: 90, status: 'paid'}
48
+ ] AS row
49
+ CREATE (:Order {region: row.region, amount: row.amount, status: row.status})
50
+ ```
51
+
52
+ ### 1. Count
53
+
54
+ Start with the simplest aggregate. One row, one column.
55
+
56
+ ```cypher
57
+ MATCH (o:Order)
58
+ RETURN count(*) AS orders
59
+ // orders: 6
60
+ ```
61
+
62
+ ### 2. Group by region
63
+
64
+ Add a non-aggregated column to group on. Now one row per region.
65
+
66
+ ```cypher
67
+ MATCH (o:Order)
68
+ RETURN o.region AS region, count(*) AS orders
69
+ // EU: 3, US: 2, APAC: 1
70
+ ```
71
+
72
+ ### 3. Add a second aggregate
73
+
74
+ Every aggregate operates on the same group. Mix as many as you like in
75
+ one `RETURN`.
76
+
77
+ ```cypher
78
+ MATCH (o:Order)
79
+ RETURN o.region AS region,
80
+ count(*) AS orders,
81
+ sum(o.amount) AS revenue,
82
+ avg(o.amount) AS avg_ticket
83
+ ORDER BY revenue DESC
84
+ ```
85
+
86
+ ### 4. Filter before aggregating
87
+
88
+ Filter with [`WHERE`](./where.md) before the `RETURN` — this narrows the
89
+ input rows that reach the aggregate.
90
+
91
+ ```cypher
92
+ MATCH (o:Order)
93
+ WHERE o.status = 'paid'
94
+ RETURN o.region AS region, sum(o.amount) AS paid_revenue
95
+ ORDER BY paid_revenue DESC
96
+ ```
97
+
98
+ ### 5. Filter after aggregating (HAVING-style)
99
+
100
+ Cypher has no `HAVING`. Aggregate into a [`WITH`](./return-with.md#with),
101
+ then filter:
102
+
103
+ ```cypher
104
+ MATCH (o:Order)
105
+ WHERE o.status = 'paid'
106
+ WITH o.region AS region, sum(o.amount) AS paid_revenue
107
+ WHERE paid_revenue > 100
108
+ RETURN region, paid_revenue
109
+ ```
110
+
111
+ > **Why `WITH` not `WHERE` directly?** Aggregates are not permitted
112
+ > inside [`WHERE`](./where.md). `WITH` promotes aggregated values into
113
+ > projected columns so the next `WHERE` can filter on them.
114
+
115
+ You now have the shape of most real aggregation queries: group, aggregate,
116
+ optionally filter. The rest of the page is a reference for every
117
+ aggregate and its edge cases.
118
+
119
+ ## Built-in aggregates
120
+
121
+ | Function | Supports `DISTINCT` | Empty input | Null input | Return type |
122
+ |---|---|---|---|---|
123
+ | `count(*)` | — | `0` | counted as 1 per row | `Int` |
124
+ | `count(expr)` | yes | `0` | skipped | `Int` |
125
+ | `collect(expr)` | yes | `[]` | skipped | `List` |
126
+ | `sum(expr)` | yes | `0` | skipped | `Int` if all-int, else `Float` |
127
+ | `avg(expr)` | yes | `null` | skipped | `Float` |
128
+ | `min(expr)` | yes | `null` | skipped | type of min element |
129
+ | `max(expr)` | yes | `null` | skipped | type of max element |
130
+ | `stdev(expr)` | — | `0.0` | skipped | `Float`, sample (n − 1) |
131
+ | `stdevp(expr)` | — | `0.0` | skipped | `Float`, population (n) |
132
+ | `percentileCont(expr, p)` | — | `null` | skipped | `Float`, linear interpolation |
133
+ | `percentileDisc(expr, p)` | — | `null` | skipped | `Float`, nearest rank |
134
+
135
+ ## count
136
+
137
+ ### Row count
138
+
139
+ ```cypher
140
+ MATCH (n:User)
141
+ RETURN count(*) AS users
142
+ ```
143
+
144
+ `count(*)` counts every input row, including rows where bound variables
145
+ are `null`.
146
+
147
+ ### Non-null count
148
+
149
+ ```cypher
150
+ MATCH (n:User)
151
+ RETURN count(n.email) AS users_with_email
152
+ ```
153
+
154
+ `count(expr)` skips rows where `expr` is `null`.
155
+
156
+ ### Distinct
157
+
158
+ ```cypher
159
+ MATCH (p:Person)
160
+ RETURN count(DISTINCT p.city) AS distinct_cities
161
+ ```
162
+
163
+ ### count(\*) vs count(expr) after OPTIONAL MATCH
164
+
165
+ This distinction matters when a row survives the left-join but has a
166
+ null binding:
167
+
168
+ ```cypher
169
+ MATCH (u:User)
170
+ OPTIONAL MATCH (u)-[:WROTE]->(p:Post)
171
+ RETURN u.name,
172
+ count(*) AS rows, // 1 even for users without posts
173
+ count(p) AS posts, // 0 for users without posts
174
+ count(DISTINCT p) AS unique_posts // same as count(p) when p is 1-1 per row
175
+ ```
176
+
177
+ Use `count(expr)` when you want zeros for empty optional matches; see
178
+ [`OPTIONAL MATCH with aggregation`](./match.md#optional-match-with-aggregation).
179
+
180
+ ### Zero input
181
+
182
+ ```cypher
183
+ MATCH (:LabelThatDoesNotExist)
184
+ RETURN count(*) // 0
185
+ ```
186
+
187
+ An empty match still produces one row from `count(*)` with the value `0`.
188
+
189
+ ## collect
190
+
191
+ `collect` turns rows into a list — useful for attaching one-to-many
192
+ results to each group.
193
+
194
+ ```cypher
195
+ MATCH (p:Person)-[:KNOWS]->(f:Person)
196
+ RETURN p.name AS person, collect(f.name) AS friends
197
+ ```
198
+
199
+ ### Distinct values
200
+
201
+ ```cypher
202
+ MATCH (p:Person)-[:VISITED]->(c:City)
203
+ RETURN p.name, collect(DISTINCT c.name) AS unique_cities
204
+ ```
205
+
206
+ ### Empty input
207
+
208
+ ```cypher
209
+ MATCH (:Never)
210
+ RETURN collect(1) // []
211
+ ```
212
+
213
+ ### Collect skips nulls
214
+
215
+ Like `count(expr)` / `sum` / `avg`, `collect` **skips** `null` values, so
216
+ an unmatched `OPTIONAL MATCH` collects to `[]`. Only a top-level `null`
217
+ is skipped: a list or map that merely contains `null` is a value and is
218
+ kept.
219
+
220
+ ```cypher
221
+ UNWIND [1, null, 2, null, 3] AS x
222
+ RETURN collect(x); // [1, 2, 3]
223
+ RETURN collect(DISTINCT x) // [1, 2, 3]
224
+
225
+ ;UNWIND [[1, null], null, {a: null}] AS x
226
+ RETURN collect(x) // [[1, null], {a: null}]
227
+ ```
228
+
229
+ ## sum, avg
230
+
231
+ ```cypher
232
+ MATCH (o:Order)
233
+ RETURN sum(o.amount) AS revenue,
234
+ avg(o.amount) AS avg_ticket
235
+ ```
236
+
237
+ - `sum` returns an `Int` when every input is an `Int`; otherwise `Float`.
238
+ - `avg` is always `Float`.
239
+ - On empty input `sum` returns `0` and `avg` returns `null` (there is
240
+ nothing to average).
241
+ - Nulls in input are skipped — they don't affect the result.
242
+
243
+ ```cypher
244
+ UNWIND [1, 2, null, 4] AS x
245
+ RETURN sum(x), avg(x) // 7, 2.333…
246
+ ```
247
+
248
+ ## min, max
249
+
250
+ ```cypher
251
+ MATCH (e:Event)
252
+ RETURN min(e.when) AS earliest,
253
+ max(e.when) AS latest
254
+ ```
255
+
256
+ - Works on numbers, strings, and [temporal values](../data-types/temporal.md)
257
+ under each type's native total order.
258
+ - Nulls skipped.
259
+ - Returns `null` on empty input.
260
+
261
+ ```cypher
262
+ UNWIND ['banana', 'apple', 'cherry'] AS s
263
+ RETURN min(s), max(s) // 'apple', 'cherry'
264
+ ```
265
+
266
+ ## Grouping
267
+
268
+ Any non-aggregated column in the same `RETURN` or `WITH` becomes part of
269
+ the implicit group key.
270
+
271
+ ```cypher
272
+ MATCH (o:Order)
273
+ RETURN o.region AS region,
274
+ count(*) AS orders,
275
+ sum(o.amount) AS revenue
276
+ ORDER BY revenue DESC
277
+ ```
278
+
279
+ Equivalent in SQL:
280
+
281
+ ```sql
282
+ SELECT region, COUNT(*), SUM(amount)
283
+ FROM Order
284
+ GROUP BY region
285
+ ORDER BY SUM(amount) DESC;
286
+ ```
287
+
288
+ ### Two-level grouping
289
+
290
+ Every non-aggregated column participates in the key:
291
+
292
+ ```cypher
293
+ MATCH (o:Order)
294
+ RETURN o.region AS region,
295
+ o.status AS status,
296
+ count(*) AS orders
297
+ ORDER BY region, status
298
+ ```
299
+
300
+ ### Grouping by a computed expression
301
+
302
+ The group key can be any expression, not just a property access:
303
+
304
+ ```cypher
305
+ MATCH (p:Person)
306
+ RETURN p.born / 100 * 100 AS century, count(*) AS n
307
+ ORDER BY century
308
+ ```
309
+
310
+ ## HAVING-style filtering
311
+
312
+ Cypher has no `HAVING`. Aggregate in a `WITH`, then filter:
313
+
314
+ ```cypher
315
+ MATCH (p:Person)-[:WORKS_AT]->(c:Company)
316
+ WITH c.name AS company, count(p) AS employees
317
+ WHERE employees > 5
318
+ RETURN company, employees
319
+ ```
320
+
321
+ Aggregates are **not** permitted in `WHERE`. Attempting
322
+ `WHERE count(x) > 5` is a semantic error — always pipe through `WITH`.
323
+
324
+ ## Aggregation after filtering
325
+
326
+ Filter before aggregating:
327
+
328
+ ```cypher
329
+ MATCH (o:Order)
330
+ WHERE o.amount > 100 AND o.status = 'paid'
331
+ RETURN count(*) AS big_paid_orders
332
+ ```
333
+
334
+ ## Duplicates vs DISTINCT
335
+
336
+ The gap between `count(x)` and `count(DISTINCT x)` reveals repeats.
337
+
338
+ ```cypher
339
+ MATCH (p:Person)-[:BOUGHT]->(b:Book)
340
+ RETURN p.name,
341
+ count(b) AS total_purchases,
342
+ count(DISTINCT b) AS distinct_books
343
+ ```
344
+
345
+ ## Multiple aggregates
346
+
347
+ Any number of aggregates may appear in one `RETURN`:
348
+
349
+ ```cypher
350
+ MATCH (r:Review)
351
+ RETURN count(*) AS n,
352
+ avg(r.stars) AS mean,
353
+ stdev(r.stars) AS sd,
354
+ percentileCont(r.stars, 0.5) AS median,
355
+ percentileCont(r.stars, 0.95) AS p95,
356
+ min(r.stars) AS worst,
357
+ max(r.stars) AS best
358
+ ```
359
+
360
+ ## percentileCont vs percentileDisc
361
+
362
+ - `percentileCont(expr, p)` — linear interpolation between ordered
363
+ values. Returns a value that may not appear in the input.
364
+ - `percentileDisc(expr, p)` — nearest-rank. Returns an input value.
365
+
366
+ ```cypher
367
+ UNWIND [1, 2, 3, 4, 5] AS x
368
+ RETURN percentileCont(x, 0.5), // 3.0
369
+ percentileDisc(x, 0.5); // 3
370
+
371
+ UNWIND [1, 2, 3, 4] AS x
372
+ RETURN percentileCont(x, 0.5), // 2.5
373
+ percentileDisc(x, 0.5) // 2
374
+ ```
375
+
376
+ Both accept `p ∈ [0, 1]`.
377
+
378
+ ## Pipeline aggregation
379
+
380
+ You can aggregate at one stage and then re-aggregate downstream:
381
+
382
+ ```cypher
383
+ MATCH (u:User)-[:PLACED]->(o:Order)
384
+ WITH u.region AS region, o.amount AS amount
385
+ WITH region, sum(amount) AS revenue
386
+ WITH avg(revenue) AS avg_region_revenue,
387
+ collect({region: region, revenue: revenue}) AS rows
388
+ RETURN avg_region_revenue, rows
389
+ ```
390
+
391
+ ## Common patterns
392
+
393
+ ### Top-N per group
394
+
395
+ ```cypher
396
+ MATCH (u:User)-[:WROTE]->(p:Post)
397
+ WITH u, count(p) AS posts
398
+ ORDER BY posts DESC
399
+ LIMIT 10
400
+ RETURN u.name, posts
401
+ ```
402
+
403
+ ### Collect top-N related
404
+
405
+ ```cypher
406
+ MATCH (u:User)-[:WROTE]->(p:Post)
407
+ WITH u, p ORDER BY p.published_at DESC
408
+ WITH u, collect(p.title)[..3] AS last_three
409
+ RETURN u.name, last_three
410
+ ```
411
+
412
+ ### Rolling window — bucket by day
413
+
414
+ ```cypher
415
+ MATCH (e:Event)
416
+ RETURN temporal.truncate('month', e.at) AS month, count(*) AS events
417
+ ORDER BY month
418
+ ```
419
+
420
+ Uses [`temporal.truncate`](../functions/temporal.md#truncation).
421
+
422
+ ### Average per category, HAVING filter
423
+
424
+ ```cypher
425
+ MATCH (p:Product)
426
+ WITH p.category AS category, avg(p.rating) AS rating
427
+ WHERE rating >= 4.0
428
+ RETURN category, rating
429
+ ORDER BY rating DESC
430
+ ```
431
+
432
+ ### Dedup with DISTINCT inside collect
433
+
434
+ ```cypher
435
+ MATCH (a:Author)-[:WROTE]->(:Book)-[:IN]->(g:Genre)
436
+ RETURN a.name, collect(DISTINCT g.name) AS genres
437
+ ```
438
+
439
+ ### Conditional count (count-if)
440
+
441
+ `count(expr)` skips `null`. Combined with
442
+ [`CASE`](./return-with.md#case-expressions) whose `ELSE` branch is
443
+ implicitly `null`, this gives you a clean "count rows matching X":
444
+
445
+ ```cypher
446
+ MATCH (o:Order)
447
+ RETURN count(*) AS total,
448
+ count(CASE WHEN o.status = 'paid' THEN 1 END) AS paid,
449
+ count(CASE WHEN o.status = 'cancelled' THEN 1 END) AS cancelled,
450
+ count(CASE WHEN o.amount >= 1000 THEN 1 END) AS large
451
+ ```
452
+
453
+ ### Percent share per group
454
+
455
+ ```cypher
456
+ MATCH (o:Order)
457
+ WITH o.region AS region, sum(o.amount) AS revenue
458
+ WITH collect({region: region, revenue: revenue}) AS rows,
459
+ sum(revenue) AS total
460
+ UNWIND rows AS r
461
+ RETURN r.region AS region,
462
+ r.revenue AS revenue,
463
+ toFloat(r.revenue) / total AS share
464
+ ORDER BY share DESC
465
+ ```
466
+
467
+ Two-pass aggregate: first compute each region's total, then divide by
468
+ the grand total from the same pipeline.
469
+
470
+ ### Running metrics over time buckets
471
+
472
+ ```cypher
473
+ MATCH (e:Event)
474
+ WHERE e.at >= temporal.now() - 'P1Y'::DURATION
475
+ RETURN temporal.truncate('month', e.at) AS month,
476
+ count(*) AS events,
477
+ count(DISTINCT e.user_id) AS unique_users,
478
+ avg(e.duration_ms) / 1000.0 AS avg_seconds
479
+ ORDER BY month
480
+ ```
481
+
482
+ ### Top contributor per group (pipeline trick)
483
+
484
+ LoraDB has no window functions. Express "top-N per group" as
485
+ aggregate-then-filter:
486
+
487
+ ```cypher
488
+ MATCH (u:User)-[:WROTE]->(p:Post)
489
+ WITH u, p ORDER BY p.views DESC
490
+ WITH u, collect(p)[..1] AS top
491
+ UNWIND top AS best_post
492
+ RETURN u.handle, best_post.title, best_post.views
493
+ ```
494
+
495
+ One row per user with their highest-viewed post. The `collect(…)[..1]`
496
+ slice picks the first element of the sort-ordered `collect`.
497
+
498
+ ## Limitations
499
+
500
+ - **No `GROUP BY` keyword.** Grouping is always implicit on
501
+ non-aggregated columns.
502
+ - **No `HAVING` keyword.** Filter post-aggregate through
503
+ `WITH … WHERE`.
504
+ - **Aggregates rejected in `WHERE`.** Analysis-time error.
505
+ - `stdev`, `stdevp`, `percentileCont`, `percentileDisc` do **not**
506
+ support `DISTINCT`. Use `collect(DISTINCT x)` +
507
+ [`UNWIND`](./unwind-merge.md#unwind) + aggregate if you need percentile
508
+ of distinct values.
509
+
510
+ See [Limitations](../limitations.md#aggregates) for the full list.
511
+
512
+ ## See also
513
+
514
+ - [**Aggregation Functions**](../functions/aggregation.md) — per-function reference.
515
+ - [**RETURN / WITH**](./return-with.md) — projection, grouping, HAVING.
516
+ - [**WHERE**](./where.md) — filtering before aggregation.
517
+ - [**UNWIND**](./unwind-merge.md#unwind) — turn an aggregated list back into rows.
518
+ - [**OPTIONAL MATCH with aggregation**](./match.md#optional-match-with-aggregation) —
519
+ `count(*)` vs `count(expr)` subtleties.
520
+ - [**Query Examples → Aggregation**](./examples.md#aggregation) — copy-paste recipes.