@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,369 @@
1
+ ---
2
+ title: "SET, REMOVE, DELETE — Mutating the Graph"
3
+ description: "The mutating clauses in LoraDB — SET for updating properties and labels, REMOVE for clearing them, DELETE and DETACH DELETE for removing nodes and relationships."
4
+ online: "https://loradb.com/docs/queries/set-delete"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # SET, REMOVE, DELETE — Mutating the Graph
9
+
10
+ Mutating clauses act on rows produced by a preceding
11
+ [`MATCH`](./match.md). They never run without a binding — a `SET`
12
+ whose `MATCH` found nothing is a silent no-op.
13
+
14
+ ## Overview
15
+
16
+ | Goal | Clause |
17
+ |---|---|
18
+ | Change one property | `SET n.prop = value` |
19
+ | Merge properties into a map | `SET n += {k: v}` |
20
+ | Replace the whole property map | `SET n = {k: v}` |
21
+ | Remove a property | `REMOVE n.prop` or `SET n.prop = null` |
22
+ | Add labels | `SET n:Label` |
23
+ | Remove labels | `REMOVE n:Label` |
24
+ | Delete a relationship | `MATCH ()-[r]->() DELETE r` |
25
+ | Delete a standalone node | `MATCH (n) DELETE n` |
26
+ | Delete a node **and** its edges | [`DETACH DELETE`](#detach-delete) |
27
+
28
+ ## SET — properties
29
+
30
+ ### Set a single property
31
+
32
+ ```cypher
33
+ MATCH (n:User {name: 'Alice'})
34
+ SET n.age = 33
35
+ RETURN n
36
+ ```
37
+
38
+ Set multiple keys in one clause by chaining with commas:
39
+
40
+ ```cypher
41
+ MATCH (n:User {name: 'Alice'})
42
+ SET n.age = 33, n.updated = temporal.timestamp()
43
+ RETURN n
44
+ ```
45
+
46
+ ### Replace all properties (`=`)
47
+
48
+ `SET n = {...}` **replaces** the full property map. Every key not in
49
+ the new map is dropped — including keys you never touched.
50
+
51
+ ```cypher
52
+ MATCH (n:User {name: 'Alice'})
53
+ SET n = {name: 'Alice', age: 33}
54
+ RETURN n
55
+ ```
56
+
57
+ Almost always a mistake unless you really mean it. Use `+=` to merge. See
58
+ [Troubleshooting → SET wiped my properties](../troubleshooting.md#set-wiped-my-properties).
59
+
60
+ ### Merge properties (`+=`)
61
+
62
+ `SET n += {...}` adds / overwrites keys without removing anything else.
63
+
64
+ ```cypher
65
+ MATCH (n:User {name: 'Alice'})
66
+ SET n += {age: 33, city: 'Amsterdam'}
67
+ RETURN n
68
+ ```
69
+
70
+ Combines naturally with parameter maps for patch-style updates:
71
+
72
+ ```cypher
73
+ MATCH (u:User {id: $id})
74
+ SET u += $patch
75
+ RETURN u
76
+ ```
77
+
78
+ Where `$patch = {name: 'New Name', active: true}`.
79
+
80
+ ### Computed expressions
81
+
82
+ The right-hand side is any expression — reference other properties, call
83
+ functions, do arithmetic.
84
+
85
+ ```cypher
86
+ MATCH (n:User) SET n.doubled = n.age * 2 RETURN n;
87
+ MATCH (n:User) SET n.greeting = 'Hello ' + n.name RETURN n;
88
+ MATCH (n:User) SET n.updated = temporal.timestamp() RETURN n
89
+ ```
90
+
91
+ ### Clear a property
92
+
93
+ Setting a property to `null` removes it — the property simply ceases to
94
+ exist on that entity.
95
+
96
+ ```cypher
97
+ MATCH (n:User {name: 'Alice'})
98
+ SET n.archived = null
99
+ RETURN n
100
+ ```
101
+
102
+ `REMOVE n.prop` does the same.
103
+
104
+ ### Copy properties from another entity
105
+
106
+ ```cypher
107
+ MATCH (src:Template {id: $src}), (dst:Record {id: $dst})
108
+ SET dst += properties(src)
109
+ RETURN dst
110
+ ```
111
+
112
+ [`properties()`](../functions/overview.md#entity-introspection) returns the
113
+ full map; `+=` folds it in.
114
+
115
+ ## SET — labels
116
+
117
+ Adding a label on a node already carrying it is a no-op.
118
+
119
+ ```cypher
120
+ MATCH (n:User {name: 'Alice'})
121
+ SET n:Admin
122
+ RETURN labels(n);
123
+
124
+ MATCH (n:User {name: 'Alice'})
125
+ SET n:Admin:Verified
126
+ RETURN labels(n)
127
+ ```
128
+
129
+ ## REMOVE
130
+
131
+ ### Remove a label
132
+
133
+ ```cypher
134
+ MATCH (n:User {name: 'Alice'})
135
+ REMOVE n:Admin
136
+ RETURN labels(n)
137
+ ```
138
+
139
+ ### Remove a property
140
+
141
+ ```cypher
142
+ MATCH (n:User {name: 'Alice'})
143
+ REMOVE n.age
144
+ RETURN n
145
+ ```
146
+
147
+ Equivalent to `SET n.age = null`. Use whichever reads more clearly at
148
+ the call site.
149
+
150
+ ### Remove multiple labels / properties
151
+
152
+ Chain with commas:
153
+
154
+ ```cypher
155
+ MATCH (n:User {name: 'Alice'})
156
+ REMOVE n:Admin, n:Verified, n.lastAudit
157
+ RETURN n
158
+ ```
159
+
160
+ ## DELETE
161
+
162
+ ### Delete a node
163
+
164
+ ```cypher
165
+ MATCH (n:User {name: 'Temp'})
166
+ DELETE n
167
+ ```
168
+
169
+ A plain `DELETE` on a node requires the node to have **no
170
+ relationships**. Otherwise the executor returns
171
+ `DeleteNodeWithRelationships` — see
172
+ [Troubleshooting → DELETE fails](../troubleshooting.md#delete-fails-with-still-has-relationships).
173
+
174
+ ### DETACH DELETE
175
+
176
+ Removes the node **and** every relationship attached to it in one step.
177
+
178
+ ```cypher
179
+ MATCH (n:User {name: 'Alice'})
180
+ DETACH DELETE n
181
+ ```
182
+
183
+ Use this for ordinary "delete the user" semantics. Plain `DELETE` is
184
+ rarely the right call on a node.
185
+
186
+ ### Delete a relationship
187
+
188
+ ```cypher
189
+ MATCH (a:User {name: 'Alice'})-[r:FOLLOWS]->(b:User)
190
+ DELETE r
191
+ ```
192
+
193
+ Node endpoints survive — the edge alone is removed.
194
+
195
+ ### Many targets in one statement
196
+
197
+ A `DELETE` first reads every row it matches, then deletes all of its
198
+ targets together: relationships first, then nodes. That has three
199
+ consequences:
200
+
201
+ - A relationship matched more than once, as an undirected pattern
202
+ matches it from both ends, is deleted once.
203
+ - A plain `DELETE` of a node succeeds when the same statement deletes
204
+ all of its relationships, even if they arrive on different rows:
205
+ `MATCH (n:Tag {name: 'old'})-[r]-() DELETE r, n`.
206
+ - Deleting many relationships of one busy node (a hub) takes time in
207
+ proportion to its degree, not its degree squared: each node's
208
+ adjacency list is edited once per statement.
209
+
210
+ This holds for `execute` and for streamed queries alike. A
211
+ `CALL { … }` body does it once per incoming row; a `DELETE` inside
212
+ `FOREACH` deletes item by item.
213
+
214
+ ### Delete everything
215
+
216
+ ```cypher
217
+ MATCH (n) DETACH DELETE n
218
+ ```
219
+
220
+ Empties the graph. Note: there is no `TRUNCATE` clause. All bindings
221
+ expose a `clear()` helper that is faster and clearer — see
222
+ [Node → other methods](../getting-started/node.md#other-methods) /
223
+ [Python → other methods](https://loradb.com/docs/getting-started/python#other-methods).
224
+
225
+ ## Common patterns
226
+
227
+ ### Upsert (create-or-update)
228
+
229
+ ```cypher
230
+ MERGE (u:User {id: $id})
231
+ ON CREATE SET u.created = temporal.timestamp()
232
+ SET u.name = $name, u.updated = temporal.timestamp()
233
+ RETURN u
234
+ ```
235
+
236
+ `ON CREATE` only runs on insert; the trailing `SET` runs in both
237
+ branches. See [`MERGE`](./unwind-merge.md#merge).
238
+
239
+ ### Patch with merge-semantics
240
+
241
+ ```cypher
242
+ MATCH (u:User {id: $id})
243
+ SET u += $patch
244
+ RETURN u
245
+ ```
246
+
247
+ Safe pattern for partial updates from a client payload.
248
+
249
+ ### Touching a timestamp
250
+
251
+ ```cypher
252
+ MATCH (n:User {id: $id})
253
+ SET n.last_seen = temporal.timestamp()
254
+ ```
255
+
256
+ ### Convert / migrate a property
257
+
258
+ ```cypher
259
+ MATCH (u:User)
260
+ WHERE u.full_name IS NOT NULL AND u.name IS NULL
261
+ SET u.name = u.full_name
262
+ REMOVE u.full_name
263
+ ```
264
+
265
+ Moves the value from `full_name` to `name`, then drops the old
266
+ key — two mutations per matched row, in order. The `WHERE` is
267
+ important: without the `u.name IS NULL` guard, users who already
268
+ have both keys would lose their existing `name`.
269
+
270
+ ### Conditional label
271
+
272
+ ```cypher
273
+ MATCH (u:User)
274
+ WHERE u.score >= 100
275
+ SET u:Pro
276
+ ```
277
+
278
+ Adds the `:Pro` label to every qualifying user. The node keeps its
279
+ existing labels — `SET n:Label` never replaces, only adds. Running
280
+ it again is a no-op for users already labelled `:Pro`.
281
+
282
+ ### Conditional value via CASE
283
+
284
+ [`CASE`](./return-with.md#case-expressions) is an expression, so it
285
+ composes into `SET`. Single-row-aware derivation:
286
+
287
+ ```cypher
288
+ MATCH (u:User)
289
+ SET u.tier = CASE
290
+ WHEN u.score >= 1000 THEN 'platinum'
291
+ WHEN u.score >= 100 THEN 'gold'
292
+ WHEN u.score >= 10 THEN 'silver'
293
+ ELSE 'bronze'
294
+ END
295
+ ```
296
+
297
+ Pairs cleanly with `MERGE`:
298
+
299
+ ```cypher
300
+ MERGE (u:User {id: $id})
301
+ ON CREATE SET u.tier = 'bronze', u.created = temporal.timestamp()
302
+ SET u.last_seen = temporal.timestamp(),
303
+ u.tier = CASE
304
+ WHEN u.score >= 100 THEN 'gold'
305
+ ELSE coalesce(u.tier, 'bronze')
306
+ END
307
+ ```
308
+
309
+ ### Bulk patch via UNWIND
310
+
311
+ ```cypher
312
+ UNWIND $patches AS patch
313
+ MATCH (u:User {id: patch.id})
314
+ SET u += patch.fields
315
+ ```
316
+
317
+ Where `$patches = [{id: 1, fields: {name: '…'}}, …]`. One
318
+ parse, one plan, N updates — per-row `MATCH` resolves the target,
319
+ `+=` merges the patch. Rows whose id doesn't match an existing
320
+ `:User` produce no update; the query doesn't error.
321
+
322
+ ## Edge cases
323
+
324
+ ### Mutate affects every matched row
325
+
326
+ A broad `MATCH` with a `SET` runs once per matched row. This is
327
+ intentional and powerful, but easy to misuse:
328
+
329
+ ```cypher
330
+ // Sets archived=true on EVERY user
331
+ MATCH (u:User) SET u.archived = true
332
+ ```
333
+
334
+ Narrow the `MATCH` with [`WHERE`](./where.md) or inline properties to scope
335
+ the change.
336
+
337
+ ### Mutate on `OPTIONAL MATCH`
338
+
339
+ `SET n.x = 1` after an `OPTIONAL MATCH` that missed will run on `null`
340
+ — a runtime error. Guard with `WHERE n IS NOT NULL`.
341
+
342
+ ### DETACH DELETE during a pattern with aggregation
343
+
344
+ Aggregations, [`RETURN`](./return-with.md), and mutations interact in
345
+ complex ways. Prefer a simple `MATCH … DETACH DELETE n` step over
346
+ combining with aggregations in one query.
347
+
348
+ ### Atomicity
349
+
350
+ Each query is one atomic step. There is no explicit transaction
351
+ boundary. If a query fails partway through execution, partial writes are
352
+ possible — keep mutations scoped and small where possible. See
353
+ [Queries → Execution model](./index.md#execution-model).
354
+
355
+ ### Constraint enforcement
356
+
357
+ `SET`, `REMOVE`, and property replacement are checked against matching
358
+ [constraints](./constraints.md). A write that duplicates a unique value,
359
+ removes a required property, or changes a property to the wrong
360
+ declared type fails.
361
+
362
+ ## See also
363
+
364
+ - [**MATCH**](./match.md) — source of bindings.
365
+ - [**MERGE**](./unwind-merge.md#merge) — create-or-match semantics.
366
+ - [**CREATE**](./create.md) — write-only counterpart.
367
+ - [**Properties**](../concepts/properties.md) — data-model background.
368
+ - [**Data Types**](../data-types/overview.md) — what values `SET` accepts.
369
+ - [**Troubleshooting**](../troubleshooting.md) — common mutation pitfalls.
@@ -0,0 +1,358 @@
1
+ ---
2
+ title: "UNWIND and MERGE — Iterating and Upserting"
3
+ description: "The UNWIND and MERGE clauses in LoraDB — UNWIND turns a list into rows for batch processing, MERGE finds a pattern or creates it, with ON MATCH and ON CREATE upsert semantics."
4
+ online: "https://loradb.com/docs/queries/unwind-merge"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # UNWIND and MERGE — Iterating and Upserting
9
+
10
+ Two clauses that don't fit neatly into read or write:
11
+
12
+ - [`UNWIND`](#unwind) turns a list into rows, one per element.
13
+ - [`MERGE`](#merge) finds a pattern in the graph, or creates it
14
+ if missing (the Cypher upsert).
15
+
16
+ ## Overview
17
+
18
+ | Goal | Clause |
19
+ |---|---|
20
+ | Turn a list into rows | [`UNWIND`](#unwind) |
21
+ | Bulk-load from a parameter | [`UNWIND $rows AS row CREATE …`](#bulk-load-from-parameter) |
22
+ | Upsert a node | [`MERGE (n:L {key: value})`](#basic-merge) |
23
+ | Different side-effect on insert vs update | [`ON CREATE` / `ON MATCH`](#on-match--on-create) |
24
+ | Ensure a relationship exists | [`MERGE (a)-[:R]->(b)`](#relationship-merge) |
25
+
26
+ ## UNWIND
27
+
28
+ `UNWIND` takes a [list](../data-types/lists-and-maps.md#lists) and emits
29
+ one row per element.
30
+
31
+ ```cypher
32
+ UNWIND [1, 2, 3] AS n RETURN n
33
+ ;// 1, 2, 3
34
+
35
+ UNWIND list.range(1, 5) AS n RETURN n
36
+ ;// 1, 2, 3, 4, 5
37
+
38
+ UNWIND [] AS n RETURN n
39
+ // zero rows
40
+ ```
41
+
42
+ ### Unwind a list of maps
43
+
44
+ Each element becomes a row; the variable holds the map.
45
+
46
+ ```cypher
47
+ UNWIND [
48
+ {name: 'Ada', born: 1815},
49
+ {name: 'Grace', born: 1906}
50
+ ] AS row
51
+ RETURN row.name, row.born
52
+ ```
53
+
54
+ ### Bulk load from parameter
55
+
56
+ The idiomatic large-ingest pattern:
57
+
58
+ ```cypher
59
+ UNWIND $people AS p
60
+ CREATE (:Person {name: p.name, born: p.born})
61
+ ```
62
+
63
+ Where `$people` is a list of maps bound from the host language. One
64
+ parse, one execution plan, N inserts.
65
+
66
+ ### Bulk relationships
67
+
68
+ Resolve endpoints per row with [`MATCH`](./match.md):
69
+
70
+ ```cypher
71
+ UNWIND $edges AS e
72
+ MATCH (a:User {id: e.from}), (b:User {id: e.to})
73
+ CREATE (a)-[:FOLLOWS {since: e.since}]->(b)
74
+ ```
75
+
76
+ ### Deduplicate a list
77
+
78
+ Combine with [`collect(DISTINCT …)`](./aggregation.md#collect):
79
+
80
+ ```cypher
81
+ UNWIND [1, 2, 2, 3, 3, 3] AS x
82
+ RETURN collect(DISTINCT x)
83
+ // [1, 2, 3]
84
+ ```
85
+
86
+ ### Chain UNWINDs
87
+
88
+ ```cypher
89
+ UNWIND $groups AS g
90
+ UNWIND g.members AS m
91
+ CREATE (:Member {group: g.name, name: m})
92
+ ```
93
+
94
+ ### Unwind after aggregation
95
+
96
+ ```cypher
97
+ MATCH (p:Person)-[:KNOWS]->(f)
98
+ WITH p, collect(f.name) AS friends
99
+ UNWIND friends AS friend
100
+ RETURN p.name, friend
101
+ ```
102
+
103
+ Re-expands an aggregated list back into rows — useful when you want to
104
+ post-process each element after collecting.
105
+
106
+ ### Empty list
107
+
108
+ `UNWIND []` emits **zero rows**. Any downstream clause runs zero times
109
+ — an empty list short-circuits the pipeline:
110
+
111
+ ```cypher
112
+ UNWIND [] AS x
113
+ CREATE (:Should_Not_Exist)
114
+ // no-op, no nodes created
115
+ ```
116
+
117
+ ### Null vs empty
118
+
119
+ `UNWIND null` emits zero rows (same as empty). This is easy to miss:
120
+
121
+ ```cypher
122
+ UNWIND $maybe_list AS x
123
+ RETURN x
124
+ // $maybe_list not bound -> null -> 0 rows
125
+ ```
126
+
127
+ Pass an explicit `[]` rather than `null` when you want to express
128
+ "nothing to do" from the host.
129
+
130
+ ## MERGE
131
+
132
+ `MERGE` finds a pattern in the graph. If a match exists, it's bound
133
+ to the variables. If not, the pattern is created — **exactly** as
134
+ written, labels and properties and all.
135
+
136
+ ```cypher
137
+ MERGE (n:User {id: 1001}) RETURN n
138
+ ```
139
+
140
+ Running that query twice produces one `:User {id: 1001}`, not two.
141
+ Running the equivalent [`CREATE`](./create.md) twice produces two distinct
142
+ nodes.
143
+
144
+ ### Basic merge
145
+
146
+ Shape the pattern around the fields that uniquely identify the entity.
147
+
148
+ ```cypher
149
+ MERGE (u:User {id: $id}) RETURN u
150
+ ```
151
+
152
+ ### ON MATCH / ON CREATE
153
+
154
+ Run different side-effects depending on whether the match existed or
155
+ had to be created.
156
+
157
+ ```cypher
158
+ MERGE (n:User {id: 1002})
159
+ ON MATCH SET n.updated = temporal.timestamp()
160
+ ON CREATE SET n.created = temporal.timestamp()
161
+ RETURN n
162
+ ```
163
+
164
+ Both clauses are optional. You can have neither, one, or both.
165
+
166
+ ### Merge + unconditional SET
167
+
168
+ A very common upsert pattern: `MERGE` on the unique key, then `SET` the
169
+ fields that always change:
170
+
171
+ ```cypher
172
+ MERGE (u:User {id: $id})
173
+ ON CREATE SET u.created = temporal.timestamp()
174
+ SET u.name = $name, u.updated = temporal.timestamp()
175
+ RETURN u
176
+ ```
177
+
178
+ The trailing `SET` runs on both `ON MATCH` and `ON CREATE` branches.
179
+
180
+ ### Relationship merge
181
+
182
+ ```cypher
183
+ MATCH (a:User {name: 'Alice'}), (b:User {name: 'Bob'})
184
+ MERGE (a)-[r:FOLLOWS]->(b)
185
+ RETURN r
186
+ ```
187
+
188
+ If an `(a)-[:FOLLOWS]->(b)` edge between those exact two nodes already
189
+ exists, it is reused. Otherwise a new one is created.
190
+
191
+ ### Merge the full pattern
192
+
193
+ `MERGE` matches on the **whole pattern**. Properties inside the node
194
+ pattern participate in the match.
195
+
196
+ ```cypher
197
+ // Matches only the exact pattern
198
+ MERGE (u:User {id: 1, status: 'active'})
199
+ ```
200
+
201
+ If a `:User {id: 1}` exists with no `status` property, this `MERGE`
202
+ **won't** match — it'll create a second node.
203
+
204
+ ### Pattern caveats
205
+
206
+ - Keep the identifying properties inside the `MERGE` pattern.
207
+ - Set everything else with a trailing [`SET`](./set-delete.md#set--properties).
208
+
209
+ ```cypher
210
+ // Bad — 'updated_at' is part of the match key
211
+ MERGE (u:User {id: $id, updated_at: temporal.now()})
212
+
213
+ // Good — identity inside, payload via SET
214
+ MERGE (u:User {id: $id})
215
+ SET u.updated_at = temporal.now()
216
+ RETURN u
217
+ ```
218
+
219
+ ### Merge missing endpoints
220
+
221
+ If the relationship endpoints aren't bound yet, `MERGE` will create them
222
+ too — usually not what you want.
223
+
224
+ ```cypher
225
+ // Risky: creates Alice and Bob if either is missing
226
+ MERGE (a:User {name: 'Alice'})-[:FOLLOWS]->(b:User {name: 'Bob'})
227
+ ```
228
+
229
+ Prefer a safer two-step: match both nodes, then merge the edge.
230
+
231
+ ```cypher
232
+ MATCH (a:User {name: 'Alice'}), (b:User {name: 'Bob'})
233
+ MERGE (a)-[:FOLLOWS]->(b)
234
+ ```
235
+
236
+ ## Common patterns
237
+
238
+ ### Idempotent bulk upsert
239
+
240
+ ```cypher
241
+ UNWIND $rows AS row
242
+ MERGE (u:User {id: row.id})
243
+ ON CREATE SET u.created = temporal.timestamp()
244
+ SET u += row.fields, u.updated = temporal.timestamp()
245
+ ```
246
+
247
+ Every row becomes a "find-or-create then update" pass.
248
+
249
+ ### Tag-or-create relationship
250
+
251
+ ```cypher
252
+ UNWIND $tags AS t
253
+ MERGE (tag:Tag {name: t})
254
+ WITH tag
255
+ MATCH (p:Post {id: $post_id})
256
+ MERGE (p)-[:TAGGED]->(tag)
257
+ ```
258
+
259
+ ### Counter (monotonic increment)
260
+
261
+ ```cypher
262
+ MERGE (c:Counter {name: 'views'})
263
+ ON CREATE SET c.value = 1
264
+ ON MATCH SET c.value = c.value + 1
265
+ RETURN c.value
266
+ ```
267
+
268
+ ### "Ensure this edge"
269
+
270
+ ```cypher
271
+ MATCH (u:User {id: $user}), (r:Role {name: $role})
272
+ MERGE (u)-[:HAS_ROLE]->(r)
273
+ ```
274
+
275
+ Run it twenty times; at most one edge exists between that user and that role.
276
+
277
+ ### Histogram from a parameter list
278
+
279
+ ```cypher
280
+ UNWIND $readings AS v
281
+ WITH (v / 10) * 10 AS bucket, count(*) AS n
282
+ RETURN bucket, n
283
+ ORDER BY bucket
284
+ ```
285
+
286
+ No graph data involved — the pipeline starts from a host-supplied
287
+ list. Useful for analytics queries that use LoraDB as a compute
288
+ environment.
289
+
290
+ ### Unwind a list, filter, aggregate
291
+
292
+ ```cypher
293
+ UNWIND $scores AS s
294
+ WITH s WHERE s IS NOT NULL AND s > 0
295
+ RETURN avg(s) AS mean, min(s) AS worst, max(s) AS best, count(*) AS n
296
+ ```
297
+
298
+ ### Upsert relationship with payload on first-sight
299
+
300
+ ```cypher
301
+ UNWIND $edges AS e
302
+ MATCH (a:User {id: e.from}), (b:User {id: e.to})
303
+ MERGE (a)-[r:FOLLOWS]->(b)
304
+ ON CREATE SET r.since = coalesce(e.since, temporal.timestamp())
305
+ SET r.last_activity = temporal.timestamp()
306
+ ```
307
+
308
+ ### Conditional MERGE via CASE
309
+
310
+ ```cypher
311
+ UNWIND $rows AS row
312
+ MERGE (u:User {id: row.id})
313
+ SET u.tier = CASE
314
+ WHEN row.amount >= 1000 THEN 'platinum'
315
+ WHEN row.amount >= 100 THEN 'gold'
316
+ ELSE coalesce(u.tier, 'bronze')
317
+ END
318
+ ```
319
+
320
+ The trailing `SET` runs on both match and create. See
321
+ [`CASE`](./return-with.md#case-expressions).
322
+
323
+ ## Edge cases
324
+
325
+ ### Whitespace in pattern vs data
326
+
327
+ `MERGE (:User {name: 'Alice'})` will not match `:User {name: 'Alice '}`.
328
+ String equality is exact — trim on the host if inputs are dirty.
329
+
330
+ ### MERGE on multi-label pattern
331
+
332
+ Labels in the `MERGE` pattern are also part of the match key:
333
+
334
+ ```cypher
335
+ // Won't match a plain :User {id: 1}
336
+ MERGE (u:User:Admin {id: 1})
337
+ ```
338
+
339
+ ### UNWIND + MERGE race
340
+
341
+ There is no concurrent write safety concern because LoraDB runs queries
342
+ serially — see
343
+ [Queries → Execution model](./index.md#execution-model).
344
+
345
+ ### Empty parameters
346
+
347
+ `UNWIND $rows AS row MERGE (:User {id: row.id})` is a no-op when
348
+ `$rows = []`. The `MERGE` doesn't run, so no accidental writes from a
349
+ stray empty list.
350
+
351
+ ## See also
352
+
353
+ - [**CREATE**](./create.md) — write-only alternative.
354
+ - [**SET / REMOVE / DELETE**](./set-delete.md) — mutations applied after `MERGE`.
355
+ - [**MATCH**](./match.md) — look up endpoints before `MERGE (a)-[…]->(b)`.
356
+ - [**Parameters**](./parameters.md) — bind `$rows`, `$patch`, …
357
+ - [**Lists & Maps**](../data-types/lists-and-maps.md) — list input for `UNWIND`.
358
+ - [**Aggregation → collect**](./aggregation.md#collect) — produce lists you can later unwind.