@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
package/README.md CHANGED
@@ -13,6 +13,11 @@ dedicated vitest).
13
13
 
14
14
  > **Package:** `@loradb/lora-node`.
15
15
 
16
+ > **Offline docs:** the published package includes a plain-Markdown copy of
17
+ > the LoraDB documentation for its own version under `docs/` (start at
18
+ > `node_modules/@loradb/lora-node/docs/README.md`). Coding agents and editors can read
19
+ > it without network access. The full site is at https://loradb.com/docs.
20
+
16
21
  ## Install (local dev)
17
22
 
18
23
  From the repository root:
package/docs/README.md ADDED
@@ -0,0 +1,86 @@
1
+ # @loradb/lora-node documentation
2
+
3
+ <!-- generated by scripts/bundle-package-docs.mjs -->
4
+
5
+ Offline copy of the LoraDB documentation for **@loradb/lora-node@0.36.2**. It describes
6
+ the version installed next to it, which can differ from the latest docs
7
+ on https://loradb.com/docs. Links to pages that are not bundled here point to
8
+ the website.
9
+
10
+ Everything else (other language bindings, the HTTP server, release notes)
11
+ lives at https://loradb.com/docs and https://loradb.com/llms.txt.
12
+
13
+ ## Overview
14
+
15
+ - [What is LoraDB](./index.md): LoraDB is a local-first, in-memory property-graph engine in Rust that speaks a pragmatic subset of Cypher, with Node.js / Python / WASM / Go / Ruby bindings, snapshots on every binding, and optional WAL-backed durability on every filesystem-backed surface.
16
+ - [Why LoraDB](./why.md): Why a local-first, in-memory property-graph engine in Rust that speaks a pragmatic subset of Cypher — built for systems that reason over connected, evolving context.
17
+
18
+ ## Getting started
19
+
20
+ Install paths and minimal working examples for every supported runtime.
21
+
22
+ - [Install and Set Up LoraDB](./getting-started/installation.md): Pick a LoraDB installation — Node.js, Python, WebAssembly, Go, Ruby, embedded Rust, or the HTTP server — with a short side-by-side of what each runtime is best for.
23
+ - [A Ten-Minute Tour of LoraDB](./getting-started/tutorial.md): A ten-minute guided tour of LoraDB in Cypher — create nodes and relationships, match patterns, filter, aggregate, walk paths, and use CASE — to learn the engine by doing.
24
+ - [Using LoraDB in Node.js and TypeScript](./getting-started/node.md): Install and use LoraDB in Node.js or TypeScript via the lora-node N-API binding — async queries on libuv, explain/profile diagnostics, helpers, snapshots, WAL persistence, and shared result shapes.
25
+
26
+ ## Concepts
27
+
28
+ - [The LoraDB Graph Data Model](./concepts/graph-model.md): The labeled property graph model LoraDB uses — nodes, typed directed relationships, properties, and internal identity — and how each piece maps to Cypher.
29
+ - [Nodes and Labels](./concepts/nodes.md): 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.
30
+ - [Relationships Between Nodes](./concepts/relationships.md): How LoraDB represents relationships — typed, directed edges between nodes with their own properties — and how to create, traverse, and constrain them in Cypher.
31
+ - [Properties on Nodes and Relationships](./concepts/properties.md): Typed key/value properties on nodes and relationships in LoraDB — reading, setting, removing, and the type rules that apply to each supported data type.
32
+ - [Schema-Free Writes and Soft Validation](./concepts/schema-free.md): 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.
33
+ - [Query Result Formats](./concepts/result-formats.md): 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.
34
+
35
+ ## Queries
36
+
37
+ The supported subset of Cypher, clause by clause, plus the cheat sheet.
38
+
39
+ - [Queries overview](./queries/index.md): An index of every Cypher clause LoraDB supports — MATCH, WHERE, RETURN, WITH, CREATE, MERGE, SET, DELETE, UNWIND, paths, and aggregation — with links to each clause reference.
40
+ - [MATCH — Finding Patterns in the Graph](./queries/match.md): The MATCH clause in LoraDB — fixed and variable-length patterns, OPTIONAL MATCH, labels, directions, chained matches, and how it produces the row stream Cypher queries build on.
41
+ - [CREATE — Writing Nodes and Relationships](./queries/create.md): 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.
42
+ - [WHERE — Filtering Rows](./queries/where.md): The WHERE clause in LoraDB — boolean filters after MATCH, WITH, or OPTIONAL MATCH — including comparisons, regex, list predicates, EXISTS subqueries, and when to filter after aggregation.
43
+ - [RETURN and WITH — Projecting and Piping Results](./queries/return-with.md): The RETURN and WITH clauses in LoraDB — RETURN ends a query and hands rows back to the caller, WITH pipes them into the next stage. Projections, aliasing, and DISTINCT semantics.
44
+ - [SET, REMOVE, DELETE — Mutating the Graph](./queries/set-delete.md): The mutating clauses in LoraDB — SET for updating properties and labels, REMOVE for clearing them, DELETE and DETACH DELETE for removing nodes and relationships.
45
+ - [UNWIND and MERGE — Iterating and Upserting](./queries/unwind-merge.md): The UNWIND and MERGE clauses in LoraDB — UNWIND turns a list into rows for batch processing, MERGE finds a pattern or creates it, with ON MATCH and ON CREATE upsert semantics.
46
+ - [Aggregating Query Results](./queries/aggregation.md): How aggregation works as a clause in LoraDB — implicit GROUP BY from non-aggregated columns, HAVING-style filtering via WITH, and distinct aggregation.
47
+ - [ORDER BY, SKIP, LIMIT — Ordering and Pagination](./queries/ordering.md): Order and paginate LoraDB query results with ORDER BY, SKIP, and LIMIT — evaluation order, stable sorting rules, and their interaction with projection and aggregation.
48
+ - [Paths and Graph Traversals](./queries/paths.md): Path traversals in LoraDB — variable-length patterns, bounded and unbounded quantifiers, zero-hop matches, path binding, shortestPath, and allShortestPaths.
49
+ - [Query Parameters](./queries/parameters.md): Bind host-side values into Cypher queries with parameters — how each binding and the HTTP API forwards them, where parameters can appear, and why they are the safe alternative to string interpolation.
50
+ - [Indexes](./queries/indexes.md): How to create, inspect, query, and drop LoraDB indexes for range, text, point, lookup, vector, and full-text workloads.
51
+ - [Constraints](./queries/constraints.md): How to create, inspect, and drop LoraDB schema constraints for uniqueness, existence, node keys, relationship keys, and property types.
52
+ - [Cypher Query Examples for LoraDB](./queries/examples.md): Copy-paste Cypher examples that run against one seeded LoraDB playground graph.
53
+ - [Cypher Cheat Sheet](./queries/cheat-sheet.md): A one-page reference for the Cypher features LoraDB supports — read, write, path, aggregation, and expression forms — each with a minimal working example.
54
+
55
+ ## Functions
56
+
57
+ - [Built-in Functions in LoraDB](./functions/overview.md): How LoraDB functions work — namespaces, compatibility aliases, casts, null and error behavior, aggregate behavior, and links to each per-category reference.
58
+ - [Aggregation Functions](./functions/aggregation.md): Aggregation functions in LoraDB — count, sum, avg, min, max, collect, stdev, and percentile family — including null handling, empty-input semantics, and implicit grouping rules.
59
+ - [String Functions](./functions/string.md): String functions in LoraDB — string.slice, string.replace, string.split, string.join, string.normalize, string.slugify, regex helpers, case conversion, and numeric parsing.
60
+ - [Math Functions](./functions/math.md): Math functions in LoraDB — math.abs, math.sign, math.sqrt, math.exp, math.log, trigonometry, rounding, and constants — with domain-safe fallbacks to null rather than errors.
61
+ - [Number Functions](./functions/number.md): Number functions in LoraDB - formatting, radix conversion, Roman numerals, integer and sign predicates, finite-value predicates, and bit helpers.
62
+ - [List Functions](./functions/list.md): List functions in LoraDB — value.size, list.first, list.rest, list.last, list.range, value.reverse, reduce, and friends — with 0-based indexing, negative indices, and null-propagation semantics.
63
+ - [Map Functions](./functions/map.md): Map functions in LoraDB — lookup, projection, patching, shallow and deep merge, nested paths, entries, flattening, grouping, and index-building helpers for MAP values.
64
+ - [Temporal Functions (Dates, Times, Durations)](./functions/temporal.md): Temporal functions in LoraDB — current-time helpers, cast-based temporal construction, component accessors, truncation, and Duration arithmetic.
65
+ - [Spatial Functions (Points, Distance)](./functions/spatial.md): Spatial functions in LoraDB — cast-based POINT construction, 2D/3D Cartesian and WGS-84 distance, bounding boxes, property round-tripping, and parameter binding.
66
+ - [Vector Functions (Similarity, Distance, Norms)](./functions/vectors.md): Vector functions in LoraDB — cast-based vector construction, cosine and Euclidean similarity, signed distance metrics, vector.norm, dimension introspection, and vector retrieval examples.
67
+ - [Utility Functions](./functions/utility.md): Utility function namespaces in LoraDB, including type and cast helpers, entity introspection, path helpers, text similarity, JSON, bytes, crypto, UUID, number predicates, and bit operations.
68
+
69
+ ## Data types
70
+
71
+ - [Supported Data Types in LoraDB](./data-types/overview.md): An index of every value type LoraDB supports — scalars, lists, maps, temporal types, spatial points, and vectors — with links to the per-type reference.
72
+ - [Scalar Types — Null, Boolean, Integer, Float, String](./data-types/scalars.md): The five scalar types in LoraDB — Null, Boolean, Integer, Float, String — their literals, comparison rules, three-valued logic, and how each round-trips to host languages.
73
+ - [Lists and Maps](./data-types/lists-and-maps.md): LoraDB's two composite value types — ordered nestable lists and string-keyed maps — including literals, indexing, slicing, nesting rules, and Cypher operations.
74
+ - [Temporal Data Types](./data-types/temporal.md): LoraDB's six temporal types — Date, Time, LocalTime, DateTime, LocalDateTime, and Duration — with component access, arithmetic, truncation, and ordering semantics.
75
+ - [Spatial Data Types (Points)](./data-types/spatial.md): The Point type in LoraDB — 2D and 3D, Cartesian and WGS-84 — its SRIDs, equality rules, property storage behaviour, and links to the spatial function library.
76
+ - [Vector Values](./data-types/vectors.md): First-class VECTOR values in LoraDB — construction in Cypher, property storage, binding round-trips, vector indexes, and built-in vector math functions.
77
+
78
+ ## Guides and reference
79
+
80
+ - [LoraDB Query Cookbook](./cookbook.md): Scenario-driven Cypher recipes for LoraDB — social graphs, e-commerce, event streams, and geospatial queries — each with a concrete data model and working query.
81
+ - [Snapshots](./snapshot.md): Manual point-in-time snapshots — save and restore the full in-memory LoraDB graph as a single file or byte payload, through every binding and the opt-in HTTP admin surface. Standalone for backups, or paired with WAL-backed recovery on every filesystem-backed surface.
82
+ - [WAL and Checkpoints](./wal.md): Continuous local durability in LoraDB via the write-ahead log. Enable WAL on Rust, Node, Python, Go, Ruby, or lora-server; recover committed writes; checkpoint to snapshots; inspect and truncate the log.
83
+ - [Performance and Benchmark Reports](./performance.md): How to read LoraDB benchmark results, inspect the CI benchmark-summary.json artifact, and compare current database performance against the smoke baseline.
84
+ - [Error reference](./errors.md): Stable error codes emitted by LoraDB across every binding and the HTTP server. Match on these codes — not on message text — to route failures in your application.
85
+ - [Limitations](./limitations.md): Every query feature and operational capability LoraDB does not support today — including procedures, clustering, browser playground boundaries, and remaining storage limitations — plus what to reach for instead.
86
+ - [Troubleshooting LoraDB Errors](./troubleshooting.md): A symptom-indexed guide to common LoraDB errors — parse failures, semantic errors, unexpected results, server startup issues — with the shortest fix for each.
@@ -0,0 +1,270 @@
1
+ ---
2
+ title: "The LoraDB Graph Data Model"
3
+ description: "The labeled property graph model LoraDB uses — nodes, typed directed relationships, properties, and internal identity — and how each piece maps to Cypher."
4
+ online: "https://loradb.com/docs/concepts/graph-model"
5
+ package: "@loradb/lora-node@0.36.2"
6
+ ---
7
+
8
+ # The LoraDB Graph Data Model
9
+
10
+ **Labelled property graph**: A data model where entities are **nodes**, connections are typed directed **relationships** between two nodes, and both nodes and relationships can carry zero or more **labels** (or one relationship type) and any number of key-value **properties**.
11
+
12
+ LoraDB uses the **labelled property graph** model. Three things live
13
+ in the graph:
14
+
15
+ | | Purpose | Example |
16
+ |---|---|---|
17
+ | [**Node**](./nodes.md) | An entity | a `:Person`, a `:City`, a `:Movie` |
18
+ | [**Relationship**](./relationships.md) | A typed, directed link between two nodes | `(a)-[:KNOWS]->(b)` |
19
+ | [**Property**](./properties.md) | A typed key/value attached to a node or relationship | `{name: 'Ada', born: 1815}` |
20
+
21
+ Both nodes and relationships can carry any number of properties. Every
22
+ relationship has exactly one **type** and exactly one **direction**,
23
+ and always connects two (possibly equal) nodes.
24
+
25
+ ## See it in four queries
26
+
27
+ The model is easier to feel than to describe. Walk through these four
28
+ queries in order — they build a tiny graph and read it back four
29
+ different ways.
30
+
31
+ ### 1. Make two nodes
32
+
33
+ ```cypher
34
+ CREATE (:Person {name: 'Ada', born: 1815})
35
+ CREATE (:Person {name: 'Grace', born: 1906})
36
+ ```
37
+
38
+ Two nodes with label `Person` and two properties each.
39
+
40
+ ### 2. Connect them
41
+
42
+ ```cypher
43
+ MATCH (ada:Person {name: 'Ada'}), (grace:Person {name: 'Grace'})
44
+ CREATE (ada)-[:INFLUENCED {year: 1843}]->(grace)
45
+ ```
46
+
47
+ One directed relationship with type `INFLUENCED` and its own `year`
48
+ property.
49
+
50
+ ### 3. Read nodes
51
+
52
+ ```cypher
53
+ MATCH (p:Person) RETURN p.name, p.born
54
+ ```
55
+
56
+ Two rows — same shape as the properties we wrote. Label and direction
57
+ are invisible in this projection.
58
+
59
+ ### 4. Read through the relationship
60
+
61
+ ```cypher
62
+ MATCH (a)-[r:INFLUENCED]->(b)
63
+ RETURN a.name AS influencer, r.year AS year, b.name AS influenced
64
+ ```
65
+
66
+ One row — Ada → Grace, with the relationship's own property alongside.
67
+ Notice we can project properties from the relationship itself, not just
68
+ from the nodes at its ends. That's the shape of a property graph:
69
+ **every piece — nodes, their labels, relationships, their types, and
70
+ the properties on either side — is addressable in a query.**
71
+
72
+ ## Vocabulary
73
+
74
+ | Term | Meaning |
75
+ |---|---|
76
+ | **Label** | A tag on a node. Zero or more per node. `:Person`, `:Admin`. Case-sensitive, conventionally `PascalCase`. |
77
+ | **Type** | The kind of a relationship. Exactly one per edge. `:FOLLOWS`, `:WORKS_AT`. Case-sensitive, conventionally `UPPER_SNAKE_CASE`. |
78
+ | **Property key** | The name of a key in a property map. Case-sensitive string. |
79
+ | **Direction** | Source → destination on a relationship. Mandatory at creation, optional in [`MATCH`](../queries/match.md). |
80
+ | **Degree** | The number of relationships touching a node. |
81
+ | **Path** | An alternating sequence of nodes and relationships, produced by a matched traversal. |
82
+
83
+ ## Schema-free
84
+
85
+ LoraDB has no `CREATE TABLE` step. Labels, relationship types, and
86
+ property keys are created implicitly the first time you use them in a
87
+ write:
88
+
89
+ ```cypher
90
+ CREATE (c:Country {name: 'NL', iso: 'NLD'})
91
+ ```
92
+
93
+ The first time this runs, the label `Country` and properties `name`,
94
+ `iso` come into existence. Writes are permissive, and reads never
95
+ reject a name — a label or type nothing carries just matches nothing.
96
+ The full rules
97
+ — and the trade-offs that come with "no schema" — live on their own
98
+ page: [**Schema-free writes and soft validation**](./schema-free.md).
99
+
100
+ When a label or relationship type needs stronger guarantees, add an
101
+ optional [constraint](../queries/constraints.md) for uniqueness,
102
+ existence, key, or property type checks. For lighter idempotent writes,
103
+ [`MERGE`](../queries/unwind-merge.md#merge) is still useful.
104
+
105
+ ## Relationship semantics
106
+
107
+ - Direction is mandatory at creation (`(a)-[:T]->(b)`) but optional in
108
+ `MATCH`: `(a)-[:T]-(b)` matches both directions.
109
+ - A relationship has **one** type, not a list.
110
+ - Types are case-sensitive strings, conventionally `UPPER_SNAKE`.
111
+ - Relationships cannot be dangling — `src` and `dst` must exist at
112
+ creation. Deleting a node with edges requires
113
+ [`DETACH DELETE`](../queries/set-delete.md#detach-delete).
114
+ - Self-loops are allowed: `(a)-[:R]->(a)`.
115
+
116
+ ## Property values
117
+
118
+ Properties are typed. See [Data Types](../data-types/overview.md) for the
119
+ full list — in short:
120
+ [scalars](../data-types/scalars.md) (null, booleans, integers, floats,
121
+ strings), [lists and maps](../data-types/lists-and-maps.md),
122
+ [temporals](../data-types/temporal.md) (`Date`, `Time`, `DateTime`,
123
+ `Duration`, …), and [spatial points](../data-types/spatial.md) (2D and 3D,
124
+ Cartesian and WGS-84).
125
+
126
+ ```cypher
127
+ CREATE (:Trip {
128
+ from: 'AMS',
129
+ to: 'LHR',
130
+ when: '2026-04-20T08:00:00Z'::DATETIME,
131
+ duration: 'PT75M'::DURATION,
132
+ route: ['AMS', 'LHR'],
133
+ origin: {latitude: 52.31, longitude: 4.76}::POINT
134
+ })
135
+ ```
136
+
137
+ ## Identity
138
+
139
+ Every node and relationship gets an auto-generated `u64` ID. IDs are:
140
+
141
+ - **Stable** within a process — they do not change after creation.
142
+ - **Opaque** — don't treat the number as meaningful; use properties for
143
+ external identity.
144
+ - **Not reused** — deleting an entity does not free its ID.
145
+
146
+ Use the built-in [`id()` function](../functions/overview.md#entity-introspection)
147
+ to read the internal ID if you really need it, but prefer matching on
148
+ your own property keys.
149
+
150
+ ```cypher
151
+ MATCH (n:User {email: $email}) RETURN id(n) AS internal_id
152
+ ```
153
+
154
+ ### One useful trick
155
+
156
+ To avoid symmetric-pair duplicates in an undirected match, filter by
157
+ `id(a) < id(b)`:
158
+
159
+ ```cypher
160
+ MATCH (a:Person)-[:KNOWS]-(b:Person)
161
+ WHERE id(a) < id(b)
162
+ RETURN a.name, b.name
163
+ ```
164
+
165
+ Otherwise you'd get both `(alice, bob)` and `(bob, alice)` rows.
166
+
167
+ ## Storage model (at a glance)
168
+
169
+ - **In-memory core.** All live data lives in the process; use snapshots or WAL
170
+ for filesystem durability. See [Limitations](../limitations.md#storage) for the
171
+ full storage shape.
172
+ - **Snapshot concurrency.** Auto-commit reads can overlap on Arc snapshots;
173
+ write commits and explicit read-write transactions serialize. There is no
174
+ per-row locking.
175
+ - **Adjacency on both ends.** Each relationship is reachable from both
176
+ endpoints without a separate index.
177
+
178
+ ## Comparison to other models
179
+
180
+ | Model | How LoraDB differs |
181
+ |---|---|
182
+ | Relational (SQL) | No schema, no joins — relationships are first-class edges. |
183
+ | Document (JSON) | Relationships are explicit, queryable, and indexable. |
184
+ | RDF / triplestore | Relationships carry properties; labels are per-node. |
185
+ | Hypergraph | Not supported — every edge connects exactly two nodes. |
186
+
187
+ ## Modelling checklist
188
+
189
+ A short, pragmatic checklist when deciding how to model a new thing.
190
+
191
+ ### "Is it a node or a property?"
192
+
193
+ | Use a node | Use a property |
194
+ |---|---|
195
+ | You'll traverse to it from elsewhere | It's a leaf value |
196
+ | It has its own identity / lifecycle | It's strictly owned by one entity |
197
+ | It's enumerated over by other queries | It's only read alongside its owner |
198
+
199
+ **Example** — `email`: address of a user. On a `User` node, a `string`
200
+ property. If two users share emails across accounts, promote to an
201
+ `:Email` node with `(u)-[:HAS_EMAIL]->(e)`.
202
+
203
+ ### "Is it a relationship or a node?"
204
+
205
+ If the "edge" itself has a lot of data, including another relationship
206
+ pointing at it, it's probably a node. Cypher can't point edges at
207
+ other edges:
208
+
209
+ ```cypher
210
+ // Edge carrying a little data — fine
211
+ CREATE (a)-[:RATED {stars: 4, at: temporal.now()}]->(b)
212
+
213
+ // Edge with further lifecycle / attachments — promote to node
214
+ CREATE (a)-[:WROTE]->(r:Review {stars: 4, body: '…', at: temporal.now()})
215
+ CREATE (r)-[:ABOUT]->(b)
216
+ CREATE (r)-[:IN_LANG]->(:Language {code: 'en'})
217
+ ```
218
+
219
+ ### "Directional, undirected, or two edges?"
220
+
221
+ | Data is… | Model it as |
222
+ |---|---|
223
+ | Asymmetric (`FOLLOWS`, `REPORTS_TO`) | One directed edge |
224
+ | Symmetric (`FRIEND`, `MARRIED`) | One directed edge + undirected `MATCH` |
225
+ | Both sides carry data (mutual but with direction-specific fields) | Two directed edges |
226
+
227
+ Symmetric relationships storing *one* edge with undirected `MATCH` is
228
+ cheaper and avoids mutability bugs — you never have to keep both
229
+ mirror edges consistent.
230
+
231
+ ### "Small enumeration — property or labelled node?"
232
+
233
+ For something like order status with a known set of values:
234
+
235
+ ```cypher
236
+ // String property — simpler
237
+ CREATE (:Order {id: 1, status: 'paid'})
238
+
239
+ // Label — makes WHERE slightly more efficient and pattern-readable
240
+ CREATE (:Order:Paid {id: 1})
241
+ ```
242
+
243
+ Labels as status flags work well when the status rarely changes and
244
+ is often the primary filter. Property status scales better when
245
+ values churn or when you carry status metadata
246
+ (`status_changed_at`, `status_reason`).
247
+
248
+ ## What is _not_ modeled
249
+
250
+ - Hyperedges (a relationship connects exactly two nodes).
251
+ - Global typed schemas — constraints are optional and scoped to a label
252
+ or relationship type, not to the whole database.
253
+ - Multi-entity or database-wide uniqueness — use
254
+ [property uniqueness constraints](../queries/constraints.md#constraint-kinds)
255
+ for one label/type scope at a time.
256
+ - Weighted relationships as a native primitive —
257
+ [shortest paths](../queries/paths.md#shortest-paths) count hops
258
+ regardless of any `weight` property.
259
+
260
+ ## See also
261
+
262
+ - [**Nodes**](./nodes.md) — labels, identity, match and mutate.
263
+ - [**Relationships**](./relationships.md) — types, direction, properties.
264
+ - [**Properties**](./properties.md) — per-entity key/value data.
265
+ - [**Schema-free**](./schema-free.md) — what implicit schema means for
266
+ writes and reads.
267
+ - [**Result formats**](./result-formats.md) — how queries come back.
268
+ - [**Data Types**](../data-types/overview.md) — what property values can be.
269
+ - [**Queries → Overview**](../queries/index.md) — clause-by-clause reference.
270
+ - [**Tutorial**](../getting-started/tutorial.md) — guided walkthrough.
@@ -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.2"
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.