@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,429 @@
1
+ ---
2
+ title: "MATCH — Finding Patterns in the Graph"
3
+ description: "The MATCH clause in LoraDB — fixed and variable-length patterns, OPTIONAL MATCH, labels, directions, chained matches, and how it produces the row stream Cypher queries build on."
4
+ online: "https://loradb.com/docs/queries/match"
5
+ package: "@loradb/lora-node@0.36.2"
6
+ ---
7
+
8
+ # MATCH — Finding Patterns in the Graph
9
+
10
+ `MATCH` describes a pattern to find in the graph. Every successful
11
+ match produces one row, with variables bound to concrete
12
+ [nodes](../concepts/nodes.md) or
13
+ [relationships](../concepts/relationships.md). A query can chain many
14
+ `MATCH` clauses in sequence — each reads the rows produced by the
15
+ previous one.
16
+
17
+ > New to pattern matching? Start with the
18
+ > [**Ten-Minute Tour → Find something**](../getting-started/tutorial.md#step-2--find-something),
19
+ > then come back for the full reference.
20
+
21
+ ## Overview
22
+
23
+ | You want to… | Pattern |
24
+ |---|---|
25
+ | Match every node | `MATCH (n)` |
26
+ | Match every node with a label | `MATCH (n:Person)` |
27
+ | Match by label + properties | `MATCH (n:Person {name: 'Ada'})` |
28
+ | Match a relationship | `MATCH (a)-[:KNOWS]->(b)` |
29
+ | Match any type, any direction | `MATCH (a)-[r]-(b)` |
30
+ | Left-join shape | [`OPTIONAL MATCH`](#optional-match) |
31
+ | Variable-length hops | [`MATCH (a)-[:R*1..3]->(b)`](./paths.md) |
32
+ | Bind the whole path | [`MATCH p = (a)-[:R]->(b)`](#path-binding) |
33
+
34
+ ## Node patterns
35
+
36
+ Start with the simplest shape — a single node.
37
+
38
+ ```cypher
39
+ MATCH (n) RETURN n
40
+ ```
41
+
42
+ One row per node in the graph. Variables are local to the query — `n`
43
+ only exists between `MATCH` and `RETURN`.
44
+
45
+ ### Filter by label
46
+
47
+ ```cypher
48
+ MATCH (n:User) RETURN n;
49
+ MATCH (n:User:Admin) RETURN n // must have BOTH labels
50
+ ```
51
+
52
+ Multiple labels on the pattern narrow the match — the node must carry
53
+ every listed label. See [Nodes](../concepts/nodes.md) for the rules on
54
+ labels, case, and conventions.
55
+
56
+ ### Inline property filter
57
+
58
+ Inline maps are a shorthand for equality-only filtering. They're
59
+ equivalent to a [`WHERE`](./where.md) clause on each property.
60
+
61
+ ```cypher
62
+ MATCH (n:User {name: 'alice'}) RETURN n;
63
+ MATCH (n:User {name: 'alice', age: 42}) RETURN n
64
+
65
+ ;// Equivalent to:
66
+ MATCH (n:User)
67
+ WHERE n.name = 'alice' AND n.age = 42
68
+ RETURN n
69
+ ```
70
+
71
+ Inline maps only express equality. For ranges, regex, or null checks,
72
+ move the predicate into [`WHERE`](./where.md).
73
+
74
+ ### Anonymous node
75
+
76
+ If you don't need the node variable, drop it:
77
+
78
+ ```cypher
79
+ MATCH (:User)-[:FOLLOWS]->(b) RETURN b
80
+ ```
81
+
82
+ The anonymous form is handy in long patterns where only endpoints matter.
83
+
84
+ ## Relationship patterns
85
+
86
+ A relationship pattern always has two endpoints, a direction (or its
87
+ absence), and optionally a type and properties.
88
+
89
+ ```cypher
90
+ // Outgoing (src → dst)
91
+ MATCH (a)-[r:FOLLOWS]->(b) RETURN a, r, b
92
+
93
+ ;// Incoming (src ← dst)
94
+ MATCH (a)<-[r:FOLLOWS]-(b) RETURN a, r, b
95
+
96
+ ;// Undirected — matches either direction, once
97
+ MATCH (a)-[r:KNOWS]-(b) RETURN a, r, b
98
+
99
+ ;// Anonymous relationship variable (we don't need \`r\`)
100
+ MATCH (a)-[:FOLLOWS]->(b) RETURN a, b
101
+
102
+ ;// Any type, any direction
103
+ MATCH (a)-[r]-(b) RETURN type(r), count(*)
104
+
105
+ ;// Inline properties on the relationship
106
+ MATCH (a)-[r:FOLLOWS {since: 2020}]->(b) RETURN a, r, b
107
+ ```
108
+
109
+ Direction on `MATCH` is optional. On [`CREATE`](./create.md) and
110
+ [`MERGE`](./unwind-merge.md#merge) it is mandatory.
111
+
112
+ ### Multiple relationship types
113
+
114
+ Use `|` to match any of several types:
115
+
116
+ ```cypher
117
+ MATCH (a)-[r:FOLLOWS|KNOWS]->(b)
118
+ RETURN type(r), count(*)
119
+ ```
120
+
121
+ ## Multi-hop patterns
122
+
123
+ Chain relationships to traverse further.
124
+
125
+ ```cypher
126
+ // Friends of friends
127
+ MATCH (a:User)-[:FOLLOWS]->(b)-[:FOLLOWS]->(c)
128
+ RETURN a.name AS who, c.name AS two_hops_away
129
+ ```
130
+
131
+ Intermediate nodes can still be labelled and filtered:
132
+
133
+ ```cypher
134
+ MATCH (p:Person)-[:WORKS_AT]->(c:Company)-[:IN]->(:City {name: 'Amsterdam'})
135
+ RETURN p.name, c.name
136
+ ```
137
+
138
+ For unknown-length traversals (1 to N hops) see
139
+ [Paths → variable-length relationships](./paths.md#variable-length-relationships).
140
+
141
+ ## Multiple patterns (cross-product)
142
+
143
+ Multiple comma-separated patterns produce a Cartesian product — one row
144
+ per combination.
145
+
146
+ ```cypher
147
+ MATCH (a:User {id: 1}), (b:User {id: 2})
148
+ CREATE (a)-[:FOLLOWS]->(b)
149
+ ```
150
+
151
+ Disconnected patterns are idiomatic when you want two endpoints for a
152
+ [`CREATE`](./create.md) or [`MERGE`](./unwind-merge.md#merge) that follows. In
153
+ a pure read query, they're usually a mistake:
154
+
155
+ ```cypher
156
+ // N * M rows — probably not what you want
157
+ MATCH (a:User), (b:User) RETURN a, b
158
+ ```
159
+
160
+ For that same shape connected by a relationship, prefer:
161
+
162
+ ```cypher
163
+ MATCH (a:User)-[:FOLLOWS]->(b:User) RETURN a, b
164
+ ```
165
+
166
+ ## Optional match
167
+
168
+ `OPTIONAL MATCH` is the graph equivalent of a SQL left join. When the
169
+ pattern matches, variables are bound. When it doesn't, they are `null`
170
+ — but the row from the previous clause still survives.
171
+
172
+ ```cypher
173
+ MATCH (a:User)
174
+ OPTIONAL MATCH (a)-[:FOLLOWS]->(b)
175
+ RETURN a.name, b.name
176
+ ```
177
+
178
+ Users with no outgoing `:FOLLOWS` edge still appear, with `b.name = null`.
179
+
180
+ ### OPTIONAL MATCH with aggregation
181
+
182
+ Very common pattern: count related entities per node, including zero.
183
+
184
+ ```cypher
185
+ MATCH (u:User)
186
+ OPTIONAL MATCH (u)-[:WROTE]->(p:Post)
187
+ RETURN u.name AS user, count(p) AS posts
188
+ ORDER BY posts DESC
189
+ ```
190
+
191
+ `count(p)` — **not** `count(*)` — is crucial here: the optional miss
192
+ binds `p` to `null`, and `count(expr)` skips nulls. `count(*)` would
193
+ count the row and incorrectly yield `1` for users with no posts. See
194
+ [`count`](../functions/aggregation.md#count).
195
+
196
+ ### Chained OPTIONAL MATCH
197
+
198
+ ```cypher
199
+ MATCH (u:User {id: $id})
200
+ OPTIONAL MATCH (u)-[:OWNS]->(repo:Repo)
201
+ OPTIONAL MATCH (repo)-[:HAS_ISSUE]->(i:Issue {status: 'open'})
202
+ RETURN u.name, collect(DISTINCT repo.name) AS repos, count(i) AS open_issues
203
+ ```
204
+
205
+ Each `OPTIONAL MATCH` is independent — a missing repo doesn't stop the
206
+ next optional from running.
207
+
208
+ ## Path binding
209
+
210
+ Bind the whole traversal to a variable with `p = …`. See also
211
+ [Paths](./paths.md).
212
+
213
+ ```cypher
214
+ MATCH p = (a)-[r:FOLLOWS]->(b)
215
+ RETURN p,
216
+ path.length(p) AS hops,
217
+ path.nodes(p) AS via,
218
+ path.edges(p) AS rels
219
+ ```
220
+
221
+ `path.length(p)` is the hop count; `path.nodes(p)` and `path.edges(p)` return
222
+ lists (see [List Functions](../functions/list.md)).
223
+
224
+ ## Progressive patterns
225
+
226
+ A brief tour, same shape, more useful at each step. Each example adds
227
+ one idea to the last.
228
+
229
+ ### 1. Just the pattern
230
+
231
+ ```cypher
232
+ MATCH (u:User)-[:FOLLOWS]->(other:User)
233
+ RETURN u, other
234
+ ```
235
+
236
+ One row per `FOLLOWS` edge. Returns whole nodes.
237
+
238
+ ### 2. Project properties
239
+
240
+ ```cypher
241
+ MATCH (u:User)-[:FOLLOWS]->(other:User)
242
+ RETURN u.handle AS follower, other.handle AS leader
243
+ ```
244
+
245
+ Cleaner for downstream consumers — only the fields that matter.
246
+
247
+ ### 3. Filter
248
+
249
+ ```cypher
250
+ MATCH (u:User)-[:FOLLOWS]->(other:User)
251
+ WHERE u.country = other.country
252
+ RETURN u.handle, other.handle
253
+ ```
254
+
255
+ Same-country follows only — the predicate references both ends of the
256
+ relationship.
257
+
258
+ ### 4. Order and paginate
259
+
260
+ ```cypher
261
+ MATCH (u:User)-[:FOLLOWS]->(other:User)
262
+ WHERE u.country = other.country
263
+ RETURN u.handle, other.handle
264
+ ORDER BY u.handle
265
+ LIMIT 50
266
+ ```
267
+
268
+ ### 5. Aggregate
269
+
270
+ ```cypher
271
+ MATCH (u:User)-[:FOLLOWS]->(other:User)
272
+ WHERE u.country = other.country
273
+ RETURN u.handle, count(other) AS same_country_follows
274
+ ORDER BY same_country_follows DESC
275
+ LIMIT 10
276
+ ```
277
+
278
+ Each step is one more clause. Users who have never written Cypher
279
+ often try to start at step 5 — starting at step 1 and adding a clause
280
+ at a time is faster and catches mistakes earlier.
281
+
282
+ ## Common patterns
283
+
284
+ ### Lookup by unique property
285
+
286
+ ```cypher
287
+ MATCH (u:User {email: $email})
288
+ RETURN u
289
+ LIMIT 1
290
+ ```
291
+
292
+ If you have not added a [uniqueness constraint](./constraints.md), `LIMIT 1`
293
+ is a belt-and-braces guard against duplicates.
294
+
295
+ ### Filter chain
296
+
297
+ ```cypher
298
+ MATCH (p:Product)-[:IN]->(c:Category {slug: $cat})
299
+ WHERE p.price <= $max AND p.in_stock
300
+ RETURN p
301
+ ORDER BY p.price ASC
302
+ LIMIT 20
303
+ ```
304
+
305
+ ### Two-sided match
306
+
307
+ ```cypher
308
+ MATCH (src:User {id: $from}), (dst:User {id: $to})
309
+ MATCH (src)-[:FOLLOWS*1..3]->(dst)
310
+ RETURN src, dst
311
+ ```
312
+
313
+ Useful with [shortest paths](./paths.md#shortest-paths).
314
+
315
+ ### Related entities in one hop
316
+
317
+ ```cypher
318
+ MATCH (p:Person {id: $id})-[:WORKS_AT]->(c:Company)
319
+ RETURN p.name, collect(c.name) AS companies
320
+ ```
321
+
322
+ ### Relationship existence check
323
+
324
+ Use [`EXISTS { pattern }`](./where.md#pattern-existence) to filter without
325
+ an extra row:
326
+
327
+ ```cypher
328
+ MATCH (u:User)
329
+ WHERE EXISTS { (u)-[:FOLLOWS]->() }
330
+ RETURN u
331
+ ```
332
+
333
+ ## Edge cases
334
+
335
+ ### Empty graph
336
+
337
+ `MATCH (:Unknown)` succeeds with zero rows — on an empty graph and on
338
+ a populated graph without any node of that label alike. Unknown labels,
339
+ relationship types, and property keys are never analysis errors; a
340
+ misspelled label just matches nothing. See
341
+ [Schema-free](../concepts/schema-free.md#unknown-names-are-not-errors).
342
+
343
+ ### Self-loops
344
+
345
+ A node connected to itself:
346
+
347
+ ```cypher
348
+ MATCH (a)-[:FOLLOWS]->(a) RETURN a
349
+ ```
350
+
351
+ ### Duplicate rows
352
+
353
+ A node reached via two different paths produces two rows. Use
354
+ [`DISTINCT`](./return-with.md#distinct) on the `RETURN` if you only want
355
+ one:
356
+
357
+ ```cypher
358
+ MATCH (a:User)-[:FOLLOWS]->(b)-[:FOLLOWS]->(c)
359
+ RETURN DISTINCT a, c
360
+ ```
361
+
362
+ ### Type mismatch in inline filter
363
+
364
+ Inline maps are strictly typed. `{id: 1}` does **not** match a node with
365
+ `{id: '1'}` — see [Troubleshooting](../troubleshooting.md#queries-return-empty-results).
366
+
367
+ ### Symmetric-pair deduplication
368
+
369
+ An undirected `(a)-[:KNOWS]-(b)` match produces both `(alice, bob)`
370
+ and `(bob, alice)` rows. Filter with
371
+ [`id()`](../functions/overview.md#entity-introspection) to keep exactly
372
+ one representative per unordered pair:
373
+
374
+ ```cypher
375
+ MATCH (a:Person)-[:KNOWS]-(b:Person)
376
+ WHERE id(a) < id(b)
377
+ RETURN a.name, b.name
378
+ ```
379
+
380
+ ### Same variable in two positions
381
+
382
+ A variable can appear multiple times in a pattern — every occurrence
383
+ must bind to the same entity. Useful for detecting cycles:
384
+
385
+ ```cypher
386
+ MATCH (a)-[:FOLLOWS]->(b)-[:FOLLOWS]->(a)
387
+ RETURN a.name, b.name
388
+ ```
389
+
390
+ Relationships within a single pattern must use **distinct** variable
391
+ names, even when the type is the same:
392
+
393
+ ```cypher
394
+ // Invalid: r reused across two relationships
395
+ MATCH (a)-[r]->(b)-[r]->(c) RETURN a, b, c
396
+
397
+ ;// Valid
398
+ MATCH (a)-[r1]->(b)-[r2]->(c) RETURN a, b, c
399
+ ```
400
+
401
+ See [Relationships → edge cases](../concepts/relationships.md#deleting-a-relationship-thats-been-matched-twice).
402
+
403
+ ### Property pattern on both sides
404
+
405
+ Filters in an inline map apply to that one node only. Filtering both
406
+ endpoints uses the shorthand twice, or drops into `WHERE` for clarity:
407
+
408
+ ```cypher
409
+ MATCH (a:User {country: 'NL'})-[:FOLLOWS]->(b:User {country: 'NL'})
410
+ RETURN a.handle, b.handle
411
+ ```
412
+
413
+ ```cypher
414
+ // Equivalent, easier to read for larger filters
415
+ MATCH (a:User)-[:FOLLOWS]->(b:User)
416
+ WHERE a.country = 'NL' AND b.country = 'NL'
417
+ RETURN a.handle, b.handle
418
+ ```
419
+
420
+ ## See also
421
+
422
+ - [**CREATE**](./create.md) — writing nodes and relationships.
423
+ - [**WHERE**](./where.md) — predicate filtering.
424
+ - [**RETURN / WITH**](./return-with.md) — projecting and piping rows.
425
+ - [**Paths**](./paths.md) — variable-length and shortest paths.
426
+ - [**Aggregation**](./aggregation.md) — grouping after `MATCH`.
427
+ - [**Concepts → Nodes**](../concepts/nodes.md),
428
+ [**Relationships**](../concepts/relationships.md),
429
+ [**Properties**](../concepts/properties.md).