@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.
Files changed (53) hide show
  1. package/README.md +5 -0
  2. package/docs/README.md +86 -0
  3. package/docs/concepts/graph-model.md +270 -0
  4. package/docs/concepts/nodes.md +285 -0
  5. package/docs/concepts/properties.md +348 -0
  6. package/docs/concepts/relationships.md +325 -0
  7. package/docs/concepts/result-formats.md +183 -0
  8. package/docs/concepts/schema-free.md +183 -0
  9. package/docs/cookbook.md +1081 -0
  10. package/docs/data-types/lists-and-maps.md +406 -0
  11. package/docs/data-types/overview.md +210 -0
  12. package/docs/data-types/scalars.md +376 -0
  13. package/docs/data-types/spatial.md +291 -0
  14. package/docs/data-types/temporal.md +349 -0
  15. package/docs/data-types/vectors.md +563 -0
  16. package/docs/errors.md +183 -0
  17. package/docs/functions/aggregation.md +372 -0
  18. package/docs/functions/list.md +522 -0
  19. package/docs/functions/map.md +207 -0
  20. package/docs/functions/math.md +421 -0
  21. package/docs/functions/number.md +197 -0
  22. package/docs/functions/overview.md +545 -0
  23. package/docs/functions/spatial.md +384 -0
  24. package/docs/functions/string.md +502 -0
  25. package/docs/functions/temporal.md +590 -0
  26. package/docs/functions/utility.md +137 -0
  27. package/docs/functions/vectors.md +772 -0
  28. package/docs/getting-started/installation.md +204 -0
  29. package/docs/getting-started/node.md +582 -0
  30. package/docs/getting-started/tutorial.md +334 -0
  31. package/docs/index.md +203 -0
  32. package/docs/limitations.md +291 -0
  33. package/docs/performance.md +219 -0
  34. package/docs/queries/aggregation.md +520 -0
  35. package/docs/queries/cheat-sheet.md +302 -0
  36. package/docs/queries/constraints.md +239 -0
  37. package/docs/queries/create.md +331 -0
  38. package/docs/queries/examples.md +453 -0
  39. package/docs/queries/index.md +169 -0
  40. package/docs/queries/indexes.md +538 -0
  41. package/docs/queries/match.md +429 -0
  42. package/docs/queries/ordering.md +359 -0
  43. package/docs/queries/parameters.md +328 -0
  44. package/docs/queries/paths.md +462 -0
  45. package/docs/queries/return-with.md +500 -0
  46. package/docs/queries/set-delete.md +369 -0
  47. package/docs/queries/unwind-merge.md +358 -0
  48. package/docs/queries/where.md +416 -0
  49. package/docs/snapshot.md +545 -0
  50. package/docs/troubleshooting.md +1158 -0
  51. package/docs/wal.md +570 -0
  52. package/docs/why.md +273 -0
  53. package/package.json +13 -14
@@ -0,0 +1,500 @@
1
+ ---
2
+ title: "RETURN and WITH — Projecting and Piping Results"
3
+ description: "The RETURN and WITH clauses in LoraDB — RETURN ends a query and hands rows back to the caller, WITH pipes them into the next stage. Projections, aliasing, and DISTINCT semantics."
4
+ online: "https://loradb.com/docs/queries/return-with"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # RETURN and WITH — Projecting and Piping Results
9
+
10
+ Both clauses project rows forward. [`WITH`](#with) hands the
11
+ projected rows to the next clause; [`RETURN`](#return) ends the
12
+ query and hands them back to the caller. Rows typically come from a
13
+ preceding [`MATCH`](./match.md) or [`UNWIND`](./unwind-merge.md#unwind).
14
+
15
+ > Think of `WITH` as a pipe between stages, and `RETURN` as the
16
+ > output of the final stage.
17
+
18
+ ## Overview
19
+
20
+ | Goal | Clause |
21
+ |---|---|
22
+ | Shape the final output | [`RETURN`](#return) |
23
+ | Rename a column | `RETURN expr AS name` |
24
+ | Deduplicate rows | [`DISTINCT`](#distinct) |
25
+ | Sort / paginate | [`ORDER BY`, `SKIP`, `LIMIT`](./ordering.md) |
26
+ | Build a subset-map per entity | [Map projection](#map-projection) |
27
+ | Conditional per-row value | [`CASE … WHEN … THEN … END`](#case-expressions) |
28
+ | Pipe into the next stage | [`WITH`](#with) |
29
+ | HAVING-style filtering | [`WITH … WHERE`](#having-style-filtering-with) |
30
+ | Combine two result sets | [`UNION` / `UNION ALL`](#union--union-all) |
31
+
32
+ ## RETURN
33
+
34
+ ### Basic projection
35
+
36
+ Return whole entities, bare properties, or any expression.
37
+
38
+ ```cypher
39
+ MATCH (n) RETURN n;
40
+ MATCH (n) RETURN n.name, n.age;
41
+ MATCH (n) RETURN n.name AS userName;
42
+ MATCH (n) RETURN n.age * 2 AS doubled_age
43
+ ```
44
+
45
+ Aliases (`AS`) set the column name in the host response. Reserve them
46
+ for anything the consumer has to look up by key.
47
+
48
+ ### Star
49
+
50
+ `RETURN *` projects every variable in scope. Handy for exploratory work,
51
+ noisy for production queries.
52
+
53
+ ```cypher
54
+ MATCH (a)-[r]->(b) RETURN *;
55
+ MATCH (a)-[r]->(b) RETURN *, a.name AS name
56
+ ```
57
+
58
+ ### Literal expressions
59
+
60
+ Return constants, function calls, arithmetic:
61
+
62
+ ```cypher
63
+ RETURN 1 + 2 AS three;
64
+ RETURN temporal.timestamp() AS now_ms;
65
+ RETURN temporal.now() AS now, temporal.today() AS today;
66
+ RETURN 'hello, ' + $name AS greeting
67
+ ```
68
+
69
+ ### DISTINCT
70
+
71
+ Deduplicate the output rows. Applies to the full row, not per-column.
72
+
73
+ ```cypher
74
+ MATCH (n) RETURN DISTINCT n.city;
75
+ MATCH (p:Person)-[:WROTE]->(:Post) RETURN DISTINCT p
76
+ ```
77
+
78
+ `DISTINCT` runs **before** [`ORDER BY`](./ordering.md) and is expensive on
79
+ large inputs — prefer filtering with [`WHERE`](./where.md) first.
80
+
81
+ ### ORDER BY, SKIP, LIMIT
82
+
83
+ Shape the final result set. Full reference:
84
+ [Ordering & Pagination](./ordering.md).
85
+
86
+ ```cypher
87
+ MATCH (n) RETURN n ORDER BY n.name ASC;
88
+ MATCH (n) RETURN n ORDER BY n.last ASC, n.first DESC;
89
+ MATCH (n) RETURN n ORDER BY n.name DESC SKIP 5 LIMIT 10;
90
+ MATCH (n) RETURN n LIMIT 1
91
+ ```
92
+
93
+ `SKIP` and `LIMIT` take a non-negative integer. `null` (for example an
94
+ unbound `$limit`), a negative number or a fraction is an error, not
95
+ "no limit".
96
+
97
+ ### Map projection
98
+
99
+ Shape a node or relationship into a map with only the keys you want —
100
+ useful when the consumer doesn't need every property.
101
+
102
+ ```cypher
103
+ // Pick a subset
104
+ MATCH (n:User) RETURN n {.name, .age}
105
+
106
+ ;// All properties (equivalent to \`properties(n)\`)
107
+ MATCH (n:User) RETURN n {.*}
108
+
109
+ ;// Rename + compute
110
+ MATCH (n:User) RETURN n {.name, score: n.age * 2}
111
+
112
+ ;// Include related data
113
+ MATCH (u:User)
114
+ RETURN u {.name, posts: [(u)-[:WROTE]->(p) | p.title]}
115
+ ```
116
+
117
+ See also [Lists & Maps → Map projection](../data-types/lists-and-maps.md#map-projection).
118
+
119
+ ### CASE expressions
120
+
121
+ `CASE` is LoraDB's conditional expression — the Cypher equivalent of
122
+ SQL's `CASE` or a ternary. It's a plain expression, so it works
123
+ anywhere a value is allowed: `RETURN`, `WITH`, `SET`, `ORDER BY`, and
124
+ inside predicates.
125
+
126
+ Two forms.
127
+
128
+ **Simple form** — match an input against successive values:
129
+
130
+ ```cypher
131
+ MATCH (p:Product)
132
+ RETURN p.name,
133
+ CASE p.tier
134
+ WHEN 'gold' THEN 1.2
135
+ WHEN 'silver' THEN 1.1
136
+ WHEN 'bronze' THEN 1.0
137
+ ELSE 0.9
138
+ END AS multiplier
139
+ ```
140
+
141
+ **Generic form** — each branch is its own boolean expression:
142
+
143
+ ```cypher
144
+ MATCH (o:Order)
145
+ RETURN o.id,
146
+ CASE
147
+ WHEN o.amount >= 1000 THEN 'large'
148
+ WHEN o.amount >= 100 THEN 'medium'
149
+ WHEN o.amount >= 10 THEN 'small'
150
+ ELSE 'tiny'
151
+ END AS bucket
152
+ ```
153
+
154
+ The generic form is the one you'll reach for most often — it allows
155
+ arbitrary predicates per branch, including
156
+ [null-safe](../data-types/scalars.md#null) checks and pattern-based
157
+ predicates.
158
+
159
+ #### ELSE is optional
160
+
161
+ Omitting `ELSE` implicitly falls through to `null`:
162
+
163
+ ```cypher
164
+ MATCH (u:User)
165
+ RETURN u.name,
166
+ CASE WHEN u.score > 100 THEN 'pro' END AS tier
167
+ // tier is null for users at or below 100
168
+ ```
169
+
170
+ #### Branches are short-circuit
171
+
172
+ Branches evaluate top-to-bottom; the first matching `WHEN` wins. Place
173
+ the narrowest condition first if branches overlap.
174
+
175
+ #### Type coercion across branches
176
+
177
+ Every branch — including the implicit `null` from a missing `ELSE` —
178
+ can return any type. Nothing forces uniformity. Most callers prefer
179
+ one type per `CASE` for predictable downstream shape:
180
+
181
+ ```cypher
182
+ RETURN CASE WHEN $has_value THEN $value ELSE null END AS maybe
183
+ ```
184
+
185
+ #### In predicates and filters
186
+
187
+ `CASE` is an expression, so it composes inside
188
+ [`WHERE`](./where.md) and [`ORDER BY`](./ordering.md):
189
+
190
+ ```cypher
191
+ MATCH (p:Product)
192
+ WHERE CASE
193
+ WHEN p.on_sale THEN p.sale_price
194
+ ELSE p.price
195
+ END < $max
196
+ RETURN p
197
+ ```
198
+
199
+ ```cypher
200
+ MATCH (t:Task)
201
+ RETURN t
202
+ ORDER BY CASE t.status
203
+ WHEN 'urgent' THEN 0
204
+ WHEN 'open' THEN 1
205
+ ELSE 2
206
+ END, t.created_at
207
+ ```
208
+
209
+ That ordering pattern is how you express "custom priority order" —
210
+ ASCII/byte order on the status string would give you `open`, `urgent`,
211
+ not what you want.
212
+
213
+ #### In SET and aggregates
214
+
215
+ ```cypher
216
+ MATCH (u:User)
217
+ SET u.tier = CASE WHEN u.score >= 100 THEN 'pro' ELSE 'free' END
218
+ ```
219
+
220
+ ```cypher
221
+ MATCH (r:Review)
222
+ RETURN r.product,
223
+ count(CASE WHEN r.stars >= 4 THEN 1 END) AS positive,
224
+ count(CASE WHEN r.stars <= 2 THEN 1 END) AS negative
225
+ ```
226
+
227
+ Combining `CASE` with [`count(expr)`](../functions/aggregation.md#count)
228
+ is the idiomatic way to express "count rows that satisfy X" inside a
229
+ larger aggregation — `count` skips `null`, so the missing `ELSE`
230
+ branch is exactly what you want.
231
+
232
+ #### See also
233
+
234
+ - [`coalesce`](../functions/overview.md#type-conversion-and-checking) — a
235
+ compact shorthand when you only need "first non-null".
236
+ - [WHERE → boolean operators](./where.md#boolean-operators) — three-valued
237
+ logic rules that `CASE` predicates follow.
238
+ - [Ordering by computed expression](./ordering.md#ordering-by-computed-expression).
239
+
240
+ ## WITH
241
+
242
+ `WITH` is the pipe of Cypher. Use it to split a query into stages. The
243
+ projected rows of one stage become the input rows of the next.
244
+
245
+ ### Piping variables
246
+
247
+ The simplest `WITH` — pass the bindings through untouched:
248
+
249
+ ```cypher
250
+ MATCH (a)-[r]->(b)
251
+ WITH a, r, b
252
+ RETURN a, r, b
253
+ ```
254
+
255
+ That's pedagogical; a real query uses `WITH` to change something.
256
+
257
+ ### Transforming between stages
258
+
259
+ `WITH` can rename, compute, filter, aggregate — anything `RETURN` does
260
+ at the end of the pipeline.
261
+
262
+ ```cypher
263
+ MATCH (u:User)
264
+ WITH u, u.born AS year
265
+ WHERE year < 1900
266
+ RETURN u.name, year
267
+ ```
268
+
269
+ ### HAVING-style filtering (WITH)
270
+
271
+ Aggregates are not allowed in [`WHERE`](./where.md). Aggregate into a
272
+ `WITH`, then filter:
273
+
274
+ ```cypher
275
+ MATCH (p:Person)-[:WORKS_AT]->(c:Company)
276
+ WITH c.name AS company, count(p) AS employees
277
+ WHERE employees > 5
278
+ RETURN company, employees
279
+ ```
280
+
281
+ See [Aggregation → HAVING-style filtering](./aggregation.md#5-filter-after-aggregating-having-style).
282
+
283
+ ### Renaming and shaping
284
+
285
+ ```cypher
286
+ MATCH (n:User)
287
+ WITH n.name AS username
288
+ RETURN username
289
+ ```
290
+
291
+ ### Ordering inside a pipeline
292
+
293
+ `ORDER BY` and `LIMIT` attach to a `WITH` stage just like they do to a
294
+ final `RETURN`. Only surviving rows move forward.
295
+
296
+ ```cypher
297
+ MATCH (n:User)
298
+ WITH n
299
+ ORDER BY n.age DESC
300
+ LIMIT 3
301
+ MATCH (n)-[:FOLLOWS]->(other)
302
+ RETURN n.name, other.name
303
+ ```
304
+
305
+ ### Chaining multiple WITH stages
306
+
307
+ ```cypher
308
+ MATCH (o:Order)-[:CONTAINS]->(i:Item)
309
+ WITH o, sum(i.price) AS total
310
+ WHERE total > 100
311
+ WITH o, total
312
+ ORDER BY total DESC
313
+ LIMIT 20
314
+ RETURN o.id, total
315
+ ```
316
+
317
+ Each stage's output columns become the next stage's bindings — any
318
+ variable not projected is dropped.
319
+
320
+ ### Losing variables through WITH
321
+
322
+ A variable must be explicitly projected into `WITH` to survive. This is
323
+ a common source of `Unknown variable` errors:
324
+
325
+ ```cypher
326
+ MATCH (a:User)-[r:KNOWS]->(b)
327
+ WITH a // r and b drop out of scope here
328
+ RETURN a, r // error: r is not in scope
329
+ ```
330
+
331
+ Either pipe them through (`WITH a, r, b`) or don't bind them in the
332
+ first place.
333
+
334
+ ## UNION / UNION ALL
335
+
336
+ Combine two result sets that share a column shape. `UNION`
337
+ deduplicates; `UNION ALL` doesn't.
338
+
339
+ ```cypher
340
+ MATCH (n:User) RETURN n.name AS name
341
+ UNION
342
+ MATCH (n:Product) RETURN n.name AS name
343
+ ```
344
+
345
+ ```cypher
346
+ MATCH (a:A) RETURN a.v AS v
347
+ UNION ALL
348
+ MATCH (b:B) RETURN b.v AS v
349
+ UNION ALL
350
+ MATCH (c:C) RETURN c.v AS v
351
+ ```
352
+
353
+ ### ORDER BY / LIMIT across UNION
354
+
355
+ Apply at the very end — they shape the combined result:
356
+
357
+ ```cypher
358
+ MATCH (n:User) RETURN n.name AS name
359
+ UNION ALL
360
+ MATCH (n:Product) RETURN n.name AS name
361
+ ORDER BY name
362
+ LIMIT 10
363
+ ```
364
+
365
+ ### Column shape must match
366
+
367
+ Both sides must expose the same column names in the same order:
368
+
369
+ ```cypher
370
+ // Valid
371
+ MATCH (n:User) RETURN n.name AS name, 'user' AS kind
372
+ UNION ALL
373
+ MATCH (n:Product) RETURN n.name AS name, 'product' AS kind
374
+
375
+ ;// Invalid — column shape mismatch
376
+ MATCH (n:User) RETURN n.name, 'user'
377
+ UNION
378
+ MATCH (n:Product) RETURN n.name, n.price, 'product'
379
+ ```
380
+
381
+ ### UNION inside CALL { }
382
+
383
+ A `UNION` inside a `CALL { }` body combines the branches once per outer
384
+ row. The query after the `CALL` can then sort, page and count the combined
385
+ rows:
386
+
387
+ ```cypher
388
+ CALL {
389
+ MATCH (f:ImageFile) RETURN f
390
+ UNION ALL
391
+ MATCH (f:VideoFile) RETURN f
392
+ }
393
+ WITH f ORDER BY f.size DESC LIMIT 20
394
+ RETURN f.key AS key, f.size AS size
395
+ ```
396
+
397
+ Each branch sees the outer row's variables, but not the variables of the
398
+ branch before it. Every branch ends in `RETURN` with the same column
399
+ names in the same order. Plain `UNION` drops duplicate rows within each
400
+ outer row, so the same row can still appear once for each outer row:
401
+
402
+ ```cypher
403
+ MATCH (p:Person)
404
+ CALL {
405
+ WITH p MATCH (p)-[:LIKES]->(t) RETURN t.name AS thing
406
+ UNION
407
+ WITH p MATCH (p)-[:OWNS]->(t) RETURN t.name AS thing
408
+ }
409
+ RETURN p.name AS person, thing
410
+ ```
411
+
412
+ ## Common patterns
413
+
414
+ ### Pick N, then follow
415
+
416
+ Top-3 users by age, then project their friends:
417
+
418
+ ```cypher
419
+ MATCH (u:User)
420
+ WITH u ORDER BY u.age DESC LIMIT 3
421
+ MATCH (u)-[:FOLLOWS]->(f)
422
+ RETURN u.name, collect(f.name) AS following
423
+ ```
424
+
425
+ ### Count-and-rank
426
+
427
+ ```cypher
428
+ MATCH (u:User)-[:WROTE]->(p:Post)
429
+ WITH u, count(p) AS posts
430
+ ORDER BY posts DESC
431
+ LIMIT 10
432
+ RETURN u.name, posts
433
+ ```
434
+
435
+ ### Project the top of a nested list
436
+
437
+ ```cypher
438
+ MATCH (p:Person)
439
+ RETURN p.name,
440
+ [(p)-[:KNOWS]->(f) | f.name][..5] AS first_five_friends
441
+ ```
442
+
443
+ ### Keep only rows that meet an aggregate
444
+
445
+ ```cypher
446
+ MATCH (r:Review)
447
+ WITH r.product AS product, avg(r.stars) AS mean
448
+ WHERE mean >= 4.5
449
+ RETURN product, mean
450
+ ORDER BY mean DESC
451
+ ```
452
+
453
+ ### Using both RETURN DISTINCT and ORDER BY
454
+
455
+ `DISTINCT` runs first — you can only order by projected columns.
456
+
457
+ ```cypher
458
+ MATCH (p:Person)
459
+ RETURN DISTINCT p.city AS city
460
+ ORDER BY city
461
+ ```
462
+
463
+ ## Edge cases
464
+
465
+ ### Empty aggregation input
466
+
467
+ `RETURN count(*)` with zero matches still emits one row with value `0`.
468
+ `sum` returns `0` on empty input; `avg`, `min` and `max` return `null`. See
469
+ [Aggregation → count](./aggregation.md#count).
470
+
471
+ ### WITH without projection
472
+
473
+ Every `WITH` must project at least one thing — there's no "pass
474
+ everything" shorthand. `WITH *` works and projects every in-scope
475
+ variable:
476
+
477
+ ```cypher
478
+ MATCH (a)-[r]->(b)
479
+ WITH *
480
+ RETURN a, r, b
481
+ ```
482
+
483
+ ### Aggregation in WITH without a group key
484
+
485
+ Aggregating with no non-aggregated column folds everything into one row:
486
+
487
+ ```cypher
488
+ MATCH (o:Order)
489
+ WITH sum(o.amount) AS total
490
+ RETURN total
491
+ ```
492
+
493
+ ## See also
494
+
495
+ - [**MATCH**](./match.md) — source of rows.
496
+ - [**WHERE**](./where.md) — predicate filtering; also used after `WITH`.
497
+ - [**Aggregation**](./aggregation.md) — group-and-collapse semantics.
498
+ - [**Ordering & Pagination**](./ordering.md) — `ORDER BY`, `SKIP`, `LIMIT`.
499
+ - [**Lists & Maps → Map projection**](../data-types/lists-and-maps.md#map-projection).
500
+ - [**List Functions → Pattern comprehension**](../functions/list.md#pattern-comprehension) — inline nested projections.