@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,285 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Nodes and Labels"
|
|
3
|
+
description: "How LoraDB represents nodes — vertices with zero or more labels, properties, and a stable internal id — and how to create, match, and label them with Cypher."
|
|
4
|
+
online: "https://loradb.com/docs/concepts/nodes"
|
|
5
|
+
package: "@loradb/lora-node@0.36.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Nodes and Labels
|
|
9
|
+
|
|
10
|
+
A **node** is a vertex in the graph. Every node has:
|
|
11
|
+
|
|
12
|
+
- Zero or more **labels** — tags that describe what kind of thing it
|
|
13
|
+
is (`Person`, `Movie`).
|
|
14
|
+
- Zero or more **[properties](./properties.md)** — typed key/value pairs.
|
|
15
|
+
- A stable internal **id** — see
|
|
16
|
+
[Graph Model → Identity](./graph-model.md#identity).
|
|
17
|
+
|
|
18
|
+
Each node is stored once. Multiple references to the same node via
|
|
19
|
+
different matches bind to the same identity.
|
|
20
|
+
|
|
21
|
+
## Create
|
|
22
|
+
|
|
23
|
+
```cypher
|
|
24
|
+
CREATE (:Person {name: 'Ada', born: 1815}) // one label
|
|
25
|
+
CREATE (:Person:Admin {name: 'Bob'}) // multiple labels
|
|
26
|
+
CREATE (:Temp) // no properties
|
|
27
|
+
CREATE () // no labels, no properties
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Even a fully-naked `()` is a valid node. Most real graphs give every
|
|
31
|
+
node at least one label — it's the primary way to scope queries.
|
|
32
|
+
|
|
33
|
+
### Bind a variable at creation
|
|
34
|
+
|
|
35
|
+
```cypher
|
|
36
|
+
CREATE (ada:Person {name: 'Ada'})
|
|
37
|
+
CREATE (ada)-[:WROTE]->(n:Note {text: 'Bernoulli numbers'})
|
|
38
|
+
RETURN ada, n
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Variables (`ada`, `n`) stay in scope for the rest of the query.
|
|
42
|
+
|
|
43
|
+
## Match by label
|
|
44
|
+
|
|
45
|
+
Labels are the primary way to scope a query.
|
|
46
|
+
|
|
47
|
+
```cypher
|
|
48
|
+
MATCH (p:Person) RETURN p; // single label
|
|
49
|
+
MATCH (a:Person:Admin) RETURN a; // must have both
|
|
50
|
+
MATCH (n) RETURN labels(n) // any node — all labels
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### Match by label + property
|
|
54
|
+
|
|
55
|
+
```cypher
|
|
56
|
+
MATCH (u:User {email: $email}) RETURN u;
|
|
57
|
+
MATCH (u:User {email: $email, active: true}) RETURN u
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Inline maps are equality-only. For ranges, regex, `IN`, or null
|
|
61
|
+
checks, move the predicate into [`WHERE`](../queries/where.md):
|
|
62
|
+
|
|
63
|
+
```cypher
|
|
64
|
+
MATCH (u:User)
|
|
65
|
+
WHERE u.age BETWEEN 18 AND 65 // NOT supported
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
```cypher
|
|
69
|
+
MATCH (u:User)
|
|
70
|
+
WHERE u.age >= 18 AND u.age <= 65 // idiomatic in LoraDB
|
|
71
|
+
RETURN u
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Labels
|
|
75
|
+
|
|
76
|
+
```cypher
|
|
77
|
+
MATCH (n:Person {name: 'Ada'}) SET n:Pioneer RETURN labels(n);
|
|
78
|
+
MATCH (n:Person {name: 'Ada'}) REMOVE n:Pioneer RETURN labels(n)
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Multiple labels
|
|
82
|
+
|
|
83
|
+
A node can have any number of labels, including zero:
|
|
84
|
+
|
|
85
|
+
```cypher
|
|
86
|
+
MATCH (n:Person {name: 'Ada'}) SET n:Admin, n:Verified
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
### Inspect labels
|
|
90
|
+
|
|
91
|
+
```cypher
|
|
92
|
+
MATCH (n) RETURN labels(n), count(*)
|
|
93
|
+
ORDER BY count(*) DESC
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
One row per distinct label-set in the graph.
|
|
97
|
+
|
|
98
|
+
### Conventions
|
|
99
|
+
|
|
100
|
+
- **Case-sensitive** strings.
|
|
101
|
+
- Conventionally **PascalCase** (`Person`, not `person`).
|
|
102
|
+
- Use singular nouns (`User`, not `Users`).
|
|
103
|
+
|
|
104
|
+
See [Troubleshooting → Queries return empty results](../troubleshooting.md#queries-return-empty-results)
|
|
105
|
+
for the classic `:user` vs `:User` mistake.
|
|
106
|
+
|
|
107
|
+
## Properties on nodes
|
|
108
|
+
|
|
109
|
+
Any [supported data type](../data-types/overview.md):
|
|
110
|
+
|
|
111
|
+
```cypher
|
|
112
|
+
CREATE (c:City {
|
|
113
|
+
name: 'Amsterdam',
|
|
114
|
+
population: 918000,
|
|
115
|
+
founded: '1275-10-27'::DATE,
|
|
116
|
+
tags: ['capital', 'port'],
|
|
117
|
+
location: {latitude: 52.37, longitude: 4.89}::POINT
|
|
118
|
+
})
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
Read, patch, and remove with [`SET` / `REMOVE`](../queries/set-delete.md):
|
|
122
|
+
|
|
123
|
+
```cypher
|
|
124
|
+
MATCH (c:City {name: 'Amsterdam'}) RETURN c.population, c.tags;
|
|
125
|
+
|
|
126
|
+
MATCH (c:City {name: 'Amsterdam'})
|
|
127
|
+
SET c.population = 920000, c.updated = temporal.timestamp()
|
|
128
|
+
RETURN c
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
See [Properties](./properties.md) for the full reference.
|
|
132
|
+
|
|
133
|
+
## Upsert
|
|
134
|
+
|
|
135
|
+
[`MERGE`](../queries/unwind-merge.md#merge) finds a node, or creates one.
|
|
136
|
+
Pair with [`ON MATCH` / `ON CREATE`](../queries/unwind-merge.md#on-match--on-create)
|
|
137
|
+
to run different side-effects per branch:
|
|
138
|
+
|
|
139
|
+
```cypher
|
|
140
|
+
MERGE (u:User {email: $email})
|
|
141
|
+
ON CREATE SET u.created_at = temporal.timestamp()
|
|
142
|
+
SET u.last_seen = temporal.timestamp()
|
|
143
|
+
RETURN u
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## Delete
|
|
147
|
+
|
|
148
|
+
```cypher
|
|
149
|
+
// Standalone node (no edges)
|
|
150
|
+
MATCH (n:Temp) DELETE n
|
|
151
|
+
|
|
152
|
+
;// Node + all edges
|
|
153
|
+
MATCH (n:User {id: $id}) DETACH DELETE n
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
See [`DETACH DELETE`](../queries/set-delete.md#detach-delete) for details.
|
|
157
|
+
|
|
158
|
+
## Common patterns
|
|
159
|
+
|
|
160
|
+
### Count by label
|
|
161
|
+
|
|
162
|
+
```cypher
|
|
163
|
+
MATCH (n) RETURN labels(n) AS labels, count(*) AS n
|
|
164
|
+
ORDER BY n DESC
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
### Ensure uniqueness at write time
|
|
168
|
+
|
|
169
|
+
Use `MERGE` for idempotent writes:
|
|
170
|
+
|
|
171
|
+
```cypher
|
|
172
|
+
MERGE (u:User {email: $email})
|
|
173
|
+
ON CREATE SET u.created_at = temporal.timestamp()
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
When duplicate values must be rejected across all `:User` nodes, add a
|
|
177
|
+
uniqueness constraint:
|
|
178
|
+
|
|
179
|
+
```cypher
|
|
180
|
+
CREATE CONSTRAINT user_email
|
|
181
|
+
FOR (u:User)
|
|
182
|
+
REQUIRE u.email IS UNIQUE
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
### Pattern-match on one label, filter on another
|
|
186
|
+
|
|
187
|
+
```cypher
|
|
188
|
+
MATCH (n:Person)
|
|
189
|
+
WHERE NOT 'Admin' IN node.labels(n)
|
|
190
|
+
RETURN n
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
### Sample a few of each
|
|
194
|
+
|
|
195
|
+
```cypher
|
|
196
|
+
MATCH (n)
|
|
197
|
+
WITH labels(n)[0] AS label, n
|
|
198
|
+
WITH label, collect(n)[..3] AS sample
|
|
199
|
+
RETURN label, sample
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### Find nodes without a given relationship
|
|
203
|
+
|
|
204
|
+
Anti-pattern: "who doesn't…" — use
|
|
205
|
+
[`NOT EXISTS { … }`](../queries/where.md#pattern-existence):
|
|
206
|
+
|
|
207
|
+
```cypher
|
|
208
|
+
MATCH (u:User)
|
|
209
|
+
WHERE NOT EXISTS { (u)-[:WROTE]->(:Post) }
|
|
210
|
+
RETURN u.handle
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
### Bulk label migration
|
|
214
|
+
|
|
215
|
+
```cypher
|
|
216
|
+
MATCH (u:User)
|
|
217
|
+
WHERE u.role = 'admin' AND NOT 'Admin' IN node.labels(u)
|
|
218
|
+
SET u:Admin
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
### Move properties between nodes
|
|
222
|
+
|
|
223
|
+
```cypher
|
|
224
|
+
MATCH (src:Person {id: $src}), (dst:Person {id: $dst})
|
|
225
|
+
SET dst += properties(src)
|
|
226
|
+
REMOVE src:Person
|
|
227
|
+
SET src:Archived
|
|
228
|
+
SET src.archived_at = temporal.timestamp()
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
### Split one node into two
|
|
232
|
+
|
|
233
|
+
A modelling change where a property becomes its own entity — useful
|
|
234
|
+
when the value starts being reachable from multiple sides:
|
|
235
|
+
|
|
236
|
+
```cypher
|
|
237
|
+
MATCH (u:User) WHERE u.company IS NOT NULL
|
|
238
|
+
WITH u, u.company AS company
|
|
239
|
+
MERGE (c:Company {name: company})
|
|
240
|
+
CREATE (u)-[:WORKS_AT]->(c)
|
|
241
|
+
REMOVE u.company
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
## Edge cases
|
|
245
|
+
|
|
246
|
+
### Labelless nodes
|
|
247
|
+
|
|
248
|
+
Valid but rare. They don't show up in `MATCH (:Any_Label)` patterns
|
|
249
|
+
and are hard to find without the `id()` function.
|
|
250
|
+
|
|
251
|
+
### Many labels
|
|
252
|
+
|
|
253
|
+
Matching `(n:A:B:C)` requires **all** listed labels. If you want "any
|
|
254
|
+
of", `UNION` two matches or use `WHERE`:
|
|
255
|
+
|
|
256
|
+
```cypher
|
|
257
|
+
MATCH (n)
|
|
258
|
+
WHERE 'Person' IN node.labels(n) OR 'Robot' IN node.labels(n)
|
|
259
|
+
RETURN n
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
### Property-only match
|
|
263
|
+
|
|
264
|
+
```cypher
|
|
265
|
+
MATCH (n {external_id: $id}) RETURN n
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
This scans the entire node set — no label scoping. Always add a label
|
|
269
|
+
when you can.
|
|
270
|
+
|
|
271
|
+
### Identity vs equality
|
|
272
|
+
|
|
273
|
+
Two nodes with identical labels and properties are still distinct — they
|
|
274
|
+
have different internal ids. Use [`id()`](../functions/overview.md#entity-introspection)
|
|
275
|
+
to compare identity; use property equality for value-based matching.
|
|
276
|
+
|
|
277
|
+
## See also
|
|
278
|
+
|
|
279
|
+
- [**Graph Model**](./graph-model.md) — the model as a whole.
|
|
280
|
+
- [**Relationships**](./relationships.md) — edges between nodes.
|
|
281
|
+
- [**Properties**](./properties.md) — per-node key/value pairs.
|
|
282
|
+
- [**CREATE**](../queries/create.md), [**MATCH**](../queries/match.md),
|
|
283
|
+
[**SET / REMOVE / DELETE**](../queries/set-delete.md) — clause syntax.
|
|
284
|
+
- [**MERGE**](../queries/unwind-merge.md#merge) — create-or-match.
|
|
285
|
+
- [**Troubleshooting**](../troubleshooting.md) — common match-failure causes.
|
|
@@ -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.1"
|
|
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`.
|