@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,291 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Limitations"
|
|
3
|
+
description: "Every query feature and operational capability LoraDB does not support today — including procedures, clustering, browser playground boundaries, and remaining storage limitations — plus what to reach for instead."
|
|
4
|
+
online: "https://loradb.com/docs/limitations"
|
|
5
|
+
package: "@loradb/lora-node@0.36.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Limitations
|
|
9
|
+
|
|
10
|
+
A single page for every query feature and operational capability
|
|
11
|
+
LoraDB does not support today, so you can decide whether LoraDB fits
|
|
12
|
+
your use case and know what to reach for instead. Every unsupported
|
|
13
|
+
feature below raises a clear error (a parse error,
|
|
14
|
+
`SemanticError::UnsupportedFeature`, or `UnknownFunction`) —
|
|
15
|
+
nothing silently misbehaves.
|
|
16
|
+
|
|
17
|
+
Wording convention used below:
|
|
18
|
+
|
|
19
|
+
- **Not supported** — hard absence with no near-term plan.
|
|
20
|
+
- **Not yet supported** — absence the docs intentionally signal as
|
|
21
|
+
future capability.
|
|
22
|
+
- **Not implemented** — the grammar accepts it but the analyzer or
|
|
23
|
+
executor rejects it today.
|
|
24
|
+
|
|
25
|
+
For the machine-checkable feature list see the
|
|
26
|
+
[Cypher support matrix](https://github.com/lora-db/lora/blob/main/docs/reference/cypher-support-matrix.md)
|
|
27
|
+
in the internal documentation.
|
|
28
|
+
|
|
29
|
+
## At a glance
|
|
30
|
+
|
|
31
|
+
| Theme | Biggest gaps |
|
|
32
|
+
|---|---|
|
|
33
|
+
| Storage | WAL-backed open exists on Rust, Node, Python, Go, Ruby, and `lora-server`; WASM stays snapshot-only; explicit RANGE/TEXT/POINT/LOOKUP/VECTOR/FULLTEXT indexes and schema constraints exist; HNSW vector search is opt-in |
|
|
34
|
+
| Concurrency | Snapshot reads can overlap; write commits and explicit read-write transactions serialize; timeout coverage is API-dependent |
|
|
35
|
+
| Clauses | `FOREACH` is supported for updating clauses; no general-purpose `CALL` or `LOAD CSV` |
|
|
36
|
+
| Patterns | No quantified path patterns |
|
|
37
|
+
| Operators | No `BETWEEN`; cross-type comparisons return `null` |
|
|
38
|
+
| Aggregates | No `GROUP BY` / `HAVING` keywords |
|
|
39
|
+
| Functions | No external utility compatibility layer; case conversion is Unicode-aware but not locale-specific |
|
|
40
|
+
| Parameters | No dynamic labels / relationship types; no parse-time type check |
|
|
41
|
+
| Spatial | No WKT I/O, no CRS transforms; `geo.within_bbox` exists for same-SRID boxes |
|
|
42
|
+
| Vectors | VECTOR indexes are exact (flat scan) by default, approximate with `vector.indexProvider: 'hnsw'`; no embedding generation; no list-of-vectors properties |
|
|
43
|
+
| Browser playground | Params are browser-local tab state; no shared hosted database, no true query abort, and no remote import |
|
|
44
|
+
|
|
45
|
+
## Clauses
|
|
46
|
+
|
|
47
|
+
| Feature | Status |
|
|
48
|
+
|---|---|
|
|
49
|
+
| General-purpose `CALL` | Not supported — analyzer rejects ordinary procedures such as `CALL db.labels()` |
|
|
50
|
+
| Index procedure `CALL` | Supported for `db.index.vector.queryNodes`, `db.index.vector.queryRelationships`, `db.index.fulltext.queryNodes`, and `db.index.fulltext.queryRelationships` |
|
|
51
|
+
| `FOREACH` | Supported for updating clauses (`CREATE`, `MERGE`, `SET`, `REMOVE`, `DELETE`, and nested `FOREACH`) |
|
|
52
|
+
| `CREATE INDEX` / `DROP INDEX` / `SHOW INDEXES` | Supported for RANGE, TEXT, POINT, LOOKUP, VECTOR, and FULLTEXT indexes; see [Indexes](./queries/indexes.md) |
|
|
53
|
+
| `CREATE CONSTRAINT` / `DROP CONSTRAINT` / `SHOW CONSTRAINTS` | Supported for uniqueness, existence, node key, relationship key, and property type constraints; see [Constraints](./queries/constraints.md) |
|
|
54
|
+
| `LOAD CSV` | Not supported |
|
|
55
|
+
| `USE <graph>` (multi-database) | Not supported |
|
|
56
|
+
| `EXPLAIN` / `PROFILE` Cypher keywords | Not supported — use the explicit binding methods (`db.explain`, `db.profile`, `Explain`, `Profile`) or HTTP `/explain` and `/profile` endpoints |
|
|
57
|
+
|
|
58
|
+
## Patterns
|
|
59
|
+
|
|
60
|
+
| Feature | Status |
|
|
61
|
+
|---|---|
|
|
62
|
+
| Quantified path patterns `((:X)-[:R]->(:Y)){1,3}` | Not supported |
|
|
63
|
+
| Inline `WHERE` inside variable-length relationships | Not supported — rejected at parse time |
|
|
64
|
+
|
|
65
|
+
## Operators and expressions
|
|
66
|
+
|
|
67
|
+
| Feature | Status |
|
|
68
|
+
|---|---|
|
|
69
|
+
| `BETWEEN a AND b` | Not supported — use `x >= a AND x <= b` |
|
|
70
|
+
| Type-mismatch detection in comparisons | Not implemented — cross-type `<` / `>` returns `null` instead of erroring |
|
|
71
|
+
| Aggregates inside [`WHERE`](./queries/where.md) | Not supported — use [`WITH … WHERE`](./queries/return-with.md#with) instead |
|
|
72
|
+
|
|
73
|
+
## Aggregates
|
|
74
|
+
|
|
75
|
+
| Feature | Status |
|
|
76
|
+
|---|---|
|
|
77
|
+
| `DISTINCT` on `stdev`, `stdevp`, `percentileCont`, `percentileDisc` | Not supported — the `DISTINCT` is silently ignored; use `collect(DISTINCT x)` and aggregate the unwound list |
|
|
78
|
+
| `GROUP BY` keyword | Not supported — non-aggregated columns are the implicit group key |
|
|
79
|
+
| `HAVING` keyword | Not supported — filter post-aggregate through `WITH … WHERE` |
|
|
80
|
+
|
|
81
|
+
## Functions
|
|
82
|
+
|
|
83
|
+
| Feature | Status |
|
|
84
|
+
|---|---|
|
|
85
|
+
| External utility compatibility layer | Not supported |
|
|
86
|
+
| User-defined functions | Not supported — no registration surface |
|
|
87
|
+
| [Truncation](./functions/temporal.md#truncation) units | Every Cypher unit, from `"millennium"` down to `"microsecond"`. `temporal.truncate(unit, value)` returns `null` for a unit the value's type does not have; `date.truncate(…)` and the other `<type>.truncate` forms fail instead |
|
|
88
|
+
| `<type>.transaction()`, `.statement()`, `.realtime()` | Supported; LoraDB has one clock, so the three agree. They take no time zone argument |
|
|
89
|
+
| [Named time zones](./functions/temporal.md#time-zones) | Supported for `DATETIME`, with daylight saving from the built-in IANA database. A `TIME` in a named zone takes the zone's current offset. A `DATETIME` stored with a named zone cannot be read by LoraDB versions before 0.19.0 |
|
|
90
|
+
| [`string.lower` / `string.upper`](./functions/string.md#tolower--toupper) | Unicode case mapping is supported; locale-specific case folding is not |
|
|
91
|
+
| [`string.normalize(str[, form])`](./functions/string.md#normalize) | Unicode NFC/NFD/NFKC/NFKD normalization is supported; locale-specific transliteration is not |
|
|
92
|
+
|
|
93
|
+
## Data types
|
|
94
|
+
|
|
95
|
+
| Feature | Status |
|
|
96
|
+
|---|---|
|
|
97
|
+
| Binary / byte arrays | Supported as a byte-string property value through binding wire formats; there is no Cypher byte literal |
|
|
98
|
+
| Fixed-precision decimals | Not supported — use scaled integers or strings |
|
|
99
|
+
| User-defined types | Not supported |
|
|
100
|
+
| Numeric overflow guarding | Integer `+`, `-`, `*`, `%` and unary `-` fail the query on overflow (`LORA_VALIDATION`); `list.sum` over integers still wraps |
|
|
101
|
+
| Very large or deeply nested values | Bounded; see [Query limits](#query-limits) |
|
|
102
|
+
|
|
103
|
+
## Spatial
|
|
104
|
+
|
|
105
|
+
| Feature | Status |
|
|
106
|
+
|---|---|
|
|
107
|
+
| WGS-84 3D [`geo.distance`](./functions/spatial.md#geodistance) honouring `height` | Not yet supported — computes surface great-circle only |
|
|
108
|
+
| `geo.within_bbox()` | Supported for same-SRID 2D/3D bounding boxes, including WGS-84 boxes across the antimeridian (lower-left longitude greater than upper-right, as in Neo4j's `point.withinBBox`); mixed SRIDs (including 2D vs 3D) fail the query |
|
|
109
|
+
| `point.fromWKT()` / WKT output | Not yet supported |
|
|
110
|
+
| CRS transformation between SRIDs | Not yet supported — cross-SRID `geo.distance` fails the query |
|
|
111
|
+
| Custom SRIDs | Not supported — only `7203`, `9157`, `4326`, `4979` |
|
|
112
|
+
|
|
113
|
+
## Vectors
|
|
114
|
+
|
|
115
|
+
| Feature | Status |
|
|
116
|
+
|---|---|
|
|
117
|
+
| Vector ANN structure | Opt-in per index with `vector.indexProvider: 'hnsw'` (tunable `vector.hnsw.*` keys); the default `flat` provider scans every matching entity. See [Indexes → Providers](./queries/indexes.md#providers-flat-exact-and-hnsw-approximate) |
|
|
118
|
+
| Built-in embedding generation | Not supported — no plugin surface; generate embeddings in host code |
|
|
119
|
+
| [List-of-vectors as a property](./data-types/vectors.md#restriction-no-list-of-vectors-as-a-property) | Not supported — rejected at write time; hang many embeddings off separate nodes |
|
|
120
|
+
| Dimension > 4096 | Not supported — rejected at construction time |
|
|
121
|
+
| `ORDER BY` on a `VECTOR` column | Deterministic but implementation-defined; order by a scalar score instead |
|
|
122
|
+
| Metric extensions (e.g. Minkowski, Chebyshev) | Not yet supported — current metrics are listed in [Vectors → Signed distance metrics](./data-types/vectors.md#signed-distance-metrics) |
|
|
123
|
+
| Passing a typed `VECTOR` helper over HTTP | HTTP accepts JSON params, not host-language helper objects — pass a numeric list and cast it with `$q::VECTOR<COORD>(DIM)` |
|
|
124
|
+
|
|
125
|
+
## Parameters
|
|
126
|
+
|
|
127
|
+
| Feature | Status |
|
|
128
|
+
|---|---|
|
|
129
|
+
| Parameter as a label or relationship type | Not supported |
|
|
130
|
+
| Parameter as a property key | Not supported |
|
|
131
|
+
| Parameter type checking at parse time | Not yet supported |
|
|
132
|
+
| Parameters over HTTP | Supported for JSON scalar, list, and map values on `/query`, `/explain`, and `/profile`; use query casts for typed values such as `DATE`, `POINT`, and `VECTOR` |
|
|
133
|
+
|
|
134
|
+
## Storage
|
|
135
|
+
|
|
136
|
+
| Gap | Impact |
|
|
137
|
+
|---|---|
|
|
138
|
+
| WAL controls are not uniform across bindings | Rust and `lora-server` expose the full [WAL](./wal.md) surface. Node exposes archive/raw WAL opens plus sync-mode control. Python, Go, and Ruby expose archive/raw WAL opens with managed snapshot options. WASM remains snapshot-only. |
|
|
139
|
+
| Time-based checkpoint scheduler — not yet supported | Explicit WAL helpers can write managed snapshots after N committed transactions, and Rust / `lora-server` expose explicit checkpoints. Nothing schedules checkpoints by wall-clock time in the background for you. |
|
|
140
|
+
| Constraint coverage is scoped | Uniqueness, existence, node key, relationship key, and property type constraints exist for a label or relationship type. There is no database-wide uniqueness constraint, and existence constraints are single-property only. |
|
|
141
|
+
| Index coverage is scoped | `CREATE INDEX`, `CREATE TEXT INDEX`, `CREATE POINT INDEX`, `CREATE VECTOR INDEX`, `CREATE FULLTEXT INDEX`, `DROP INDEX`, and `SHOW INDEXES` exist. Composite RANGE indexes are cataloged, but current planner rewrites are single-property. Vector indexes are exact flat scans unless created with the `'hnsw'` provider. |
|
|
142
|
+
| Explicit transactions are surface-dependent | Rust and in-process bindings expose transaction APIs; HTTP has no multi-query transaction endpoint |
|
|
143
|
+
| ID reuse — not supported | Deleting an entity does not free its `u64` id |
|
|
144
|
+
|
|
145
|
+
## Query limits
|
|
146
|
+
|
|
147
|
+
Every stage of the engine walks queries and values recursively, so a
|
|
148
|
+
query is bounded in shape and in the size of the values it builds. A
|
|
149
|
+
query over a limit fails with an error instead of exhausting the stack
|
|
150
|
+
or memory of the process it runs in.
|
|
151
|
+
|
|
152
|
+
| Limit | Value | Error |
|
|
153
|
+
|---|---|---|
|
|
154
|
+
| Nesting of brackets, parentheses, braces, `CASE` expressions and `LIST<...>` types in query text | 64 levels | `LORA_PARSE` |
|
|
155
|
+
| Depth of an operator chain: each operator in `a + b + c`, each `NOT`, comparison, sign and postfix lookup (`.key`, `[i]`, `::TYPE`) adds a level, summed through nested expressions | 256 levels | `LORA_PARSE` |
|
|
156
|
+
| Clauses in one query, counting the clauses of `CALL { ... }` bodies; each `UNION` branch counts separately | 256 | `LORA_PARSE` |
|
|
157
|
+
| Hops named by a variable-length relationship (`-[*1..n]->`); without an upper bound a pattern stops at 100 hops | 1000 | `LORA_PARSE` |
|
|
158
|
+
| Nesting of lists and maps in any value: parameters, values a query builds, stored properties | 128 levels | `LORA_INVALID_PARAMS` for a parameter, otherwise `LORA_VALIDATION` |
|
|
159
|
+
| Size of a single value: a string or byte array, or a list or map counted as 8 bytes per element plus the strings it holds; also the properties one `CREATE` writes for one node or relationship | 128 MiB | `LORA_INVALID_PARAMS` for a parameter, otherwise `LORA_VALIDATION` |
|
|
160
|
+
| Paths one variable-length expansion holds at once when a query has no `LIMIT` to stream against | 128 MiB of relationship ids | `LORA_VALIDATION` |
|
|
161
|
+
| Length of a regular expression | 16 KiB | `LORA_VALIDATION` |
|
|
162
|
+
| Compiled size of a regular expression (the regex engine's default) | 10 MiB | `LORA_VALIDATION` |
|
|
163
|
+
| Character pairs `text.distance` and `text.similarity` compare (the product of both lengths, except for `'hamming'`) | 2^28 | `LORA_VALIDATION` |
|
|
164
|
+
|
|
165
|
+
Queries do not need a large thread stack. When a deep query runs low on
|
|
166
|
+
the stack of the thread that called the engine, the engine continues on a
|
|
167
|
+
separately allocated stack segment instead of overflowing, so any thread
|
|
168
|
+
works: a 128 KiB musl thread, a 512 KiB macOS secondary thread, a Ruby or
|
|
169
|
+
Go thread. On a thread with less than about 512 KiB of stack, each query,
|
|
170
|
+
and each row pulled from a stream, allocates such a segment, which adds a
|
|
171
|
+
few microseconds. WebAssembly builds cannot switch stacks; there, a query
|
|
172
|
+
at every limit at once fits the 1 MiB stack a wasm build gets.
|
|
173
|
+
|
|
174
|
+
Staying well inside the limits is still better. For example, a long chain
|
|
175
|
+
of `OR` tests is better written with `IN`:
|
|
176
|
+
|
|
177
|
+
```cypher
|
|
178
|
+
// 300 alternatives is past the operator-chain limit:
|
|
179
|
+
// MATCH (n) WHERE n.id = 1 OR n.id = 2 OR ... OR n.id = 300 RETURN n
|
|
180
|
+
// One list membership test is a single operator:
|
|
181
|
+
MATCH (n) WHERE n.id IN $ids RETURN n
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
The long chain fails with code `LORA_PARSE` and the message:
|
|
185
|
+
|
|
186
|
+
```text
|
|
187
|
+
parse error at 16..4105: expression nests more than 256 operators deep; split it up, for example with WITH or a list function
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
A value nested too deeply is refused while it is built:
|
|
191
|
+
|
|
192
|
+
```cypher
|
|
193
|
+
RETURN reduce(acc = [], i IN range(1, 200) | [acc]) AS deep
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
fails with code `LORA_VALIDATION` and the message:
|
|
197
|
+
|
|
198
|
+
```text
|
|
199
|
+
value nests lists and maps more than 128 levels deep
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
## Concurrency
|
|
203
|
+
|
|
204
|
+
- Auto-commit read-only queries load Arc snapshots and can overlap.
|
|
205
|
+
- Write commits serialize, and explicit read-write transactions hold the
|
|
206
|
+
writer slot until commit or rollback.
|
|
207
|
+
- Query timeouts are cooperative and not exposed uniformly across every
|
|
208
|
+
binding or HTTP endpoint.
|
|
209
|
+
- HTTP rate limiting — not supported.
|
|
210
|
+
|
|
211
|
+
## HTTP server
|
|
212
|
+
|
|
213
|
+
- Authentication — not supported. TLS — not supported. Bind to
|
|
214
|
+
`127.0.0.1` only in production until this changes; see the
|
|
215
|
+
security notes on the [Contact](https://loradb.com/contact#security) page.
|
|
216
|
+
- Admin endpoints ([`POST /admin/snapshot/save`](https://loradb.com/docs/api/http#admin-endpoints-opt-in)
|
|
217
|
+
and `/admin/snapshot/load`, plus `/admin/checkpoint`,
|
|
218
|
+
`/admin/wal/status`, and `/admin/wal/truncate` when WAL is enabled)
|
|
219
|
+
are opt-in via `--snapshot-path` / `--wal-dir` and have **no
|
|
220
|
+
authentication**. The optional `path` body field is rejected unless
|
|
221
|
+
the server runs with `--admin-path-root`, and must then stay inside
|
|
222
|
+
that directory. Do not enable them on a network-reachable host
|
|
223
|
+
without authenticated ingress in front.
|
|
224
|
+
- HTTP results are built in memory before they are sent.
|
|
225
|
+
`--max-result-rows` (default 1,000,000) and `--max-response-bytes`
|
|
226
|
+
(default 256 MiB) cap how large one can get, and `--query-timeout-ms`
|
|
227
|
+
(default 30 s) bounds how long a query can run. Page through larger
|
|
228
|
+
results with `SKIP` and `LIMIT`.
|
|
229
|
+
- Multi-query transactions over HTTP — not supported. Each `/query`
|
|
230
|
+
call executes independently.
|
|
231
|
+
- Multi-database — not supported. One process serves exactly one
|
|
232
|
+
in-memory graph; run multiple processes for isolation.
|
|
233
|
+
|
|
234
|
+
## Browser playground
|
|
235
|
+
|
|
236
|
+
- Parameter values are local tab state. The playground supports a
|
|
237
|
+
JSON Params panel and share links can include that JSON, but params
|
|
238
|
+
are not stored in a hosted database or synced between users.
|
|
239
|
+
- Shared hosted database — not supported. The hosted app runs against
|
|
240
|
+
a browser-origin database; saved queries, snapshots, settings,
|
|
241
|
+
history, and auto-restored graph state are local browser data.
|
|
242
|
+
- True query abort — not yet supported. The Cancel button drops the
|
|
243
|
+
pending result from the UI, but the current WASM call still runs until
|
|
244
|
+
it returns.
|
|
245
|
+
- Multi-database selector — not supported. Use a different browser
|
|
246
|
+
profile/origin or clear site data when you need a separate local
|
|
247
|
+
scratch graph.
|
|
248
|
+
- Remote import — not supported. Import accepts local snapshot files;
|
|
249
|
+
the app does not fetch remote URLs to seed a graph.
|
|
250
|
+
|
|
251
|
+
## Workarounds cheatsheet
|
|
252
|
+
|
|
253
|
+
| Instead of | Use |
|
|
254
|
+
|---|---|
|
|
255
|
+
| `BETWEEN a AND b` | `x >= a AND x <= b` |
|
|
256
|
+
| `HAVING` | [`WITH … WHERE`](./queries/return-with.md#having-style-filtering-with) |
|
|
257
|
+
| `GROUP BY cols` | Non-aggregated columns in `RETURN` / `WITH` |
|
|
258
|
+
| `CREATE INDEX ON :L(prop)` | Use `CREATE INDEX name FOR (n:L) ON (n.prop)` |
|
|
259
|
+
| `CONSTRAINT UNIQUE` shorthand | `CREATE CONSTRAINT name FOR (n:Label) REQUIRE n.key IS UNIQUE` |
|
|
260
|
+
| `LOAD CSV` | Parse on host, pass as `$rows`, [`UNWIND $rows`](./queries/unwind-merge.md#unwind) |
|
|
261
|
+
| External utility procedures | Re-implement in the host language |
|
|
262
|
+
| `geo.within_bbox()` | Use `geo.within_bbox(p, lowerLeft, upperRight)` with matching SRIDs |
|
|
263
|
+
| `point.fromWKT()` | Parse host-side, pass as a [point param](./functions/spatial.md#parameters) |
|
|
264
|
+
| `GROUP BY year` | `RETURN e.at.year AS year, count(*)` |
|
|
265
|
+
| `IF/THEN/ELSE` expressions | [`CASE … WHEN … THEN … END`](./queries/return-with.md#case-expressions) |
|
|
266
|
+
| Window function `row_number()` per group | `ORDER BY … collect(…)[..N]` pipeline |
|
|
267
|
+
| `COUNT(*) FILTER (WHERE …)` | [`count(CASE WHEN … THEN 1 END)`](./queries/aggregation.md#conditional-count-count-if) |
|
|
268
|
+
|
|
269
|
+
## Out of scope (for now)
|
|
270
|
+
|
|
271
|
+
These are part of standard Cypher but **not** on the short-term
|
|
272
|
+
roadmap:
|
|
273
|
+
|
|
274
|
+
- General-purpose stored procedures (`CALL` family), except the supported
|
|
275
|
+
index query procedures
|
|
276
|
+
- `LOAD CSV`-based ingestion
|
|
277
|
+
- Multi-database `USE`
|
|
278
|
+
|
|
279
|
+
See [Why LoraDB](./why.md) for the project's intended direction.
|
|
280
|
+
|
|
281
|
+
## See also
|
|
282
|
+
|
|
283
|
+
- [**Troubleshooting**](./troubleshooting.md) — what to do when a query errors.
|
|
284
|
+
- [**HTTP API → Admin endpoints (opt-in)**](https://loradb.com/docs/api/http#admin-endpoints-opt-in) — how snapshot and WAL admin routes are exposed over HTTP.
|
|
285
|
+
- [**WAL and checkpoints**](./wal.md) — recovery, sync modes, and admin semantics.
|
|
286
|
+
- [**Queries → Overview**](./queries/index.md) — the supported subset.
|
|
287
|
+
- [**Cheat sheet**](./queries/cheat-sheet.md) — one-page quick reference.
|
|
288
|
+
- [**Parameters**](./queries/parameters.md) — typed parameter binding across bindings and JSON parameter binding over HTTP.
|
|
289
|
+
- [**Schema-free**](./concepts/schema-free.md) — permissive writes, lenient reads.
|
|
290
|
+
- [**Functions → Overview**](./functions/overview.md) — supported functions.
|
|
291
|
+
- [**Concepts → Graph Model**](./concepts/graph-model.md) — the underlying data model.
|
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Performance and Benchmark Reports"
|
|
3
|
+
description: "How to read LoraDB benchmark results, inspect the CI benchmark-summary.json artifact, and compare current database performance against the smoke baseline."
|
|
4
|
+
online: "https://loradb.com/docs/performance"
|
|
5
|
+
package: "@loradb/lora-node@0.36.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Performance and Benchmark Reports
|
|
9
|
+
|
|
10
|
+
LoraDB benchmarks are meant to answer two different questions:
|
|
11
|
+
|
|
12
|
+
| Question | Source | Use it for |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| Is this build obviously slower? | `perf-smoke` CI workflow | Pull request review and regression triage |
|
|
15
|
+
| What does this release look like overall? | Manual `benchmarks` workflow | Release notes, dashboards, and capacity planning experiments |
|
|
16
|
+
|
|
17
|
+
The shared output is `benchmark-summary.json`: a compact JSON file
|
|
18
|
+
generated from Criterion's bencher output. It gives you a table-friendly
|
|
19
|
+
view of the current database state without scraping terminal logs.
|
|
20
|
+
|
|
21
|
+
> **Note**
|
|
22
|
+
>
|
|
23
|
+
>
|
|
24
|
+
> CI runners are noisy. Treat these numbers as a trend signal for the same
|
|
25
|
+
> benchmark on the same workflow, not as a hardware-independent promise.
|
|
26
|
+
>
|
|
27
|
+
|
|
28
|
+
## Current Snapshot
|
|
29
|
+
|
|
30
|
+
Representative numbers below come from the Criterion benchmark suite
|
|
31
|
+
used for LoraDB performance tracking. Throughput units are benchmark
|
|
32
|
+
specific: scans count nodes, traversals count edges or paths, writes
|
|
33
|
+
count entities or full write operations.
|
|
34
|
+
|
|
35
|
+
| Area | Benchmark | Dataset | Mean time | Throughput | Unit | What it tells you |
|
|
36
|
+
|---|---|---:|---:|---:|---|---|
|
|
37
|
+
| Scan | `match/all_nodes/1000` | 1,000 nodes | 285.13 µs | 3,507,211 | nodes/sec | Full label scan plus projection |
|
|
38
|
+
| Count | `aggregation/count_star/1000` | 1,000 rows | 59.52 µs | 16,801,625 | rows/sec | Fast aggregate path without row projection |
|
|
39
|
+
| Traversal | `traversal/single_hop_chain/1000` | 1,000-node chain | 527.42 µs | 1,894,126 | edges/sec | Basic relationship iteration |
|
|
40
|
+
| Traversal | `traversal/tree_depth3_branch5_traverse` | 155 descendants | 55.63 µs | 2,786,462 | paths/sec | Bounded tree expansion |
|
|
41
|
+
| Ordering | `ordering/order_by_single/1000` | 1,000 rows | 853.55 µs | 1,171,582 | rows/sec | Sort cost for a single key |
|
|
42
|
+
| Write | `write/create_single_node` | fresh DB | 8.60 µs | 116,331 | ops/sec | Single-node write overhead |
|
|
43
|
+
| Write | `write/batch_create_unwind/500` | 500 creates | 554.79 µs | 901,238 | nodes/sec | Batched `UNWIND` insertion |
|
|
44
|
+
| Workload | `realistic/social_friend_of_friend_500` | 500 persons | 399.46 µs | 2,503 | queries/sec | Representative two-hop social query |
|
|
45
|
+
|
|
46
|
+
## Live Smoke Report
|
|
47
|
+
|
|
48
|
+
The PR-facing `perf-smoke` workflow produces a smaller table with a
|
|
49
|
+
baseline comparison. The table below is loaded from
|
|
50
|
+
[`/benchmarks/perf-smoke-summary.json`](https://loradb.com/benchmarks/perf-smoke-summary.json)
|
|
51
|
+
on the live website.
|
|
52
|
+
|
|
53
|
+
_The live benchmark summary table is rendered on the website: https://loradb.com/docs/performance_
|
|
54
|
+
|
|
55
|
+
The smoke gate fails only when a benchmark is slower than its configured
|
|
56
|
+
threshold. The default threshold is `3.0x`, because shared CI machines
|
|
57
|
+
vary enough that a tight gate would be noisy instead of useful.
|
|
58
|
+
|
|
59
|
+
## JSON Shape
|
|
60
|
+
|
|
61
|
+
The summary artifact is designed to be boring to consume. The useful
|
|
62
|
+
top-level fields are:
|
|
63
|
+
|
|
64
|
+
| Field | Type | Purpose |
|
|
65
|
+
|---|---|---|
|
|
66
|
+
| `schema_version` | number | Incremented only when the artifact contract changes |
|
|
67
|
+
| `generated_at` | string | ISO timestamp for the summary generation time |
|
|
68
|
+
| `suite` | string | Workflow or explicit suite name, such as `perf-smoke` |
|
|
69
|
+
| `source.github` | object | Repository, SHA, ref, workflow, run id, and actor when produced in GitHub Actions |
|
|
70
|
+
| `source.runner` | object | OS, CPU architecture, and CPU count |
|
|
71
|
+
| `summary` | object | Benchmark count, group count, fastest and slowest benchmarks |
|
|
72
|
+
| `baseline` | object | Compared, ok, regressed, new, and missing benchmark counts |
|
|
73
|
+
| `groups` | array | Per-group rollups: count, fastest, median, p95, slowest, average |
|
|
74
|
+
| `benchmarks` | array | One row per benchmark, ready for table rendering |
|
|
75
|
+
|
|
76
|
+
Each `benchmarks[]` row contains:
|
|
77
|
+
|
|
78
|
+
| Field | Meaning |
|
|
79
|
+
|---|---|
|
|
80
|
+
| `name` | Full Criterion name, for example `perf_smoke/scan_1k` |
|
|
81
|
+
| `group` | First path segment, for example `perf_smoke` |
|
|
82
|
+
| `case` | Remaining path segments |
|
|
83
|
+
| `ns_per_iter` | Current mean time in nanoseconds per iteration |
|
|
84
|
+
| `error_ns` | Criterion reported error in nanoseconds |
|
|
85
|
+
| `relative_error_pct` | `error_ns / ns_per_iter * 100` |
|
|
86
|
+
| `iterations_per_second` | Derived `1_000_000_000 / ns_per_iter` |
|
|
87
|
+
| `baseline.status` | `ok`, `regressed`, or `new` when a baseline is supplied |
|
|
88
|
+
| `baseline.ratio` | `current / baseline` |
|
|
89
|
+
| `baseline.threshold` | Maximum allowed ratio for the smoke gate |
|
|
90
|
+
|
|
91
|
+
## Render A Table
|
|
92
|
+
|
|
93
|
+
After downloading a workflow artifact, render the benchmark rows into a
|
|
94
|
+
developer-readable table with `jq`:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
jq -r '
|
|
98
|
+
["benchmark","current_ns","baseline_ns","ratio","status"],
|
|
99
|
+
(.benchmarks[] | [
|
|
100
|
+
.name,
|
|
101
|
+
.ns_per_iter,
|
|
102
|
+
(.baseline.ns_per_iter // ""),
|
|
103
|
+
(.baseline.ratio // ""),
|
|
104
|
+
(.baseline.status // "")
|
|
105
|
+
])
|
|
106
|
+
| @tsv
|
|
107
|
+
' benchmark-summary.json
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
For Markdown:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
jq -r '
|
|
114
|
+
"| Benchmark | Current ns | Baseline ns | Ratio | Status |",
|
|
115
|
+
"|---|---:|---:|---:|---|",
|
|
116
|
+
(.benchmarks[] |
|
|
117
|
+
"| `\(.name)` | \(.ns_per_iter) | \(.baseline.ns_per_iter // "") | \(.baseline.ratio // "") | \(.baseline.status // "") |"
|
|
118
|
+
)
|
|
119
|
+
' benchmark-summary.json
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
## Reproduce Locally
|
|
123
|
+
|
|
124
|
+
Run the smoke suite and produce the same JSON shape:
|
|
125
|
+
|
|
126
|
+
```bash
|
|
127
|
+
cargo bench -p lora-database --bench perf_smoke \
|
|
128
|
+
-- --output-format bencher > bencher.log
|
|
129
|
+
|
|
130
|
+
node scripts/summarize-benchmarks.mjs \
|
|
131
|
+
--input bencher.log \
|
|
132
|
+
--output benchmark-summary.json \
|
|
133
|
+
--baseline crates/lora-database/benches/perf_smoke_baseline.json \
|
|
134
|
+
--suite perf-smoke-local
|
|
135
|
+
|
|
136
|
+
node scripts/check-perf-smoke.mjs --input bencher.log
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
Run the full suite when you want a release-level snapshot:
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
cargo bench --locked -p lora-database --benches \
|
|
143
|
+
-- --output-format bencher > benchmarks.log
|
|
144
|
+
|
|
145
|
+
node scripts/summarize-benchmarks.mjs \
|
|
146
|
+
--input benchmarks.log \
|
|
147
|
+
--output benchmark-summary.json \
|
|
148
|
+
--suite release-benchmarks
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Reading Regressions
|
|
152
|
+
|
|
153
|
+
| Signal | Meaning | Next step |
|
|
154
|
+
|---|---|---|
|
|
155
|
+
| `baseline.regressed_count > 0` | One or more current timings exceeded threshold | Inspect the named rows in `baseline.regressions` |
|
|
156
|
+
| `baseline.new_count > 0` | A benchmark exists in the run but not the baseline | Add it deliberately with a baseline refresh |
|
|
157
|
+
| `baseline.missing_count > 0` | A baseline entry was not produced | Check for renamed or deleted benchmark cases |
|
|
158
|
+
| High `relative_error_pct` | Criterion saw noisy measurements | Re-run before drawing conclusions |
|
|
159
|
+
| One slow outlier in CI | Shared runner noise is possible | Re-run the job, then compare trend across runs |
|
|
160
|
+
|
|
161
|
+
## Query Shape Notes
|
|
162
|
+
|
|
163
|
+
### Lookup by id
|
|
164
|
+
|
|
165
|
+
A `WHERE` conjunct `id(n) = $id` or
|
|
166
|
+
`id(n) IN $ids` fetches the node directly
|
|
167
|
+
(`NodeByIdSeek` in `EXPLAIN`) instead of scanning, with or without a
|
|
168
|
+
label on `n`, and also for writes such as
|
|
169
|
+
`MATCH (n) WHERE id(n) = $id SET n.x = 1`. The same
|
|
170
|
+
holds for a relationship: `MATCH (a)-[r]->(b) WHERE id(r) = $id`
|
|
171
|
+
plans as `RelByIdSeek`. The value must not read `n` itself, and the
|
|
172
|
+
conjunct must be joined to the rest of the `WHERE` with `AND`: under
|
|
173
|
+
`OR`, or as `id(n) + 0 = $id`, the query scans.
|
|
174
|
+
|
|
175
|
+
### Unbound start nodes in pattern subqueries
|
|
176
|
+
|
|
177
|
+
A pattern comprehension, `EXISTS { }` or
|
|
178
|
+
`COUNT { }` runs once per outer row. When its start
|
|
179
|
+
node is not bound by the outer row, write the lookup key as an inline
|
|
180
|
+
property map. LoraDB then seeks that property through an index, the
|
|
181
|
+
same way `MATCH` does, instead of scanning the whole label once per
|
|
182
|
+
outer row:
|
|
183
|
+
|
|
184
|
+
```cypher
|
|
185
|
+
// Seeks :Person(subject) once per row
|
|
186
|
+
MATCH (n:Post)
|
|
187
|
+
WHERE size([(v:Person {subject: $s}) WHERE v.verified | 1]) > 0
|
|
188
|
+
RETURN count(n) AS c
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
The seek applies to the inline map only. Moving the same key into the
|
|
192
|
+
inner `WHERE` (`(v:Person) WHERE v.subject = $s`)
|
|
193
|
+
keeps the per-row label scan, so its cost grows with the size of the
|
|
194
|
+
label times the number of outer rows. Other predicates, such as
|
|
195
|
+
`v.verified` above, still belong in `WHERE`.
|
|
196
|
+
|
|
197
|
+
### Constant values in a filter
|
|
198
|
+
|
|
199
|
+
A temporal or spatial value written with constant arguments, such as
|
|
200
|
+
`datetime('2024-01-01T00:00:00Z')`,
|
|
201
|
+
`date('2024-01-01')`,
|
|
202
|
+
`duration('PT1H')` or
|
|
203
|
+
`point({x: 0, y: 0})`, is built once when the query
|
|
204
|
+
is planned, not again for every row. Casts and `math.*` functions on
|
|
205
|
+
constant arguments are folded the same way. A value built from a
|
|
206
|
+
parameter (`datetime($since)`) is still built per
|
|
207
|
+
row, since a plan is reused across parameter values. The clock
|
|
208
|
+
(`datetime()`, `timestamp()`),
|
|
209
|
+
random values and a `TIME` are never folded, and a call that fails on
|
|
210
|
+
its arguments, such as `datetime('not a date')`,
|
|
211
|
+
still fails only when a row reaches it.
|
|
212
|
+
|
|
213
|
+
## See Also
|
|
214
|
+
|
|
215
|
+
- [Queries → Paths](./queries/paths.md#performance) for path-query cost notes.
|
|
216
|
+
- [Limitations](./limitations.md#concurrency) for the current single-process
|
|
217
|
+
concurrency model.
|
|
218
|
+
- [WAL and Checkpoints](./wal.md) for persistence behavior, which can affect
|
|
219
|
+
write-heavy measurements when WAL is enabled.
|