@loradb/lora-node 0.35.1 → 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 (57) hide show
  1. package/README.md +5 -0
  2. package/dist/types.d.ts +2 -1
  3. package/dist/types.d.ts.map +1 -1
  4. package/dist/types.js +1 -0
  5. package/dist/types.js.map +1 -1
  6. package/docs/README.md +86 -0
  7. package/docs/concepts/graph-model.md +270 -0
  8. package/docs/concepts/nodes.md +285 -0
  9. package/docs/concepts/properties.md +348 -0
  10. package/docs/concepts/relationships.md +325 -0
  11. package/docs/concepts/result-formats.md +183 -0
  12. package/docs/concepts/schema-free.md +183 -0
  13. package/docs/cookbook.md +1081 -0
  14. package/docs/data-types/lists-and-maps.md +406 -0
  15. package/docs/data-types/overview.md +210 -0
  16. package/docs/data-types/scalars.md +376 -0
  17. package/docs/data-types/spatial.md +291 -0
  18. package/docs/data-types/temporal.md +349 -0
  19. package/docs/data-types/vectors.md +563 -0
  20. package/docs/errors.md +183 -0
  21. package/docs/functions/aggregation.md +372 -0
  22. package/docs/functions/list.md +522 -0
  23. package/docs/functions/map.md +207 -0
  24. package/docs/functions/math.md +421 -0
  25. package/docs/functions/number.md +197 -0
  26. package/docs/functions/overview.md +545 -0
  27. package/docs/functions/spatial.md +384 -0
  28. package/docs/functions/string.md +502 -0
  29. package/docs/functions/temporal.md +590 -0
  30. package/docs/functions/utility.md +137 -0
  31. package/docs/functions/vectors.md +772 -0
  32. package/docs/getting-started/installation.md +204 -0
  33. package/docs/getting-started/node.md +582 -0
  34. package/docs/getting-started/tutorial.md +334 -0
  35. package/docs/index.md +203 -0
  36. package/docs/limitations.md +291 -0
  37. package/docs/performance.md +219 -0
  38. package/docs/queries/aggregation.md +520 -0
  39. package/docs/queries/cheat-sheet.md +302 -0
  40. package/docs/queries/constraints.md +239 -0
  41. package/docs/queries/create.md +331 -0
  42. package/docs/queries/examples.md +453 -0
  43. package/docs/queries/index.md +169 -0
  44. package/docs/queries/indexes.md +538 -0
  45. package/docs/queries/match.md +429 -0
  46. package/docs/queries/ordering.md +359 -0
  47. package/docs/queries/parameters.md +328 -0
  48. package/docs/queries/paths.md +462 -0
  49. package/docs/queries/return-with.md +500 -0
  50. package/docs/queries/set-delete.md +369 -0
  51. package/docs/queries/unwind-merge.md +358 -0
  52. package/docs/queries/where.md +416 -0
  53. package/docs/snapshot.md +545 -0
  54. package/docs/troubleshooting.md +1158 -0
  55. package/docs/wal.md +570 -0
  56. package/docs/why.md +273 -0
  57. package/package.json +13 -14
@@ -0,0 +1,1158 @@
1
+ ---
2
+ title: "Troubleshooting LoraDB Errors"
3
+ description: "A symptom-indexed guide to common LoraDB errors — parse failures, semantic errors, unexpected results, server startup issues — with the shortest fix for each."
4
+ online: "https://loradb.com/docs/troubleshooting"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # Troubleshooting LoraDB Errors
9
+
10
+ When a query fails, returns no rows, or the server refuses to start,
11
+ find the symptom in the lookup table below and jump to the fix.
12
+ Each section names the cause, shows the failure mode, and gives the
13
+ shortest way out.
14
+
15
+ ## Frequent fixes
16
+
17
+ #### Why does my LoraDB query return no rows when I know the data is there?
18
+
19
+ Cypher labels and relationship types are case-sensitive. (:Person) and (:person) match different nodes; [:KNOWS] and [:knows] are different relationship types. Check the case of every label and type in the query against what was used at CREATE time. If labels match, also confirm the direction of relationships — (a)-[:R]->(b) does not match (b)-[:R]->(a).
20
+
21
+ #### Why is LoraDB throwing 'Unknown function' on a function I know exists?
22
+
23
+ LoraDB functions are namespaced. string.lower(x) works; lower(x) without the namespace does not. See Functions → Overview for the full list of namespaces (string, math, list, map, temporal, spatial, vectors, utility) and the compatibility aliases.
24
+
25
+ #### How do I fix 'DeleteNodeWithRelationships' when deleting a node?
26
+
27
+ Plain DELETE refuses to remove a node that still has relationships attached, to prevent dangling edges. Use DETACH DELETE n to remove the node and every relationship touching it in one step, or DELETE every relationship first and then DELETE the node.
28
+
29
+ #### Why does my LoraDB MATCH produce an N times M row explosion?
30
+
31
+ Independent MATCH patterns produce a Cartesian product unless joined by a shared variable. MATCH (a:Person), (b:Movie) is one pattern; MATCH (a:Person)-[:WATCHED]->(b:Movie) is another. If you need both pieces independently, project them through WITH and re-MATCH, or wire them together via a shared variable.
32
+
33
+ #### Why does my SET clause overwrite existing properties instead of merging?
34
+
35
+ SET n = {key: value} replaces every property on n with the given map. To add or update specific properties without disturbing the rest, use SET n.key = value or SET n += {key: value} for merge semantics.
36
+
37
+ ## Quick lookup
38
+
39
+ | Symptom | Jump to |
40
+ |---|---|
41
+ | Parse error, missing paren/direction | [Parse errors](#parse-errors) |
42
+ | `Unknown variable`, `Unknown function`, `WrongArity` | [Semantic errors](#semantic-errors) |
43
+ | `DeleteNodeWithRelationships` | [Executor errors](#executor-errors) |
44
+ | Query returns empty for no reason | [Queries return empty results](#queries-return-empty-results) |
45
+ | N × M row explosion | [MATCH returns a cross-product](#match-returns-a-cross-product) |
46
+ | `SET` destroyed properties | [SET wiped my properties](#set-wiped-my-properties) |
47
+ | `DELETE` complains about edges | [DELETE fails](#delete-fails-with-still-has-relationships) |
48
+ | Parameters seem ignored | [Parameters](#parameters) |
49
+ | Server won't start | [Server](#server) |
50
+ | Admin snapshot endpoint returns 404 | [Snapshots → `/admin/snapshot/*` returns 404](#admin-snapshot-returns-404) |
51
+ | A `.tmp` file is left beside the snapshot | [Snapshots → leftover `.tmp` file](#leftover-tmp-file-beside-the-snapshot) |
52
+ | Snapshot load fails with "bad magic" or checksum mismatch | [Snapshots → load fails with bad magic / checksum](#snapshot-load-fails-with-bad-magic-or-crc) |
53
+ | Snapshot load reports unsupported version | [Snapshots → unsupported format version](#snapshot-load-reports-unsupported-format-version) |
54
+ | Result JSON shape is wrong | [Result format](#result-json-looks-nothing-like-what-i-expected) |
55
+ | Install or package build fails | [Install and setup](#install-and-setup) |
56
+ | Build fails | [Build](#build) |
57
+
58
+ ## Install and setup
59
+
60
+ ### I just want to try LoraDB
61
+
62
+ Use [play.loradb.com](https://play.loradb.com) first. It runs in the
63
+ browser and avoids local toolchain setup. Move to a binding or the
64
+ HTTP server once you need runtime-supplied parameters; use a binding
65
+ when you also want host-language types or direct persistence APIs.
66
+
67
+ ### `yarn` uses the wrong version
68
+
69
+ The repository pins Yarn through Corepack. From the repository root:
70
+
71
+ ```bash
72
+ corepack enable
73
+ yarn install --immutable
74
+ ```
75
+
76
+ If `yarn install --immutable` complains about the lockfile after a pull,
77
+ do not edit `yarn.lock` by hand. Re-run with the pinned Yarn and check
78
+ whether the branch intentionally changed dependencies.
79
+
80
+ ### Node package scripts fail immediately
81
+
82
+ Use Node.js 20+. The docs site, playground, WASM package, and workspace
83
+ tooling assume the Node 20 runtime even when a single package may appear
84
+ to build on older versions.
85
+
86
+ ### Go binding cannot find `liblora_ffi`
87
+
88
+ Build the Rust FFI library before running Go tests:
89
+
90
+ ```bash
91
+ cargo build --release -p lora-ffi
92
+ cd crates/bindings/lora-go
93
+ go test -race ./...
94
+ ```
95
+
96
+ Consumer projects outside the repository need `CGO_CFLAGS` and
97
+ `CGO_LDFLAGS` pointing at the release archive or local checkout. See
98
+ [Go → Installation](https://loradb.com/docs/getting-started/go#installation--setup).
99
+
100
+ ## Build
101
+
102
+ ### `error: linker 'cc' not found`
103
+
104
+ Install a C toolchain. On macOS:
105
+
106
+ ```bash
107
+ xcode-select --install
108
+ ```
109
+
110
+ ### `cargo: command not found` or wrong Rust version
111
+
112
+ Install Rust with `rustup`, then let the repository's
113
+ `rust-toolchain.toml` select the pinned stable toolchain:
114
+
115
+ ```bash
116
+ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
117
+ rustup show
118
+ ```
119
+
120
+ The workspace currently requires Rust 1.87 or newer. If `cargo build`
121
+ reports an older compiler, run `rustup update stable` and retry from
122
+ the repository root.
123
+
124
+ ### Slow release builds
125
+
126
+ Release builds use `lto = "fat"` and `codegen-units = 1`. For faster
127
+ iteration, use debug builds:
128
+
129
+ ```bash
130
+ cargo build # debug — fast
131
+ cargo build --release # release — slow, optimised
132
+ ```
133
+
134
+ ## Server
135
+
136
+ ### `Address already in use`
137
+
138
+ Another process holds the server port (default `4747`):
139
+
140
+ ```bash
141
+ lsof -i :4747
142
+ kill <PID>
143
+ ```
144
+
145
+ Or start on a different port:
146
+
147
+ ```bash
148
+ lora-server --port 5000
149
+ # or
150
+ LORA_SERVER_PORT=5000 lora-server
151
+ ```
152
+
153
+ See [HTTP Server → run](https://loradb.com/docs/getting-started/server#configure) for all options.
154
+
155
+ ### HTTP 400 on every request
156
+
157
+ Check the `content-type` header — the server expects `application/json`:
158
+
159
+ ```bash
160
+ curl -s http://127.0.0.1:4747/query \
161
+ -H 'content-type: application/json' \
162
+ -d '{"query": "MATCH (n) RETURN count(*)"}'
163
+ ```
164
+
165
+ ### Result JSON looks nothing like what I expected
166
+
167
+ Different `format` values return different shapes. The engine default
168
+ is `graph`, which returns deduplicated nodes+edges — if you were
169
+ expecting rows, pass `"format": "rows"` (or `"rowArrays"`). See
170
+ [**Result formats**](./concepts/result-formats.md) for every shape and
171
+ when to pick which.
172
+
173
+ ## Queries
174
+
175
+ ### Parse errors
176
+
177
+ Common mistakes:
178
+
179
+ - Missing parentheses: `MATCH n` → `MATCH (n)`.
180
+ - Missing direction on `CREATE`: `(a)-[:T]-(b)` is valid in `MATCH`,
181
+ not in [`CREATE`](./queries/create.md). Use `-[:T]->` or `<-[:T]-`.
182
+ - Missing type on `CREATE`: `(a)-[]->(b)` must have a type, e.g.
183
+ `-[:FOLLOWS]->`.
184
+ - `BETWEEN` is **not** supported — use `x >= a AND x <= b`. See
185
+ [Limitations](./limitations.md#operators-and-expressions).
186
+ - Unclosed string literal — double the quote to escape:
187
+ `'it''s fine'`. See [Scalars → String](./data-types/scalars.md#string).
188
+
189
+ ### Semantic errors
190
+
191
+ | Message | Cause |
192
+ |---|---|
193
+ | `Unknown variable x` | `x` wasn't introduced by an earlier clause, or it was dropped by a [`WITH`](./queries/return-with.md#with) that didn't project it. |
194
+ | `unsupported feature: unknown procedure` | General-purpose procedures such as `db.labels()` are not implemented. The supported `CALL` surface is limited to vector and full-text index query procedures; see [Indexes](./queries/indexes.md). |
195
+ | `Unknown function 'foo'` | Not in the built-in list. See [Functions](./functions/overview.md). |
196
+ | `WrongArity` | Function exists but was called with the wrong number of arguments. |
197
+ | `Aggregate in WHERE` | Aggregates aren't allowed in [`WHERE`](./queries/where.md). Use [`WITH … WHERE`](./queries/return-with.md#having-style-filtering-with). |
198
+
199
+ ### Executor errors
200
+
201
+ | Message | Cause |
202
+ |---|---|
203
+ | `DeleteNodeWithRelationships` | Use [`DETACH DELETE`](./queries/set-delete.md#detach-delete) instead of plain `DELETE`. |
204
+ | `MissingRelationshipType` | `CREATE (a)-[]->(b)` — a [relationship](./concepts/relationships.md) must have a type. |
205
+ | `ReadOnlyCreate` | Should not occur via normal paths; file a bug if you see this. |
206
+ | `LIMIT expects a non-negative integer, got null` | `SKIP` / `LIMIT` got `null` (often a parameter bound to `null`), a negative number or a fraction. See [below](#limit-expects-a-non-negative-integer-got-null). |
207
+ | `expected parameter: $name` | The query uses `$name` but the params map has no `name` entry. See [Unbound parameter](#unbound-parameter). |
208
+
209
+ ### Queries return empty results
210
+
211
+ 1. **Data was created on a different non-persistent handle.** Plain
212
+ in-memory databases start empty on each process run. Use a
213
+ container-backed open (`createDatabase("app", { databaseDir: "./data" })`, `Database.create("app", {"database_dir": "./data"})`,
214
+ `lora.New("app", lora.Options{DatabaseDir: "./data"})`, etc.), an
215
+ explicit WAL open (`openWalDatabase({ walDir: "./wal" })`,
216
+ `Database.open_wal("./wal")`, `lora.OpenWal(...)`,
217
+ `LoraRuby::Database.open_wal("./wal")`), or load a snapshot if you expect data to
218
+ survive restarts. See [Limitations → Storage](./limitations.md#storage).
219
+ 2. **Label typo or case mismatch** — `:user` ≠ `:User`, and `:Usr`
220
+ is not an error. Labels and types are case-sensitive, and a name no
221
+ entity carries simply matches nothing. See [Nodes](./concepts/nodes.md)
222
+ and [Schema-free](./concepts/schema-free.md#unknown-names-are-not-errors).
223
+ 3. **Property type mismatch** — `{id: 1}` matches integer `1`, not the
224
+ string `"1"`. See [Data Types](./data-types/overview.md).
225
+ 4. **A parameter is `null`** — a parameter bound to `null` never
226
+ equals anything, so it filters everything out. (A parameter that is
227
+ missing from the map is an error, not `null`.) See
228
+ [Parameters](./queries/parameters.md).
229
+ 5. **`= null`** — never matches. Use
230
+ [`IS NULL` / `IS NOT NULL`](./queries/where.md#null-checks).
231
+ 6. **Regex anchoring** — `=~ 'foo'` matches only the full string
232
+ `"foo"`. Use `.*` or `CONTAINS` for substring. See
233
+ [WHERE → regex](./queries/where.md#regex).
234
+
235
+ ### `MATCH` returns a cross-product
236
+
237
+ ```cypher
238
+ MATCH (a:User), (b:User) RETURN a, b // N * N rows
239
+ ```
240
+
241
+ Use a relationship pattern to connect them:
242
+
243
+ ```cypher
244
+ MATCH (a:User)-[:FOLLOWS]->(b:User) RETURN a, b
245
+ ```
246
+
247
+ Or scope both sides before the write:
248
+
249
+ ```cypher
250
+ MATCH (a:User {id: $from}), (b:User {id: $to})
251
+ CREATE (a)-[:FOLLOWS]->(b)
252
+ ```
253
+
254
+ ### `SET` wiped my properties
255
+
256
+ [`SET n = {…}`](./queries/set-delete.md#replace-all-properties-)
257
+ **replaces** the property map. To update individual keys:
258
+
259
+ ```cypher
260
+ SET n.prop = value // single key
261
+ SET n += {newProp: value} // merge keys
262
+ ```
263
+
264
+ ### `DELETE` fails with "still has relationships"
265
+
266
+ ```cypher
267
+ MATCH (n:User {id: 1}) DETACH DELETE n
268
+ ```
269
+
270
+ [`DETACH DELETE`](./queries/set-delete.md#detach-delete) removes the edges
271
+ in one step.
272
+
273
+ ### WITH dropped my variable
274
+
275
+ A variable must be explicitly projected through `WITH`:
276
+
277
+ ```cypher
278
+ MATCH (a)-[r:KNOWS]->(b)
279
+ WITH a // r and b are now out of scope
280
+ RETURN a, r // error: Unknown variable r
281
+ ```
282
+
283
+ Either pass them through — `WITH a, r, b` — or don't bind them in the
284
+ first place.
285
+
286
+ ### Aggregation gave one row when I expected per-group
287
+
288
+ Every non-aggregated column in the same `RETURN` becomes part of the
289
+ implicit group key. See
290
+ [Aggregation → Grouping](./queries/aggregation.md#grouping).
291
+
292
+ ### Ordering puts nulls in an unexpected place
293
+
294
+ `null` sorts last ASC / first DESC. Override with
295
+ [`coalesce`](./functions/overview.md#type-conversion-and-checking):
296
+
297
+ ```cypher
298
+ MATCH (p:Person)
299
+ RETURN p.name, p.rank
300
+ ORDER BY coalesce(p.rank, 2147483647) ASC
301
+ ```
302
+
303
+ See [Ordering → nulls in ordering](./queries/ordering.md#nulls-in-ordering).
304
+
305
+ ### Shortest path returns nothing
306
+
307
+ 1. No path exists between the endpoints.
308
+ 2. The relationship type filter excludes the only path.
309
+ 3. Direction is too strict — try `[:R*]` or `[:R*]-` (undirected) on
310
+ `MATCH`.
311
+
312
+ Wrap in [`OPTIONAL MATCH`](./queries/match.md#optional-match) if you still
313
+ want a row:
314
+
315
+ ```cypher
316
+ MATCH (a:User {id: $from}), (b:User {id: $to})
317
+ OPTIONAL MATCH p = shortestPath((a)-[:FOLLOWS*]->(b))
318
+ RETURN a, b, path.length(p) AS hops
319
+ ```
320
+
321
+ ## Snapshots
322
+
323
+ ### `/admin/snapshot/*` returns 404 {#admin-snapshot-returns-404}
324
+
325
+ **Symptom:** `POST /admin/snapshot/save` or `/admin/snapshot/load`
326
+ returns `404 Not Found`.
327
+
328
+ **Likely cause:** The server was not started with
329
+ `--snapshot-path <PATH>` (or the `LORA_SERVER_SNAPSHOT_PATH` env
330
+ var). The admin routes are **opt-in** — they are not mounted at all
331
+ when that flag is unset.
332
+
333
+ **Fix:** Restart with the flag, or use a per-binding
334
+ `save_snapshot` call instead.
335
+
336
+ ```bash
337
+ lora-server \
338
+ --host 127.0.0.1 --port 4747 \
339
+ --snapshot-path /var/lib/lora/db.bin
340
+ ```
341
+
342
+ See [HTTP server → Snapshots, WAL, and restore](https://loradb.com/docs/getting-started/server#snapshots-wal-and-restore)
343
+ and the [HTTP API reference](https://loradb.com/docs/api/http#admin-endpoints-opt-in).
344
+
345
+ ### Leftover `.tmp` file beside the snapshot
346
+
347
+ **Symptom:** A file named `<path>.tmp` sits next to the target
348
+ snapshot file.
349
+
350
+ **Likely cause:** A save was interrupted — `SIGKILL`, a power loss,
351
+ or `ENOSPC` on the target disk. The save writes to `<path>.tmp`,
352
+ `fsync`s, and renames over the target in one atomic step. If the
353
+ process died between the write and the rename, the tmp remains.
354
+
355
+ **Fix:** If the target `<path>` still exists, it is valid and loads
356
+ cleanly — the last successful save. Delete the `<path>.tmp` and
357
+ investigate whatever killed the process (disk space? OOM? operator
358
+ error?). If the target does **not** exist, the tmp is your most
359
+ recent attempt but has not been atomically committed — rename it
360
+ and try loading; if checksum validation fails, restore from an earlier
361
+ backup.
362
+
363
+ ### Snapshot load fails with "bad magic" or checksum mismatch {#snapshot-load-fails-with-bad-magic-or-crc}
364
+
365
+ **Symptom:** a bad-magic error, checksum-mismatch error, or
366
+ `snapshot load failed: bad magic` style message on load.
367
+
368
+ **Likely cause:**
369
+ - **Bad magic** — the file is not a LoraDB snapshot. The first 8
370
+ bytes should be `LORACOL1` for the current columnar format.
371
+ - **Checksum mismatch** — the file is corrupt (truncated,
372
+ bit-flipped, copied incompletely, or an
373
+ unrelated file matching the magic by accident).
374
+
375
+ **Fix:**
376
+
377
+ ```bash
378
+ # Confirm it looks like a snapshot at all.
379
+ head -c 8 path/to/snapshot.bin
380
+ # => LORACOL1
381
+ ```
382
+
383
+ If the magic is wrong, check you pointed at the right path. If the
384
+ magic is right but the checksum fails, restore from a known-good copy — a
385
+ corrupt snapshot never loads partially on purpose, to prevent
386
+ silently accepting half a graph. See [Snapshots → File format](./snapshot.md#file-format-reference)
387
+ for the on-disk layout.
388
+
389
+ ### Snapshot load reports unsupported format version
390
+
391
+ **Symptom:** `SnapshotError::UnsupportedVersion` on load.
392
+
393
+ **Likely cause:**
394
+ - The file was written by a **newer** LoraDB than the reader — the
395
+ reader is older than the writer.
396
+ - The file was written by an **obsolete** LoraDB whose format has
397
+ since been retired.
398
+
399
+ **Fix:**
400
+ - If the reader is older: upgrade the reader to a release that
401
+ understands the file's format.
402
+ - If the file is from a retired format: use the last LoraDB release
403
+ that accepted that version, export via Cypher (`MATCH (n) RETURN n`
404
+ and `MATCH (a)-[r]->(b) RETURN id(a), id(b), type(r), properties(r)`),
405
+ and re-import on the new release.
406
+
407
+ Version / compatibility policy (internal):
408
+ [Change management → Snapshot format compatibility](https://github.com/lora-db/lora/blob/main/docs/design/change-management.md#snapshot-format-compatibility).
409
+
410
+ ## WAL and checkpoints
411
+
412
+ ### `/admin/wal/*` or `/admin/checkpoint` returns 404
413
+
414
+ **Symptom:** `POST /admin/wal/status`,
415
+ `POST /admin/wal/truncate`, or `POST /admin/checkpoint` returns
416
+ `404 Not Found`.
417
+
418
+ **Likely cause:** The server was not started with `--wal-dir <DIR>`
419
+ (or the `LORA_SERVER_WAL_DIR` env var). WAL admin routes are mounted
420
+ only when a WAL directory is attached.
421
+
422
+ **Fix:** Restart with a WAL directory:
423
+
424
+ ```bash
425
+ lora-server \
426
+ --host 127.0.0.1 --port 4747 \
427
+ --wal-dir /var/lib/lora/wal
428
+ ```
429
+
430
+ See [WAL and checkpoints](./wal.md) and
431
+ [HTTP API → Admin endpoints](https://loradb.com/docs/api/http#admin-endpoints-opt-in).
432
+
433
+ ### `/admin/checkpoint` returns 400
434
+
435
+ **Symptom:** `POST /admin/checkpoint` returns
436
+ `400 Bad Request` with a message about no checkpoint path.
437
+
438
+ **Likely cause:** The server has `--wal-dir` but no
439
+ `--snapshot-path`, and the request body did not provide a `path`.
440
+ WAL-only deployments can checkpoint, but the target snapshot path must
441
+ come from the request body.
442
+
443
+ **Fix:** Either pass `path` in the request:
444
+
445
+ ```bash
446
+ curl -sX POST http://127.0.0.1:4747/admin/checkpoint \
447
+ -H 'content-type: application/json' \
448
+ -d '{"path":"/var/lib/lora/checkpoint.bin"}'
449
+ ```
450
+
451
+ or start the server with `--snapshot-path` so body-less checkpoints
452
+ have a default target.
453
+
454
+ ### WAL/container root is already open
455
+
456
+ **Symptom:** Opening a WAL-backed or container-backed database fails with
457
+ a `LORA_LOCKED` error saying the database directory is locked by another process or live handle.
458
+
459
+ **Likely cause:** Another live process or database handle already owns
460
+ that WAL directory or `.loradb` archive. LoraDB takes a lock so two appenders
461
+ cannot write to the same log at once.
462
+
463
+ **Fix:** Use one WAL/container root per live database, or close the first
464
+ handle before reopening the same directory in the same process:
465
+ `db.dispose()` in Node, `db.close()` / `await db.close()` in Python,
466
+ `db.Close()` in Go, or `db.close` in Ruby.
467
+
468
+ ### WAL is poisoned or `bgFailure` is set
469
+
470
+ **Symptom:** Queries fail with `WAL poisoned`, `WAL flush failed`, or
471
+ `/admin/wal/status` returns a non-null `bgFailure`.
472
+
473
+ **Likely cause:** A WAL append or fsync failed. In `group` sync mode,
474
+ the background flusher latches the first fsync failure so later writes
475
+ fail loudly instead of pretending they are durable.
476
+
477
+ **Fix:** Stop accepting writes, fix the underlying disk or permission
478
+ problem, then restart from the last consistent snapshot + WAL. Inspect
479
+ `/admin/wal/status` before restart if you need the latched error text
480
+ for logs.
481
+
482
+ ### Recovery warns about an older snapshot
483
+
484
+ **Symptom:** Startup prints a warning that the snapshot LSN is older
485
+ than the newest checkpoint marker in the WAL.
486
+
487
+ **Likely cause:** The WAL contains evidence of a newer checkpoint than
488
+ the snapshot passed to `--restore-from` or `Database::recover(...)`.
489
+
490
+ **Fix:** If you have the newer checkpoint snapshot, restore from that
491
+ file instead. If not, the current recovery is still safe: LoraDB
492
+ replays every committed WAL record above the snapshot's own `walLsn`,
493
+ which may take longer but preserves correctness.
494
+
495
+ ## Parameters
496
+
497
+ ### Why are my queries returning nothing?
498
+
499
+ A [parameter](./queries/parameters.md) bound to `null` never equals
500
+ anything, so it usually filters everything out. Check the values you
501
+ pass, not only the keys: a missing key fails the query with
502
+ `expected parameter: $name`, but an explicit `null` runs it.
503
+
504
+ ### The HTTP API rejected my parameters
505
+
506
+ `POST /query`, `/explain`, and `/profile` accept a `params` object.
507
+ If you get `LORA_INVALID_PARAMS`, check that `params` is a JSON object
508
+ keyed by parameter name, not an array or scalar:
509
+
510
+ ```json
511
+ { "query": "RETURN $v AS v", "params": { "v": 42 } }
512
+ ```
513
+
514
+ For typed values such as dates, points, and vectors, pass the JSON
515
+ value and cast it in the query. See [Parameters](./queries/parameters.md#http-api).
516
+
517
+ ### Integer precision lost in JS
518
+
519
+ JS `number` loses precision above `Number.MAX_SAFE_INTEGER` (2^53).
520
+ Use `bigint` parameters or string-encoded ids for large values. See
521
+ [Node → gotchas](./getting-started/node.md#performance--best-practices).
522
+
523
+ ## Performance
524
+
525
+ ### Query is slow on a big graph
526
+
527
+ - Explicit RANGE, TEXT, and POINT indexes help common property, string, and
528
+ point predicates when the query is scoped to the matching label or
529
+ relationship type. Scope to a label (`MATCH (n:L {id: 1})`) and add an
530
+ index for hot predicates. Vector similarity remains exhaustive.
531
+ - Unbounded variable-length traversals explode fast. Cap with a max
532
+ depth: `[:R*1..6]`.
533
+ - `ORDER BY` on a huge unbounded result requires a full sort. Pair
534
+ it with `LIMIT` (a literal or a parameter): the sort then keeps only
535
+ `SKIP + LIMIT` rows, though it still reads every match.
536
+ - See [Limitations → Storage](./limitations.md#storage) for the full list
537
+ of storage gaps.
538
+
539
+ ### Queries block each other
540
+
541
+ Auto-commit reads can overlap on Arc snapshots. Write commits and explicit
542
+ read-write transactions still serialize. See
543
+ [Limitations → Concurrency](./limitations.md#concurrency).
544
+
545
+ ## Debugging query pipelines
546
+
547
+ A Cypher query is a pipeline — each clause feeds its rows into the
548
+ next. When a query returns surprising results the bug is almost
549
+ always **between stages**, not within a single clause. The cure is to
550
+ step through the pipeline and inspect what each stage emits.
551
+
552
+ ### The golden rule
553
+
554
+ > If a query doesn't return what you expect, read it clause by
555
+ > clause and ask: _what does this stage produce, and which variables
556
+ > are in scope after it?_
557
+
558
+ ### Variable scope across WITH
559
+
560
+ A variable leaves scope the moment it isn't projected through `WITH`.
561
+ Future clauses can't see it.
562
+
563
+ **Symptom:** `Unknown variable r` / `Unknown variable b`.
564
+
565
+ **Likely cause:** A `WITH` between `MATCH` and `RETURN` dropped the
566
+ variable.
567
+
568
+ **Fix:** Project every variable you need downstream.
569
+
570
+ **Example:**
571
+
572
+ ```cypher
573
+ // Broken
574
+ MATCH (a)-[r:KNOWS]->(b)
575
+ WITH a // r and b are now out of scope
576
+ RETURN a, r, b // error
577
+
578
+ ;// Fixed
579
+ MATCH (a)-[r:KNOWS]->(b)
580
+ WITH a, r, b
581
+ RETURN a, r, b
582
+ ```
583
+
584
+ See [WITH — losing variables](./queries/return-with.md#losing-variables-through-with).
585
+
586
+ ### `WITH *` vs explicit projection
587
+
588
+ `WITH *` passes every in-scope variable forward — convenient but
589
+ easy to misuse. The instant you add a computed column, you need to
590
+ enumerate the existing variables too, otherwise they silently drop.
591
+
592
+ **Symptom:** A variable that existed a moment ago is suddenly
593
+ unknown.
594
+
595
+ **Likely cause:** Someone wrote `WITH x AS renamed` expecting the
596
+ other variables to survive.
597
+
598
+ **Fix:** Either use `WITH *, x AS renamed` or list every needed
599
+ variable explicitly.
600
+
601
+ **Example:**
602
+
603
+ ```cypher
604
+ // Broken — drops u
605
+ MATCH (u:User)-[:WROTE]->(p:Post)
606
+ WITH count(p) AS posts
607
+ RETURN u.name, posts // error: u is not in scope
608
+
609
+ ;// Fixed
610
+ MATCH (u:User)-[:WROTE]->(p:Post)
611
+ WITH u, count(p) AS posts
612
+ RETURN u.name, posts
613
+ ```
614
+
615
+ The fix is not `WITH *` — aggregates plus `WITH *` together cause
616
+ different trouble, because the aggregate needs an explicit grouping
617
+ key column.
618
+
619
+ ### Variable loss between stages
620
+
621
+ **Symptom:** Second `MATCH` in a multi-stage query returns zero rows.
622
+
623
+ **Likely cause:** A `WITH` stage narrowed the rows to a subset, and
624
+ subsequent `MATCH` clauses only run for the surviving rows.
625
+
626
+ **Fix:** Push the second `MATCH` earlier, or remove the narrowing.
627
+
628
+ **Example:**
629
+
630
+ ```cypher
631
+ // "Only see friends of the top-3 oldest users" — works
632
+ MATCH (u:User)
633
+ WITH u ORDER BY u.age DESC LIMIT 3
634
+ MATCH (u)-[:FOLLOWS]->(other)
635
+ RETURN u.name, other.name
636
+
637
+ ;// Likely a bug — the LIMIT 3 applies too soon
638
+ MATCH (u:User)
639
+ WITH u LIMIT 3
640
+ MATCH (u)-[:FOLLOWS]->(other:User)
641
+ WHERE other.active
642
+ RETURN u, other
643
+ ```
644
+
645
+ The second `MATCH` sees at most three users; if none of their
646
+ follows are `active`, the whole query is empty. Push the filter up
647
+ into the first `WITH`, or don't `LIMIT` yet.
648
+
649
+ ### Debugging inside the pipeline
650
+
651
+ Print-debug a pipeline by swapping the final `RETURN` for one that
652
+ exposes intermediate state:
653
+
654
+ ```cypher
655
+ // Inspect what WITH is emitting
656
+ MATCH (u:User)
657
+ WITH u.country AS country, count(*) AS n
658
+ RETURN country, n
659
+ ORDER BY n DESC
660
+ ```
661
+
662
+ Then paste the rows into a spreadsheet — spotting duplicate keys, a
663
+ missing `country`, or an unexpected cardinality often takes five
664
+ seconds once you can see the rows.
665
+
666
+ ## CASE expression pitfalls
667
+
668
+ [`CASE`](./queries/return-with.md#case-expressions) is powerful but its
669
+ rules interact with three-valued logic and type-mixing in ways that
670
+ surprise new users.
671
+
672
+ ### Missing ELSE returns null
673
+
674
+ **Symptom:** A derived column has `null` values you didn't expect.
675
+
676
+ **Likely cause:** The `CASE` has no `ELSE` branch and one of the
677
+ input rows doesn't satisfy any `WHEN`.
678
+
679
+ **Fix:** Add an explicit `ELSE`, or accept `null` as the implicit
680
+ default.
681
+
682
+ **Example:**
683
+
684
+ ```cypher
685
+ // Broken — users with score < 50 become null
686
+ MATCH (u:User)
687
+ RETURN u.name,
688
+ CASE WHEN u.score >= 50 THEN 'ok' END AS tier
689
+
690
+ ;// Fixed
691
+ MATCH (u:User)
692
+ RETURN u.name,
693
+ CASE WHEN u.score >= 50 THEN 'ok' ELSE 'low' END AS tier
694
+ ```
695
+
696
+ ### Null in the predicate
697
+
698
+ `CASE WHEN expr` treats a `null` `expr` as *not matching* — because
699
+ three-valued logic propagates.
700
+
701
+ **Symptom:** Rows with `null` properties land in the `ELSE` branch,
702
+ even though the condition wasn't explicitly false.
703
+
704
+ **Likely cause:** `u.score >= 50` is `null` (not `false`) when
705
+ `u.score` is `null`; the branch doesn't fire.
706
+
707
+ **Fix:** Guard with [`coalesce`](./functions/overview.md#type-conversion-and-checking)
708
+ or an explicit `IS NULL` branch placed **before** the numeric
709
+ comparison.
710
+
711
+ ```cypher
712
+ MATCH (u:User)
713
+ RETURN u.name,
714
+ CASE
715
+ WHEN u.score IS NULL THEN 'unknown'
716
+ WHEN u.score >= 50 THEN 'ok'
717
+ ELSE 'low'
718
+ END AS tier
719
+ ```
720
+
721
+ ### Inconsistent branch types
722
+
723
+ **Symptom:** A downstream `ORDER BY` or comparison misbehaves on
724
+ the `CASE` column.
725
+
726
+ **Likely cause:** Different branches return different types — e.g.
727
+ an `Int` in one branch and a `String` in another.
728
+
729
+ **Fix:** Make every branch return the same type. If you genuinely
730
+ need heterogeneous output, convert with `toString`.
731
+
732
+ **Example:**
733
+
734
+ ```cypher
735
+ // Mixed types — results downstream-unpredictable
736
+ CASE WHEN n.score >= 50 THEN n.score ELSE 'unknown' END
737
+
738
+ // Fixed
739
+ CASE WHEN n.score >= 50 THEN toString(n.score) ELSE 'unknown' END
740
+ ```
741
+
742
+ ### Simple vs generic form confusion
743
+
744
+ Simple form (`CASE x WHEN v THEN …`) compares `x` against values
745
+ using equality. It can't express ranges or boolean predicates per
746
+ branch — that's the generic form (`CASE WHEN pred THEN …`).
747
+
748
+ ```cypher
749
+ // Doesn't work — comparison is hidden inside the simple form
750
+ CASE p.age WHEN >= 18 THEN 'adult' ELSE 'minor' END
751
+
752
+ // Use the generic form
753
+ CASE WHEN p.age >= 18 THEN 'adult' ELSE 'minor' END
754
+ ```
755
+
756
+ ## WITH clause pitfalls
757
+
758
+ ### Aggregate without an explicit group key
759
+
760
+ **Symptom:** The aggregate returns a single row when you expected
761
+ one row per group.
762
+
763
+ **Likely cause:** There's no non-aggregated column in the `WITH` or
764
+ `RETURN`, so all rows collapse to a single group.
765
+
766
+ **Fix:** Add the grouping column.
767
+
768
+ **Example:**
769
+
770
+ ```cypher
771
+ // "Orders per region" — one row total
772
+ MATCH (o:Order)
773
+ RETURN count(*)
774
+
775
+ ;// Fixed — one row per region
776
+ MATCH (o:Order)
777
+ RETURN o.region, count(*)
778
+ ORDER BY count(*) DESC
779
+ ```
780
+
781
+ ### Implicit group key by accident
782
+
783
+ The opposite surprise: an aggregate query that returns many rows
784
+ because a non-aggregated column you didn't realise was there formed
785
+ part of the key.
786
+
787
+ **Symptom:** A `count(*)` query returns many rows instead of one.
788
+
789
+ **Likely cause:** You projected something extra (e.g. the `Node`
790
+ itself) alongside the aggregate, and each node became its own group.
791
+
792
+ **Fix:** Drop the extra column.
793
+
794
+ ```cypher
795
+ // Broken: returns one row per user
796
+ MATCH (u:User)
797
+ RETURN u, count(*)
798
+
799
+ ;// Fixed: single total
800
+ MATCH (u:User)
801
+ RETURN count(*)
802
+ ```
803
+
804
+ ### Aggregates in WHERE
805
+
806
+ **Symptom:** `Aggregate in WHERE` analysis error.
807
+
808
+ **Likely cause:** Aggregates aren't allowed in `WHERE`. Cypher has
809
+ no `HAVING` keyword.
810
+
811
+ **Fix:** Pipe through `WITH` and filter after.
812
+
813
+ ```cypher
814
+ // Broken
815
+ MATCH (u:User)-[:WROTE]->(p:Post)
816
+ WHERE count(p) > 5
817
+ RETURN u
818
+
819
+ ;// Fixed (HAVING-style)
820
+ MATCH (u:User)-[:WROTE]->(p:Post)
821
+ WITH u, count(p) AS posts
822
+ WHERE posts > 5
823
+ RETURN u, posts
824
+ ```
825
+
826
+ See [WITH — HAVING-style filtering](./queries/return-with.md#having-style-filtering-with).
827
+
828
+ ### Ordering a `WITH` drops the order downstream?
829
+
830
+ **Symptom:** You sort in a `WITH` stage and the final result comes
831
+ back unsorted.
832
+
833
+ **Likely cause:** `ORDER BY` attached to `WITH` only guarantees
834
+ ordering for that stage's output and for any `ORDER BY`-sensitive
835
+ aggregate that immediately consumes it (such as `collect`). A
836
+ subsequent `MATCH` then re-emits rows in no particular order.
837
+
838
+ **Fix:** Either `collect` in the sorted stage, or re-apply `ORDER
839
+ BY` on the final `RETURN`.
840
+
841
+ ```cypher
842
+ // Broken — final order is unspecified
843
+ MATCH (u:User)
844
+ WITH u ORDER BY u.created DESC
845
+ MATCH (u)-[:WROTE]->(p)
846
+ RETURN u.name, count(p)
847
+
848
+ ;// Fixed
849
+ MATCH (u:User)
850
+ WITH u ORDER BY u.created DESC
851
+ MATCH (u)-[:WROTE]->(p)
852
+ RETURN u.name, count(p)
853
+ ORDER BY u.created DESC
854
+ ```
855
+
856
+ ## Aggregation pitfalls
857
+
858
+ ### `count(*)` vs `count(expr)`
859
+
860
+ **Symptom:** `OPTIONAL MATCH` aggregation yields `1` for entities
861
+ that should be `0`.
862
+
863
+ **Likely cause:** `count(*)` counts rows. An `OPTIONAL MATCH` that
864
+ missed still produces a row with `null` bindings — `count(*)`
865
+ counts it.
866
+
867
+ **Fix:** Use `count(expr)` on a variable from the optional side.
868
+ `count(expr)` skips `null`.
869
+
870
+ **Example:**
871
+
872
+ ```cypher
873
+ // Broken — users with no posts get 1
874
+ MATCH (u:User)
875
+ OPTIONAL MATCH (u)-[:WROTE]->(p:Post)
876
+ RETURN u.name, count(*) AS posts
877
+
878
+ ;// Fixed
879
+ MATCH (u:User)
880
+ OPTIONAL MATCH (u)-[:WROTE]->(p:Post)
881
+ RETURN u.name, count(p) AS posts
882
+ ```
883
+
884
+ ### Missing DISTINCT in collect
885
+
886
+ **Symptom:** `collect` returns duplicate values.
887
+
888
+ **Likely cause:** A many-to-many join upstream produced the same
889
+ child multiple times, once per ancestor.
890
+
891
+ **Fix:** `collect(DISTINCT …)`.
892
+
893
+ **Example:**
894
+
895
+ ```cypher
896
+ // Broken — same city listed many times if the person visited it often
897
+ MATCH (p:Person)-[:VISITED]->(c:City)
898
+ RETURN p.name, collect(c.name) AS cities
899
+
900
+ ;// Fixed
901
+ MATCH (p:Person)-[:VISITED]->(c:City)
902
+ RETURN p.name, collect(DISTINCT c.name) AS cities
903
+ ```
904
+
905
+ ### Aggregating after filtering vs after projection
906
+
907
+ **Symptom:** Aggregate seems to include rows the `WHERE` should
908
+ have excluded.
909
+
910
+ **Likely cause:** The `WHERE` runs against post-aggregate output,
911
+ not the rows that fed the aggregate — because the query put it in
912
+ the wrong stage.
913
+
914
+ **Fix:** If you want the filter *before* the aggregate, place it in
915
+ a pre-aggregate `WHERE`. If you want it *after* (HAVING-style),
916
+ pipe through `WITH`.
917
+
918
+ ```cypher
919
+ // Pre-aggregate filter (input rows only)
920
+ MATCH (o:Order)
921
+ WHERE o.status = 'paid'
922
+ RETURN o.region, sum(o.amount) AS revenue
923
+
924
+ ;// Post-aggregate filter (computed totals only)
925
+ MATCH (o:Order)
926
+ WITH o.region AS region, sum(o.amount) AS revenue
927
+ WHERE revenue > 1000
928
+ RETURN region, revenue
929
+ ```
930
+
931
+ ### `stdev`/`percentile*` don't support DISTINCT
932
+
933
+ **Symptom:** `stdev(DISTINCT …)` / `percentileCont(DISTINCT …)` returns
934
+ the same value as without `DISTINCT` — duplicates are still counted.
935
+
936
+ **Likely cause:** These aggregates ignore `DISTINCT` silently (see
937
+ [Limitations](./limitations.md#aggregates)).
938
+
939
+ **Fix:** `collect(DISTINCT …)`, `UNWIND`, then aggregate.
940
+
941
+ ```cypher
942
+ // Broken
943
+ MATCH (r:Review) RETURN stdev(DISTINCT r.stars)
944
+
945
+ ;// Fixed
946
+ MATCH (r:Review)
947
+ WITH collect(DISTINCT r.stars) AS xs
948
+ UNWIND xs AS x
949
+ RETURN stdev(x)
950
+ ```
951
+
952
+ ## Empty results and filtering issues
953
+
954
+ ### Unbound parameter
955
+
956
+ **Symptom:** The query fails with `expected parameter: $id` (code
957
+ `LORA_INVALID_PARAMS`).
958
+
959
+ **Cause:** The query uses `$id` but the params map has no `id` entry.
960
+
961
+ **Fix:** Bind it, as `null` if it has no value. A parameter bound to
962
+ `null` runs, but never equals anything:
963
+
964
+ ```cypher
965
+ MATCH (u:User) WHERE u.id = $id RETURN u
966
+ // {} -> error: expected parameter: $id
967
+ // {id: null} -> zero rows
968
+ ```
969
+
970
+ ### `LIMIT expects a non-negative integer, got null`
971
+
972
+ **Symptom:** A paginated query fails with
973
+ `LIMIT expects a non-negative integer, got null` (or the same message
974
+ for `SKIP`).
975
+
976
+ **Likely cause:** The `$limit` / `$offset` parameter was not bound, or
977
+ the host passed `null`, a negative number or a fraction. `SKIP` and
978
+ `LIMIT` take a non-negative integer (an integral float such as `10.0`
979
+ is accepted). As in Neo4j, `LIMIT null` is an error, not "no limit";
980
+ older LoraDB releases treated it as unlimited.
981
+
982
+ **Fix:** Bind an integer on every call. To make the limit optional,
983
+ build the query without the `LIMIT` clause when the caller wants every
984
+ row.
985
+
986
+ ```cypher
987
+ MATCH (u:User)
988
+ RETURN u
989
+ ORDER BY u.id
990
+ SKIP $offset
991
+ LIMIT $limit
992
+ // Both $offset and $limit must be bound to non-negative integers
993
+ ```
994
+
995
+ ### `= null` never matches
996
+
997
+ **Symptom:** A predicate intended to match missing properties
998
+ returns zero rows.
999
+
1000
+ **Likely cause:** `prop = null` is always `null`. Use
1001
+ `IS NULL` / `IS NOT NULL`.
1002
+
1003
+ **Fix:**
1004
+
1005
+ ```cypher
1006
+ // Broken
1007
+ MATCH (n) WHERE n.optional = null RETURN n
1008
+
1009
+ ;// Fixed
1010
+ MATCH (n) WHERE n.optional IS NULL RETURN n
1011
+ ```
1012
+
1013
+ ### Regex anchored by default
1014
+
1015
+ `=~ 'foo'` matches only the *full* string `foo`, not any string
1016
+ containing `foo`. Use `=~ '.*foo.*'` or `CONTAINS 'foo'` for
1017
+ substring matching.
1018
+
1019
+ ### Case-sensitive when you meant insensitive
1020
+
1021
+ All string operators (`=`, `STARTS WITH`, `ENDS WITH`, `CONTAINS`)
1022
+ are case-sensitive. Normalise both sides with `string.lower`.
1023
+
1024
+ ```cypher
1025
+ MATCH (u:User)
1026
+ WHERE string.lower(u.email) = string.lower($candidate)
1027
+ RETURN u
1028
+ ```
1029
+
1030
+ ## Duplicate results
1031
+
1032
+ ### Pattern reached twice
1033
+
1034
+ **Symptom:** The same node appears in results multiple times.
1035
+
1036
+ **Likely cause:** Two different paths reach the same node; the
1037
+ pattern matches each path independently.
1038
+
1039
+ **Fix:** Use [`DISTINCT`](./queries/return-with.md#distinct) on the
1040
+ `RETURN`, or restructure with `EXISTS { }` when you only need
1041
+ existence.
1042
+
1043
+ ```cypher
1044
+ // May duplicate \`c\` if a is connected to many b
1045
+ MATCH (a:Person)-[:FOLLOWS]->(b)-[:FOLLOWS]->(c)
1046
+ RETURN a, c
1047
+
1048
+ ;// One row per distinct (a, c) pair
1049
+ MATCH (a:Person)-[:FOLLOWS]->(b)-[:FOLLOWS]->(c)
1050
+ RETURN DISTINCT a, c
1051
+ ```
1052
+
1053
+ ### Undirected match doubles symmetric pairs
1054
+
1055
+ **Symptom:** Every pair appears twice in the results.
1056
+
1057
+ **Likely cause:** `(a)-[:R]-(b)` matches both directions. A pattern
1058
+ that's symmetric in `a` / `b` matches each pair twice.
1059
+
1060
+ **Fix:** Filter with `id(a) < id(b)` (or `<>`).
1061
+
1062
+ ```cypher
1063
+ MATCH (a:Person)-[:KNOWS]-(b:Person)
1064
+ WHERE id(a) < id(b)
1065
+ RETURN a.name, b.name
1066
+ ```
1067
+
1068
+ ## Debugging workflow (step-by-step)
1069
+
1070
+ When a query misbehaves, follow this loop. Every step is cheap.
1071
+
1072
+ ### 1. Simplify the MATCH
1073
+
1074
+ Remove everything except the patterns. Check you get any rows at
1075
+ all.
1076
+
1077
+ ```cypher
1078
+ MATCH (u:User) RETURN count(*)
1079
+ ```
1080
+
1081
+ Zero? Your label is wrong or the graph is empty. See
1082
+ [Queries return empty results](#queries-return-empty-results).
1083
+
1084
+ ### 2. Remove WHERE, inspect rows
1085
+
1086
+ Drop the `WHERE` and look at what the pattern actually binds.
1087
+
1088
+ ```cypher
1089
+ MATCH (u:User)-[:FOLLOWS]->(f)
1090
+ RETURN u.handle, f.handle
1091
+ LIMIT 20
1092
+ ```
1093
+
1094
+ Spot duplicates, unexpected relationships, or nulls here.
1095
+
1096
+ ### 3. Reintroduce predicates one at a time
1097
+
1098
+ Add each `WHERE` clause back one at a time. Count rows at each step
1099
+ — the step that drops too many rows is the bug.
1100
+
1101
+ ```cypher
1102
+ MATCH (u:User)-[:FOLLOWS]->(f)
1103
+ WHERE u.active // step 1
1104
+ RETURN count(*);
1105
+
1106
+ MATCH (u:User)-[:FOLLOWS]->(f)
1107
+ WHERE u.active
1108
+ AND f.country = u.country // step 2
1109
+ RETURN count(*)
1110
+ ```
1111
+
1112
+ ### 4. Inspect intermediate WITH stages
1113
+
1114
+ If your query has multiple stages, replace the final `RETURN` with
1115
+ one that exposes the `WITH` stage output. Do this per stage.
1116
+
1117
+ ```cypher
1118
+ // Instead of the full query:
1119
+ MATCH (u:User)-[:WROTE]->(p:Post)
1120
+ WITH u, count(p) AS posts
1121
+ WHERE posts > 5
1122
+ RETURN u.handle, posts
1123
+
1124
+ ;// Inspect stage 1:
1125
+ MATCH (u:User)-[:WROTE]->(p:Post)
1126
+ RETURN u.handle, count(p) AS posts
1127
+ ORDER BY posts DESC
1128
+ LIMIT 20
1129
+ ```
1130
+
1131
+ Does stage 1 emit what you think? If not, the bug is before the
1132
+ `WITH`.
1133
+
1134
+ ### 5. Check parameter bindings
1135
+
1136
+ Confirm every `$param` the query uses has the value you expect. A
1137
+ missing one fails the query; a `null` one silently filters.
1138
+
1139
+ ### 6. Re-read the problem
1140
+
1141
+ If you've been through the loop twice and the result is still
1142
+ wrong, the bug may be in the **data model**, not the query. See the
1143
+ [Modelling checklist](./concepts/graph-model.md#modelling-checklist).
1144
+
1145
+ ## See also
1146
+
1147
+ - [**Limitations**](./limitations.md) — what's intentionally not supported.
1148
+ - [**Queries**](./queries/index.md) — clause reference.
1149
+ - [**Cheat sheet**](./queries/cheat-sheet.md) — one-page quick reference.
1150
+ - [**Parameters**](./queries/parameters.md) — typed parameter binding.
1151
+ - [**Result formats**](./concepts/result-formats.md) — each response shape in detail.
1152
+ - [**Schema-free**](./concepts/schema-free.md) — permissive writes, lenient reads.
1153
+ - [**WHERE**](./queries/where.md) — predicate reference.
1154
+ - [**RETURN / WITH**](./queries/return-with.md) — projection and HAVING.
1155
+ - [**Aggregation (queries)**](./queries/aggregation.md) — clause-level grouping.
1156
+ - [**Aggregation (functions)**](./functions/aggregation.md) — per-function details.
1157
+ - [**Functions → Overview**](./functions/overview.md) — built-ins.
1158
+ - [**Tutorial**](./getting-started/tutorial.md) — guided walkthrough from scratch.