@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.
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 +349 -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 +538 -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,545 @@
1
+ ---
2
+ title: "Snapshots"
3
+ description: "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."
4
+ online: "https://loradb.com/docs/snapshot"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # Snapshots
9
+
10
+ LoraDB can dump the in-memory graph to a single file and restore it
11
+ later. A snapshot is the full graph frozen from the database's current
12
+ Arc snapshot — taken on demand, atomic on rename, readable from any
13
+ binding.
14
+
15
+ Snapshots are shipped as of v0.3. They close the "no persistence at
16
+ all" gap for workloads that only need occasional save / restore
17
+ operations (seeded services, notebooks, graceful-shutdown saves,
18
+ scheduled backups). Continuous durability is now available through the
19
+ [WAL](./wal.md) on every filesystem-backed surface, but snapshots are
20
+ still the portable file primitive those surfaces checkpoint to.
21
+
22
+ ## What a snapshot is
23
+
24
+ - A **single encoded payload** containing the full graph — every node,
25
+ every relationship, every property — plus a short header describing
26
+ the format. Filesystem bindings write that payload as one file; WASM
27
+ returns bytes or web-native wrappers around those bytes.
28
+ - A **point-in-time dump.** The save loads the current Arc snapshot and
29
+ encodes that graph consistently; readers already using an older Arc
30
+ continue normally.
31
+ - **Atomic on rename for path-based saves.** Writes land in
32
+ `<path>.tmp`, are `fsync`'d, then renamed over the target; a
33
+ crashed save can leave a stale `.tmp` file but never a half-written
34
+ target.
35
+ - **Format-versioned.** Files declare an envelope/body format version; the
36
+ reader accepts supported versions and rejects unsupported ones rather than
37
+ partially loading unknown data.
38
+
39
+ ## What snapshots are not
40
+
41
+ The bright line, stated explicitly so it cannot be missed:
42
+
43
+ - **Not continuous durability.** A crash between two saves loses every
44
+ mutation in the window unless you pair snapshots with the WAL on a
45
+ filesystem-backed surface.
46
+ - **Not a wall-clock checkpoint scheduler.** Manual snapshots run when
47
+ you call them. Explicit WAL helpers can also write managed snapshots
48
+ after N committed transactions, but there is no built-in timer.
49
+ - **Not a WAL write.** Loading a snapshot into a WAL-backed database
50
+ checkpoints the loaded graph into its managed snapshot directory or
51
+ `.loradb` file before the load returns. A WAL-backed database with
52
+ neither refuses the load with `LORA_CONFIG`; restore it at startup with
53
+ `--restore-from` instead.
54
+ - **Not a general persistent storage layer.** There is no alternative
55
+ backend; a snapshot is a dump of the in-memory graph, not a format
56
+ a different engine writes into.
57
+ - **Not free.** Saves and loads are whole-graph operations. Existing
58
+ readers can keep using their pinned Arc snapshot, but the encode/decode work
59
+ is still proportional to graph size.
60
+ - **Not a multi-tenant boundary.** One process holds one graph; each
61
+ process you run needs its own snapshot file.
62
+
63
+ ## When to use snapshots
64
+
65
+ Good fits:
66
+
67
+ - **Seeded services and agents.** Build the graph offline from a
68
+ cheaper source, snapshot it, and ship the file alongside the
69
+ deployment. Every restart boots in one file-read.
70
+ - **Notebooks, demos, research tooling.** Save what you've curated;
71
+ reload it tomorrow with one call.
72
+ - **Graceful shutdown.** A final `save_snapshot` (or `POST
73
+ /admin/snapshot/save` from systemd `ExecStop`) preserves the graph
74
+ across planned restarts.
75
+ - **Scheduled backups.** A cron that calls the admin endpoint with a
76
+ rotating filename every N minutes is a complete backup policy for
77
+ graphs that fit the save window.
78
+
79
+ Bad fits:
80
+
81
+ - **Hard-durability workloads.** If losing even a minute of mutations
82
+ on crash is unacceptable, snapshots alone are not enough — use one
83
+ of the [WAL-enabled surfaces](./wal.md).
84
+ - **Very large graphs where save time exceeds your query window.** Save work is
85
+ proportional to graph size and can add meaningful CPU/I/O pressure.
86
+
87
+ ## Metadata
88
+
89
+ Path-based saves, load calls, and HTTP admin calls return a small
90
+ metadata record. Byte-output save APIs such as WASM `saveSnapshot()` or
91
+ Node `saveSnapshot()` return the snapshot bytes directly instead.
92
+
93
+ ```json
94
+ {
95
+ "formatVersion": 3,
96
+ "nodeCount": 1024,
97
+ "relationshipCount": 4096,
98
+ "walLsn": null
99
+ }
100
+ ```
101
+
102
+ | Field | Type | Meaning |
103
+ |---|---|---|
104
+ | `formatVersion` | integer | Envelope format of the snapshot file. `3` for every snapshot this release writes; `2` when loading one an older release wrote. |
105
+ | `nodeCount` | integer | Nodes in the saved / restored graph. |
106
+ | `relationshipCount` | integer | Relationships in the saved / restored graph. |
107
+ | `walLsn` | integer or null | The WAL fence on a WAL-backed database, for saves and checkpoints alike; `null` for a database without a WAL. |
108
+
109
+ Whenever metadata is returned, every binding uses the same four
110
+ fields; the spelling of the field names matches the wire shape
111
+ (camelCase).
112
+
113
+ ## Compression and encryption
114
+
115
+ Embedded bindings can save snapshots with codec options:
116
+
117
+ | Option | Supported values |
118
+ |---|---|
119
+ | `compression` | `"none"`, `"gzip"`, `"zstd"`, `{ format: "gzip", level: 0..9 }` or `{ format: "zstd", level: 1..22 }` (zstd: native builds; wasm reads it but cannot write it) |
120
+ | `encryption` | Password / passphrase encryption, or a raw 32-byte key |
121
+
122
+ Password encryption is the most portable shape:
123
+
124
+ ```ts
125
+ const encryption = {
126
+ type: 'password',
127
+ keyId: 'backup-key',
128
+ password: process.env.LORA_SNAPSHOT_PASSWORD!,
129
+ };
130
+
131
+ await db.saveSnapshot('graph.lorasnap', {
132
+ compression: { format: 'gzip', level: 1 },
133
+ encryption,
134
+ });
135
+
136
+ await db.loadSnapshot('graph.lorasnap', { credentials: encryption });
137
+ ```
138
+
139
+ Node, Python, WASM, and Ruby accept this JSON-style option shape; Go
140
+ mirrors it with `SnapshotOptions`, `SnapshotCompression`, and
141
+ `SnapshotEncryption` structs; Rust uses the typed `SnapshotOptions`,
142
+ `SnapshotPassword`, and `EncryptionKey` structs. Load calls accept the
143
+ credentials either under `credentials` or `encryption`, so the same
144
+ object used to save can usually be reused to load. HTTP admin snapshot
145
+ routes do not accept per-call codec options today; use an in-process
146
+ binding when you need custom compression or encryption.
147
+
148
+ ## Binding examples
149
+
150
+ Snapshots are exposed on every binding that exposes the engine. The
151
+ shape is always "save produces a file or byte payload, load consumes a
152
+ source, and metadata is returned whenever the operation has a metadata
153
+ surface".
154
+
155
+ ### Rust
156
+
157
+ The reference surface. Every other binding wraps these two methods.
158
+
159
+ ```rust
160
+ use lora_database::Database;
161
+
162
+ let db = Database::in_memory();
163
+ db.execute("CREATE (:Person {name: 'Ada'})", None)?;
164
+
165
+ // Dump the graph to a file. Atomic on rename.
166
+ let meta = db.save_snapshot_to("graph.bin")?;
167
+ println!("saved {} nodes, {} relationships",
168
+ meta.node_count, meta.relationship_count);
169
+
170
+ // Boot a fresh Database directly from the snapshot.
171
+ let db2 = Database::in_memory_from_snapshot("graph.bin")?;
172
+
173
+ // Or overlay a snapshot onto an existing handle.
174
+ db.load_snapshot_from("graph.bin")?;
175
+ ```
176
+
177
+ `SnapshotMeta` is re-exported from `lora_database`:
178
+
179
+ ```rust
180
+ use lora_database::SnapshotMeta;
181
+ fn log_meta(m: SnapshotMeta) {
182
+ tracing::info!(
183
+ format = m.format_version,
184
+ nodes = m.node_count,
185
+ rels = m.relationship_count,
186
+ wal = ?m.wal_lsn,
187
+ );
188
+ }
189
+ ```
190
+
191
+ ### Python
192
+
193
+ Synchronous:
194
+
195
+ ```python
196
+ from lora_python import Database
197
+
198
+ db = Database.create()
199
+ db.execute("CREATE (:Person {name: 'Ada'})")
200
+
201
+ meta = db.save_snapshot("graph.bin")
202
+ print(meta["nodeCount"], meta["relationshipCount"])
203
+
204
+ db2 = Database.create()
205
+ db2.load_snapshot("graph.bin")
206
+ ```
207
+
208
+ Async — same methods as coroutines on `AsyncDatabase`:
209
+
210
+ ```python
211
+ import asyncio
212
+ from lora_python import AsyncDatabase
213
+
214
+ async def main():
215
+ db = await AsyncDatabase.create()
216
+ await db.execute("CREATE (:Person {name: 'Ada'})")
217
+ await db.save_snapshot("graph.bin")
218
+
219
+ db2 = await AsyncDatabase.create()
220
+ await db2.load_snapshot("graph.bin")
221
+
222
+ asyncio.run(main())
223
+ ```
224
+
225
+ Both the sync and async forms run with the GIL released (sync) / on a
226
+ worker thread (async) so other Python threads / coroutines make
227
+ progress during the call. A large save still consumes native engine work and
228
+ filesystem I/O proportional to graph size.
229
+
230
+ ### Node.js / TypeScript
231
+
232
+ ```ts
233
+ import { createDatabase, type SnapshotMeta } from '@loradb/lora-node';
234
+
235
+ const db = await createDatabase(); // in-memory by default
236
+ // const db = await createDatabase('app', { databaseDir: './data' }); // container-backed
237
+ await db.execute("CREATE (:Person {name: 'Ada'})");
238
+
239
+ const meta: SnapshotMeta = await db.saveSnapshot('graph.bin');
240
+ console.log(meta.nodeCount, meta.relationshipCount);
241
+
242
+ const db2 = await createDatabase();
243
+ await db2.loadSnapshot('graph.bin');
244
+ ```
245
+
246
+ `saveSnapshot(path)` writes atomically and resolves to `SnapshotMeta`.
247
+ Calling `saveSnapshot()` with no path returns a Node `Buffer`; you can
248
+ also request `uint8Array`, `arrayBuffer`, `base64`, or a Node stream.
249
+ `loadSnapshot` accepts a string / `URL` path, `Buffer`, `Uint8Array`,
250
+ `ArrayBuffer`, Node `Readable`, Web `ReadableStream`, or async
251
+ iterable. The native engine work still encodes or decodes the whole graph for
252
+ the duration of the save or load.
253
+
254
+ ### WebAssembly
255
+
256
+ WASM has no filesystem path API. The snapshot API is byte/source based:
257
+ the caller chooses where to persist the bytes, and `loadSnapshot` never
258
+ accepts a string path.
259
+
260
+ ```ts
261
+ import { createDatabase } from '@loradb/lora-wasm';
262
+
263
+ const db = await createDatabase();
264
+ await db.execute("CREATE (:Person {name: 'Ada'})");
265
+
266
+ // Serialize the graph to a Uint8Array.
267
+ const bytes: Uint8Array = await db.saveSnapshot();
268
+
269
+ // Persist however your app already stores state:
270
+ // IndexedDB, localStorage, OPFS, a POST to your backend,
271
+ // `fs.writeFileSync` in Node — all work.
272
+
273
+ // Later (same or a new session), restore from bytes.
274
+ const db2 = await createDatabase();
275
+ await db2.loadSnapshot(bytes);
276
+ ```
277
+
278
+ `saveSnapshot` can also return `{ format: "arrayBuffer" }`,
279
+ `"blob"`, `"response"`, `"stream"`, or `"url"`. `loadSnapshot`
280
+ accepts `URL`, `Uint8Array`, `ArrayBuffer`, `Blob`, `Response`, or a
281
+ `ReadableStream<Uint8Array | ArrayBuffer>`.
282
+
283
+ The Worker-backed surface (`createWorkerDatabase`) exposes the same
284
+ `saveSnapshot` / `loadSnapshot` methods and moves the snapshot work to
285
+ the worker thread.
286
+
287
+ #### Persist across reloads with IndexedDB
288
+
289
+ ```ts
290
+ const DB = 'loradb-snapshots', STORE = 'graph', KEY = 'main';
291
+
292
+ async function idb(): Promise<IDBDatabase> {
293
+ return await new Promise((ok, err) => {
294
+ const r = indexedDB.open(DB, 1);
295
+ r.onupgradeneeded = () => r.result.createObjectStore(STORE);
296
+ r.onsuccess = () => ok(r.result);
297
+ r.onerror = () => err(r.error);
298
+ });
299
+ }
300
+
301
+ async function saveToIdb(db: Database) {
302
+ const bytes = await db.saveSnapshot();
303
+ const idbDb = await idb();
304
+ await new Promise<void>((ok, err) => {
305
+ const tx = idbDb.transaction(STORE, 'readwrite');
306
+ tx.objectStore(STORE).put(bytes, KEY);
307
+ tx.oncomplete = () => ok();
308
+ tx.onerror = () => err(tx.error);
309
+ });
310
+ }
311
+
312
+ async function loadFromIdb(db: Database) {
313
+ const idbDb = await idb();
314
+ const bytes = await new Promise<Uint8Array | undefined>((ok, err) => {
315
+ const tx = idbDb.transaction(STORE, 'readonly');
316
+ const r = tx.objectStore(STORE).get(KEY);
317
+ r.onsuccess = () => ok(r.result);
318
+ r.onerror = () => err(r.error);
319
+ });
320
+ if (bytes) await db.loadSnapshot(bytes);
321
+ }
322
+ ```
323
+
324
+ ### Go
325
+
326
+ ```go
327
+ import lora "github.com/lora-db/lora/crates/bindings/lora-go"
328
+
329
+ db, err := lora.New()
330
+ if err != nil { log.Fatal(err) }
331
+ defer db.Close()
332
+
333
+ if _, err := db.Execute("CREATE (:Person {name: 'Ada'})", nil); err != nil {
334
+ log.Fatal(err)
335
+ }
336
+
337
+ meta, err := db.SaveSnapshot("graph.bin")
338
+ if err != nil { log.Fatal(err) }
339
+ fmt.Printf("nodes=%d rels=%d\n", meta.NodeCount, meta.RelationshipCount)
340
+
341
+ db2, err := lora.New()
342
+ if err != nil { log.Fatal(err) }
343
+ defer db2.Close()
344
+
345
+ if _, err := db2.LoadSnapshot("graph.bin"); err != nil {
346
+ log.Fatal(err)
347
+ }
348
+ ```
349
+
350
+ `SnapshotMeta.WalLsn` is a `*uint64`; it is `nil` for snapshots saved
351
+ without a WAL and non-`nil` when you load or save a snapshot stamped by a
352
+ WAL-enabled surface.
353
+
354
+ ### Ruby
355
+
356
+ ```ruby
357
+ require "lora_ruby"
358
+
359
+ db = LoraRuby::Database.create
360
+ db.execute("CREATE (:Person {name: 'Ada'})")
361
+
362
+ meta = db.save_snapshot("graph.bin")
363
+ puts "#{meta['nodeCount']} nodes, #{meta['relationshipCount']} relationships"
364
+
365
+ db2 = LoraRuby::Database.create
366
+ db2.load_snapshot("graph.bin")
367
+ ```
368
+
369
+ ## HTTP admin surface
370
+
371
+ `lora-server` exposes snapshot save and load as two HTTP endpoints.
372
+ Both are **opt-in**: they are mounted only when the server is started
373
+ with `--snapshot-path`.
374
+
375
+ ### Enabling the endpoints
376
+
377
+ ```bash
378
+ lora-server \
379
+ --host 127.0.0.1 --port 4747 \
380
+ --snapshot-path /var/lib/lora/db.bin
381
+ ```
382
+
383
+ Without the flag, the routes return `404`. This is deliberate — the
384
+ admin surface has no authentication, and an unauthenticated admin
385
+ endpoint on a network-reachable port is a footgun. Off by default
386
+ means "never exposed by accident".
387
+
388
+ The same path can also be provided via the `LORA_SERVER_SNAPSHOT_PATH`
389
+ environment variable.
390
+
391
+ ### Saving and loading
392
+
393
+ ```bash
394
+ curl -sX POST http://127.0.0.1:4747/admin/snapshot/save
395
+ # => {"formatVersion":3,"nodeCount":1024,"relationshipCount":4096,"walLsn":null,"path":"/var/lib/lora/db.bin"}
396
+
397
+ curl -sX POST http://127.0.0.1:4747/admin/snapshot/load
398
+ ```
399
+
400
+ Both endpoints accept an optional `{ "path": "…" }` body that
401
+ overrides the configured default for one request — useful for ad-hoc
402
+ backups to a rotated filename. Overrides are only accepted when the
403
+ server runs with `--admin-path-root <DIR>`, and must stay inside `DIR`:
404
+
405
+ ```bash
406
+ curl -sX POST http://127.0.0.1:4747/admin/snapshot/save \
407
+ -H 'content-type: application/json' \
408
+ -d '{"path": "/var/backups/lora/2026-04-24.bin"}'
409
+ ```
410
+
411
+ The response includes the same four metadata fields as every other
412
+ binding, plus the `path` that was actually used.
413
+
414
+ When WAL is enabled, every save stamps `walLsn` with the durable WAL
415
+ fence, so the file can be recovered over the same WAL directory without
416
+ replaying writes it already holds. `POST /admin/checkpoint` writes the
417
+ same format and also marks the WAL and drops the segments the snapshot
418
+ covers; a plain save leaves the WAL alone. See
419
+ [WAL and checkpoints](./wal.md).
420
+
421
+ ### Restoring at boot
422
+
423
+ `--restore-from <PATH>` loads a snapshot once, at startup, before the
424
+ server begins accepting queries:
425
+
426
+ ```bash
427
+ lora-server \
428
+ --restore-from /var/lib/lora/seed.bin \
429
+ --snapshot-path /var/lib/lora/runtime.bin
430
+ ```
431
+
432
+ - A missing file at boot is fine: the server logs a message and starts
433
+ with an empty graph.
434
+ - A malformed file at boot is fatal.
435
+ - `--restore-from` is **independent** of `--snapshot-path`. You can
436
+ restore from a read-only seed and snapshot to a writable runtime
437
+ path, or pass the same path to both for the "boot from the last save
438
+ every time" pattern:
439
+
440
+ ```bash
441
+ lora-server \
442
+ --host 127.0.0.1 --port 4747 \
443
+ --snapshot-path /var/lib/lora/db.bin \
444
+ --restore-from /var/lib/lora/db.bin
445
+ ```
446
+
447
+ ### Security warning
448
+
449
+ > **Caution**
450
+ >
451
+ >
452
+ > The admin endpoints have **no authentication**, and the optional
453
+ > `path` body field is passed straight to the OS. Any client that can
454
+ > reach the admin port can:
455
+ >
456
+ > - write files anywhere the server UID can write, or
457
+ > - swap the live graph by pointing `load` at an attacker-staged file.
458
+ >
459
+ > Do not expose the admin surface on a network-reachable host without
460
+ > authenticated ingress in front of it. A reverse proxy with auth, a
461
+ > Unix socket, or simply not binding the port at all are all acceptable
462
+ > answers. Future releases may add authentication; until then, the
463
+ > correct deployment is "admin surface disabled by default, enabled only
464
+ > behind an auth boundary".
465
+ >
466
+ > See [Limitations → HTTP server](./limitations.md#http-server) and
467
+ > [HTTP API → Admin endpoints (opt-in)](https://loradb.com/docs/api/http#admin-endpoints-opt-in)
468
+ > for the detailed security profile.
469
+ >
470
+
471
+ ## File format (reference)
472
+
473
+ Snapshots are written in envelope format 3: framed records, each frame
474
+ compressed on its own so snapshots are built and read on every core. Files
475
+ declare their envelope format version and are rejected when the reader does not
476
+ support it. Format 2 (one column-oriented body) still loads; the `LORASNAP`
477
+ legacy format has been retired.
478
+
479
+ ```
480
+ [0..8) magic "LORACOL1"
481
+ [8..12) format u32 — envelope format, currently 3
482
+ [12..16) manifest_len u32
483
+ [16..24) body_len u64
484
+ [24..56) checksum BLAKE3(manifest || body)
485
+ [56..) manifest explicit binary manifest
486
+ [...end) body framed records and catalogs (format 3), or a column-oriented payload (format 2)
487
+ ```
488
+
489
+ The manifest carries `walLsn`, node and relationship counts,
490
+ compression, encryption metadata, and the body length. A format 3 body holds
491
+ the id counters and the graph's dictionaries, then nodes and relationships in
492
+ frames of 4,096 ids, then one catalog frame with the index, constraint and
493
+ vector index definitions, so `SHOW INDEXES` and `SHOW CONSTRAINTS` state
494
+ survives snapshot save/load. Each frame is compressed on its own (zstd by
495
+ default, gzip or none); encryption seals the whole body. A format 2 body stores
496
+ the same graph in separate columns (body versions 2 to 5); older catalog-free
497
+ bodies still load with empty index and constraint lists.
498
+
499
+ Readers validate the magic bytes, the format version, every length and
500
+ the BLAKE3 checksum, and build the loaded graph beside the current one.
501
+ A file that fails any check is rejected, and the graph in memory is not
502
+ touched until the load succeeds. Snapshots may come from uploads, so a
503
+ reader never allocates from a length the file states: a frame claiming
504
+ more than 1 GiB, inflating to a different size than it declares, or
505
+ holding bytes after its compressed data is refused.
506
+
507
+ ## Limitations
508
+
509
+ Worth restating, because the failure modes are where snapshots bite:
510
+
511
+ - **Manual save and restore only.** Manual snapshots run when you call
512
+ them. Explicit WAL helpers can also write managed snapshots after N
513
+ committed transactions, but there is no wall-clock scheduler.
514
+ - **Snapshots alone are not continuous durability.** A crash between
515
+ saves loses every mutation in the window unless you pair snapshots
516
+ with the [WAL](./wal.md).
517
+ - **Whole-graph work.** Save and load encode/decode the entire graph. Existing
518
+ readers can continue on already-loaded Arc snapshots, but new queries see the
519
+ restored graph only after load publishes it.
520
+ - **One process, one graph.** Each process you run needs its own
521
+ snapshot file.
522
+ - **No partial or incremental snapshots.** Every save serializes the
523
+ whole graph.
524
+ - **Admin surface is unauthenticated.** Opt-in is the only safety
525
+ control today; put an authenticated ingress in front of it on any
526
+ host that isn't exclusively localhost.
527
+
528
+ For the underlying engine internals (wire format, mutation-event
529
+ surface, forward-compatibility rules, atomicity guarantees on the
530
+ parent-dir fsync), see the internal
531
+ [Snapshots operator doc](https://github.com/lora-db/lora/blob/main/docs/operations/snapshots.md).
532
+
533
+ ## See also
534
+
535
+ - [**Rust guide → Persisting your graph**](https://loradb.com/docs/getting-started/rust#persisting-your-graph)
536
+ - [**Python guide → Persisting your graph**](https://loradb.com/docs/getting-started/python#persisting-your-graph)
537
+ - [**Node guide → Persisting your graph**](./getting-started/node.md#persisting-your-graph)
538
+ - [**WASM guide → Persisting your graph**](https://loradb.com/docs/getting-started/wasm#persisting-your-graph)
539
+ - [**Go guide → Persisting your graph**](https://loradb.com/docs/getting-started/go#persisting-your-graph)
540
+ - [**HTTP server → Snapshots, WAL, and restore**](https://loradb.com/docs/getting-started/server#snapshots-wal-and-restore)
541
+ - [**HTTP API → Admin endpoints (opt-in)**](https://loradb.com/docs/api/http#admin-endpoints-opt-in)
542
+ - [**WAL and checkpoints**](./wal.md)
543
+ - [**Cookbook → Backup and restore**](./cookbook.md#backup-and-restore)
544
+ - [**Limitations → Storage**](./limitations.md#storage)
545
+ - [**Troubleshooting → Snapshots**](./troubleshooting.md#snapshots)