@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.
- package/README.md +5 -0
- package/dist/types.d.ts +2 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +1 -0
- package/dist/types.js.map +1 -1
- 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,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.
|