@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
package/docs/why.md
ADDED
|
@@ -0,0 +1,273 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Why LoraDB"
|
|
3
|
+
description: "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."
|
|
4
|
+
online: "https://loradb.com/docs/why"
|
|
5
|
+
package: "@loradb/lora-node@0.36.2"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Why LoraDB
|
|
9
|
+
|
|
10
|
+
Most systems end up modelling relationships. Users follow users,
|
|
11
|
+
agents reference entities, scenes contain objects, events depend on
|
|
12
|
+
other events. When the questions you care about are _"everything
|
|
13
|
+
reachable from here"_ or _"what connects these two"_, the shape of
|
|
14
|
+
your data is a graph — even when the store is a table.
|
|
15
|
+
|
|
16
|
+
LoraDB is a local-first, in-memory property-graph engine written in
|
|
17
|
+
Rust that speaks a pragmatic subset of Cypher. It's built for code
|
|
18
|
+
paths where the graph needs to live next to the code that uses it,
|
|
19
|
+
not behind a network boundary.
|
|
20
|
+
|
|
21
|
+
## The problem with traditional approaches
|
|
22
|
+
|
|
23
|
+
### Relational stores fight relational questions
|
|
24
|
+
|
|
25
|
+
SQL expresses relationships with foreign keys and join tables. That
|
|
26
|
+
works, until the query is "find everyone within three hops", "what's
|
|
27
|
+
the shortest dependency chain", or "summarise the neighbourhood of
|
|
28
|
+
this node". Expressing those in SQL means self-joins stacked on
|
|
29
|
+
self-joins; running them means the planner guessing how to traverse a
|
|
30
|
+
graph it doesn't know is a graph.
|
|
31
|
+
|
|
32
|
+
### Document stores fight evolving relationships
|
|
33
|
+
|
|
34
|
+
Nesting works when ownership is strict and fan-out is small. Real
|
|
35
|
+
systems have bidirectional edges, many-to-many links, and entities
|
|
36
|
+
that migrate between documents. At that point every lookup becomes an
|
|
37
|
+
ad-hoc index or a second round-trip, and consistency moves into
|
|
38
|
+
application code.
|
|
39
|
+
|
|
40
|
+
### Graph platforms are often disproportionate
|
|
41
|
+
|
|
42
|
+
Established graph databases solve real problems — clustering,
|
|
43
|
+
durability, multi-user isolation, huge graphs. They also come with a
|
|
44
|
+
service to deploy, a protocol to speak, and a TCO that only pays off
|
|
45
|
+
once the graph is big enough. For a service, agent, or pipeline that
|
|
46
|
+
wants a graph _data structure_ inside its own process, they're too
|
|
47
|
+
much.
|
|
48
|
+
|
|
49
|
+
## Why relationships matter
|
|
50
|
+
|
|
51
|
+
A graph model turns three things into first-class primitives:
|
|
52
|
+
|
|
53
|
+
- **Edges** — typed, directed, property-bearing. Not a join column.
|
|
54
|
+
- **Patterns** — `(a)-[:KNOWS]->(b)-[:WORKS_AT]->(c)` is the query,
|
|
55
|
+
not an implementation detail.
|
|
56
|
+
- **Traversal** — "walk from here" is `O(degree)`, not a recursive
|
|
57
|
+
CTE.
|
|
58
|
+
|
|
59
|
+
Cypher is a language optimised for _describing_ relationships rather
|
|
60
|
+
than _computing_ joins. Once the model matches the question, the
|
|
61
|
+
queries get short, and short queries are easier to read, review, and
|
|
62
|
+
optimise.
|
|
63
|
+
|
|
64
|
+
## Why modern systems need this
|
|
65
|
+
|
|
66
|
+
Agents, robots, and real-time pipelines all end up building the same
|
|
67
|
+
thing by accident: an in-memory structure of entities and relations
|
|
68
|
+
with typed keys and an evolving shape. LoraDB is that structure, on
|
|
69
|
+
purpose.
|
|
70
|
+
|
|
71
|
+
### AI agents and LLM pipelines
|
|
72
|
+
|
|
73
|
+
An agent's context is a graph — tools, entities, observations,
|
|
74
|
+
decisions, and the links between them. Retrieval over that context is
|
|
75
|
+
a graph question:
|
|
76
|
+
|
|
77
|
+
```cypher
|
|
78
|
+
MATCH (t:Task {id: $task})-[:DEPENDS_ON*1..3]->(e:Entity)
|
|
79
|
+
OPTIONAL MATCH (e)-[:OBSERVED_IN]->(s:Session)
|
|
80
|
+
RETURN e.id, e.summary, collect(DISTINCT s.id) AS sessions
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Vectors are great for similarity. Graphs are great for _structure_ —
|
|
84
|
+
what depends on what, what's been tried, what contradicts what. Most
|
|
85
|
+
agent systems end up needing both.
|
|
86
|
+
|
|
87
|
+
### Context memory and retrieval
|
|
88
|
+
|
|
89
|
+
Memory that's only a list of chunks loses the relationships between
|
|
90
|
+
them. A graph keeps them: which fact supports which claim, which
|
|
91
|
+
document cites which, which entity was introduced by which turn. When
|
|
92
|
+
the model asks _"why do we believe X"_, that's a traversal.
|
|
93
|
+
|
|
94
|
+
### Robotics and stateful systems
|
|
95
|
+
|
|
96
|
+
Scene graphs, task graphs, capability graphs — robotics is full of
|
|
97
|
+
them. LoraDB runs in the controller's process, so scene updates and
|
|
98
|
+
plan queries don't cross a network. Schemas can evolve as the robot
|
|
99
|
+
learns new object categories without a migration.
|
|
100
|
+
|
|
101
|
+
### Event-driven architectures
|
|
102
|
+
|
|
103
|
+
Stream processors resolve entities, infer relationships, and emit
|
|
104
|
+
enrichments. Doing that in memory next to the handler avoids a hot
|
|
105
|
+
round-trip per event. Cypher makes the rules readable:
|
|
106
|
+
|
|
107
|
+
```cypher
|
|
108
|
+
MATCH (u:User {id: $user})-[:PLACED]->(o:Order)-[:CONTAINS]->(p:Product)
|
|
109
|
+
WHERE o.placed_at >= temporal.now() - 'P7D'::DURATION
|
|
110
|
+
RETURN p.category, count(*) AS recent
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Real-time reasoning over relationships
|
|
114
|
+
|
|
115
|
+
Anywhere a decision has to look across multiple entities and their
|
|
116
|
+
links — fraud signals, access control, lineage, recommendations — a
|
|
117
|
+
graph query says what you mean in one expression.
|
|
118
|
+
|
|
119
|
+
## What LoraDB enables
|
|
120
|
+
|
|
121
|
+
### Model relationships naturally
|
|
122
|
+
|
|
123
|
+
Labels and types are first-class. The model is what you read in the
|
|
124
|
+
query:
|
|
125
|
+
|
|
126
|
+
```cypher
|
|
127
|
+
CREATE (ada:Person {name: 'Ada'})
|
|
128
|
+
CREATE (grace:Person {name: 'Grace'})
|
|
129
|
+
CREATE (ada)-[:INFLUENCED {year: 1843}]->(grace)
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
No join table, no enum column, no convention to remember.
|
|
133
|
+
|
|
134
|
+
### Compose queries for reasoning and analysis
|
|
135
|
+
|
|
136
|
+
`WITH` pipes one stage's output into the next, so
|
|
137
|
+
non-trivial questions read top-to-bottom:
|
|
138
|
+
|
|
139
|
+
```cypher
|
|
140
|
+
MATCH (u:User)-[:PLACED]->(o:Order {status: 'paid'})
|
|
141
|
+
WITH u, count(o) AS orders
|
|
142
|
+
WHERE orders > 1
|
|
143
|
+
RETURN u.email, orders ORDER BY orders DESC
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Filter, aggregate, filter again — one expression, no temp tables.
|
|
147
|
+
|
|
148
|
+
### Keep evolving context cheap
|
|
149
|
+
|
|
150
|
+
LoraDB is schema-free. Adding a new label, a new relationship type,
|
|
151
|
+
or a new property means _writing_ it — there's no migration, no
|
|
152
|
+
`ALTER`, no restart. That fits systems that keep discovering new
|
|
153
|
+
categories of thing.
|
|
154
|
+
|
|
155
|
+
### Run in-process
|
|
156
|
+
|
|
157
|
+
Opening a database is a function call:
|
|
158
|
+
|
|
159
|
+
```rust
|
|
160
|
+
let mut db = Database::new();
|
|
161
|
+
db.execute("CREATE (:Person {name: 'Ada'})", None)?;
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Same story in [Node](./getting-started/node.md),
|
|
165
|
+
[Python](https://loradb.com/docs/getting-started/python), and
|
|
166
|
+
[WASM](https://loradb.com/docs/getting-started/wasm). There's also an
|
|
167
|
+
[HTTP server](https://loradb.com/docs/getting-started/server) when you'd rather reach it
|
|
168
|
+
over the wire, and a [browser playground](https://play.loradb.com)
|
|
169
|
+
when you'd rather try it before installing anything.
|
|
170
|
+
|
|
171
|
+
### Stay small enough to understand
|
|
172
|
+
|
|
173
|
+
A small Rust codebase — parser, analyzer, compiler, optimizer,
|
|
174
|
+
executor, storage — readable end-to-end. If the database matters to
|
|
175
|
+
your product, you should be able to read it. That's a deliberate
|
|
176
|
+
constraint, not a marketing line.
|
|
177
|
+
|
|
178
|
+
## Positioned against the alternatives
|
|
179
|
+
|
|
180
|
+
| | LoraDB | Managed graph DB | SQL + recursive CTEs | Document store |
|
|
181
|
+
|---|---|---|---|---|
|
|
182
|
+
| Deployment | A crate / binding | A service | Existing DB | Existing DB |
|
|
183
|
+
| Relationship model | First-class | First-class | Join tables | Nested or foreign-keyed |
|
|
184
|
+
| Query language | Pragmatic subset of Cypher | Full Cypher / GQL | SQL | Proprietary |
|
|
185
|
+
| Schema | Free | Typed / free | Strict | Free |
|
|
186
|
+
| Latency to query | Function call | Network hop | Network hop | Network hop |
|
|
187
|
+
| Scale | Single process | Horizontal | Horizontal | Horizontal |
|
|
188
|
+
| Fit for in-process / agent loops | Direct | Indirect | Indirect | Indirect |
|
|
189
|
+
|
|
190
|
+
LoraDB is **not** a replacement for a full graph platform when you
|
|
191
|
+
need durability, multi-tenant isolation, or horizontal scale. It's
|
|
192
|
+
the option that was missing in the other direction — the one you
|
|
193
|
+
reach for when the graph belongs _inside_ your process.
|
|
194
|
+
|
|
195
|
+
## Concrete scenarios
|
|
196
|
+
|
|
197
|
+
- **Agent working memory.** An LLM agent stores tools, observations,
|
|
198
|
+
and entity references as nodes, with typed edges between them. The
|
|
199
|
+
retrieval step is a `MATCH` pattern, not a similarity score.
|
|
200
|
+
- **Robot scene graph.** Objects, rooms, and affordances as nodes;
|
|
201
|
+
"is-on", "can-grasp", "observed-from" as edges. Plan queries run in
|
|
202
|
+
the controller.
|
|
203
|
+
- **Streaming entity resolution.** Events flow in; LoraDB holds the
|
|
204
|
+
current graph of resolved entities; enrichers consult it via
|
|
205
|
+
Cypher and emit back.
|
|
206
|
+
- **Permission inference.** Users, groups, resources, and grants as a
|
|
207
|
+
graph. "Can user U read resource R?" is a reachability query, not
|
|
208
|
+
a recursive SQL.
|
|
209
|
+
- **Lineage and dependency analysis.** Pipelines, models, datasets —
|
|
210
|
+
walk upstream or downstream in one query, not one join per hop.
|
|
211
|
+
|
|
212
|
+
## Where it's going
|
|
213
|
+
|
|
214
|
+
Near-term direction, not promises:
|
|
215
|
+
|
|
216
|
+
- **Persistence** — optional durable storage behind the same API.
|
|
217
|
+
- **Indexing** — hash and range indexes on property keys.
|
|
218
|
+
- **Query planner improvements** — better join ordering and cost
|
|
219
|
+
estimates.
|
|
220
|
+
- **Richer Cypher surface** — procedures,
|
|
221
|
+
`UNION`, list comprehensions.
|
|
222
|
+
|
|
223
|
+
See [**Limitations**](./limitations.md) for what's not yet supported,
|
|
224
|
+
and the [**docs**](./index.md) for what works today.
|
|
225
|
+
|
|
226
|
+
## Common questions
|
|
227
|
+
|
|
228
|
+
#### Is LoraDB a drop-in replacement for Neo4j or Memgraph?
|
|
229
|
+
|
|
230
|
+
No. LoraDB supports a scoped subset of Cypher — enough for application-level graph workloads, not the full surface that hosted graph platforms offer. The trade-off is that LoraDB embeds in-process with no separate server, no network hop, and no operational tier to run.
|
|
231
|
+
|
|
232
|
+
#### Does LoraDB scale horizontally?
|
|
233
|
+
|
|
234
|
+
Not today. LoraDB is an embedded engine, not a distributed database. One LoraDB instance lives inside one host process. Horizontal scaling, sharding, and replication are out of scope for the current design; if your dataset does not fit in RAM on one machine, LoraDB is the wrong choice.
|
|
235
|
+
|
|
236
|
+
#### Is LoraDB ACID?
|
|
237
|
+
|
|
238
|
+
Writes serialize at commit through a single lane. Reads run lock-free against an Arc snapshot taken at the start of the query, so concurrent reads never block writes or each other. With WAL enabled, commits are durable; without WAL, durability is at the granularity of explicit snapshots.
|
|
239
|
+
|
|
240
|
+
#### Why an in-memory engine in 2026?
|
|
241
|
+
|
|
242
|
+
Because the workloads LoraDB targets — AI agents, robot scene graphs, permission inference, retrieval over knowledge graphs — touch every node they care about on every query. The working set is hot by definition. Pushing it through a disk-based planner means paying for storage abstractions you do not need.
|
|
243
|
+
|
|
244
|
+
#### Can LoraDB persist data?
|
|
245
|
+
|
|
246
|
+
Yes. Snapshots write the full graph to a single file with an atomic rename and ship on every binding. WAL-backed durability is available on every filesystem-backed surface (Rust, Node, Python, Go, Ruby, and the HTTP server) — commits append to a write-ahead log and replay on recover above the snapshot fence.
|
|
247
|
+
|
|
248
|
+
#### What query language does LoraDB use?
|
|
249
|
+
|
|
250
|
+
A pragmatic subset of Cypher. Read clauses (MATCH, OPTIONAL MATCH, WHERE, WITH, RETURN), write clauses (CREATE, MERGE, SET, DELETE, REMOVE), iteration (UNWIND), paths and variable-length traversals, aggregation, and most built-in functions are supported. See Limitations for what is out of scope.
|
|
251
|
+
|
|
252
|
+
## See also
|
|
253
|
+
|
|
254
|
+
- [**What is LoraDB**](./index.md) — introduction, audiences, and quick start.
|
|
255
|
+
- [**Installation**](./getting-started/installation.md) — pick your
|
|
256
|
+
platform and get running.
|
|
257
|
+
- [**Ten-Minute Tour**](./getting-started/tutorial.md) — the case from
|
|
258
|
+
"why" to a working query.
|
|
259
|
+
- [**Graph Model**](./concepts/graph-model.md) — the data model in
|
|
260
|
+
four queries.
|
|
261
|
+
- [**Queries → Overview**](./queries/index.md) — the Cypher surface LoraDB
|
|
262
|
+
supports.
|
|
263
|
+
- [**Cookbook**](./cookbook.md) — scenario-driven recipes.
|
|
264
|
+
- [**Limitations**](./limitations.md) — what's not yet supported.
|
|
265
|
+
|
|
266
|
+
### Background reading
|
|
267
|
+
|
|
268
|
+
- [**Why I started LoraDB**](https://loradb.com/blog/why-i-started-loradb) — the
|
|
269
|
+
original motivation.
|
|
270
|
+
- [**In-memory or it does not work**](https://loradb.com/blog/in-memory-or-it-does-not-work)
|
|
271
|
+
— why the engine starts in RAM.
|
|
272
|
+
- [**Vectors belong next to relationships**](https://loradb.com/blog/vectors-belong-next-to-relationships)
|
|
273
|
+
— why `VECTOR` lives as a first-class value type.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@loradb/lora-node",
|
|
3
|
-
"version": "0.36.
|
|
3
|
+
"version": "0.36.2",
|
|
4
4
|
"description": "Node.js / TypeScript bindings for the Lora in-memory graph database",
|
|
5
5
|
"license": "BUSL-1.1",
|
|
6
6
|
"packageManager": "yarn@4.5.1",
|
|
@@ -40,6 +40,7 @@
|
|
|
40
40
|
"dist/",
|
|
41
41
|
"ts/native.js",
|
|
42
42
|
"ts/native.d.ts",
|
|
43
|
+
"docs/",
|
|
43
44
|
"README.md",
|
|
44
45
|
"LICENSE"
|
|
45
46
|
],
|
|
@@ -72,15 +73,13 @@
|
|
|
72
73
|
"scripts": {
|
|
73
74
|
"sync:types": "node -e \"const fs=require('fs'); for (const f of ['types.ts','decode.ts']) fs.copyFileSync('../shared-ts/' + f, 'ts/' + f);\"",
|
|
74
75
|
"verify:types": "node -e \"const fs=require('fs'); for (const f of ['types.ts','decode.ts']) { const a=fs.readFileSync('../shared-ts/' + f,'utf8'); const b=fs.readFileSync('ts/' + f,'utf8'); if (a!==b) { console.error('ts/' + f + ' is out of sync with shared-ts/' + f + ' — run yarn run sync:types'); process.exit(1);} } \"",
|
|
75
|
-
"prebuild": "yarn run sync:types",
|
|
76
|
-
"pretypecheck": "yarn run sync:types",
|
|
77
|
-
"pretest": "yarn run sync:types",
|
|
78
76
|
"build:native": "napi build --platform --release --js false",
|
|
79
77
|
"build:native:debug": "napi build --platform --js false",
|
|
80
78
|
"build:ts": "tsc -p tsconfig.json",
|
|
81
|
-
"build": "yarn run build:native && yarn run build:ts",
|
|
82
|
-
"
|
|
83
|
-
"
|
|
79
|
+
"build": "yarn run sync:types && yarn run build:native && yarn run build:ts && yarn run docs:bundle",
|
|
80
|
+
"docs:bundle": "node ../../../scripts/bundle-package-docs.mjs",
|
|
81
|
+
"typecheck": "yarn run sync:types && tsc -p tsconfig.json --noEmit",
|
|
82
|
+
"test": "yarn run sync:types && vitest run",
|
|
84
83
|
"test:watch": "vitest",
|
|
85
84
|
"lint": "eslint ts test",
|
|
86
85
|
"lint:fix": "eslint ts test --fix",
|
|
@@ -99,12 +98,12 @@
|
|
|
99
98
|
"vitest": "^2.1.1"
|
|
100
99
|
},
|
|
101
100
|
"optionalDependencies": {
|
|
102
|
-
"@loradb/lora-node-linux-x64-gnu": "0.36.
|
|
103
|
-
"@loradb/lora-node-linux-arm64-gnu": "0.36.
|
|
104
|
-
"@loradb/lora-node-linux-x64-musl": "0.36.
|
|
105
|
-
"@loradb/lora-node-linux-arm64-musl": "0.36.
|
|
106
|
-
"@loradb/lora-node-darwin-x64": "0.36.
|
|
107
|
-
"@loradb/lora-node-darwin-arm64": "0.36.
|
|
108
|
-
"@loradb/lora-node-win32-x64-msvc": "0.36.
|
|
101
|
+
"@loradb/lora-node-linux-x64-gnu": "0.36.2",
|
|
102
|
+
"@loradb/lora-node-linux-arm64-gnu": "0.36.2",
|
|
103
|
+
"@loradb/lora-node-linux-x64-musl": "0.36.2",
|
|
104
|
+
"@loradb/lora-node-linux-arm64-musl": "0.36.2",
|
|
105
|
+
"@loradb/lora-node-darwin-x64": "0.36.2",
|
|
106
|
+
"@loradb/lora-node-darwin-arm64": "0.36.2",
|
|
107
|
+
"@loradb/lora-node-win32-x64-msvc": "0.36.2"
|
|
109
108
|
}
|
|
110
109
|
}
|