@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.
- package/README.md +5 -0
- 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 +355 -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 +546 -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,331 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "CREATE — Writing Nodes and Relationships"
|
|
3
|
+
description: "The CREATE clause in LoraDB — always inserts new nodes and relationships, with property literals, multi-pattern writes, and the difference from MERGE's upsert semantics."
|
|
4
|
+
online: "https://loradb.com/docs/queries/create"
|
|
5
|
+
package: "@loradb/lora-node@0.36.2"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# CREATE — Writing Nodes and Relationships
|
|
9
|
+
|
|
10
|
+
`CREATE` writes new [nodes](../concepts/nodes.md) and
|
|
11
|
+
[relationships](../concepts/relationships.md) into the graph. Every
|
|
12
|
+
pattern element on the create side becomes a new entity — `CREATE`
|
|
13
|
+
never deduplicates. For upsert semantics use
|
|
14
|
+
[`MERGE`](./unwind-merge.md#merge).
|
|
15
|
+
|
|
16
|
+
> A quick guided walkthrough lives in the
|
|
17
|
+
> [**Ten-Minute Tour → Create some data**](../getting-started/tutorial.md#step-1--create-some-data).
|
|
18
|
+
|
|
19
|
+
## Overview
|
|
20
|
+
|
|
21
|
+
| You want to… | Clause |
|
|
22
|
+
|---|---|
|
|
23
|
+
| Add a node | `CREATE (n:Label {k: v})` |
|
|
24
|
+
| Add multiple nodes | `CREATE (a:L), (b:L)` |
|
|
25
|
+
| Add an edge between existing nodes | `MATCH (a), (b) CREATE (a)-[:R]->(b)` |
|
|
26
|
+
| Add nodes + edge in one shot | `CREATE (a:L)-[:R]->(b:L)` |
|
|
27
|
+
| Bulk import from a list | [`UNWIND $rows AS row CREATE (…)`](./unwind-merge.md#unwind) |
|
|
28
|
+
| Upsert | [`MERGE`](./unwind-merge.md#merge) |
|
|
29
|
+
|
|
30
|
+
## Nodes
|
|
31
|
+
|
|
32
|
+
The simplest `CREATE` — one node, optional labels, optional property map.
|
|
33
|
+
|
|
34
|
+
```cypher
|
|
35
|
+
CREATE (n:User {name: 'Alice', age: 32}) RETURN n;
|
|
36
|
+
CREATE (n:User:Admin {name: 'Bob'}) RETURN n;
|
|
37
|
+
CREATE (n:TempOnly) // no properties, no return
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
Labels are added to the node as-is. Property values follow the standard
|
|
41
|
+
[data-type rules](../data-types/overview.md).
|
|
42
|
+
|
|
43
|
+
### Multiple nodes in one query
|
|
44
|
+
|
|
45
|
+
Comma-separated patterns:
|
|
46
|
+
|
|
47
|
+
```cypher
|
|
48
|
+
CREATE
|
|
49
|
+
(ada:Person {name: 'Ada', born: 1815}),
|
|
50
|
+
(grace:Person {name: 'Grace', born: 1906}),
|
|
51
|
+
(alan:Person {name: 'Alan', born: 1912})
|
|
52
|
+
RETURN ada, grace, alan
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Variables (`ada`, `grace`, …) stay in scope for the rest of the query —
|
|
56
|
+
useful if you want to wire them up with a relationship immediately
|
|
57
|
+
afterwards.
|
|
58
|
+
|
|
59
|
+
### Typed property values
|
|
60
|
+
|
|
61
|
+
Properties accept every
|
|
62
|
+
[supported data type](../data-types/overview.md), including
|
|
63
|
+
[temporals](../data-types/temporal.md) and [points](../data-types/spatial.md):
|
|
64
|
+
|
|
65
|
+
```cypher
|
|
66
|
+
CREATE (c:City {
|
|
67
|
+
name: 'Amsterdam',
|
|
68
|
+
population: 918000,
|
|
69
|
+
tags: ['capital', 'port'],
|
|
70
|
+
founded: '1275-10-27'::DATE,
|
|
71
|
+
location: {latitude: 52.37, longitude: 4.89}::POINT
|
|
72
|
+
})
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Relationships
|
|
76
|
+
|
|
77
|
+
`CREATE` for a relationship requires both endpoints to exist — either
|
|
78
|
+
bound by an earlier [`MATCH`](./match.md), or created inline in the same
|
|
79
|
+
`CREATE`.
|
|
80
|
+
|
|
81
|
+
### Match-then-create
|
|
82
|
+
|
|
83
|
+
Look up both endpoints, then add the edge:
|
|
84
|
+
|
|
85
|
+
```cypher
|
|
86
|
+
MATCH (a:User {name: 'Alice'}), (b:User {name: 'Bob'})
|
|
87
|
+
CREATE (a)-[r:FOLLOWS {since: 2020}]->(b)
|
|
88
|
+
RETURN a, r, b
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Relationships have their own
|
|
92
|
+
[property maps](../concepts/properties.md). `r.since = 2020` is stored on
|
|
93
|
+
the edge, not on the endpoints.
|
|
94
|
+
|
|
95
|
+
### Pattern-create
|
|
96
|
+
|
|
97
|
+
A single `CREATE` can produce both nodes and the relationship between
|
|
98
|
+
them:
|
|
99
|
+
|
|
100
|
+
```cypher
|
|
101
|
+
CREATE (a:User {name: 'Alice'})-[:FOLLOWS]->(b:User {name: 'Bob'})
|
|
102
|
+
RETURN a, b
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### Multi-hop pattern-create
|
|
106
|
+
|
|
107
|
+
Chain freely:
|
|
108
|
+
|
|
109
|
+
```cypher
|
|
110
|
+
CREATE
|
|
111
|
+
(ada:Person {name: 'Ada'}),
|
|
112
|
+
(grace:Person {name: 'Grace'}),
|
|
113
|
+
(alan:Person {name: 'Alan'}),
|
|
114
|
+
(ada)-[:INFLUENCED]->(grace),
|
|
115
|
+
(grace)-[:INFLUENCED]->(alan)
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Direction and type are mandatory
|
|
119
|
+
|
|
120
|
+
On `CREATE`:
|
|
121
|
+
|
|
122
|
+
- `(a)-[:T]-(b)` — **error** (no direction).
|
|
123
|
+
- `(a)-[]->(b)` — **error** (no type).
|
|
124
|
+
- `(a)-[:T]->(b)` — valid.
|
|
125
|
+
- `(a)<-[:T]-(b)` — valid (reversed).
|
|
126
|
+
|
|
127
|
+
See [Troubleshooting → Parse errors](../troubleshooting.md#parse-errors).
|
|
128
|
+
|
|
129
|
+
## Bulk create with UNWIND
|
|
130
|
+
|
|
131
|
+
The idiomatic bulk-load shape pairs `CREATE` with
|
|
132
|
+
[`UNWIND`](./unwind-merge.md#unwind) — one row per list element.
|
|
133
|
+
|
|
134
|
+
### Literal list
|
|
135
|
+
|
|
136
|
+
```cypher
|
|
137
|
+
UNWIND [
|
|
138
|
+
{name: 'Ada', born: 1815},
|
|
139
|
+
{name: 'Grace', born: 1906},
|
|
140
|
+
{name: 'Alan', born: 1912}
|
|
141
|
+
] AS p
|
|
142
|
+
CREATE (:Person {name: p.name, born: p.born})
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Parameter list
|
|
146
|
+
|
|
147
|
+
Pass the list in from the host language:
|
|
148
|
+
|
|
149
|
+
```cypher
|
|
150
|
+
UNWIND $people AS p
|
|
151
|
+
CREATE (:Person {name: p.name, born: p.born})
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Where `$people = [{name: 'Ada', born: 1815}, …]`. This is the
|
|
155
|
+
recommended way to load hundreds or thousands of rows in one query —
|
|
156
|
+
see each binding's parameters section
|
|
157
|
+
([Rust](https://loradb.com/docs/getting-started/rust#parameterised-query),
|
|
158
|
+
[Node](../getting-started/node.md#parameterised-query),
|
|
159
|
+
[Python](https://loradb.com/docs/getting-started/python#parameterised-query)).
|
|
160
|
+
|
|
161
|
+
### Bulk relationships
|
|
162
|
+
|
|
163
|
+
Pair an `UNWIND` with a [`MATCH`](./match.md) to wire up pre-existing nodes:
|
|
164
|
+
|
|
165
|
+
```cypher
|
|
166
|
+
UNWIND $edges AS e
|
|
167
|
+
MATCH (a:User {id: e.from}), (b:User {id: e.to})
|
|
168
|
+
CREATE (a)-[:FOLLOWS {since: e.since}]->(b)
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Uniqueness
|
|
172
|
+
|
|
173
|
+
`CREATE` **never** deduplicates. Running the same `CREATE` twice
|
|
174
|
+
produces two distinct nodes with the same labels and properties unless
|
|
175
|
+
a matching uniqueness or key constraint rejects the second write.
|
|
176
|
+
|
|
177
|
+
```cypher
|
|
178
|
+
CREATE (:User {id: 1})
|
|
179
|
+
CREATE (:User {id: 1})
|
|
180
|
+
// now there are two :User {id: 1} nodes
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
To reject duplicates, add a [uniqueness constraint](./constraints.md):
|
|
184
|
+
|
|
185
|
+
```cypher
|
|
186
|
+
CREATE CONSTRAINT user_id
|
|
187
|
+
FOR (u:User)
|
|
188
|
+
REQUIRE u.id IS UNIQUE
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
For create-if-not-exists semantics use [`MERGE`](./unwind-merge.md#merge):
|
|
192
|
+
|
|
193
|
+
```cypher
|
|
194
|
+
MERGE (u:User {id: 1}) RETURN u
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Running that same query twice yields one node. See
|
|
198
|
+
[MERGE pattern caveats](./unwind-merge.md#pattern-caveats) for the rules on
|
|
199
|
+
what it matches.
|
|
200
|
+
|
|
201
|
+
## Returning what you created
|
|
202
|
+
|
|
203
|
+
`CREATE` can be followed by [`RETURN`](./return-with.md) to hand the new
|
|
204
|
+
entity back — essential when the host needs its internal ID.
|
|
205
|
+
|
|
206
|
+
```cypher
|
|
207
|
+
CREATE (u:User {email: $email})
|
|
208
|
+
RETURN id(u) AS id, u
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
`id()` is the [internal identity](../concepts/graph-model.md#identity).
|
|
212
|
+
Prefer your own stable property (`id`, `email`, …) for external
|
|
213
|
+
addressing.
|
|
214
|
+
|
|
215
|
+
## Common patterns
|
|
216
|
+
|
|
217
|
+
### Upsert with MERGE + SET
|
|
218
|
+
|
|
219
|
+
`CREATE` on its own can't express "insert or update". Combine
|
|
220
|
+
[`MERGE`](./unwind-merge.md#merge) with [`SET`](./set-delete.md#set--properties):
|
|
221
|
+
|
|
222
|
+
```cypher
|
|
223
|
+
MERGE (u:User {id: $id})
|
|
224
|
+
ON CREATE SET u.created = temporal.timestamp()
|
|
225
|
+
SET u.name = $name, u.updated = temporal.timestamp()
|
|
226
|
+
RETURN u
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
### Create + link
|
|
230
|
+
|
|
231
|
+
```cypher
|
|
232
|
+
MATCH (c:Category {slug: $cat})
|
|
233
|
+
CREATE (p:Product {
|
|
234
|
+
name: $name,
|
|
235
|
+
price: $price
|
|
236
|
+
})-[:IN]->(c)
|
|
237
|
+
RETURN p
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
### Clone a node shape
|
|
241
|
+
|
|
242
|
+
```cypher
|
|
243
|
+
MATCH (src:Template {id: $src})
|
|
244
|
+
CREATE (dst:Template)
|
|
245
|
+
SET dst = properties(src)
|
|
246
|
+
SET dst.id = $new_id
|
|
247
|
+
RETURN dst
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
### Create from aggregated input
|
|
251
|
+
|
|
252
|
+
`CREATE` can consume rows produced by a preceding stage. This is how
|
|
253
|
+
you turn an aggregate into new nodes:
|
|
254
|
+
|
|
255
|
+
```cypher
|
|
256
|
+
MATCH (o:Order)
|
|
257
|
+
WITH o.region AS region, sum(o.amount) AS revenue
|
|
258
|
+
CREATE (:RegionStat {region: region, revenue: revenue})
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
One `:RegionStat` node per region.
|
|
262
|
+
|
|
263
|
+
### Mirror-write: create a node plus several relationships
|
|
264
|
+
|
|
265
|
+
```cypher
|
|
266
|
+
MATCH (u:User {id: $user_id}),
|
|
267
|
+
(cat:Category {slug: $cat})
|
|
268
|
+
CREATE (p:Product {
|
|
269
|
+
id: $id,
|
|
270
|
+
name: $name,
|
|
271
|
+
price: $price
|
|
272
|
+
})
|
|
273
|
+
CREATE (u)-[:OWNS]->(p)
|
|
274
|
+
CREATE (p)-[:IN]->(cat)
|
|
275
|
+
RETURN p
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
Each `CREATE` runs once per input row; since the `MATCH` produces one
|
|
279
|
+
row, this creates one product plus two edges in a single query.
|
|
280
|
+
|
|
281
|
+
### Create with conditional properties via CASE
|
|
282
|
+
|
|
283
|
+
```cypher
|
|
284
|
+
CREATE (u:User {
|
|
285
|
+
id: $id,
|
|
286
|
+
email: $email,
|
|
287
|
+
tier: CASE WHEN $paying THEN 'pro' ELSE 'free' END,
|
|
288
|
+
created: temporal.timestamp()
|
|
289
|
+
})
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
See [CASE expressions](./return-with.md#case-expressions).
|
|
293
|
+
|
|
294
|
+
## Edge cases
|
|
295
|
+
|
|
296
|
+
### `CREATE` over empty graph
|
|
297
|
+
|
|
298
|
+
Works unconditionally — there's no schema migration step and no entity
|
|
299
|
+
schema to validate
|
|
300
|
+
against. Labels and relationship types come into existence implicitly on
|
|
301
|
+
first use. See [Graph model → Schema-free](../concepts/graph-model.md#schema-free).
|
|
302
|
+
|
|
303
|
+
### `CREATE` with duplicate variable
|
|
304
|
+
|
|
305
|
+
Reusing a variable for different entities is an analysis error:
|
|
306
|
+
|
|
307
|
+
```cypher
|
|
308
|
+
CREATE (n:A), (n:B) // error: variable 'n' already bound
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
### `CREATE` with relationship to a non-existent node
|
|
312
|
+
|
|
313
|
+
Both endpoints must be in scope. A `CREATE (a)-[:R]->(b)` where `a` or
|
|
314
|
+
`b` isn't bound will fail analysis.
|
|
315
|
+
|
|
316
|
+
### Storage considerations
|
|
317
|
+
|
|
318
|
+
Every node is `O(1)` to create. Relationships are stored on both
|
|
319
|
+
endpoints, so creating one edge is `O(1)` too. Declared secondary
|
|
320
|
+
indexes speed up scoped hot predicates, but unlabeled `MATCH (n {p: v})`
|
|
321
|
+
lookups still have no label scope and fall back to scanning.
|
|
322
|
+
|
|
323
|
+
## See also
|
|
324
|
+
|
|
325
|
+
- [**MATCH**](./match.md) — pattern matching.
|
|
326
|
+
- [**MERGE**](./unwind-merge.md#merge) — create-if-not-exists.
|
|
327
|
+
- [**UNWIND**](./unwind-merge.md#unwind) — bulk-load from a list.
|
|
328
|
+
- [**SET / REMOVE / DELETE**](./set-delete.md) — mutate after creation.
|
|
329
|
+
- [**Properties**](../concepts/properties.md) and
|
|
330
|
+
[**Data Types**](../data-types/overview.md) — value shapes.
|
|
331
|
+
- [**Query Examples**](./examples.md) — end-to-end recipes.
|