@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
@@ -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.2"
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** | [![npm](https://img.shields.io/npm/v/@loradb/lora-node?label=%40loradb%2Flora-node&logo=npm)](https://www.npmjs.com/package/@loradb/lora-node) | `npm install @loradb/lora-node` | [Node →](./node.md) |
69
+ | **Python** | [![PyPI](https://img.shields.io/pypi/v/lora-python?label=pypi&logo=pypi&logoColor=white)](https://pypi.org/project/lora-python/) | `pip install lora-python` | [Python →](https://loradb.com/docs/getting-started/python) |
70
+ | **Browser / WASM** | [![npm](https://img.shields.io/npm/v/@loradb/lora-wasm?label=%40loradb%2Flora-wasm&logo=npm)](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** | [![Gem](https://img.shields.io/gem/v/lora-ruby?label=lora-ruby&logo=rubygems&logoColor=white)](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
+ [![crates.io](https://img.shields.io/crates/v/lora-database?label=crates.io&logo=rust)](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.