@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,325 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Relationships Between Nodes"
|
|
3
|
+
description: "How LoraDB represents relationships — typed, directed edges between nodes with their own properties — and how to create, traverse, and constrain them in Cypher."
|
|
4
|
+
online: "https://loradb.com/docs/concepts/relationships"
|
|
5
|
+
package: "@loradb/lora-node@0.36.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Relationships Between Nodes
|
|
9
|
+
|
|
10
|
+
A **relationship** is a directed, typed edge between two nodes. Like
|
|
11
|
+
nodes, it can carry properties. Every relationship has:
|
|
12
|
+
|
|
13
|
+
- exactly one **type** (e.g. `KNOWS`, `ACTED_IN`);
|
|
14
|
+
- exactly one **direction** — start node `→` end node;
|
|
15
|
+
- any number of [**properties**](./properties.md).
|
|
16
|
+
|
|
17
|
+
## Quick reference
|
|
18
|
+
|
|
19
|
+
| You want… | Pattern |
|
|
20
|
+
|---|---|
|
|
21
|
+
| Create with direction | `(a)-[:T]->(b)` |
|
|
22
|
+
| Reversed | `(a)<-[:T]-(b)` |
|
|
23
|
+
| Match either direction | `(a)-[:T]-(b)` (MATCH only) |
|
|
24
|
+
| Anonymous | `(a)-[:T]->(b)` (no rel variable) |
|
|
25
|
+
| Bind the rel | `(a)-[r:T]->(b)` |
|
|
26
|
+
| With properties | `(a)-[:T {k: v}]->(b)` |
|
|
27
|
+
| Any type | `(a)-[r]->(b)` (MATCH only) |
|
|
28
|
+
| Multiple types | `(a)-[:T1|T2]->(b)` (MATCH only — pipe is the "or" operator) |
|
|
29
|
+
|
|
30
|
+
## Create
|
|
31
|
+
|
|
32
|
+
Endpoints must exist first — either bound by an earlier `MATCH` or
|
|
33
|
+
created in the same clause.
|
|
34
|
+
|
|
35
|
+
### Match then create
|
|
36
|
+
|
|
37
|
+
```cypher
|
|
38
|
+
MATCH (a:Person {name: 'Ada'}), (b:Person {name: 'Grace'})
|
|
39
|
+
CREATE (a)-[:KNOWS {since: 1843}]->(b)
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Inline in one CREATE
|
|
43
|
+
|
|
44
|
+
```cypher
|
|
45
|
+
CREATE (a:Person {name: 'Ada'})-[:INFLUENCED]->(b:Person {name: 'Grace'})
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### Chained patterns
|
|
49
|
+
|
|
50
|
+
A single `CREATE` can chain several edges through the same variables:
|
|
51
|
+
|
|
52
|
+
```cypher
|
|
53
|
+
CREATE
|
|
54
|
+
(ada:Person {name: 'Ada'}),
|
|
55
|
+
(grace:Person {name: 'Grace'}),
|
|
56
|
+
(alan:Person {name: 'Alan'}),
|
|
57
|
+
(ada)-[:INFLUENCED]->(grace),
|
|
58
|
+
(grace)-[:INFLUENCED]->(alan)
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
### Idempotent create — MERGE
|
|
62
|
+
|
|
63
|
+
`CREATE` doesn't deduplicate. [`MERGE`](../queries/unwind-merge.md#merge)
|
|
64
|
+
does:
|
|
65
|
+
|
|
66
|
+
```cypher
|
|
67
|
+
MATCH (a:Person {name: 'Ada'}), (b:Person {name: 'Grace'})
|
|
68
|
+
MERGE (a)-[:KNOWS]->(b)
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Running this twice yields exactly one `KNOWS` edge.
|
|
72
|
+
|
|
73
|
+
### Rules on CREATE
|
|
74
|
+
|
|
75
|
+
- Direction is **mandatory** — `(a)-[:T]-(b)` in a `CREATE` is an error.
|
|
76
|
+
- Type is **mandatory** — `(a)-[]->(b)` is an error.
|
|
77
|
+
- Both endpoints must be in scope.
|
|
78
|
+
|
|
79
|
+
See [Troubleshooting → Parse errors](../troubleshooting.md#parse-errors).
|
|
80
|
+
|
|
81
|
+
## Match
|
|
82
|
+
|
|
83
|
+
Relationships can be matched with or without a type, with or without a
|
|
84
|
+
direction.
|
|
85
|
+
|
|
86
|
+
```cypher
|
|
87
|
+
MATCH (a)-[r:KNOWS]->(b) RETURN a, r, b; // outgoing
|
|
88
|
+
MATCH (a)<-[r:KNOWS]-(b) RETURN a, r, b; // incoming
|
|
89
|
+
MATCH (a)-[r:KNOWS]-(b) RETURN a, r, b; // either direction
|
|
90
|
+
MATCH (a)-[r]->(b) RETURN a, r, b; // any type
|
|
91
|
+
MATCH (a)-[r:FOLLOWS|KNOWS]->(b) RETURN a, r, b; // multiple types
|
|
92
|
+
MATCH (a)-[:FOLLOWS {since: 2020}]->(b) RETURN a, b
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Projection
|
|
96
|
+
|
|
97
|
+
```cypher
|
|
98
|
+
MATCH (a)-[r:FOLLOWS]->(b)
|
|
99
|
+
RETURN type(r), r.since, a.name, b.name
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
[`type(r)`](../functions/overview.md#entity-introspection) returns the
|
|
103
|
+
relationship's type as a string.
|
|
104
|
+
|
|
105
|
+
### Variable-length
|
|
106
|
+
|
|
107
|
+
```cypher
|
|
108
|
+
MATCH (a)-[:FOLLOWS*1..3]->(b) RETURN b
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
See [Paths → variable-length](../queries/paths.md#variable-length-relationships).
|
|
112
|
+
|
|
113
|
+
## Mutate or delete
|
|
114
|
+
|
|
115
|
+
```cypher
|
|
116
|
+
MATCH (a)-[r:KNOWS]->(b) SET r.since = 2025 RETURN r;
|
|
117
|
+
MATCH (a)-[r:KNOWS]->(b) DELETE r
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Deleting a node that has relationships requires
|
|
121
|
+
[`DETACH DELETE`](../queries/set-delete.md#detach-delete):
|
|
122
|
+
|
|
123
|
+
```cypher
|
|
124
|
+
MATCH (n:User {id: $id}) DETACH DELETE n
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
## Properties on relationships
|
|
128
|
+
|
|
129
|
+
Exactly the same shape as on nodes:
|
|
130
|
+
|
|
131
|
+
```cypher
|
|
132
|
+
MATCH (a)-[r:FOLLOWS]->(b)
|
|
133
|
+
SET r.since = 2025, r.visibility = 'public';
|
|
134
|
+
|
|
135
|
+
MATCH (a)-[r:FOLLOWS]->(b)
|
|
136
|
+
SET r += {muted: true};
|
|
137
|
+
|
|
138
|
+
MATCH (a)-[r:FOLLOWS]->(b)
|
|
139
|
+
REMOVE r.muted
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Access and project them like any other
|
|
143
|
+
[property](./properties.md):
|
|
144
|
+
|
|
145
|
+
```cypher
|
|
146
|
+
MATCH (a)-[r:FOLLOWS]->(b)
|
|
147
|
+
RETURN a.name, b.name, r.since
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
## Direction conventions
|
|
151
|
+
|
|
152
|
+
LoraDB's direction is semantic — use it to reflect the real-world
|
|
153
|
+
direction of the relationship.
|
|
154
|
+
|
|
155
|
+
| Relationship | Direction |
|
|
156
|
+
|---|---|
|
|
157
|
+
| `FOLLOWS`, `KNOWS`, `LIKES` | `follower -> followee` |
|
|
158
|
+
| `WROTE`, `AUTHORED` | `author -> work` |
|
|
159
|
+
| `CONTAINS`, `OWNS` | `container -> item` |
|
|
160
|
+
| `IN`, `PART_OF` | `child -> parent` |
|
|
161
|
+
|
|
162
|
+
When in doubt, pick one and document it. Queries can always match
|
|
163
|
+
either direction with `(a)-[:T]-(b)` if you later need symmetry.
|
|
164
|
+
|
|
165
|
+
## Common patterns
|
|
166
|
+
|
|
167
|
+
### "Mutual" follows
|
|
168
|
+
|
|
169
|
+
```cypher
|
|
170
|
+
MATCH (a)-[:FOLLOWS]->(b)-[:FOLLOWS]->(a)
|
|
171
|
+
WHERE id(a) < id(b)
|
|
172
|
+
RETURN a.name, b.name
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
### Count by type
|
|
176
|
+
|
|
177
|
+
```cypher
|
|
178
|
+
MATCH (a)-[r]->(b)
|
|
179
|
+
RETURN type(r), count(*) ORDER BY count(*) DESC
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Per-node degree
|
|
183
|
+
|
|
184
|
+
```cypher
|
|
185
|
+
MATCH (n)-[r]->()
|
|
186
|
+
RETURN n.name, count(r) AS out_degree
|
|
187
|
+
ORDER BY out_degree DESC
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
```cypher
|
|
191
|
+
MATCH (n)<-[r]-()
|
|
192
|
+
RETURN n.name, count(r) AS in_degree
|
|
193
|
+
ORDER BY in_degree DESC
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### Self-loops
|
|
197
|
+
|
|
198
|
+
Rare but sometimes the right modelling choice:
|
|
199
|
+
|
|
200
|
+
```cypher
|
|
201
|
+
MATCH (n)
|
|
202
|
+
WHERE EXISTS { (n)-[:RECURSES_INTO]->(n) }
|
|
203
|
+
RETURN n
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
### Ensure this edge (once)
|
|
207
|
+
|
|
208
|
+
```cypher
|
|
209
|
+
MATCH (a:User {id: $u}), (r:Role {name: $role})
|
|
210
|
+
MERGE (a)-[:HAS_ROLE]->(r)
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Repeatable without creating duplicates.
|
|
214
|
+
|
|
215
|
+
### Remove every edge of a type
|
|
216
|
+
|
|
217
|
+
```cypher
|
|
218
|
+
MATCH ()-[r:OBSOLETE_LINK]->()
|
|
219
|
+
DELETE r
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
### Oldest / newest edge per pair
|
|
223
|
+
|
|
224
|
+
Relationships carry their own properties and can be ranked like
|
|
225
|
+
nodes:
|
|
226
|
+
|
|
227
|
+
```cypher
|
|
228
|
+
MATCH (a:User)-[r:MESSAGED]->(b:User)
|
|
229
|
+
RETURN a.handle, b.handle,
|
|
230
|
+
min(r.at) AS first,
|
|
231
|
+
max(r.at) AS last,
|
|
232
|
+
count(r) AS total
|
|
233
|
+
ORDER BY total DESC
|
|
234
|
+
LIMIT 20
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
### "Any edge at all" between two nodes
|
|
238
|
+
|
|
239
|
+
```cypher
|
|
240
|
+
MATCH (a:User {id: $a}), (b:User {id: $b})
|
|
241
|
+
RETURN EXISTS { (a)-[]-(b) } AS connected
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
### Count in-degree vs out-degree in one pass
|
|
245
|
+
|
|
246
|
+
```cypher
|
|
247
|
+
MATCH (n:User)
|
|
248
|
+
OPTIONAL MATCH (n)-[out]->()
|
|
249
|
+
WITH n, count(out) AS out_deg
|
|
250
|
+
OPTIONAL MATCH (n)<-[in]-()
|
|
251
|
+
RETURN n.handle, out_deg, count(in) AS in_deg
|
|
252
|
+
ORDER BY in_deg + out_deg DESC
|
|
253
|
+
LIMIT 20
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
Note the two `OPTIONAL MATCH` stages — any node with zero edges in
|
|
257
|
+
either direction still appears.
|
|
258
|
+
|
|
259
|
+
### Convert one relationship type to another
|
|
260
|
+
|
|
261
|
+
Useful during a schema-change migration.
|
|
262
|
+
|
|
263
|
+
```cypher
|
|
264
|
+
MATCH (a)-[r:OLD_TYPE]->(b)
|
|
265
|
+
CREATE (a)-[r2:NEW_TYPE]->(b)
|
|
266
|
+
SET r2 = properties(r)
|
|
267
|
+
DELETE r
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
## Edge cases
|
|
271
|
+
|
|
272
|
+
### Zero-or-more traversals
|
|
273
|
+
|
|
274
|
+
`[:R*0..]` includes the starting node itself as a zero-hop match — see
|
|
275
|
+
[Paths → zero-hop](../queries/paths.md#zero-hop-semantics).
|
|
276
|
+
|
|
277
|
+
### Matching either direction on CREATE
|
|
278
|
+
|
|
279
|
+
```cypher
|
|
280
|
+
CREATE (a)-[:T]-(b) // error
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
Direction is required on writes. Decide which way makes sense.
|
|
284
|
+
|
|
285
|
+
### Deleting a relationship that's been matched twice
|
|
286
|
+
|
|
287
|
+
A query like `MATCH (a)-[r]->(b)-[r]->(c)` won't compile — `r` must be
|
|
288
|
+
unique. Use two distinct variables:
|
|
289
|
+
|
|
290
|
+
```cypher
|
|
291
|
+
MATCH (a)-[r1:T]->(b)-[r2:T]->(c)
|
|
292
|
+
RETURN r1, r2
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
### Multiple parallel edges
|
|
296
|
+
|
|
297
|
+
Nothing prevents two `KNOWS` edges between the same pair:
|
|
298
|
+
|
|
299
|
+
```cypher
|
|
300
|
+
CREATE (a)-[:KNOWS]->(b)
|
|
301
|
+
CREATE (a)-[:KNOWS]->(b)
|
|
302
|
+
// now there are two :KNOWS edges
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
Use `MERGE (a)-[:KNOWS]->(b)` for dedup. For modelling-time
|
|
306
|
+
uniqueness (one edge only), enforce in application code.
|
|
307
|
+
|
|
308
|
+
## Notes
|
|
309
|
+
|
|
310
|
+
- Relationship types are **case-sensitive**, conventionally `UPPER_SNAKE`.
|
|
311
|
+
- A relationship has **one** type — not a list.
|
|
312
|
+
- Relationships cannot be dangling — src and dst must both exist.
|
|
313
|
+
- Deleting a relationship does not delete its endpoints.
|
|
314
|
+
|
|
315
|
+
## See also
|
|
316
|
+
|
|
317
|
+
- [**Graph Model**](./graph-model.md) — where relationships fit.
|
|
318
|
+
- [**Nodes**](./nodes.md) — endpoints.
|
|
319
|
+
- [**Properties**](./properties.md) — key/value payload.
|
|
320
|
+
- [**CREATE**](../queries/create.md), [**MATCH**](../queries/match.md),
|
|
321
|
+
[**MERGE**](../queries/unwind-merge.md#merge),
|
|
322
|
+
[**SET / DELETE**](../queries/set-delete.md) — clause syntax.
|
|
323
|
+
- [**Paths**](../queries/paths.md) — variable-length and shortest-path traversals.
|
|
324
|
+
- [**Functions → Entity introspection**](../functions/overview.md#entity-introspection)
|
|
325
|
+
— `id`, `type`, `labels`, `keys`, `properties`.
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Query Result Formats"
|
|
3
|
+
description: "The four result shapes LoraDB returns — rows, rowArrays, graph, and combined — with the trade-offs between payload size, client ergonomics, and graph versus tabular access."
|
|
4
|
+
online: "https://loradb.com/docs/concepts/result-formats"
|
|
5
|
+
package: "@loradb/lora-node@0.36.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Query Result Formats
|
|
9
|
+
|
|
10
|
+
Every query returns the same data; the engine can shape it into one
|
|
11
|
+
of four wire formats. The choice is a trade-off between payload size,
|
|
12
|
+
ease of access in host code, and whether you want a row view or a
|
|
13
|
+
graph view.
|
|
14
|
+
|
|
15
|
+
## The four formats
|
|
16
|
+
|
|
17
|
+
| Format | Shape | Use when… |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| [`rows`](#rows) | One object per row, keyed by column. | Most app code — each row reads like a record. |
|
|
20
|
+
| [`rowArrays`](#rowarrays) | Columns plus tuple rows. | Wide result sets where keys are repetitive. |
|
|
21
|
+
| [`graph`](#graph) | De-duplicated nodes + relationships. | Rendering a graph — visualisers, diffs. |
|
|
22
|
+
| [`combined`](#combined) | Rows **and** a side graph. | You want both per-row data and the underlying entities. |
|
|
23
|
+
|
|
24
|
+
## Choosing a format
|
|
25
|
+
|
|
26
|
+
| If your consumer… | Pick |
|
|
27
|
+
|---|---|
|
|
28
|
+
| Reads values by column name | `rows` |
|
|
29
|
+
| Processes many rows with the same columns | `rowArrays` (smaller payload) |
|
|
30
|
+
| Draws a graph of matched entities | `graph` |
|
|
31
|
+
| Needs rows **and** the graph they touched | `combined` |
|
|
32
|
+
|
|
33
|
+
If you don't care: `rows` is the most ergonomic default in host code.
|
|
34
|
+
|
|
35
|
+
## Setting the format
|
|
36
|
+
|
|
37
|
+
| Transport | How |
|
|
38
|
+
|---|---|
|
|
39
|
+
| Rust / Node / Python / WASM / Go / Ruby | `ExecuteOptions { format }` or per-call option |
|
|
40
|
+
| HTTP | `"format": "rows"` in the `POST /query` body |
|
|
41
|
+
|
|
42
|
+
If omitted, the engine-default is [`graph`](#graph). Bindings may
|
|
43
|
+
override that default for ergonomics — for example, `lora-node` and
|
|
44
|
+
`lora-python` return `rows` unless you ask for another shape.
|
|
45
|
+
|
|
46
|
+
## `rows`
|
|
47
|
+
|
|
48
|
+
The most natural shape for application code: one JSON object per row,
|
|
49
|
+
keyed by the `RETURN` column name.
|
|
50
|
+
|
|
51
|
+
### Example
|
|
52
|
+
|
|
53
|
+
For `MATCH (p:Person) RETURN p.name AS name, p.born AS born`:
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"rows": [
|
|
58
|
+
{ "name": "Ada", "born": 1815 },
|
|
59
|
+
{ "name": "Grace", "born": 1906 }
|
|
60
|
+
]
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### When to prefer it
|
|
65
|
+
|
|
66
|
+
- You want to iterate with `row.name`, `row["name"]`, etc.
|
|
67
|
+
- Result sets are small-to-medium; the per-row key repetition isn't a
|
|
68
|
+
concern.
|
|
69
|
+
|
|
70
|
+
## `rowArrays`
|
|
71
|
+
|
|
72
|
+
Columns are listed once; rows are arrays indexed by column position.
|
|
73
|
+
|
|
74
|
+
### Example
|
|
75
|
+
|
|
76
|
+
```json
|
|
77
|
+
{
|
|
78
|
+
"columns": ["name", "born"],
|
|
79
|
+
"rows": [
|
|
80
|
+
["Ada", 1815],
|
|
81
|
+
["Grace", 1906]
|
|
82
|
+
]
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### When to prefer it
|
|
87
|
+
|
|
88
|
+
- Large result sets — avoids repeating the column keys per row.
|
|
89
|
+
- You're streaming into a tabular UI that already knows column order.
|
|
90
|
+
|
|
91
|
+
### Gotcha
|
|
92
|
+
|
|
93
|
+
You index rows by position. A schema change (e.g. reordering `RETURN`
|
|
94
|
+
expressions) breaks downstream code. Prefer `rows` for code that's
|
|
95
|
+
read outside the query author's head.
|
|
96
|
+
|
|
97
|
+
## `graph`
|
|
98
|
+
|
|
99
|
+
Every matched [node](./nodes.md) and [relationship](./relationships.md),
|
|
100
|
+
de-duplicated, with labels, types, and properties hydrated.
|
|
101
|
+
|
|
102
|
+
### Example
|
|
103
|
+
|
|
104
|
+
For `MATCH (a:Person)-[r:KNOWS]->(b:Person) RETURN a, r, b`:
|
|
105
|
+
|
|
106
|
+
```json
|
|
107
|
+
{
|
|
108
|
+
"graph": {
|
|
109
|
+
"nodes": [
|
|
110
|
+
{ "id": 1, "labels": ["Person"], "properties": { "name": "Ada" } },
|
|
111
|
+
{ "id": 2, "labels": ["Person"], "properties": { "name": "Grace" } }
|
|
112
|
+
],
|
|
113
|
+
"relationships": [
|
|
114
|
+
{ "id": 10, "startId": 1, "endId": 2, "type": "KNOWS", "properties": {} }
|
|
115
|
+
]
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### When to prefer it
|
|
121
|
+
|
|
122
|
+
- You're rendering the graph in a visualiser.
|
|
123
|
+
- You need every entity the query touched, exactly once, regardless of
|
|
124
|
+
how many rows referenced it.
|
|
125
|
+
|
|
126
|
+
### Gotcha
|
|
127
|
+
|
|
128
|
+
Scalar projections (`RETURN p.name`) don't contribute new entities to
|
|
129
|
+
the graph — you'll get an empty `nodes` / `relationships` list unless
|
|
130
|
+
the query returns nodes or relationships directly.
|
|
131
|
+
|
|
132
|
+
## `combined`
|
|
133
|
+
|
|
134
|
+
Rows and a side graph in one payload. Useful when you want both
|
|
135
|
+
per-row results and the backing entities (for example: rows for a
|
|
136
|
+
table, and nodes+edges for a graph preview beside it).
|
|
137
|
+
|
|
138
|
+
### Example
|
|
139
|
+
|
|
140
|
+
```json
|
|
141
|
+
{
|
|
142
|
+
"columns": ["a", "r", "b"],
|
|
143
|
+
"data": [
|
|
144
|
+
{ "a": { "$node": 1 }, "r": { "$rel": 10 }, "b": { "$node": 2 } }
|
|
145
|
+
],
|
|
146
|
+
"graph": {
|
|
147
|
+
"nodes": [ /* nodes 1 and 2, as in the `graph` format */ ],
|
|
148
|
+
"relationships": [ /* relationship 10 */ ]
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Entities in `data` appear as references (e.g. `{"$node": 1}`); their
|
|
154
|
+
full hydrated form lives in `graph`. This keeps the payload compact
|
|
155
|
+
when the same node appears in many rows.
|
|
156
|
+
|
|
157
|
+
### When to prefer it
|
|
158
|
+
|
|
159
|
+
- Dual views (table + graph) of the same query.
|
|
160
|
+
- You've got a UI that links a table row to a node on a canvas.
|
|
161
|
+
|
|
162
|
+
## Typed values in every format
|
|
163
|
+
|
|
164
|
+
Regardless of format, scalar and structured values round-trip through
|
|
165
|
+
the same [shared contract](../data-types/overview.md):
|
|
166
|
+
|
|
167
|
+
- Primitives — `Null`, `Boolean`, `Integer`, `Float`, `String`.
|
|
168
|
+
- [Lists & maps](../data-types/lists-and-maps.md).
|
|
169
|
+
- [Temporal values](../data-types/temporal.md) — tagged with
|
|
170
|
+
`{kind: "date" | "datetime" | …, iso: "…"}`.
|
|
171
|
+
- [Spatial points](../data-types/spatial.md) — tagged with
|
|
172
|
+
`{kind: "point", srid, crs, x, y[, z]}`.
|
|
173
|
+
- Graph values — tagged with `{kind: "node" | "relationship" | "path"}`.
|
|
174
|
+
|
|
175
|
+
Each language binding provides narrow type guards to tell them apart
|
|
176
|
+
(`isNode`, `is_point`, …).
|
|
177
|
+
|
|
178
|
+
## See also
|
|
179
|
+
|
|
180
|
+
- [Data types overview](../data-types/overview.md) — the value model.
|
|
181
|
+
- [Queries — Overview](../queries/index.md) — clauses and the pipeline.
|
|
182
|
+
- [HTTP API reference](https://loradb.com/docs/api/http) — how `format` is set over HTTP.
|
|
183
|
+
- [Troubleshooting → JSON/result format confusion](../troubleshooting.md#queries-return-empty-results).
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Schema-Free Writes and Soft Validation"
|
|
3
|
+
description: "How LoraDB handles schema — labels, relationship types, and property keys spring into existence on write, reads never depend on which names exist — and where validation still applies."
|
|
4
|
+
online: "https://loradb.com/docs/concepts/schema-free"
|
|
5
|
+
package: "@loradb/lora-node@0.36.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Schema-Free Writes and Soft Validation
|
|
9
|
+
|
|
10
|
+
**Writes are permissive, and so are reads.** `CREATE` / `MERGE` /
|
|
11
|
+
`SET` accept any label, relationship type, or property key without a
|
|
12
|
+
`CREATE TABLE` step — names come into existence the first time they're
|
|
13
|
+
written. `MATCH` accepts any name too: a label or relationship type no
|
|
14
|
+
entity carries simply matches nothing, and a missing property key
|
|
15
|
+
yields `null`.
|
|
16
|
+
|
|
17
|
+
That is standard Cypher behaviour, and it keeps answers stable: the same
|
|
18
|
+
query gives the same *kind* of answer on an empty graph, a populated
|
|
19
|
+
one, and one whose last `:Comment` was just deleted or rolled back.
|
|
20
|
+
Whether a query is valid never depends on what data happens to exist.
|
|
21
|
+
|
|
22
|
+
## What "schema-free" actually means
|
|
23
|
+
|
|
24
|
+
The graph tracks three things as the process runs:
|
|
25
|
+
|
|
26
|
+
- The set of **labels** seen on any node since process start.
|
|
27
|
+
- The set of **relationship types** seen on any relationship.
|
|
28
|
+
- The **property keys** seen on any node or relationship.
|
|
29
|
+
|
|
30
|
+
No declaration, no `ALTER TABLE`, no migration. The first write that
|
|
31
|
+
mentions a new name brings it into existence; subsequent writes reuse
|
|
32
|
+
it.
|
|
33
|
+
|
|
34
|
+
```cypher
|
|
35
|
+
CREATE (c:Country {name: 'NL', iso: 'NLD'})
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
On an empty graph, this creates the label `Country` and the property
|
|
39
|
+
keys `name` and `iso`. The next `MATCH (:Country)` will find it.
|
|
40
|
+
|
|
41
|
+
### Unknown names are not errors
|
|
42
|
+
|
|
43
|
+
A `MATCH` for a label that was **never** created is still a valid
|
|
44
|
+
query — it returns zero rows:
|
|
45
|
+
|
|
46
|
+
```cypher
|
|
47
|
+
MATCH (u:NeverWritten) RETURN u
|
|
48
|
+
// 0 rows
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The flip side: a typo such as `:Persn` also returns zero rows instead of
|
|
52
|
+
failing. Catch those in tests or with a small app-layer list of valid
|
|
53
|
+
labels (see [below](#when-to-add-a-soft-schema-at-the-app-layer)).
|
|
54
|
+
|
|
55
|
+
## Permissive writes
|
|
56
|
+
|
|
57
|
+
`CREATE`, [`MERGE`](../queries/unwind-merge.md#merge), and
|
|
58
|
+
[`SET`](../queries/set-delete.md) accept any name without complaint.
|
|
59
|
+
|
|
60
|
+
```cypher
|
|
61
|
+
CREATE (:Spaceship {name: 'Rocinante', crew: 4})
|
|
62
|
+
;// "Spaceship" was never declared. Fine — it now exists.
|
|
63
|
+
|
|
64
|
+
MATCH (s:Spaceship)
|
|
65
|
+
SET s.engine = 'Epstein drive'
|
|
66
|
+
// Adds a new property key; totally legal.
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
This is good for quick iteration and bad for safety. Unless you add a
|
|
70
|
+
[constraint](../queries/constraints.md), nothing prevents you from creating
|
|
71
|
+
a second `:Spaceship` with completely different properties, and nothing
|
|
72
|
+
ever stops you from typo-ing `Spaceshi` and polluting the label set.
|
|
73
|
+
|
|
74
|
+
### Things the engine won't catch without constraints
|
|
75
|
+
|
|
76
|
+
- Two `:Person` nodes with different property sets
|
|
77
|
+
(`{name, born}` vs `{username, dob}`).
|
|
78
|
+
- A property named `email` on one node and `e_mail` on another.
|
|
79
|
+
- A `:FOLLOWS` edge with an `active` property on one and not on
|
|
80
|
+
another.
|
|
81
|
+
- A property value that's an `Integer` in one place and `String` in
|
|
82
|
+
another.
|
|
83
|
+
|
|
84
|
+
If any of these matter, declare [constraints](../queries/constraints.md)
|
|
85
|
+
(existence, uniqueness, key, or property type), enforce them at the
|
|
86
|
+
application layer, or use [`MERGE`](#merge-for-idempotent-writes).
|
|
87
|
+
Differently-named keys such as `email` vs `e_mail` are only ever caught
|
|
88
|
+
at the application layer.
|
|
89
|
+
|
|
90
|
+
## Lenient reads
|
|
91
|
+
|
|
92
|
+
[`MATCH`](../queries/match.md) does not check label, relationship-type, or
|
|
93
|
+
property-key names against the stored data. The same rules hold on an
|
|
94
|
+
empty graph, a populated one, and after the last entity of a kind was
|
|
95
|
+
deleted, had its label removed, or was rolled back:
|
|
96
|
+
|
|
97
|
+
- A label or relationship type no entity carries matches nothing.
|
|
98
|
+
- A property key an entity doesn't have yields `null` on access. See
|
|
99
|
+
[Properties → missing vs null](./properties.md#missing-vs-null).
|
|
100
|
+
- `OPTIONAL MATCH` over an unknown name keeps the outer row with
|
|
101
|
+
`null`s; `UNION` branches over unknown names contribute no rows.
|
|
102
|
+
|
|
103
|
+
### Reading back what you wrote
|
|
104
|
+
|
|
105
|
+
```cypher
|
|
106
|
+
CREATE (:Spaceship {name: 'Rocinante'});
|
|
107
|
+
MATCH (s:Spaceship) RETURN s; // 1 row
|
|
108
|
+
MATCH (s:NeverWritten) RETURN s; // 0 rows — not an error
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
## `MERGE` for idempotent writes
|
|
112
|
+
|
|
113
|
+
`MERGE` is the write-side idempotency tool: it matches on the given
|
|
114
|
+
pattern, creating only if missing. Add a uniqueness constraint when you
|
|
115
|
+
also need the database to reject duplicate keys:
|
|
116
|
+
|
|
117
|
+
```cypher
|
|
118
|
+
MERGE (u:User {email: $email})
|
|
119
|
+
ON CREATE SET u.created = temporal.timestamp()
|
|
120
|
+
ON MATCH SET u.last_seen = temporal.timestamp()
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
It's an important building block for schema-free writes:
|
|
124
|
+
|
|
125
|
+
- **Safe upsert** — a repeated run won't create duplicates.
|
|
126
|
+
- **Constraint-friendly** — a matching uniqueness constraint rejects
|
|
127
|
+
competing duplicate writes. See [Constraints](../queries/constraints.md).
|
|
128
|
+
- **No index required** — without a supporting index or constraint,
|
|
129
|
+
`MERGE` scans the label/type scope for the key map, which is fine for
|
|
130
|
+
moderate scales. See [Limitations → Storage](../limitations.md#storage).
|
|
131
|
+
|
|
132
|
+
See [MERGE](../queries/unwind-merge.md#merge) for the full reference.
|
|
133
|
+
|
|
134
|
+
## Runtime type checks
|
|
135
|
+
|
|
136
|
+
Because a property's type is only enforced when written — not when
|
|
137
|
+
declared — you occasionally need to verify it at query time:
|
|
138
|
+
|
|
139
|
+
```cypher
|
|
140
|
+
MATCH (r:Record)
|
|
141
|
+
WHERE type.of(r.id) = 'INTEGER'
|
|
142
|
+
RETURN r
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
See [Functions → type conversion and checking](../functions/overview.md#type-conversion-and-checking)
|
|
146
|
+
for `type.of`, `toInteger`, `toString`, and friends.
|
|
147
|
+
|
|
148
|
+
## Trade-offs at a glance
|
|
149
|
+
|
|
150
|
+
| Property | Traditional schema | LoraDB |
|
|
151
|
+
|---|---|---|
|
|
152
|
+
| Declare up front | Required (`CREATE TABLE`) | Not required |
|
|
153
|
+
| Add a new property | Migration | Just `SET it` |
|
|
154
|
+
| Enforce "every node has X" | Constraint | [Existence constraint](../queries/constraints.md) (`IS NOT NULL`) |
|
|
155
|
+
| Enforce "X is unique" | `UNIQUE` | [Uniqueness constraint](../queries/constraints.md) + `MERGE` on the key |
|
|
156
|
+
| Catch typos in writes | Schema | Code review / tests |
|
|
157
|
+
| Catch typos in reads | Schema | Tests / app-layer name list — unknown names return zero rows |
|
|
158
|
+
| Index lookups | Explicit schema-managed indexes | Optional RANGE/TEXT/POINT/LOOKUP/VECTOR/FULLTEXT indexes for performance and search |
|
|
159
|
+
|
|
160
|
+
## When to add a "soft schema" at the app layer
|
|
161
|
+
|
|
162
|
+
Schema-free is a tool, not a lifestyle. If your data model stabilises,
|
|
163
|
+
pin it down in host code:
|
|
164
|
+
|
|
165
|
+
- A small module that returns the valid labels / types and fails fast
|
|
166
|
+
on typos.
|
|
167
|
+
- A `create_user` function that's the *only* writer of `:User` nodes
|
|
168
|
+
and always sets the same property keys.
|
|
169
|
+
- A `MERGE` on the business key rather than letting callers fan out
|
|
170
|
+
to different shapes.
|
|
171
|
+
|
|
172
|
+
You lose the "schema" catch-your-typo net. Good architecture puts the
|
|
173
|
+
net back, where it's cheap.
|
|
174
|
+
|
|
175
|
+
## See also
|
|
176
|
+
|
|
177
|
+
- [Graph data model](./graph-model.md) — nodes, relationships, properties.
|
|
178
|
+
- [MERGE](../queries/unwind-merge.md#merge) — idempotent writes.
|
|
179
|
+
- [Properties](./properties.md) — missing vs null, value typing.
|
|
180
|
+
- [Troubleshooting → Semantic errors](../troubleshooting.md#semantic-errors)
|
|
181
|
+
— what the analyzer still rejects.
|
|
182
|
+
- [Limitations → Storage](../limitations.md#storage) — scoped index and
|
|
183
|
+
constraint coverage.
|