@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,334 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "A Ten-Minute Tour of LoraDB"
|
|
3
|
+
description: "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."
|
|
4
|
+
online: "https://loradb.com/docs/getting-started/tutorial"
|
|
5
|
+
package: "@loradb/lora-node@0.36.2"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# A Ten-Minute Tour of LoraDB
|
|
9
|
+
|
|
10
|
+
A guided walkthrough. Run each block in order and you'll end up with
|
|
11
|
+
a populated graph, the Cypher basics that shape it, and the
|
|
12
|
+
aggregation patterns you'll reach for most often.
|
|
13
|
+
|
|
14
|
+
> Already installed LoraDB? Good — use whichever binding you picked.
|
|
15
|
+
> The queries are the same in every language. If you haven't, start
|
|
16
|
+
> with [**Installation**](./installation.md).
|
|
17
|
+
|
|
18
|
+
**Learn LoraDB in ten minutes**
|
|
19
|
+
|
|
20
|
+
A guided Cypher tour: build a small social graph, then match patterns, filter, project, aggregate, walk variable-length traversals, and mutate the graph.
|
|
21
|
+
|
|
22
|
+
1. **Create nodes and relationships**: Use CREATE to insert four Person nodes with name and born properties, then connect them with directed FOLLOWS relationships. Labels and relationship types are case-sensitive.
|
|
23
|
+
2. **Match patterns**: Use MATCH to find nodes and traversals. (p:Person) binds every Person to p; (a)-[:FOLLOWS]->(b) walks one hop along a FOLLOWS edge in the given direction.
|
|
24
|
+
3. **Filter with WHERE**: Add WHERE clauses to narrow results: WHERE p.born > 1900, WHERE p.name STARTS WITH 'A', WHERE p.name IN ['Ada', 'Grace']. CASE expressions handle conditional values inline.
|
|
25
|
+
4. **Project and shape results**: Pick the columns you want with RETURN p.name AS name, p.born AS born. Use map projection RETURN p { .* } for full property maps, or compose pipelines with WITH.
|
|
26
|
+
5. **Count and aggregate**: count(*), sum(), avg(), collect() aggregate over the row stream. Non-aggregated columns become the implicit group-by; HAVING-style filtering goes through WITH.
|
|
27
|
+
6. **Walk multi-hop paths**: Variable-length patterns like (a)-[:FOLLOWS*1..3]->(b) traverse one to three hops. shortestPath() and allShortestPaths() find graph-distance answers in a single query.
|
|
28
|
+
7. **Mutate the graph**: SET updates properties, MERGE upserts a pattern with ON CREATE / ON MATCH clauses, DETACH DELETE removes a node and every relationship touching it in one step.
|
|
29
|
+
|
|
30
|
+
## What you'll learn
|
|
31
|
+
|
|
32
|
+
| Step | Topic |
|
|
33
|
+
|---|---|
|
|
34
|
+
| [1](#step-1--create-some-data) | Create nodes and relationships |
|
|
35
|
+
| [2](#step-2--find-something) | MATCH patterns |
|
|
36
|
+
| [3](#step-3--filter) | WHERE, case, string matching |
|
|
37
|
+
| [4](#step-4--project-and-shape-results) | RETURN, aliases, map projection |
|
|
38
|
+
| [5](#step-5--count-and-aggregate) | count, implicit group-by |
|
|
39
|
+
| [6](#step-6--walk-multi-step-patterns) | Multi-hop and variable-length patterns |
|
|
40
|
+
| [7](#step-7--update-and-delete) | SET, MERGE, DETACH DELETE |
|
|
41
|
+
| [8](#step-8--conditional-values-bonus) | CASE expressions |
|
|
42
|
+
| [Next](#where-to-go-next) | Where to go from here |
|
|
43
|
+
|
|
44
|
+
## Step 1 — Create some data
|
|
45
|
+
|
|
46
|
+
We'll model a tiny network: a handful of people and who follows whom.
|
|
47
|
+
|
|
48
|
+
```cypher
|
|
49
|
+
CREATE (ada:Person {name: 'Ada', born: 1815})
|
|
50
|
+
CREATE (grace:Person {name: 'Grace', born: 1906})
|
|
51
|
+
CREATE (alan:Person {name: 'Alan', born: 1912})
|
|
52
|
+
CREATE (linus:Person {name: 'Linus', born: 1969})
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Four `Person` [nodes](../concepts/nodes.md), each with `name` and `born`
|
|
56
|
+
[properties](../concepts/properties.md). `Person` is a **label** — a tag
|
|
57
|
+
you can use later to filter [`MATCH`](../queries/match.md) queries. The
|
|
58
|
+
variables (`ada`, `grace`, …) only live for the duration of this query.
|
|
59
|
+
|
|
60
|
+
Now wire them up:
|
|
61
|
+
|
|
62
|
+
```cypher
|
|
63
|
+
MATCH (ada:Person {name: 'Ada'}),
|
|
64
|
+
(grace:Person {name: 'Grace'}),
|
|
65
|
+
(alan:Person {name: 'Alan'}),
|
|
66
|
+
(linus:Person {name: 'Linus'})
|
|
67
|
+
CREATE (grace)-[:FOLLOWS]->(ada),
|
|
68
|
+
(alan)-[:FOLLOWS]->(ada),
|
|
69
|
+
(linus)-[:FOLLOWS]->(alan),
|
|
70
|
+
(linus)-[:FOLLOWS]->(grace)
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
We re-bind the nodes by `name` and [`CREATE`](../queries/create.md) four
|
|
74
|
+
directed `FOLLOWS` [relationships](../concepts/relationships.md). A
|
|
75
|
+
relationship is always between two nodes, always has a single **type**,
|
|
76
|
+
always has a direction, and can carry its own properties.
|
|
77
|
+
|
|
78
|
+
> **Why this matters.** In a relational schema you'd model this with
|
|
79
|
+
> a `follows` join table; in LoraDB the relationship is a first-class
|
|
80
|
+
> value you can pattern-match directly.
|
|
81
|
+
|
|
82
|
+
## Step 2 — Find something
|
|
83
|
+
|
|
84
|
+
[`MATCH`](../queries/match.md) describes a shape you want to find in the
|
|
85
|
+
graph. The simplest possible shape: "every Person":
|
|
86
|
+
|
|
87
|
+
```cypher
|
|
88
|
+
MATCH (p:Person)
|
|
89
|
+
RETURN p.name
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
You'll see four rows back — Ada, Grace, Alan, Linus.
|
|
93
|
+
|
|
94
|
+
Now a shape with a relationship:
|
|
95
|
+
|
|
96
|
+
```cypher
|
|
97
|
+
MATCH (follower:Person)-[:FOLLOWS]->(leader:Person)
|
|
98
|
+
RETURN follower.name, leader.name
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
This returns one row per edge — four rows:
|
|
102
|
+
|
|
103
|
+
| follower | leader |
|
|
104
|
+
|---|---|
|
|
105
|
+
| Grace | Ada |
|
|
106
|
+
| Alan | Ada |
|
|
107
|
+
| Linus | Alan |
|
|
108
|
+
| Linus | Grace |
|
|
109
|
+
|
|
110
|
+
The pattern reads left-to-right: "a `:Person` named `follower` who has
|
|
111
|
+
an outgoing `:FOLLOWS` relationship to another `:Person` named
|
|
112
|
+
`leader`." `MATCH` returns **every assignment** of variables to graph
|
|
113
|
+
entities that makes the pattern true.
|
|
114
|
+
|
|
115
|
+
## Step 3 — Filter
|
|
116
|
+
|
|
117
|
+
[`WHERE`](../queries/where.md) narrows the rows. It runs after `MATCH`
|
|
118
|
+
and can reference anything the match bound.
|
|
119
|
+
|
|
120
|
+
```cypher
|
|
121
|
+
MATCH (p:Person)
|
|
122
|
+
WHERE p.born >= 1900
|
|
123
|
+
RETURN p.name, p.born
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Three rows back: Grace (1906), Alan (1912), Linus (1969). `WHERE` is
|
|
127
|
+
also where most null-safe checks and
|
|
128
|
+
[string matching](../functions/string.md#string-operators-in-where) live:
|
|
129
|
+
|
|
130
|
+
```cypher
|
|
131
|
+
MATCH (p:Person)
|
|
132
|
+
WHERE p.name STARTS WITH 'A'
|
|
133
|
+
RETURN p.name
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Two rows: Ada, Alan. Run through
|
|
137
|
+
[`string.lower`](../functions/string.md#tolower--toupper) if you want
|
|
138
|
+
case-insensitive matching:
|
|
139
|
+
|
|
140
|
+
```cypher
|
|
141
|
+
MATCH (p:Person)
|
|
142
|
+
WHERE string.lower(p.name) CONTAINS 'a'
|
|
143
|
+
RETURN p.name
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
### Range filters
|
|
147
|
+
|
|
148
|
+
```cypher
|
|
149
|
+
MATCH (p:Person)
|
|
150
|
+
WHERE p.born >= 1900 AND p.born < 1950
|
|
151
|
+
RETURN p.name, p.born
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
LoraDB has no `BETWEEN` keyword — use explicit `>=` / `<=`. See
|
|
155
|
+
[Limitations](../limitations.md#operators-and-expressions).
|
|
156
|
+
|
|
157
|
+
## Step 4 — Project and shape results
|
|
158
|
+
|
|
159
|
+
[`RETURN`](../queries/return-with.md) can rename with `AS`, compute
|
|
160
|
+
expressions, and pick subsets via
|
|
161
|
+
[**map projection**](../data-types/lists-and-maps.md#map-projection):
|
|
162
|
+
|
|
163
|
+
```cypher
|
|
164
|
+
MATCH (p:Person)
|
|
165
|
+
RETURN p.name AS name,
|
|
166
|
+
2026 - p.born AS approx_age,
|
|
167
|
+
p {.name, .born} AS record
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
One row per person; each row has three columns. `p {.name, .born}`
|
|
171
|
+
builds a [map](../data-types/lists-and-maps.md#maps) from the node's
|
|
172
|
+
properties — useful for shaping results when your consumer only needs
|
|
173
|
+
a subset.
|
|
174
|
+
|
|
175
|
+
## Step 5 — Count and aggregate
|
|
176
|
+
|
|
177
|
+
[Aggregates](../queries/aggregation.md) collapse rows. The simplest is
|
|
178
|
+
[`count(*)`](../functions/aggregation.md#count):
|
|
179
|
+
|
|
180
|
+
```cypher
|
|
181
|
+
MATCH (p:Person)
|
|
182
|
+
RETURN count(*) AS total
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
One row, one column, value `4`. More interestingly: how many people
|
|
186
|
+
does each person follow?
|
|
187
|
+
|
|
188
|
+
```cypher
|
|
189
|
+
MATCH (follower:Person)-[:FOLLOWS]->(leader:Person)
|
|
190
|
+
RETURN follower.name AS follower,
|
|
191
|
+
count(leader) AS following
|
|
192
|
+
ORDER BY following DESC
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
| follower | following |
|
|
196
|
+
|---|---|
|
|
197
|
+
| Linus | 2 |
|
|
198
|
+
| Grace | 1 |
|
|
199
|
+
| Alan | 1 |
|
|
200
|
+
|
|
201
|
+
> **Why this works.** `follower.name` is non-aggregated, so it becomes
|
|
202
|
+
> an implicit **group key**. One row per group. `count(leader)` is the
|
|
203
|
+
> size of each group.
|
|
204
|
+
|
|
205
|
+
And the reverse — how many followers does each person have?
|
|
206
|
+
|
|
207
|
+
```cypher
|
|
208
|
+
MATCH (follower:Person)-[:FOLLOWS]->(leader:Person)
|
|
209
|
+
RETURN leader.name AS person,
|
|
210
|
+
count(follower) AS followers
|
|
211
|
+
ORDER BY followers DESC
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
### Filter after aggregating (HAVING-style)
|
|
215
|
+
|
|
216
|
+
Cypher has no `HAVING`. Use
|
|
217
|
+
[`WITH` + `WHERE`](../queries/return-with.md#having-style-filtering-with):
|
|
218
|
+
|
|
219
|
+
```cypher
|
|
220
|
+
MATCH (follower:Person)-[:FOLLOWS]->(leader:Person)
|
|
221
|
+
WITH leader.name AS person, count(follower) AS followers
|
|
222
|
+
WHERE followers >= 2
|
|
223
|
+
RETURN person, followers
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
## Step 6 — Walk multi-step patterns
|
|
227
|
+
|
|
228
|
+
Cypher really earns its keep on multi-hop patterns. Who follows someone
|
|
229
|
+
who follows Ada?
|
|
230
|
+
|
|
231
|
+
```cypher
|
|
232
|
+
MATCH (n:Person)-[:FOLLOWS]->(mid:Person)-[:FOLLOWS]->(ada:Person {name: 'Ada'})
|
|
233
|
+
RETURN n.name AS two_hops_away
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
One row: Linus, because Linus → Alan → Ada (and Linus → Grace → Ada).
|
|
237
|
+
|
|
238
|
+
You can bind the whole [path](../queries/paths.md) and read its length:
|
|
239
|
+
|
|
240
|
+
```cypher
|
|
241
|
+
MATCH p = (linus:Person {name: 'Linus'})-[:FOLLOWS*1..3]->(ada:Person {name: 'Ada'})
|
|
242
|
+
RETURN path.length(p), path.nodes(p)
|
|
243
|
+
```
|
|
244
|
+
|
|
245
|
+
`*1..3` means "between 1 and 3 hops along `:FOLLOWS` edges" — see
|
|
246
|
+
[variable-length patterns](../queries/paths.md#variable-length-relationships).
|
|
247
|
+
`path.length(p)` is the hop count; `path.nodes(p)` is the list of nodes on that
|
|
248
|
+
path.
|
|
249
|
+
|
|
250
|
+
### Shortest path
|
|
251
|
+
|
|
252
|
+
```cypher
|
|
253
|
+
MATCH p = shortestPath(
|
|
254
|
+
(linus:Person {name: 'Linus'})-[:FOLLOWS*]->(ada:Person {name: 'Ada'})
|
|
255
|
+
)
|
|
256
|
+
RETURN path.length(p) AS hops, [n IN path.nodes(p) | n.name] AS via
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
## Step 7 — Update and delete
|
|
260
|
+
|
|
261
|
+
[`SET`](../queries/set-delete.md#set--properties) changes properties or
|
|
262
|
+
adds labels on existing nodes:
|
|
263
|
+
|
|
264
|
+
```cypher
|
|
265
|
+
MATCH (ada:Person {name: 'Ada'})
|
|
266
|
+
SET ada.field = 'Mathematics'
|
|
267
|
+
RETURN ada
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
```cypher
|
|
271
|
+
MATCH (ada:Person {name: 'Ada'})
|
|
272
|
+
SET ada:Pioneer
|
|
273
|
+
RETURN labels(ada)
|
|
274
|
+
// ['Person', 'Pioneer']
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
[`MERGE`](../queries/unwind-merge.md#merge) is "match, or create if
|
|
278
|
+
missing":
|
|
279
|
+
|
|
280
|
+
```cypher
|
|
281
|
+
MERGE (p:Person {name: 'Ada'})
|
|
282
|
+
ON MATCH SET p.updated = temporal.timestamp()
|
|
283
|
+
ON CREATE SET p.created = temporal.timestamp()
|
|
284
|
+
RETURN p.name, p.updated, p.created
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
And [`DETACH DELETE`](../queries/set-delete.md#detach-delete) removes a
|
|
288
|
+
node and all its relationships:
|
|
289
|
+
|
|
290
|
+
```cypher
|
|
291
|
+
MATCH (alan:Person {name: 'Alan'})
|
|
292
|
+
DETACH DELETE alan
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
## Step 8 — Conditional values (bonus)
|
|
296
|
+
|
|
297
|
+
[`CASE`](../queries/return-with.md#case-expressions) is LoraDB's
|
|
298
|
+
ternary. Two forms — match a value, or boolean-per-branch:
|
|
299
|
+
|
|
300
|
+
```cypher
|
|
301
|
+
MATCH (p:Person)
|
|
302
|
+
RETURN p.name,
|
|
303
|
+
CASE
|
|
304
|
+
WHEN p.born < 1900 THEN '19th century'
|
|
305
|
+
WHEN p.born < 2000 THEN '20th century'
|
|
306
|
+
ELSE '21st century'
|
|
307
|
+
END AS era
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
Works anywhere a value is allowed — `RETURN`, `WITH`, `SET`,
|
|
311
|
+
`ORDER BY`, inside function arguments.
|
|
312
|
+
|
|
313
|
+
## Where to go next
|
|
314
|
+
|
|
315
|
+
You've now touched every common clause: `CREATE`, `MATCH`, `WHERE`,
|
|
316
|
+
`RETURN`, `ORDER BY`, `count`, `MERGE`, `SET`, `DETACH DELETE`, and
|
|
317
|
+
`CASE`. From here:
|
|
318
|
+
|
|
319
|
+
- **[Query reference](../queries/index.md)** — clause-by-clause details.
|
|
320
|
+
- **[Query examples](../queries/examples.md)** — copy-paste patterns for
|
|
321
|
+
common shapes.
|
|
322
|
+
- **[Aggregation](../queries/aggregation.md)** — grouping, `collect`,
|
|
323
|
+
percentiles, HAVING-style filtering.
|
|
324
|
+
- **[Paths](../queries/paths.md)** — variable-length and shortest paths.
|
|
325
|
+
- **[Functions](../functions/overview.md)** — string, math, list, temporal,
|
|
326
|
+
spatial.
|
|
327
|
+
- **[Data Types](../data-types/overview.md)** — the complete value catalogue.
|
|
328
|
+
- **[Limitations](../limitations.md)** — what's intentionally not supported today.
|
|
329
|
+
|
|
330
|
+
## See also
|
|
331
|
+
|
|
332
|
+
- [**Graph Model**](../concepts/graph-model.md) — the underlying data model.
|
|
333
|
+
- [**Installation**](./installation.md) — pick your platform.
|
|
334
|
+
- [**Troubleshooting**](../troubleshooting.md) — common errors and fixes.
|
package/docs/index.md
ADDED
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "What is LoraDB"
|
|
3
|
+
description: "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."
|
|
4
|
+
online: "https://loradb.com/docs"
|
|
5
|
+
package: "@loradb/lora-node@0.36.2"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# What is LoraDB
|
|
9
|
+
|
|
10
|
+
LoraDB is a **local-first, in-memory property-graph engine** written
|
|
11
|
+
in Rust that speaks a pragmatic subset of Cypher. It runs in-process
|
|
12
|
+
inside your service, pipeline, or agent — no separate database tier
|
|
13
|
+
— and reaches you through a Rust crate, five bindings, or an HTTP
|
|
14
|
+
server.
|
|
15
|
+
|
|
16
|
+
It is:
|
|
17
|
+
|
|
18
|
+
- **A query engine.** Parser, analyzer, planner, optimizer, and
|
|
19
|
+
executor live in separate Rust crates with one shared pipeline.
|
|
20
|
+
- **An in-process graph store.** Nodes, relationships, and properties
|
|
21
|
+
held in RAM.
|
|
22
|
+
- **A set of bindings over one shared core.** Node, Python, WASM, Go
|
|
23
|
+
(via a shared C ABI), and Ruby, plus an Axum-based HTTP server.
|
|
24
|
+
|
|
25
|
+
It is **not**:
|
|
26
|
+
|
|
27
|
+
- A drop-in replacement for other graph databases. The Cypher surface
|
|
28
|
+
is a scoped subset — see [Limitations](./limitations.md) for what's
|
|
29
|
+
in and out.
|
|
30
|
+
- A product suite. The source-available core is something you embed or run
|
|
31
|
+
locally, not a managed service you operate as-is.
|
|
32
|
+
- A durable, clustered database tier — local WAL-backed durability
|
|
33
|
+
exists on filesystem-backed surfaces, but the engine is still
|
|
34
|
+
single-process and intentionally small. See
|
|
35
|
+
[the engine's boundaries](#the-engines-boundaries) below.
|
|
36
|
+
|
|
37
|
+
For the longer-form positioning — why an embedded graph at all, and
|
|
38
|
+
how LoraDB compares against managed graph DBs, SQL, and document
|
|
39
|
+
stores — see [**Why LoraDB**](./why.md).
|
|
40
|
+
|
|
41
|
+
## Who it's for
|
|
42
|
+
|
|
43
|
+
| Workload | Why LoraDB fits |
|
|
44
|
+
|---|---|
|
|
45
|
+
| **Backend services** | A graph view over already-owned storage — permissions, org charts, supply chains, lineage — without a second database tier. |
|
|
46
|
+
| **AI agents and LLM pipelines** | Entities, observations, tool calls, and decisions as typed traversals rather than ad-hoc JSON. [`VECTOR`](./data-types/vectors.md) is a first-class value, so embeddings live on the same node as labels and edges — similarity and traversal share one query. |
|
|
47
|
+
| **Robotics and stateful systems** | Scenes, maps, tasks, and dependencies as a graph. Running in the controller's process avoids cross-service latency on the control loop. |
|
|
48
|
+
| **Event-driven / real-time pipelines** | Entity resolution, relationship inference, and path queries over streams — in-memory, alongside the handler. |
|
|
49
|
+
| **Notebooks, CLIs, tests, research tooling** | A Cypher-capable graph you open in one line of code. No Docker, no auth, no network hop. |
|
|
50
|
+
|
|
51
|
+
## Why it fits modern workloads
|
|
52
|
+
|
|
53
|
+
Agents, robots, and streaming pipelines all end up building the same
|
|
54
|
+
structure by accident: entities with typed keys, evolving relations,
|
|
55
|
+
accessed in-process. Three properties make an in-memory graph a good
|
|
56
|
+
fit for that structure:
|
|
57
|
+
|
|
58
|
+
- **Context is relational.** What matters is rarely a row; it's how
|
|
59
|
+
rows connect. A graph model states that directly.
|
|
60
|
+
- **Context changes.** Schemas shift as the system learns. LoraDB is
|
|
61
|
+
schema-free — new labels and properties come into existence the
|
|
62
|
+
first time you write them.
|
|
63
|
+
- **Context must stay close.** Reasoning that crosses a network
|
|
64
|
+
boundary is slower and less reliable. Running in-process removes
|
|
65
|
+
the boundary.
|
|
66
|
+
|
|
67
|
+
## From zero to first query
|
|
68
|
+
|
|
69
|
+
Four steps. Pick your host language on step 2; everything else is
|
|
70
|
+
identical. To skip step 1, open the
|
|
71
|
+
[**playground**](https://loradb.com/docs/getting-started/playground) — it runs LoraDB compiled
|
|
72
|
+
to WASM in your browser, no install, no account.
|
|
73
|
+
|
|
74
|
+
If this is your first run, stay in memory until the query shape feels
|
|
75
|
+
right. Plain in-memory handles start empty on every process run; move
|
|
76
|
+
to a named `.loradb` archive, snapshots, or WAL when the graph should
|
|
77
|
+
survive restarts.
|
|
78
|
+
|
|
79
|
+
### 1. Install
|
|
80
|
+
|
|
81
|
+
| Host | Command |
|
|
82
|
+
|---|---|
|
|
83
|
+
| [Node / TypeScript](./getting-started/node.md) | `npm install @loradb/lora-node` |
|
|
84
|
+
| [Python](https://loradb.com/docs/getting-started/python) | `pip install lora-python` |
|
|
85
|
+
| [Browser / WASM](https://loradb.com/docs/getting-started/wasm) | `npm install @loradb/lora-wasm` |
|
|
86
|
+
| [Go](https://loradb.com/docs/getting-started/go) | `go get github.com/lora-db/lora/crates/bindings/lora-go` |
|
|
87
|
+
| [Ruby](https://loradb.com/docs/getting-started/ruby) | `gem install lora-ruby` |
|
|
88
|
+
| [Rust (embedded)](https://loradb.com/docs/getting-started/rust) | `cargo add lora-database` |
|
|
89
|
+
| [HTTP server](https://loradb.com/docs/getting-started/server) | `cargo install lora-server` |
|
|
90
|
+
|
|
91
|
+
### 2. Create data
|
|
92
|
+
|
|
93
|
+
```cypher
|
|
94
|
+
CREATE (ada:Person {name: 'Ada', born: 1815})
|
|
95
|
+
CREATE (grace:Person {name: 'Grace', born: 1906})
|
|
96
|
+
CREATE (ada)-[:INFLUENCED {year: 1843}]->(grace)
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
One node per `CREATE (…)`. Relationships have a type, direction, and
|
|
100
|
+
their own properties. See [Graph model](./concepts/graph-model.md).
|
|
101
|
+
|
|
102
|
+
### 3. Query
|
|
103
|
+
|
|
104
|
+
```cypher
|
|
105
|
+
MATCH (a:Person)-[:INFLUENCED]->(b:Person)
|
|
106
|
+
WHERE a.born < 1900
|
|
107
|
+
RETURN a.name AS influencer, b.name AS influenced
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Clauses stream rows: `MATCH` finds patterns, `WHERE` filters, `RETURN`
|
|
111
|
+
projects. See [Queries → Overview](./queries/index.md) or jump into the
|
|
112
|
+
[**Cheat sheet**](./queries/cheat-sheet.md) for a single-page reference.
|
|
113
|
+
|
|
114
|
+
### 4. Choose an API
|
|
115
|
+
|
|
116
|
+
| If you… | Use |
|
|
117
|
+
|---|---|
|
|
118
|
+
| Ship Node / TS code | [Node binding](./getting-started/node.md) |
|
|
119
|
+
| Write Python (sync or asyncio) | [Python binding](https://loradb.com/docs/getting-started/python) |
|
|
120
|
+
| Run in a browser / Web Worker / edge | [WASM binding](https://loradb.com/docs/getting-started/wasm) |
|
|
121
|
+
| Build a Go service or CLI (cgo) | [Go binding](https://loradb.com/docs/getting-started/go) |
|
|
122
|
+
| Ship a Ruby app or Rails service | [Ruby binding](https://loradb.com/docs/getting-started/ruby) |
|
|
123
|
+
| Embed inline in a Rust binary | [Rust crate](https://loradb.com/docs/getting-started/rust) |
|
|
124
|
+
| Want a polyglot HTTP service | [HTTP server](https://loradb.com/docs/getting-started/server) + [HTTP API reference](https://loradb.com/docs/api/http) |
|
|
125
|
+
| Want a typed GraphQL API over the graph | [GraphQL for LoraDB](https://loradb.com/docs/graphql), on the Node binding |
|
|
126
|
+
|
|
127
|
+
All bindings share the same query language and result shapes — see
|
|
128
|
+
[Result formats](./concepts/result-formats.md) for the four response
|
|
129
|
+
shapes (`rows`, `rowArrays`, `graph`, `combined`).
|
|
130
|
+
|
|
131
|
+
## First-time decisions
|
|
132
|
+
|
|
133
|
+
Most confusion comes from choosing the wrong surface for the job, or
|
|
134
|
+
expecting an in-memory graph to persist automatically. Use this table
|
|
135
|
+
before wiring LoraDB into an app:
|
|
136
|
+
|
|
137
|
+
| Need | Pick | Why |
|
|
138
|
+
|---|---|---|
|
|
139
|
+
| Learn the query language | [Playground](https://loradb.com/docs/getting-started/playground) | No install, browser-local state, good for copy-paste experiments. |
|
|
140
|
+
| Build an app in one language | The matching [binding](./getting-started/installation.md) | Real parameters, typed values, snapshots, and host-language error handling. |
|
|
141
|
+
| Share one local graph across languages | [HTTP server](https://loradb.com/docs/getting-started/server) | Simple `POST /query` API from any client. |
|
|
142
|
+
| Accept untrusted user input | Parameters on any binding or HTTP `/query` | Never interpolate raw input into query text. |
|
|
143
|
+
| Survive process restarts | Named `.loradb` archive, snapshots, or [WAL](./wal.md) | Plain in-memory databases intentionally start empty. |
|
|
144
|
+
| Expose over a network | Put `lora-server` behind authenticated ingress | Built-in HTTP auth, TLS, and rate limiting are not included. |
|
|
145
|
+
|
|
146
|
+
## What you'll read next
|
|
147
|
+
|
|
148
|
+
| Section | What's inside |
|
|
149
|
+
|---|---|
|
|
150
|
+
| [**Playground**](https://loradb.com/docs/getting-started/playground) | Run LoraDB queries in your browser, inspect graph/table/JSON/analysis views, share query URLs, and export snapshots. |
|
|
151
|
+
| [**Tutorial**](./getting-started/tutorial.md) | A ten-minute guided tour — create, match, filter, aggregate, paths, CASE. |
|
|
152
|
+
| [**Concepts**](./concepts/graph-model.md) | Graph model, nodes, relationships, properties, [schema-free](./concepts/schema-free.md), [result formats](./concepts/result-formats.md). |
|
|
153
|
+
| [**Queries**](./queries/index.md) | Clause reference, [parameters](./queries/parameters.md), [cheat sheet](./queries/cheat-sheet.md). |
|
|
154
|
+
| [**Functions**](./functions/overview.md) | String, math, list, aggregation, temporal, spatial, vector, type, and cast helpers. |
|
|
155
|
+
| [**Data types**](./data-types/overview.md) | Scalars, lists, maps, temporals, spatial points, [vectors](./data-types/vectors.md) — how each round-trips. |
|
|
156
|
+
| [**HTTP API**](https://loradb.com/docs/api/http) | Endpoint reference for `lora-server`. |
|
|
157
|
+
| [**Cookbook**](./cookbook.md) | Scenario-driven recipes: social graphs, e-commerce, events, geospatial, [backup and restore](./cookbook.md#backup-and-restore). |
|
|
158
|
+
| [**Snapshots**](./snapshot.md) | Save / load the full graph as a file or byte payload — every binding, plus the opt-in HTTP admin surface. |
|
|
159
|
+
| [**WAL & checkpoints**](./wal.md) | Continuous durability on Rust, Node, Python, Go, Ruby, and `lora-server` — with full operator controls on Rust and the server. |
|
|
160
|
+
| [**Performance**](./performance.md) | Benchmark tables, CI `benchmark-summary.json`, and how to read regression signals. |
|
|
161
|
+
| [**Errors**](./errors.md) | Error codes, diagnostic shape, and how to read parser / analyzer / runtime failures. |
|
|
162
|
+
| [**Limitations**](./limitations.md) | What's not supported - binding-level WAL-control asymmetry, limited `CALL`, no embedding generation, etc. |
|
|
163
|
+
| [**Troubleshooting**](./troubleshooting.md) | Common errors and the shortest path out. |
|
|
164
|
+
|
|
165
|
+
## The engine's boundaries
|
|
166
|
+
|
|
167
|
+
Every item below is a deliberate trade-off, not an oversight:
|
|
168
|
+
|
|
169
|
+
- **Durability depends on the surface.** Every binding can
|
|
170
|
+
[save / load snapshots](./snapshot.md). Filesystem-backed surfaces can
|
|
171
|
+
also attach a [WAL](./wal.md) for continuous durability between
|
|
172
|
+
checkpoints or managed commit-count snapshots. WASM remains
|
|
173
|
+
snapshot-only and pathless. The engine is still an in-memory,
|
|
174
|
+
single-process system — not a separate persistent storage tier.
|
|
175
|
+
- **Indexes are explicit but scoped.** `CREATE INDEX`, `CREATE TEXT INDEX`,
|
|
176
|
+
`CREATE POINT INDEX`, `CREATE VECTOR INDEX`, `CREATE FULLTEXT INDEX`,
|
|
177
|
+
`DROP INDEX`, and `SHOW INDEXES` exist for node and relationship scopes.
|
|
178
|
+
Vector indexes are exact flat scans by default; approximate HNSW search
|
|
179
|
+
is opt-in per index with `vector.indexProvider: 'hnsw'`.
|
|
180
|
+
- **Constraints are optional.** Use
|
|
181
|
+
[`CREATE CONSTRAINT`](./queries/constraints.md) for uniqueness, existence,
|
|
182
|
+
node keys, relationship keys, and property type checks when a label or
|
|
183
|
+
relationship type needs stronger guarantees.
|
|
184
|
+
- **Single-process concurrency.** Auto-commit reads can overlap on Arc snapshots;
|
|
185
|
+
write commits and explicit read-write transactions serialize.
|
|
186
|
+
- **No HTTP auth / TLS.** Bind the server to localhost or put it behind
|
|
187
|
+
a reverse proxy. The opt-in admin snapshot and WAL endpoints also ship
|
|
188
|
+
without auth — see [Limitations → HTTP server](./limitations.md#http-server).
|
|
189
|
+
- **HTTP is intentionally small.** `/query`, `/explain`, and
|
|
190
|
+
`/profile` accept JSON parameters, but HTTP has no multi-query
|
|
191
|
+
transaction handles and no built-in auth / TLS. Use an in-process
|
|
192
|
+
binding for direct embedding and host-language typed helpers.
|
|
193
|
+
|
|
194
|
+
Full list in [**Limitations**](./limitations.md).
|
|
195
|
+
|
|
196
|
+
## Help and community
|
|
197
|
+
|
|
198
|
+
- [**Troubleshooting**](./troubleshooting.md) — first stop when something
|
|
199
|
+
breaks.
|
|
200
|
+
- [**GitHub**](https://github.com/lora-db/lora) — source, issues,
|
|
201
|
+
discussions.
|
|
202
|
+
- [**Discord**](https://discord.gg/vUgKb6C8Af) — ask a question or
|
|
203
|
+
lurk on updates.
|