@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.
- package/README.md +5 -0
- package/dist/types.d.ts +2 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +1 -0
- package/dist/types.js.map +1 -1
- package/docs/README.md +86 -0
- package/docs/concepts/graph-model.md +270 -0
- package/docs/concepts/nodes.md +285 -0
- package/docs/concepts/properties.md +348 -0
- package/docs/concepts/relationships.md +325 -0
- package/docs/concepts/result-formats.md +183 -0
- package/docs/concepts/schema-free.md +183 -0
- package/docs/cookbook.md +1081 -0
- package/docs/data-types/lists-and-maps.md +406 -0
- package/docs/data-types/overview.md +210 -0
- package/docs/data-types/scalars.md +376 -0
- package/docs/data-types/spatial.md +291 -0
- package/docs/data-types/temporal.md +349 -0
- package/docs/data-types/vectors.md +563 -0
- package/docs/errors.md +183 -0
- package/docs/functions/aggregation.md +372 -0
- package/docs/functions/list.md +522 -0
- package/docs/functions/map.md +207 -0
- package/docs/functions/math.md +421 -0
- package/docs/functions/number.md +197 -0
- package/docs/functions/overview.md +545 -0
- package/docs/functions/spatial.md +384 -0
- package/docs/functions/string.md +502 -0
- package/docs/functions/temporal.md +590 -0
- package/docs/functions/utility.md +137 -0
- package/docs/functions/vectors.md +772 -0
- package/docs/getting-started/installation.md +204 -0
- package/docs/getting-started/node.md +582 -0
- package/docs/getting-started/tutorial.md +334 -0
- package/docs/index.md +203 -0
- package/docs/limitations.md +291 -0
- package/docs/performance.md +219 -0
- package/docs/queries/aggregation.md +520 -0
- package/docs/queries/cheat-sheet.md +302 -0
- package/docs/queries/constraints.md +239 -0
- package/docs/queries/create.md +331 -0
- package/docs/queries/examples.md +453 -0
- package/docs/queries/index.md +169 -0
- package/docs/queries/indexes.md +538 -0
- package/docs/queries/match.md +429 -0
- package/docs/queries/ordering.md +359 -0
- package/docs/queries/parameters.md +328 -0
- package/docs/queries/paths.md +462 -0
- package/docs/queries/return-with.md +500 -0
- package/docs/queries/set-delete.md +369 -0
- package/docs/queries/unwind-merge.md +358 -0
- package/docs/queries/where.md +416 -0
- package/docs/snapshot.md +545 -0
- package/docs/troubleshooting.md +1158 -0
- package/docs/wal.md +570 -0
- package/docs/why.md +273 -0
- 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.
|