@loradb/lora-node 0.36.0 → 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/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,204 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Install and Set Up LoraDB"
|
|
3
|
+
description: "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."
|
|
4
|
+
online: "https://loradb.com/docs/getting-started/installation"
|
|
5
|
+
package: "@loradb/lora-node@0.36.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Install and Set Up LoraDB
|
|
9
|
+
|
|
10
|
+
## Overview
|
|
11
|
+
|
|
12
|
+
LoraDB is one Rust engine with bindings for the major application
|
|
13
|
+
runtimes — Node.js, Python, WebAssembly, Go, and Ruby — plus a
|
|
14
|
+
standalone HTTP server and direct embedding from Rust. Every binding
|
|
15
|
+
shares the same parser, planner, executor, and result shape, so
|
|
16
|
+
switching hosts later is a mechanical translation. This page helps
|
|
17
|
+
you pick; each binding guide covers install, connect, execute, and
|
|
18
|
+
error handling end-to-end.
|
|
19
|
+
|
|
20
|
+
If you only want to try the query surface first, start with the
|
|
21
|
+
[browser playground](https://loradb.com/docs/getting-started/playground). It runs LoraDB through WASM without
|
|
22
|
+
installing a package.
|
|
23
|
+
|
|
24
|
+
**Install LoraDB and run your first query**
|
|
25
|
+
|
|
26
|
+
The shortest happy path: pick the binding for your runtime, install one package, open an in-memory handle, and run a Cypher query.
|
|
27
|
+
|
|
28
|
+
1. **Pick a runtime**: Choose the binding that matches your host: Node.js, Python, WebAssembly in the browser, Go, Ruby, the lora-database Rust crate for direct embedding, or the lora-server HTTP service. Every binding wraps the same engine.
|
|
29
|
+
2. **Install the package**: Run npm install @loradb/lora-node, pip install lora-python, npm install @loradb/lora-wasm, go get github.com/lora-db/lora/crates/bindings/lora-go, gem install loradb, or cargo add lora-database depending on the runtime you picked.
|
|
30
|
+
3. **Open an in-memory database**: Call Database.create() (Node, Python, Ruby) or its equivalent in your binding. The handle starts with an empty graph and is safe to share across threads / async tasks.
|
|
31
|
+
4. **Run a Cypher query**: Execute CREATE (:Person {name: 'Ada'}) followed by MATCH (p:Person) RETURN p.name to confirm the install works end-to-end.
|
|
32
|
+
5. **Add persistence when ready**: Save the graph with a snapshot (saveSnapshot / save_snapshot_to) or open with WAL-backed durability for continuous persistence. Snapshots are atomic on rename; WAL replays above the snapshot fence on recover.
|
|
33
|
+
|
|
34
|
+
## First-time checklist
|
|
35
|
+
|
|
36
|
+
Before choosing an install path, decide three things:
|
|
37
|
+
|
|
38
|
+
| Question | Recommendation |
|
|
39
|
+
|---|---|
|
|
40
|
+
| Do you need parameters for user input? | Use any binding or HTTP `/query` with `params`. Never interpolate raw input into query text. |
|
|
41
|
+
| Should data survive process restarts? | Open a named `.loradb` archive, save snapshots, or use a WAL-backed open. Plain in-memory handles are scratch graphs. |
|
|
42
|
+
| Will the graph be reachable over a network? | Prefer an in-process binding. If you use `lora-server`, keep it on `127.0.0.1` or put auth, TLS, and rate limiting in front. |
|
|
43
|
+
|
|
44
|
+
The shortest happy path for most app developers is: install the
|
|
45
|
+
binding for your host language, run the minimal example in that guide,
|
|
46
|
+
then add persistence only when the prototype needs it.
|
|
47
|
+
|
|
48
|
+
## Installation / Setup
|
|
49
|
+
|
|
50
|
+
### Requirements by surface
|
|
51
|
+
|
|
52
|
+
| Surface | Extra requirements |
|
|
53
|
+
|---|---|
|
|
54
|
+
| Node / TS | Node.js 18+ for the published package; Node.js 20+ for repo-local workspace tooling |
|
|
55
|
+
| Python | Python 3.8+; `maturin` only when building from source |
|
|
56
|
+
| WASM | Node.js 20+ for bundling/testing |
|
|
57
|
+
| Go | Go 1.21+, cgo enabled, C toolchain, and `liblora_ffi` |
|
|
58
|
+
| Ruby | Ruby 3.1+, Bundler, and a native build toolchain |
|
|
59
|
+
| Rust / server from source | Rust 1.87+ through `rustup` |
|
|
60
|
+
|
|
61
|
+
Published packages hide most native build steps. Repo-local development needs
|
|
62
|
+
the toolchains above because the bindings compile the Rust engine.
|
|
63
|
+
|
|
64
|
+
### Pick a platform
|
|
65
|
+
|
|
66
|
+
| Platform | Package | Install | Guide |
|
|
67
|
+
|---|---|---|---|
|
|
68
|
+
| **Node / TS** | [](https://www.npmjs.com/package/@loradb/lora-node) | `npm install @loradb/lora-node` | [Node →](./node.md) |
|
|
69
|
+
| **Python** | [](https://pypi.org/project/lora-python/) | `pip install lora-python` | [Python →](https://loradb.com/docs/getting-started/python) |
|
|
70
|
+
| **Browser / WASM** | [](https://www.npmjs.com/package/@loradb/lora-wasm) | `npm install @loradb/lora-wasm` | [WASM →](https://loradb.com/docs/getting-started/wasm) |
|
|
71
|
+
| **Go** | [pkg.go.dev](https://pkg.go.dev/github.com/lora-db/lora/crates/bindings/lora-go) | `go get github.com/lora-db/lora/crates/bindings/lora-go` | [Go →](https://loradb.com/docs/getting-started/go) |
|
|
72
|
+
| **Ruby** | [](https://rubygems.org/gems/lora-ruby) | `gem install lora-ruby` | [Ruby →](https://loradb.com/docs/getting-started/ruby) |
|
|
73
|
+
|
|
74
|
+
> **Tip**
|
|
75
|
+
>
|
|
76
|
+
>
|
|
77
|
+
> Click any badge to jump to its package-registry page. Each platform
|
|
78
|
+
> guide also documents repo-local build steps for contributors working
|
|
79
|
+
> from a clone.
|
|
80
|
+
>
|
|
81
|
+
|
|
82
|
+
### Which to pick?
|
|
83
|
+
|
|
84
|
+
| If you… | Pick |
|
|
85
|
+
|---|---|
|
|
86
|
+
| Ship a Node server / CLI | Node.js |
|
|
87
|
+
| Build in Python (sync or asyncio) | Python |
|
|
88
|
+
| Run in the browser / Web Worker / edge | WASM |
|
|
89
|
+
| Build a Go service or CLI (cgo) | Go |
|
|
90
|
+
| Ship a Ruby app, worker, or Rails service | Ruby |
|
|
91
|
+
| Evaluate from a shell or another language | HTTP server |
|
|
92
|
+
|
|
93
|
+
All bindings share the same query surface and result shape — the
|
|
94
|
+
Cypher is identical, only the host-language wrapper differs.
|
|
95
|
+
|
|
96
|
+
### Rust and HTTP server
|
|
97
|
+
|
|
98
|
+
Two more paths share the same Cypher surface:
|
|
99
|
+
|
|
100
|
+
- [**Rust crate**](https://loradb.com/docs/getting-started/rust) — embed `lora-database` directly in a
|
|
101
|
+
Rust binary for the lowest-overhead option.
|
|
102
|
+
[](https://crates.io/crates/lora-database)
|
|
103
|
+
- [**HTTP server**](https://loradb.com/docs/getting-started/server) — run `lora-server` and `POST /query`
|
|
104
|
+
from any language.
|
|
105
|
+
|
|
106
|
+
## Creating a Client / Connection
|
|
107
|
+
|
|
108
|
+
Every binding exposes the same two primitives:
|
|
109
|
+
|
|
110
|
+
1. A `Database` with `execute(query, params?)`.
|
|
111
|
+
2. A result: `{ columns, rows }`, where each row maps column name →
|
|
112
|
+
typed value.
|
|
113
|
+
|
|
114
|
+
See each platform guide for the language-specific shape.
|
|
115
|
+
|
|
116
|
+
## Running Your First Query
|
|
117
|
+
|
|
118
|
+
```cypher
|
|
119
|
+
CREATE (:Person {name: 'Ada'})
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
```cypher
|
|
123
|
+
MATCH (p:Person) RETURN p.name
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
In any binding that's two `execute` calls; the platform guide shows
|
|
127
|
+
the language-specific syntax.
|
|
128
|
+
|
|
129
|
+
## Examples
|
|
130
|
+
|
|
131
|
+
### Shared value model
|
|
132
|
+
|
|
133
|
+
Typed values follow one contract (defined in
|
|
134
|
+
`crates/bindings/shared-ts/types.ts`): primitives, lists/maps, graph entities
|
|
135
|
+
(tagged `{kind: "node" | "relationship" | "path"}`), temporals
|
|
136
|
+
(tagged `{kind: "date" | "datetime" | ...}`), and points (tagged
|
|
137
|
+
`{kind: "point", srid, crs, ...}`).
|
|
138
|
+
|
|
139
|
+
See [**Data Types Overview**](../data-types/overview.md) for the full
|
|
140
|
+
catalogue and each binding's parameters section for how host values
|
|
141
|
+
map in.
|
|
142
|
+
|
|
143
|
+
## Common Patterns
|
|
144
|
+
|
|
145
|
+
### One process, one graph
|
|
146
|
+
|
|
147
|
+
Each binding defaults to **one process, one in-memory graph**.
|
|
148
|
+
Auto-commit reads on the same handle can overlap on snapshots; write commits
|
|
149
|
+
and explicit read-write transactions serialize. Spawn multiple `Database`
|
|
150
|
+
instances only when you intentionally want separate graphs or archives.
|
|
151
|
+
|
|
152
|
+
If you want persistence, opt into it explicitly:
|
|
153
|
+
|
|
154
|
+
- On `lora-node`, pass a database name and database directory to `createDatabase('app', { databaseDir: './data' })`.
|
|
155
|
+
- On `lora-node`, use `openWalDatabase({ walDir: './data/wal' })` for an explicit WAL directory.
|
|
156
|
+
- On Rust / `lora-server`, configure a WAL directory.
|
|
157
|
+
- On Python, Go, and Ruby, pass a database name plus their `database_dir` /
|
|
158
|
+
`DatabaseDir` option for `.loradb` archives, or use `open_wal` /
|
|
159
|
+
`OpenWal` for an explicit WAL directory.
|
|
160
|
+
|
|
161
|
+
### Bulk-load from the host
|
|
162
|
+
|
|
163
|
+
The idiomatic large-write shape across every binding is
|
|
164
|
+
[`UNWIND $rows AS row CREATE …`](../queries/unwind-merge.md#bulk-load-from-parameter).
|
|
165
|
+
The `$rows` parameter comes from a plain list in the host language.
|
|
166
|
+
|
|
167
|
+
### Share a database across modules
|
|
168
|
+
|
|
169
|
+
Wrap the handle in whatever sharing primitive your language provides
|
|
170
|
+
— `Arc` in Rust, a module singleton in Node/Python, a Worker in the
|
|
171
|
+
browser.
|
|
172
|
+
|
|
173
|
+
## Error Handling
|
|
174
|
+
|
|
175
|
+
Every binding exposes two error layers:
|
|
176
|
+
|
|
177
|
+
- **Query-level errors** — parse, semantic, or runtime — surface the
|
|
178
|
+
engine's message. Typical cases live in
|
|
179
|
+
[Troubleshooting](../troubleshooting.md).
|
|
180
|
+
- **Connection / host-level errors** — language-specific (HTTP
|
|
181
|
+
status, FFI exceptions, spawn failures). Each platform guide
|
|
182
|
+
covers its own.
|
|
183
|
+
|
|
184
|
+
## Performance / Best Practices
|
|
185
|
+
|
|
186
|
+
- **Persistence depends on the binding.** Point-in-time snapshots via
|
|
187
|
+
`save_snapshot` / `load_snapshot` exist on every binding
|
|
188
|
+
(byte-based on WASM). Continuous durability via WAL exists on every
|
|
189
|
+
filesystem-backed binding: Rust, `lora-node`, Python, Go, Ruby, and
|
|
190
|
+
`lora-server`. WASM remains snapshot-only.
|
|
191
|
+
See [Limitations → Storage](../limitations.md#storage).
|
|
192
|
+
- **No query cancellation.** Once dispatched, queries run to
|
|
193
|
+
completion. Keep queries bounded (`LIMIT`, `*..N` caps).
|
|
194
|
+
- **Parameters, not string interpolation.** The only safe way to
|
|
195
|
+
mix untrusted input into a query.
|
|
196
|
+
|
|
197
|
+
## See also
|
|
198
|
+
|
|
199
|
+
- [**Ten-Minute Tour**](./tutorial.md) — guided walkthrough.
|
|
200
|
+
- [**Graph Model**](../concepts/graph-model.md) — what lives in the graph.
|
|
201
|
+
- [**Query Examples**](../queries/examples.md) — copy-paste recipes.
|
|
202
|
+
- [**Cookbook**](../cookbook.md) — scenario-based recipes.
|
|
203
|
+
- [**Data Types**](../data-types/overview.md) — values and parameters.
|
|
204
|
+
- [**Troubleshooting**](../troubleshooting.md) — when something goes wrong.
|