@loradb/lora-node 0.36.0 → 0.36.2

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 +355 -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 +546 -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,462 @@
1
+ ---
2
+ title: "Paths and Graph Traversals"
3
+ description: "Path traversals in LoraDB — variable-length patterns, bounded and unbounded quantifiers, zero-hop matches, path binding, shortestPath, and allShortestPaths."
4
+ online: "https://loradb.com/docs/queries/paths"
5
+ package: "@loradb/lora-node@0.36.2"
6
+ ---
7
+
8
+ # Paths and Graph Traversals
9
+
10
+ Paths describe traversals through the graph. On top of fixed-hop
11
+ [`MATCH`](./match.md) patterns, LoraDB supports variable-length
12
+ traversals, path binding, and shortest-path search.
13
+
14
+ > For an intuition-first walkthrough, see the
15
+ > [**Ten-Minute Tour → Walk multi-step patterns**](../getting-started/tutorial.md#step-6--walk-multi-step-patterns).
16
+
17
+ ## Overview
18
+
19
+ | Goal | Pattern |
20
+ |---|---|
21
+ | Fixed hop count | `(a)-[:R]->(b)-[:R]->(c)` |
22
+ | 1 to 3 hops | `(a)-[:R*1..3]->(b)` |
23
+ | Exactly 3 hops | `(a)-[:R*3..3]->(b)` |
24
+ | Up to 3 hops | `(a)-[:R*..3]->(b)` |
25
+ | 3 or more hops | `(a)-[:R*3..]->(b)` |
26
+ | Any positive number of hops | `(a)-[:R*]->(b)` |
27
+ | Zero-or-more hops (includes `a`) | `(a)-[:R*0..]->(b)` |
28
+ | Single shortest path | [`shortestPath(…)`](#shortest-paths) |
29
+ | All shortest paths | [`allShortestPaths(…)`](#all-shortest-paths) |
30
+ | Pattern existence, no rows | [`EXISTS { (…)-[…]->(…) }`](./where.md#pattern-existence) |
31
+ | Attach 1-to-many inline | [Pattern comprehension](../functions/list.md#pattern-comprehension) |
32
+
33
+ ## Variable-length relationships
34
+
35
+ Cypher's `*` operator marks a relationship as variable-length — the
36
+ traversal can cross any number of that relationship between the given
37
+ bounds.
38
+
39
+ ```cypher
40
+ // 1 to 2 hops
41
+ MATCH (a)-[:FOLLOWS*1..2]->(b) RETURN a, b
42
+
43
+ ;// Exactly 3 hops (same as *3..3)
44
+ MATCH (a)-[:FOLLOWS*3]->(b) RETURN b
45
+
46
+ ;// Up to 3 hops (same as 1..3)
47
+ MATCH (a)-[:FOLLOWS*..3]->(b) RETURN a, b
48
+
49
+ ;// 3 or more, unbounded
50
+ MATCH (a)-[:FOLLOWS*3..]->(b) RETURN a, b
51
+
52
+ ;// Any positive number of hops
53
+ MATCH (a)-[:FOLLOWS*]->(b) RETURN a, b
54
+
55
+ ;// Zero-hop included — \`a\` itself matches as \`b\`
56
+ MATCH (a)-[:FOLLOWS*0..1]->(b) RETURN b
57
+ ```
58
+
59
+ Each match produces one row per distinct traversal, so a single `a`
60
+ reached via two separate paths appears twice. Use
61
+ [`DISTINCT`](./return-with.md#distinct) on the `RETURN` when you only
62
+ care about which nodes are reachable, not how many ways.
63
+
64
+ ### Cycle avoidance
65
+
66
+ Within a single matched path, **no relationship is traversed twice**.
67
+ This makes `*..N` safe on cyclic graphs without explicit guard logic.
68
+ Nodes can still repeat on a single path — see
69
+ [Unique nodes on path](#unique-nodes-on-path) for the distinction.
70
+
71
+ ### Traverse any type
72
+
73
+ Drop the type to traverse any relationship kind:
74
+
75
+ ```cypher
76
+ MATCH (a)-[*1..3]-(b) RETURN a, b
77
+ ```
78
+
79
+ This is rarely what you want on non-trivial graphs — the result set
80
+ explodes fast.
81
+
82
+ ## Binding the path
83
+
84
+ `MATCH p = (…)-[…]->(…)` binds the whole path to `p`. Use the built-in
85
+ path functions to inspect it.
86
+
87
+ ```cypher
88
+ MATCH p = (a:User)-[:FOLLOWS*1..3]->(b:User)
89
+ RETURN path.length(p) AS hops,
90
+ path.nodes(p) AS via,
91
+ path.edges(p) AS rels
92
+ ```
93
+
94
+ ### Path functions
95
+
96
+ | Function | Returns |
97
+ |---|---|
98
+ | `path.length(p)` | Number of relationships on the path (`Int`) |
99
+ | `path.nodes(p)` | List of nodes, start to end |
100
+ | `path.edges(p)` | List of relationships, in traversal order |
101
+
102
+ `path.length(p)` for a zero-hop path is `0`; `path.nodes(p)` has one element; `path.edges(p)` is empty.
103
+
104
+ ### Project intermediate nodes
105
+
106
+ ```cypher
107
+ MATCH p = (a:City {name: 'Amsterdam'})-[:ROUTE*2..3]->(b:City)
108
+ RETURN a.name, b.name,
109
+ [n IN path.nodes(p) | n.name] AS via
110
+ ```
111
+
112
+ ## Shortest paths
113
+
114
+ ### Single shortest path
115
+
116
+ Returns one path of minimum length per `(start, end)` pair.
117
+
118
+ ```cypher
119
+ MATCH p = shortestPath(
120
+ (a:Station {name: 'Amsterdam'})-[:ROUTE*]->(b:Station {name: 'Den Haag'})
121
+ )
122
+ RETURN p, path.length(p)
123
+ ```
124
+
125
+ Hop count here is the number of `:ROUTE` relationships traversed —
126
+ every relationship has cost 1, regardless of any weight property.
127
+ Ties are broken arbitrarily: if two paths have the same minimum
128
+ length you get one of them, not both — use
129
+ [`allShortestPaths`](#all-shortest-paths) when you need every
130
+ minimum-length path.
131
+
132
+ ### All shortest paths
133
+
134
+ Returns every path tied for the minimum length.
135
+
136
+ ```cypher
137
+ MATCH p = allShortestPaths(
138
+ (a:Station {name: 'Amsterdam'})-[:ROUTE*]->(b:Station {name: 'Den Haag'})
139
+ )
140
+ RETURN p, path.length(p)
141
+ ```
142
+
143
+ ### Reachability check
144
+
145
+ ```cypher
146
+ MATCH p = shortestPath((a:Node {id: $src})-[*]-(b:Node {id: $dst}))
147
+ RETURN path.length(p) AS hops
148
+ ```
149
+
150
+ One row back when a path exists; **zero rows** when nothing connects
151
+ `a` and `b` — the outer `MATCH` emits nothing, so the `RETURN` never
152
+ runs. Wrap with [`OPTIONAL MATCH`](./match.md#optional-match) (see
153
+ [Disconnected nodes](#disconnected-nodes) below) if you want a row
154
+ back with `hops = null` for the unreachable case.
155
+
156
+ ### Shortest path with type filter
157
+
158
+ ```cypher
159
+ MATCH p = shortestPath(
160
+ (a:User {id: $from})-[:FOLLOWS*]->(b:User {id: $to})
161
+ )
162
+ RETURN path.length(p)
163
+ ```
164
+
165
+ Only `:FOLLOWS` edges count as hops.
166
+
167
+ ## Patterns in expressions
168
+
169
+ ### Pattern comprehension
170
+
171
+ Attach a one-to-many result inline — no extra `MATCH` needed. See also
172
+ [List Functions → pattern comprehension](../functions/list.md#pattern-comprehension).
173
+
174
+ ```cypher
175
+ MATCH (p:Person)
176
+ RETURN p.name,
177
+ [(p)-[:KNOWS]->(f) | f.name] AS friends
178
+ ```
179
+
180
+ With a filter:
181
+
182
+ ```cypher
183
+ MATCH (p:Person)
184
+ RETURN p.name,
185
+ [(p)-[:WROTE]->(post:Post) WHERE post.published | post.title] AS posts
186
+ ```
187
+
188
+ ### Existence check
189
+
190
+ Use [`EXISTS { pattern }`](./where.md#pattern-existence) to filter rows by
191
+ whether a pattern matches — without introducing extra rows.
192
+
193
+ ```cypher
194
+ MATCH (n:User)
195
+ WHERE EXISTS { (n)-[:FOLLOWS]->() }
196
+ RETURN n
197
+ ```
198
+
199
+ ## Common patterns
200
+
201
+ ### Friends-of-friends
202
+
203
+ ```cypher
204
+ MATCH (me:User {id: $id})-[:FOLLOWS*2..2]->(fof)
205
+ WHERE fof <> me
206
+ RETURN DISTINCT fof.name
207
+ ```
208
+
209
+ `*2..2` forces exactly two hops — direct follows don't count. A
210
+ given `fof` can be reached through multiple mutual friends, so
211
+ `DISTINCT` collapses those duplicates to one row per person. The
212
+ `fof <> me` guard drops cycles back to the starting user.
213
+
214
+ ### Reachable set
215
+
216
+ ```cypher
217
+ MATCH (start:Node {id: $id})-[*0..5]-(n)
218
+ RETURN DISTINCT n
219
+ ```
220
+
221
+ Every node within 5 hops, in any direction. `*0..5` includes the
222
+ start node itself (via the zero-hop interpretation), so `n` covers
223
+ `start` plus everything reachable within five relationships.
224
+ Unbounded range (`*0..`) works but will expand the entire connected
225
+ component — keep a cap.
226
+
227
+ ### Shortest route length
228
+
229
+ ```cypher
230
+ MATCH p = shortestPath(
231
+ (a:City {name: $from})-[:ROAD*]->(b:City {name: $to})
232
+ )
233
+ RETURN path.length(p) AS hops
234
+ ```
235
+
236
+ ### All nearby neighbors of each node
237
+
238
+ ```cypher
239
+ MATCH (n:Node)
240
+ RETURN n,
241
+ [(n)-[*1..2]-(m) | m] AS within_two_hops
242
+ ```
243
+
244
+ ### Path with property check along the way
245
+
246
+ ```cypher
247
+ MATCH p = (a:User {id: $from})-[:FOLLOWS*1..3]->(b:User {id: $to})
248
+ WHERE all(r IN path.edges(p) WHERE r.active)
249
+ RETURN p
250
+ ```
251
+
252
+ Filter the whole path with [list predicates](../functions/list.md#predicates-in-where)
253
+ like `all`, `any`, `none`.
254
+
255
+ ### Path with minimum intermediate-property value
256
+
257
+ ```cypher
258
+ MATCH p = (a:Station {code: $from})-[:ROUTE*1..6]->(b:Station {code: $to})
259
+ WHERE all(r IN path.edges(p) WHERE r.status = 'open')
260
+ WITH p, reduce(cost = 0, r IN path.edges(p) | cost + r.km) AS km
261
+ ORDER BY km ASC
262
+ LIMIT 1
263
+ RETURN p, km
264
+ ```
265
+
266
+ A manual "cheapest path of length ≤ 6" — `shortestPath` counts hops
267
+ only, so for weighted traversals you [`reduce`](../functions/list.md#reduce)
268
+ the relationship list yourself, then pick the minimum.
269
+
270
+ ### Excluded node on path
271
+
272
+ ```cypher
273
+ MATCH p = (a:User {id: $from})-[:FOLLOWS*]->(b:User {id: $to})
274
+ WHERE none(n IN path.nodes(p) WHERE n.blocked)
275
+ RETURN p
276
+ ```
277
+
278
+ Path must not pass through any `blocked` user.
279
+
280
+ ### Unique nodes on path
281
+
282
+ #### Why duplicates happen
283
+
284
+ Variable-length patterns guarantee **no relationship is traversed
285
+ twice** on a single path (see [cycle avoidance](#cycle-avoidance)) —
286
+ but the same **node** can still appear more than once when two
287
+ different edges reach it. On a triangle `A → B → C → A`, the path
288
+ `A → B → C → A` visits `A` twice via two distinct edges.
289
+
290
+ This is path uniqueness (always enforced) vs node uniqueness (not
291
+ enforced). For "pure" acyclic walks you need to filter node
292
+ uniqueness yourself.
293
+
294
+ #### The duplicate in practice
295
+
296
+ ```cypher
297
+ CREATE
298
+ (a:Stop {code: 'A'}),
299
+ (b:Stop {code: 'B'}),
300
+ (c:Stop {code: 'C'}),
301
+ (a)-[:NEXT]->(b),
302
+ (b)-[:NEXT]->(c),
303
+ (c)-[:NEXT]->(a)
304
+ ```
305
+
306
+ ```cypher
307
+ MATCH p = (:Stop {code: 'A'})-[:NEXT*1..4]->(end)
308
+ RETURN [n IN path.nodes(p) | n.code] AS path
309
+ ```
310
+
311
+ | path |
312
+ |---|
313
+ | `['A', 'B']` |
314
+ | `['A', 'B', 'C']` |
315
+ | `['A', 'B', 'C', 'A']` ← `A` repeats |
316
+ | `['A', 'B', 'C', 'A', 'B']` ← `A` and `B` repeat |
317
+
318
+ The third and fourth rows are the "node-repeats" cases.
319
+
320
+ #### Workaround: filter on size equality
321
+
322
+ Collect node ids into a list, then require the list size to match the
323
+ size of its de-duplicated form. LoraDB has no `distinct(list)`
324
+ helper, so express dedup as "keep only elements whose first
325
+ occurrence is at their own index":
326
+
327
+ ```cypher
328
+ MATCH p = (:Stop {code: 'A'})-[:NEXT*1..4]->(end)
329
+ WITH p,
330
+ [n IN path.nodes(p) | id(n)] AS ids
331
+ WITH p, ids,
332
+ [i IN list.range(0, value.size(ids) - 1) WHERE NOT ids[i] IN ids[..i]
333
+ | ids[i]] AS unique_ids
334
+ WHERE value.size(ids) = value.size(unique_ids)
335
+ RETURN [n IN path.nodes(p) | n.code] AS path
336
+ ```
337
+
338
+ Same graph:
339
+
340
+ | path |
341
+ |---|
342
+ | `['A', 'B']` |
343
+ | `['A', 'B', 'C']` |
344
+
345
+ Cycles filtered.
346
+
347
+ #### Mental model
348
+
349
+ Treat `path.nodes(p)` as a list. Every list-level operation you'd reach for
350
+ in the [List Functions](../functions/list.md) page works on it. When a
351
+ query asks "are all elements unique?" there's no single function
352
+ — you express it by comparing `value.size(list)` with the size of the
353
+ filtered "first-occurrence-only" form.
354
+
355
+ #### Why this is awkward (and a future-facing note)
356
+
357
+ > This pattern is harder to read than it should be because there's no
358
+ > built-in `distinct(list)` or `collect(DISTINCT …)` helper **over a
359
+ > literal list**. `collect(DISTINCT …)` is an aggregate and only
360
+ > applies to rows. A future helper — for example `distinct_list(xs)`
361
+ > — would let the pattern collapse to
362
+ > `WHERE value.size(ids) = value.size(distinct_list(ids))`. Until then, the
363
+ > comprehension form above is idiomatic.
364
+
365
+ See [Limitations](../limitations.md) for the current list-function gaps.
366
+
367
+ #### Related
368
+
369
+ - [List comprehension](../functions/list.md#list-comprehension) — the
370
+ syntax used for the "first-occurrence-only" filter.
371
+ - [`collect(DISTINCT …)`](../functions/aggregation.md#collect) — distinct
372
+ values when *rows* are your input, not a literal list.
373
+ - [`list.unique` and set-style helpers](../functions/list.md#deduplicate-and-set-operations)
374
+ — the row-level workaround.
375
+ - [DISTINCT on `RETURN`](./return-with.md#distinct) — dedup whole output
376
+ rows.
377
+ - [Cycle avoidance](#cycle-avoidance) — why relationship uniqueness is
378
+ automatic.
379
+
380
+ ### Longest path up to N
381
+
382
+ `shortestPath` has no "longest" counterpart. Bound the depth, collect,
383
+ and sort:
384
+
385
+ ```cypher
386
+ MATCH p = (a:User {id: $id})-[:FOLLOWS*1..5]->(b:User)
387
+ WITH a, b, p
388
+ ORDER BY path.length(p) DESC
389
+ LIMIT 1
390
+ RETURN p, path.length(p) AS hops
391
+ ```
392
+
393
+ Expensive on dense graphs — prefer a bounded variable-length match
394
+ with a small `*..N` cap.
395
+
396
+ ## Edge cases
397
+
398
+ ### Disconnected nodes
399
+
400
+ If no path connects `a` and `b`, the `MATCH` emits zero rows. A
401
+ following [`RETURN path.length(p)`](#path-functions) never runs. Wrap with
402
+ [`OPTIONAL MATCH`](./match.md#optional-match) if you still want a row:
403
+
404
+ ```cypher
405
+ MATCH (a:User {id: $from}), (b:User {id: $to})
406
+ OPTIONAL MATCH p = shortestPath((a)-[:FOLLOWS*]->(b))
407
+ RETURN a, b, path.length(p) AS hops // hops = null if unreachable
408
+ ```
409
+
410
+ ### Self-loops
411
+
412
+ `(a)-[:R*1..]->(a)` matches only if there's a cycle back to `a`.
413
+ `(a)-[:R*0..]->(a)` always matches `a` via the zero-hop interpretation.
414
+
415
+ ### Performance
416
+
417
+ Unbounded variable-length traversals can be expensive. Bound with a
418
+ maximum depth whenever the answer is "and not further":
419
+
420
+ ```cypher
421
+ // Good — bounded
422
+ MATCH (a)-[:KNOWS*1..6]-(b) …
423
+
424
+ // Risky on large graphs — unbounded
425
+ MATCH (a)-[:KNOWS*]-(b) …
426
+ ```
427
+
428
+ A pattern without an upper bound (`*`, `*2..`) stops at 100 hops. An
429
+ explicit bound may be at most 1000 hops: `*1..1001` is a parse error.
430
+ Without a `LIMIT` to stream against, one expansion may hold at most
431
+ 128 MiB of paths at once before the query fails with `LORA_VALIDATION`.
432
+ See [Query limits](../limitations.md#query-limits).
433
+
434
+ ### Zero-hop semantics
435
+
436
+ `[:R*0..N]` includes the start node itself as a valid `b` via a
437
+ zero-hop "path". `path.nodes(p)` has one element, `path.edges(p)` is
438
+ empty. Useful when the answer may be "myself plus my neighbors within
439
+ N".
440
+
441
+ ## What's not supported
442
+
443
+ - **Weighted shortest paths.** `shortestPath` treats every relationship
444
+ as cost 1 — no cost argument, no Dijkstra-style weighting. Compute
445
+ weighted paths in host code (or via `reduce` over `path.edges(p)`).
446
+ - **Quantified path patterns** (`((:X)-[:R]->(:Y)){1,3}`) — not in
447
+ the grammar.
448
+ - **Path utility procedures** — no `CALL` surface.
449
+ - **Inline `WHERE` inside `*` patterns** — rejected at parse time.
450
+ Move the predicate into a standalone `WHERE` using `path.nodes(p)` /
451
+ `path.edges(p)`.
452
+
453
+ See [Limitations](../limitations.md) for the full list.
454
+
455
+ ## See also
456
+
457
+ - [**MATCH**](./match.md) — underlying pattern language.
458
+ - [**WHERE**](./where.md) — path predicates with `all` / `any` / `EXISTS`.
459
+ - [**RETURN / WITH**](./return-with.md) — project path contents.
460
+ - [**List Functions → Pattern comprehension**](../functions/list.md#pattern-comprehension).
461
+ - [**Functions → Entity introspection**](../functions/overview.md#entity-introspection) — `id`, `labels`, `type`.
462
+ - [**Graph Model → Relationship semantics**](../concepts/graph-model.md#relationship-semantics).