@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,348 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Properties on Nodes and Relationships"
|
|
3
|
+
description: "Typed key/value properties on nodes and relationships in LoraDB — reading, setting, removing, and the type rules that apply to each supported data type."
|
|
4
|
+
online: "https://loradb.com/docs/concepts/properties"
|
|
5
|
+
package: "@loradb/lora-node@0.36.2"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Properties on Nodes and Relationships
|
|
9
|
+
|
|
10
|
+
**Properties** are typed key/value pairs attached to
|
|
11
|
+
[nodes](./nodes.md) and [relationships](./relationships.md). Keys are
|
|
12
|
+
case-sensitive strings; values are any of the
|
|
13
|
+
[supported data types](../data-types/overview.md).
|
|
14
|
+
|
|
15
|
+
## At a glance
|
|
16
|
+
|
|
17
|
+
| Operation | Clause |
|
|
18
|
+
|---|---|
|
|
19
|
+
| Set a single key | `SET n.prop = value` |
|
|
20
|
+
| Merge keys | `SET n += {k: v}` |
|
|
21
|
+
| Replace the whole map | `SET n = {…}` |
|
|
22
|
+
| Remove a key | `REMOVE n.prop` / `SET n.prop = null` |
|
|
23
|
+
| Bulk patch from param | `SET n += $patch` |
|
|
24
|
+
| Read a key | `n.prop` |
|
|
25
|
+
| Read the whole map | `properties(n)` |
|
|
26
|
+
| List the keys | `keys(n)` |
|
|
27
|
+
| Project a subset | `n {.name, .born}` |
|
|
28
|
+
|
|
29
|
+
## Write properties
|
|
30
|
+
|
|
31
|
+
### On create
|
|
32
|
+
|
|
33
|
+
```cypher
|
|
34
|
+
CREATE (:City {
|
|
35
|
+
name: 'Amsterdam',
|
|
36
|
+
population: 918000,
|
|
37
|
+
location: {latitude: 52.37, longitude: 4.89}::POINT,
|
|
38
|
+
founded: '1275-10-27'::DATE,
|
|
39
|
+
tags: ['capital', 'port']
|
|
40
|
+
})
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### On an existing entity
|
|
44
|
+
|
|
45
|
+
```cypher
|
|
46
|
+
MATCH (c:City {name: 'Amsterdam'})
|
|
47
|
+
SET c.population = 920000
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### Patch with a parameter map
|
|
51
|
+
|
|
52
|
+
```cypher
|
|
53
|
+
MATCH (c:City {name: 'Amsterdam'})
|
|
54
|
+
SET c += $patch
|
|
55
|
+
RETURN c
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
See [`SET`](../queries/set-delete.md#set--properties) for the full rules
|
|
59
|
+
on `=`, `+=`, and `null` assignment.
|
|
60
|
+
|
|
61
|
+
## Read properties
|
|
62
|
+
|
|
63
|
+
### Dot access
|
|
64
|
+
|
|
65
|
+
```cypher
|
|
66
|
+
MATCH (c:City {name: 'Amsterdam'})
|
|
67
|
+
RETURN c.name, c.population, c.location.latitude
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
### Bracket access (computed key)
|
|
71
|
+
|
|
72
|
+
```cypher
|
|
73
|
+
MATCH (c:City {name: 'Amsterdam'})
|
|
74
|
+
WITH c, 'population' AS k
|
|
75
|
+
RETURN c[k]
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
### Full map
|
|
79
|
+
|
|
80
|
+
```cypher
|
|
81
|
+
MATCH (c:City) RETURN properties(c)
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### Key list
|
|
85
|
+
|
|
86
|
+
```cypher
|
|
87
|
+
MATCH (c:City) RETURN keys(c) // e.g. ['name', 'population', …]
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Map projection
|
|
91
|
+
|
|
92
|
+
Shape an entity into a map with only the keys you want — see also
|
|
93
|
+
[Lists & Maps → Map projection](../data-types/lists-and-maps.md#map-projection):
|
|
94
|
+
|
|
95
|
+
```cypher
|
|
96
|
+
MATCH (c:City)
|
|
97
|
+
RETURN c {.name, .population};
|
|
98
|
+
RETURN c {.*};
|
|
99
|
+
RETURN c {.name, density: c.population / c.area}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Update
|
|
103
|
+
|
|
104
|
+
| Operation | Clause |
|
|
105
|
+
|---|---|
|
|
106
|
+
| Set a single property | `SET n.prop = value` |
|
|
107
|
+
| Merge keys into the map | `SET n += {k1: v1, k2: v2}` |
|
|
108
|
+
| Replace the whole map | `SET n = {…}` |
|
|
109
|
+
| Remove a property | `REMOVE n.prop` or `SET n.prop = null` |
|
|
110
|
+
|
|
111
|
+
```cypher
|
|
112
|
+
MATCH (c:City {name: 'Amsterdam'})
|
|
113
|
+
SET c += {updated_at: temporal.now(), active: true}
|
|
114
|
+
RETURN c
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Replace vs merge
|
|
118
|
+
|
|
119
|
+
`SET n = {…}` **replaces** the entire property map — every key not in
|
|
120
|
+
the new map is dropped. `SET n += {…}` only adds/overwrites the listed
|
|
121
|
+
keys. Pick `+=` for partial updates (almost always what you want). See
|
|
122
|
+
[Troubleshooting → SET wiped my properties](../troubleshooting.md#set-wiped-my-properties).
|
|
123
|
+
|
|
124
|
+
## Properties on relationships
|
|
125
|
+
|
|
126
|
+
Identical shape — relationships have their own property map.
|
|
127
|
+
|
|
128
|
+
```cypher
|
|
129
|
+
MATCH (a)-[r:KNOWS]->(b)
|
|
130
|
+
SET r.since = 2020, r.visibility = 'public'
|
|
131
|
+
RETURN r.since
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Value types
|
|
135
|
+
|
|
136
|
+
Properties accept every [LoraDB data type](../data-types/overview.md):
|
|
137
|
+
|
|
138
|
+
| Category | Pages |
|
|
139
|
+
|---|---|
|
|
140
|
+
| Scalars (`Null`, `Boolean`, `Integer`, `Float`, `String`) | [Scalars](../data-types/scalars.md) |
|
|
141
|
+
| Collections (`List`, `Map`) | [Lists & Maps](../data-types/lists-and-maps.md) |
|
|
142
|
+
| Temporals (`Date`, `Time`, `DateTime`, `Duration`, …) | [Temporal](../data-types/temporal.md) |
|
|
143
|
+
| Spatial (`Point`) | [Spatial](../data-types/spatial.md) |
|
|
144
|
+
| `Vector` (typed fixed-dimension coordinates) | [Vectors](../data-types/vectors.md) |
|
|
145
|
+
|
|
146
|
+
Graph types (`Node`, `Relationship`, `Path`) are **not** storable as
|
|
147
|
+
properties — they only appear in query results. Writing one, even inside
|
|
148
|
+
a list or map, is an error (`cannot store a node as a property`) and the
|
|
149
|
+
statement changes nothing; store `id(n)` or a key property instead.
|
|
150
|
+
|
|
151
|
+
A `VECTOR` can be a property value and can appear as a value inside a
|
|
152
|
+
`Map` property, but a **list that contains a `VECTOR` is rejected at
|
|
153
|
+
write time** — store many embeddings as separate nodes, not as a list.
|
|
154
|
+
See [Vectors → Storage](../data-types/vectors.md#storage) for the exact
|
|
155
|
+
rule.
|
|
156
|
+
|
|
157
|
+
## Common patterns
|
|
158
|
+
|
|
159
|
+
### Default via coalesce
|
|
160
|
+
|
|
161
|
+
```cypher
|
|
162
|
+
MATCH (u:User)
|
|
163
|
+
RETURN u.name, coalesce(u.nickname, u.name) AS display
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
`coalesce` returns the first non-null argument, so users with a
|
|
167
|
+
nickname get it under `display` and everyone else falls back to
|
|
168
|
+
`name`. No extra row work — this is a per-row projection.
|
|
169
|
+
|
|
170
|
+
### Touch a timestamp on write
|
|
171
|
+
|
|
172
|
+
```cypher
|
|
173
|
+
MATCH (u:User {id: $id})
|
|
174
|
+
SET u.last_seen = temporal.timestamp()
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### Migrate a property
|
|
178
|
+
|
|
179
|
+
```cypher
|
|
180
|
+
MATCH (u:User)
|
|
181
|
+
WHERE u.full_name IS NOT NULL AND u.name IS NULL
|
|
182
|
+
SET u.name = u.full_name
|
|
183
|
+
REMOVE u.full_name
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
Moves values from `full_name` to `name` on every matched row.
|
|
187
|
+
Because the predicate filters out rows that already have a `name`,
|
|
188
|
+
this is safe to re-run — users who are already migrated are
|
|
189
|
+
skipped.
|
|
190
|
+
|
|
191
|
+
### Conditional add
|
|
192
|
+
|
|
193
|
+
```cypher
|
|
194
|
+
MERGE (u:User {id: $id})
|
|
195
|
+
ON CREATE SET u.created = temporal.timestamp()
|
|
196
|
+
SET u.updated = temporal.timestamp()
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
### Copy properties from one entity to another
|
|
200
|
+
|
|
201
|
+
```cypher
|
|
202
|
+
MATCH (src:Template {id: $src}), (dst:Record {id: $dst})
|
|
203
|
+
SET dst += properties(src)
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
[`properties(src)`](../functions/overview.md#entity-introspection)
|
|
207
|
+
returns every key on `src` as a map; `+=` merges that map into
|
|
208
|
+
`dst`, overwriting matching keys and leaving anything unique to
|
|
209
|
+
`dst` untouched. Useful for applying a template over an existing
|
|
210
|
+
record without nuking custom fields.
|
|
211
|
+
|
|
212
|
+
### Bulk patch via UNWIND
|
|
213
|
+
|
|
214
|
+
```cypher
|
|
215
|
+
UNWIND $patches AS patch
|
|
216
|
+
MATCH (u:User {id: patch.id})
|
|
217
|
+
SET u += patch.fields
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
### Derived property with CASE
|
|
221
|
+
|
|
222
|
+
```cypher
|
|
223
|
+
MATCH (u:User)
|
|
224
|
+
SET u.tier = CASE
|
|
225
|
+
WHEN u.score >= 1000 THEN 'platinum'
|
|
226
|
+
WHEN u.score >= 100 THEN 'gold'
|
|
227
|
+
ELSE 'bronze'
|
|
228
|
+
END
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
See [`CASE`](../queries/return-with.md#case-expressions).
|
|
232
|
+
|
|
233
|
+
### Compact property dump for debugging
|
|
234
|
+
|
|
235
|
+
```cypher
|
|
236
|
+
MATCH (n)
|
|
237
|
+
WHERE id(n) = $raw_id
|
|
238
|
+
RETURN labels(n) AS labels,
|
|
239
|
+
keys(n) AS keys,
|
|
240
|
+
properties(n) AS props
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
### Keys as a set
|
|
244
|
+
|
|
245
|
+
`keys(n)` is a list. Use list predicates to ask set-style questions:
|
|
246
|
+
|
|
247
|
+
```cypher
|
|
248
|
+
MATCH (u:User)
|
|
249
|
+
WHERE all(k IN ['email', 'name', 'created_at'] WHERE k IN keys(u))
|
|
250
|
+
RETURN u
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
One row per user who carries all three required keys — the list
|
|
254
|
+
predicate [`all`](../functions/list.md#predicates-in-where) holds only
|
|
255
|
+
when every element of the input list passes the inner `WHERE`. Swap
|
|
256
|
+
`all` for `none` to find users *missing* a required key.
|
|
257
|
+
|
|
258
|
+
### Nullable property check
|
|
259
|
+
|
|
260
|
+
```cypher
|
|
261
|
+
MATCH (n)
|
|
262
|
+
WHERE n.optional IS NULL RETURN n; // missing or explicitly null
|
|
263
|
+
MATCH (n)
|
|
264
|
+
WHERE n.optional IS NOT NULL RETURN n // present and non-null
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
## Edge cases
|
|
268
|
+
|
|
269
|
+
### Missing vs null
|
|
270
|
+
|
|
271
|
+
A missing key and a key set to `null` are indistinguishable — both
|
|
272
|
+
return `null` on access. `SET n.prop = null` is the idiomatic way to
|
|
273
|
+
remove a key (see [SET](../queries/set-delete.md#clear-a-property)).
|
|
274
|
+
|
|
275
|
+
### Keys as strings
|
|
276
|
+
|
|
277
|
+
Keys are always case-sensitive strings. `user.Name` ≠ `user.name`.
|
|
278
|
+
|
|
279
|
+
### Type drift
|
|
280
|
+
|
|
281
|
+
Without a property type constraint, the same key can hold different
|
|
282
|
+
types on different entities:
|
|
283
|
+
|
|
284
|
+
```cypher
|
|
285
|
+
CREATE (:Item {stock: 5})
|
|
286
|
+
CREATE (:Item {stock: '5'}) // legal but will surprise you
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
Use [`type.of`](../functions/overview.md#type-conversion-and-checking)
|
|
290
|
+
to detect at query time, normalise on write, or add a
|
|
291
|
+
[property type constraint](../queries/constraints.md#property-types) for
|
|
292
|
+
labels or relationship types that need a fixed shape.
|
|
293
|
+
|
|
294
|
+
### Indexes and nested values
|
|
295
|
+
|
|
296
|
+
Property filters without a label are broad scans. Always scope to a
|
|
297
|
+
label when you can, and add an explicit index for hot top-level
|
|
298
|
+
properties:
|
|
299
|
+
|
|
300
|
+
```cypher
|
|
301
|
+
CREATE INDEX user_email FOR (u:User) ON (u.email)
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
```cypher
|
|
305
|
+
MATCH (u:User {email: $email}) RETURN u
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
Broad scan shape to avoid on hot paths:
|
|
309
|
+
|
|
310
|
+
```cypher
|
|
311
|
+
MATCH (u {email: $email}) RETURN u
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
See [Queries → Indexes](../queries/indexes.md).
|
|
315
|
+
|
|
316
|
+
### Deep property paths
|
|
317
|
+
|
|
318
|
+
Accessing nested map keys works:
|
|
319
|
+
|
|
320
|
+
```cypher
|
|
321
|
+
MATCH (c:City)
|
|
322
|
+
RETURN c.location.latitude, c.tags[0]
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
But explicit indexes target top-level entity properties, not inner map
|
|
326
|
+
paths. For frequent inner-key filters, promote to a dedicated property
|
|
327
|
+
at write time.
|
|
328
|
+
|
|
329
|
+
## Notes
|
|
330
|
+
|
|
331
|
+
- Property keys are case-sensitive strings.
|
|
332
|
+
- A single entity can hold any number of properties.
|
|
333
|
+
- Required properties and property types are optional constraints; when
|
|
334
|
+
no constraint is present, different nodes with the same label can have
|
|
335
|
+
different property sets.
|
|
336
|
+
- For the full type catalogue see [Data Types](../data-types/overview.md).
|
|
337
|
+
|
|
338
|
+
## See also
|
|
339
|
+
|
|
340
|
+
- [**Graph Model**](./graph-model.md) — where properties fit.
|
|
341
|
+
- [**Nodes**](./nodes.md) / [**Relationships**](./relationships.md) — carriers.
|
|
342
|
+
- [**Data Types**](../data-types/overview.md) — value types.
|
|
343
|
+
- [**SET / REMOVE / DELETE**](../queries/set-delete.md) — mutation clauses.
|
|
344
|
+
- [**WHERE**](../queries/where.md) — property-based filters.
|
|
345
|
+
- [**Constraints**](../queries/constraints.md) — required properties,
|
|
346
|
+
uniqueness, keys, and property types.
|
|
347
|
+
- [**Functions → Entity introspection**](../functions/overview.md#entity-introspection)
|
|
348
|
+
— `keys`, `properties`, `id`.
|
|
@@ -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.2"
|
|
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`.
|