@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,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.