@loradb/lora-node 0.36.0 → 0.36.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -0
- 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,359 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "ORDER BY, SKIP, LIMIT — Ordering and Pagination"
|
|
3
|
+
description: "Order and paginate LoraDB query results with ORDER BY, SKIP, and LIMIT — evaluation order, stable sorting rules, and their interaction with projection and aggregation."
|
|
4
|
+
online: "https://loradb.com/docs/queries/ordering"
|
|
5
|
+
package: "@loradb/lora-node@0.36.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# ORDER BY, SKIP, LIMIT — Ordering and Pagination
|
|
9
|
+
|
|
10
|
+
`ORDER BY`, `SKIP`, and `LIMIT` shape the final result set of a
|
|
11
|
+
query, or the output of a [`WITH`](./return-with.md#with) stage. They
|
|
12
|
+
are **evaluated after** projection and
|
|
13
|
+
[aggregation](./aggregation.md).
|
|
14
|
+
|
|
15
|
+
## Overview
|
|
16
|
+
|
|
17
|
+
| Goal | Clause |
|
|
18
|
+
|---|---|
|
|
19
|
+
| Sort ascending | `ORDER BY expr ASC` (default) |
|
|
20
|
+
| Sort descending | `ORDER BY expr DESC` |
|
|
21
|
+
| Sort by multiple keys | `ORDER BY a ASC, b DESC` |
|
|
22
|
+
| Skip rows | `SKIP n` |
|
|
23
|
+
| Limit rows | `LIMIT n` |
|
|
24
|
+
| Top-N | `ORDER BY expr LIMIT n` |
|
|
25
|
+
| Pagination | `ORDER BY key SKIP $offset LIMIT $size` |
|
|
26
|
+
|
|
27
|
+
## Syntax
|
|
28
|
+
|
|
29
|
+
```text
|
|
30
|
+
<RETURN | WITH> expr [, expr]
|
|
31
|
+
[ORDER BY expr [ASC | DESC] [NULLS FIRST | NULLS LAST] [, ...]]
|
|
32
|
+
[SKIP n]
|
|
33
|
+
[LIMIT n]
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`n` must be a non-negative integer literal or a parameter that resolves
|
|
37
|
+
to one. An integral float such as `10.0` is accepted. A negative number,
|
|
38
|
+
a fraction, or `null` is an error, as in Neo4j. That includes an omitted
|
|
39
|
+
parameter: if the host never binds `$limit`, then
|
|
40
|
+
`LIMIT $limit` fails with
|
|
41
|
+
`LIMIT expects a non-negative integer, got null` instead of returning
|
|
42
|
+
every row.
|
|
43
|
+
|
|
44
|
+
## Order a single column
|
|
45
|
+
|
|
46
|
+
```cypher
|
|
47
|
+
MATCH (n:User)
|
|
48
|
+
RETURN n.name
|
|
49
|
+
ORDER BY n.name ASC
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
`ASC` is the default; `ORDER BY n.name` is equivalent.
|
|
53
|
+
|
|
54
|
+
### Direction comparison
|
|
55
|
+
|
|
56
|
+
| Type | Ordering |
|
|
57
|
+
|---|---|
|
|
58
|
+
| `Int`, `Float` | Numeric (`NaN` is incomparable) |
|
|
59
|
+
| `String` | Byte-lexicographic |
|
|
60
|
+
| `Boolean` | `false < true` |
|
|
61
|
+
| `Date`, `DateTime`, `Time`, `LocalTime`, `LocalDateTime` | Chronological |
|
|
62
|
+
| `Duration` | By total length (calendar-aware) |
|
|
63
|
+
| `Point` | Not orderable — equality only |
|
|
64
|
+
| `Null` | See [Nulls in ordering](#nulls-in-ordering) |
|
|
65
|
+
|
|
66
|
+
## Multi-key ordering
|
|
67
|
+
|
|
68
|
+
Later keys break ties in earlier keys.
|
|
69
|
+
|
|
70
|
+
```cypher
|
|
71
|
+
MATCH (p:Person)
|
|
72
|
+
RETURN p
|
|
73
|
+
ORDER BY p.last_name ASC, p.first_name ASC, p.id ASC
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Mix directions freely:
|
|
77
|
+
|
|
78
|
+
```cypher
|
|
79
|
+
MATCH (u:User)
|
|
80
|
+
RETURN u
|
|
81
|
+
ORDER BY u.country ASC, u.age DESC
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Ordering by computed expression
|
|
85
|
+
|
|
86
|
+
You can order on anything that evaluates to a comparable value.
|
|
87
|
+
|
|
88
|
+
```cypher
|
|
89
|
+
MATCH (p:Person)
|
|
90
|
+
RETURN p.name, p.age
|
|
91
|
+
ORDER BY p.age * -1 DESC // youngest first
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
You can also order by an alias defined in the same `RETURN`:
|
|
95
|
+
|
|
96
|
+
```cypher
|
|
97
|
+
MATCH (u:User)-[:WROTE]->(:Post)
|
|
98
|
+
RETURN u.name AS author, count(*) AS posts
|
|
99
|
+
ORDER BY posts DESC, author ASC
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Pagination — SKIP + LIMIT
|
|
103
|
+
|
|
104
|
+
```cypher
|
|
105
|
+
MATCH (n:User)
|
|
106
|
+
RETURN n
|
|
107
|
+
ORDER BY n.id
|
|
108
|
+
SKIP 20
|
|
109
|
+
LIMIT 10
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
- `SKIP 0` / no `SKIP` — start at the first row.
|
|
113
|
+
- `LIMIT 0` — return zero rows.
|
|
114
|
+
- `LIMIT n` without `ORDER BY` — the "first n" rows are **undefined**
|
|
115
|
+
without a tiebreaker. Always pair `LIMIT` with `ORDER BY` when the
|
|
116
|
+
order matters.
|
|
117
|
+
|
|
118
|
+
Parameters work identically:
|
|
119
|
+
|
|
120
|
+
```cypher
|
|
121
|
+
MATCH (n:User)
|
|
122
|
+
RETURN n
|
|
123
|
+
ORDER BY n.id
|
|
124
|
+
SKIP $offset
|
|
125
|
+
LIMIT $page_size
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Bind both parameters on every call. An unbound `$page_size` resolves to
|
|
129
|
+
`null`, and `LIMIT null` is an error rather than "no limit". To make
|
|
130
|
+
the limit optional, leave the `LIMIT` clause out of the query text, or
|
|
131
|
+
pass a large explicit number from the host.
|
|
132
|
+
|
|
133
|
+
### Stable pagination
|
|
134
|
+
|
|
135
|
+
`SKIP + LIMIT` is offset-based and can miss / repeat rows if the
|
|
136
|
+
underlying data changes between pages. For stable pagination, sort by an
|
|
137
|
+
immutable key and filter by "last seen":
|
|
138
|
+
|
|
139
|
+
```cypher
|
|
140
|
+
MATCH (n:User)
|
|
141
|
+
WHERE n.id > $after
|
|
142
|
+
RETURN n
|
|
143
|
+
ORDER BY n.id
|
|
144
|
+
LIMIT $page_size
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Then use the last row's id as the next `$after`.
|
|
148
|
+
|
|
149
|
+
## Ordering inside a pipeline
|
|
150
|
+
|
|
151
|
+
`ORDER BY` and `LIMIT` can attach to a [`WITH`](./return-with.md#with)
|
|
152
|
+
stage. Only the surviving rows move forward.
|
|
153
|
+
|
|
154
|
+
```cypher
|
|
155
|
+
MATCH (u:User)-[:WROTE]->(p:Post)
|
|
156
|
+
WITH u, count(p) AS posts
|
|
157
|
+
ORDER BY posts DESC
|
|
158
|
+
LIMIT 10
|
|
159
|
+
MATCH (u)-[:FOLLOWS]->(other)
|
|
160
|
+
RETURN u.name, count(other) AS following
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
This is how you express "top 10 posters, then each of their followings".
|
|
164
|
+
|
|
165
|
+
### Custom sort order with CASE
|
|
166
|
+
|
|
167
|
+
Use [`CASE`](./return-with.md#case-expressions) to project a sort key
|
|
168
|
+
that doesn't match the data's natural ordering. Typical for ordering
|
|
169
|
+
strings by business meaning rather than alphabet:
|
|
170
|
+
|
|
171
|
+
```cypher
|
|
172
|
+
MATCH (t:Task)
|
|
173
|
+
RETURN t.title, t.status
|
|
174
|
+
ORDER BY CASE t.status
|
|
175
|
+
WHEN 'urgent' THEN 0
|
|
176
|
+
WHEN 'open' THEN 1
|
|
177
|
+
WHEN 'review' THEN 2
|
|
178
|
+
ELSE 3
|
|
179
|
+
END, t.created_at DESC
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
One row per task, sorted urgent-first then newest-within-tier.
|
|
183
|
+
|
|
184
|
+
## DISTINCT + ORDER BY
|
|
185
|
+
|
|
186
|
+
[`DISTINCT`](./return-with.md#distinct) runs before ordering. A column used
|
|
187
|
+
to sort must either be a projected column or a deterministic expression
|
|
188
|
+
over projected columns.
|
|
189
|
+
|
|
190
|
+
```cypher
|
|
191
|
+
MATCH (p:Person)
|
|
192
|
+
RETURN DISTINCT p.city
|
|
193
|
+
ORDER BY p.city
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## UNION + ORDER BY / LIMIT
|
|
197
|
+
|
|
198
|
+
For [`UNION` / `UNION ALL`](./return-with.md#union--union-all),
|
|
199
|
+
`ORDER BY` and `LIMIT` apply to the combined result:
|
|
200
|
+
|
|
201
|
+
```cypher
|
|
202
|
+
MATCH (n:User) RETURN n.name AS name
|
|
203
|
+
UNION ALL
|
|
204
|
+
MATCH (n:Product) RETURN n.name AS name
|
|
205
|
+
ORDER BY name
|
|
206
|
+
LIMIT 20
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
## Nulls in ordering
|
|
210
|
+
|
|
211
|
+
`null` values sort **last** in ascending order and **first** in
|
|
212
|
+
descending order. `NULLS FIRST` or `NULLS LAST` after the direction (GQL
|
|
213
|
+
syntax) puts a key's nulls there whichever the direction. `NULLS`,
|
|
214
|
+
`FIRST` and `LAST` are not reserved: they still work as names.
|
|
215
|
+
|
|
216
|
+
```cypher
|
|
217
|
+
// The biggest score first, the unscored at the end
|
|
218
|
+
MATCH (a:Artist)
|
|
219
|
+
RETURN a.name, a.popularityScore
|
|
220
|
+
ORDER BY a.popularityScore DESC NULLS LAST, a.name
|
|
221
|
+
|
|
222
|
+
;// The unscored first, then the smallest score
|
|
223
|
+
MATCH (a:Artist)
|
|
224
|
+
RETURN a.name, a.popularityScore
|
|
225
|
+
ORDER BY a.popularityScore NULLS FIRST
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
With a RANGE index on the key, a nulls-last page can walk the index
|
|
229
|
+
instead of sorting. Bound the key to its type and name the nulls, so the
|
|
230
|
+
planner sees a range: the index is walked in order, then the label's
|
|
231
|
+
nodes without the key, and the scan stops at the limit. With more keys
|
|
232
|
+
the sort becomes a `PartialSort` in `EXPLAIN`, which orders each run of
|
|
233
|
+
equal scores by the next key only.
|
|
234
|
+
|
|
235
|
+
```cypher
|
|
236
|
+
MATCH (a:Artist)
|
|
237
|
+
WHERE a.popularityScore >= toFloat('-Infinity') OR a.popularityScore IS NULL
|
|
238
|
+
RETURN a.name, a.popularityScore
|
|
239
|
+
ORDER BY a.popularityScore DESC NULLS LAST, a.key
|
|
240
|
+
LIMIT 24
|
|
241
|
+
|
|
242
|
+
;// The next page, after the last row's (score, key)
|
|
243
|
+
MATCH (a:Artist)
|
|
244
|
+
WHERE (a.popularityScore <= $score AND (a.popularityScore < $score OR a.key > $key))
|
|
245
|
+
OR a.popularityScore IS NULL
|
|
246
|
+
RETURN a.name, a.popularityScore
|
|
247
|
+
ORDER BY a.popularityScore DESC NULLS LAST, a.key
|
|
248
|
+
LIMIT 24
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
A page that starts among the nulls (`WHERE a.popularityScore IS NULL AND
|
|
252
|
+
a.key > $key`) has no range left to walk and sorts the label's nulls.
|
|
253
|
+
|
|
254
|
+
## Common patterns
|
|
255
|
+
|
|
256
|
+
### Top-N
|
|
257
|
+
|
|
258
|
+
```cypher
|
|
259
|
+
MATCH (u:User)-[:WROTE]->(p:Post)
|
|
260
|
+
RETURN u.name, count(p) AS posts
|
|
261
|
+
ORDER BY posts DESC
|
|
262
|
+
LIMIT 10
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
### First row only
|
|
266
|
+
|
|
267
|
+
```cypher
|
|
268
|
+
MATCH (u:User {email: $email})
|
|
269
|
+
RETURN u
|
|
270
|
+
ORDER BY u.created ASC
|
|
271
|
+
LIMIT 1
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
### Bottom-N (with tiebreaker)
|
|
275
|
+
|
|
276
|
+
```cypher
|
|
277
|
+
MATCH (p:Product)
|
|
278
|
+
RETURN p
|
|
279
|
+
ORDER BY p.price ASC, p.id ASC
|
|
280
|
+
LIMIT 5
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
### Page N
|
|
284
|
+
|
|
285
|
+
```cypher
|
|
286
|
+
MATCH (n:Post)
|
|
287
|
+
RETURN n
|
|
288
|
+
ORDER BY n.published_at DESC, n.id DESC
|
|
289
|
+
SKIP ($page - 1) * $size
|
|
290
|
+
LIMIT $size
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
### Random sample (unstable)
|
|
294
|
+
|
|
295
|
+
```cypher
|
|
296
|
+
MATCH (n)
|
|
297
|
+
RETURN n
|
|
298
|
+
ORDER BY math.random()
|
|
299
|
+
LIMIT 10
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
[`math.random()`](../functions/math.md#random) is re-evaluated per row — good for
|
|
303
|
+
a rough sample, but don't rely on it for cryptographic randomness.
|
|
304
|
+
|
|
305
|
+
## Edge cases
|
|
306
|
+
|
|
307
|
+
### Ordering by a nullable column with NULL present
|
|
308
|
+
|
|
309
|
+
```cypher
|
|
310
|
+
MATCH (p:Person)
|
|
311
|
+
RETURN p.name, p.rank
|
|
312
|
+
ORDER BY p.rank ASC
|
|
313
|
+
// Rows where p.rank IS NULL appear at the end
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
### Ordering by a type-mixed column
|
|
317
|
+
|
|
318
|
+
If `p.score` is sometimes `Int` and sometimes `String`, ordering is
|
|
319
|
+
well-defined but unlikely to match your intent. Cast with
|
|
320
|
+
[`toString`](../functions/string.md#type-conversion) or
|
|
321
|
+
[`toInteger`](../functions/overview.md#type-conversion-and-checking) first.
|
|
322
|
+
|
|
323
|
+
### LIMIT in the middle of a pipeline
|
|
324
|
+
|
|
325
|
+
`LIMIT` on a `WITH` trims rows for downstream stages — subsequent
|
|
326
|
+
`MATCH` clauses only run for the surviving rows. Use it to keep a
|
|
327
|
+
multi-stage query bounded:
|
|
328
|
+
|
|
329
|
+
```cypher
|
|
330
|
+
MATCH (u:User)
|
|
331
|
+
WITH u ORDER BY u.created DESC LIMIT 100
|
|
332
|
+
MATCH (u)-[:WROTE]->(p)
|
|
333
|
+
RETURN u.name, count(p)
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
### SKIP larger than result count
|
|
337
|
+
|
|
338
|
+
Returns zero rows — never an error.
|
|
339
|
+
|
|
340
|
+
## Notes on performance
|
|
341
|
+
|
|
342
|
+
- `ORDER BY` sorts the full projected result set in memory. Combine with
|
|
343
|
+
[`LIMIT`](./ordering.md) when the input is large.
|
|
344
|
+
- `ORDER BY n.prop` sorts the matched rows in memory, unless a RANGE
|
|
345
|
+
index on `prop` can supply the order: with a range predicate on it
|
|
346
|
+
(`WHERE n.prop > $after ORDER BY n.prop LIMIT k`, or the nulls form in
|
|
347
|
+
[Nulls in ordering](#nulls-in-ordering)) rows stream from the index and
|
|
348
|
+
the scan stops after `k`. A tie-breaking second key keeps that, as a
|
|
349
|
+
`PartialSort` over each run of equal values.
|
|
350
|
+
- Pair `LIMIT` with a stable key (like an id) so re-running the same
|
|
351
|
+
query yields the same rows.
|
|
352
|
+
|
|
353
|
+
## See also
|
|
354
|
+
|
|
355
|
+
- [**RETURN / WITH**](./return-with.md) — where ordering attaches.
|
|
356
|
+
- [**Aggregation**](./aggregation.md) — aggregation runs before ordering.
|
|
357
|
+
- [**Query Examples**](./examples.md) — copy-paste Top-N / pagination.
|
|
358
|
+
- [**Math → random**](../functions/math.md#random) — random sampling.
|
|
359
|
+
- [**Temporal Functions**](../functions/temporal.md) — ordering dates.
|
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Query Parameters"
|
|
3
|
+
description: "Bind host-side values into Cypher queries with parameters — how each binding and the HTTP API forwards them, where parameters can appear, and why they are the safe alternative to string interpolation."
|
|
4
|
+
online: "https://loradb.com/docs/queries/parameters"
|
|
5
|
+
package: "@loradb/lora-node@0.36.1"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Query Parameters
|
|
9
|
+
|
|
10
|
+
Parameters are the **only** safe way to mix host-side values into a
|
|
11
|
+
query. Every binding accepts them, and `lora-server` accepts a JSON
|
|
12
|
+
`params` object on `/query`, `/explain`, and `/profile`.
|
|
13
|
+
|
|
14
|
+
```cypher
|
|
15
|
+
MATCH (u:User) WHERE u.id = $id RETURN u
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
`$id` is a placeholder. The host supplies its value at call time.
|
|
19
|
+
|
|
20
|
+
## Why parameters
|
|
21
|
+
|
|
22
|
+
- **Safety.** Parameters cannot rewrite the query shape — no
|
|
23
|
+
injection. Inlining untrusted values is unsafe.
|
|
24
|
+
- **Cacheability.** The parser and analyzer can reuse the same plan
|
|
25
|
+
across calls with different `$id` values.
|
|
26
|
+
- **Type fidelity.** Typed values (dates, points, bigints) survive the
|
|
27
|
+
trip — no string round-trip through the query text.
|
|
28
|
+
|
|
29
|
+
## Binding parameters by host
|
|
30
|
+
|
|
31
|
+
### Rust
|
|
32
|
+
|
|
33
|
+
```rust
|
|
34
|
+
use std::collections::BTreeMap;
|
|
35
|
+
use lora_database::{Database, LoraValue};
|
|
36
|
+
|
|
37
|
+
let db = Database::in_memory();
|
|
38
|
+
|
|
39
|
+
let mut params: BTreeMap<String, LoraValue> = BTreeMap::new();
|
|
40
|
+
params.insert("name".into(), LoraValue::String("Ada".into()));
|
|
41
|
+
params.insert("min".into(), LoraValue::Int(1800));
|
|
42
|
+
|
|
43
|
+
db.execute_with_params(
|
|
44
|
+
"MATCH (p:Person)
|
|
45
|
+
WHERE p.name = $name AND p.born >= $min
|
|
46
|
+
RETURN p.name AS name",
|
|
47
|
+
None,
|
|
48
|
+
params,
|
|
49
|
+
)?;
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
More detail: [Rust → Parameterised query](https://loradb.com/docs/getting-started/rust#parameterised-query).
|
|
53
|
+
|
|
54
|
+
### Node / TypeScript
|
|
55
|
+
|
|
56
|
+
```ts
|
|
57
|
+
await db.execute(
|
|
58
|
+
"MATCH (p:Person) WHERE p.name = $name RETURN p",
|
|
59
|
+
{ name: 'Ada' }
|
|
60
|
+
);
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
More detail: [Node → Parameterised query](../getting-started/node.md#parameterised-query).
|
|
64
|
+
|
|
65
|
+
### Python
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
db.execute(
|
|
69
|
+
"MATCH (p:Person) WHERE p.name = $name RETURN p",
|
|
70
|
+
{"name": "Ada"},
|
|
71
|
+
)
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
More detail: [Python → Parameterised query](https://loradb.com/docs/getting-started/python#parameterised-query).
|
|
75
|
+
|
|
76
|
+
### WASM
|
|
77
|
+
|
|
78
|
+
```ts
|
|
79
|
+
await db.execute(
|
|
80
|
+
"MATCH (u:User) WHERE u.handle = $handle RETURN u",
|
|
81
|
+
{ handle: 'alice' }
|
|
82
|
+
);
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
More detail: [WASM → Parameterised query](https://loradb.com/docs/getting-started/wasm#parameterised-query).
|
|
86
|
+
|
|
87
|
+
### Go
|
|
88
|
+
|
|
89
|
+
```go
|
|
90
|
+
db.Execute(
|
|
91
|
+
"MATCH (u:User) WHERE u.handle = $handle RETURN u",
|
|
92
|
+
lora.Params{"handle": "alice"},
|
|
93
|
+
)
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
More detail: [Go → Parameterised query](https://loradb.com/docs/getting-started/go#parameterised-query).
|
|
97
|
+
|
|
98
|
+
### Ruby
|
|
99
|
+
|
|
100
|
+
```ruby
|
|
101
|
+
db.execute(
|
|
102
|
+
"MATCH (u:User) WHERE u.handle = $handle RETURN u",
|
|
103
|
+
{ handle: "alice" },
|
|
104
|
+
)
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
More detail: [Ruby → Parameterised query](https://loradb.com/docs/getting-started/ruby#parameterised-query).
|
|
108
|
+
|
|
109
|
+
### HTTP
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
curl -s http://127.0.0.1:4747/query \
|
|
113
|
+
-H 'content-type: application/json' \
|
|
114
|
+
-d '{"query":"MATCH (u:User) WHERE u.handle = $handle RETURN u","format":"rows","params":{"handle":"alice"}}'
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
More detail: [HTTP API → `POST /query`](https://loradb.com/docs/api/http#post-query).
|
|
118
|
+
|
|
119
|
+
## Host → LoraDB type mapping
|
|
120
|
+
|
|
121
|
+
| Host value | LoraDB type |
|
|
122
|
+
|---|---|
|
|
123
|
+
| `null` / `None` / `undefined` | [`Null`](../data-types/scalars.md#null) |
|
|
124
|
+
| `bool` / `boolean` | [`Boolean`](../data-types/scalars.md#boolean) |
|
|
125
|
+
| `int` / integer `number` / `i64` | [`Integer`](../data-types/scalars.md#integer) |
|
|
126
|
+
| `float` / non-integer `number` / `f64` | [`Float`](../data-types/scalars.md#float) |
|
|
127
|
+
| `str` / `String` | [`String`](../data-types/scalars.md#string) |
|
|
128
|
+
| list / array / `Vec` | [`List`](../data-types/lists-and-maps.md#lists) |
|
|
129
|
+
| dict / object / `BTreeMap` | [`Map`](../data-types/lists-and-maps.md#maps) |
|
|
130
|
+
| `date()` helper | [`Date`](../data-types/temporal.md) |
|
|
131
|
+
| `datetime()` / `localdatetime()` helper | [`DateTime`](../data-types/temporal.md) / [`LocalDateTime`](../data-types/temporal.md) |
|
|
132
|
+
| `duration()` helper | [`Duration`](../data-types/temporal.md) |
|
|
133
|
+
| `wgs84()` / `cartesian()` helper | [`Point`](../data-types/spatial.md) |
|
|
134
|
+
| `vector()` helper / tagged object | [`Vector`](../data-types/vectors.md) |
|
|
135
|
+
|
|
136
|
+
These helper names are host-language APIs, not query constructors. In
|
|
137
|
+
query text, prefer casts such as `'2026-05-01'::DATE`,
|
|
138
|
+
`{longitude: 4.89, latitude: 52.37}::POINT`, and
|
|
139
|
+
`[1, 2, 3]::VECTOR<INTEGER>(3)`.
|
|
140
|
+
|
|
141
|
+
Every `$name` the query uses must be in the params map: a missing one
|
|
142
|
+
fails the query before it runs, with `expected parameter: $name`
|
|
143
|
+
(error code `LORA_INVALID_PARAMS`), instead of silently reading as
|
|
144
|
+
`null`. To pass "no value", bind `null` explicitly. See
|
|
145
|
+
[Troubleshooting → Unbound parameter](../troubleshooting.md#unbound-parameter).
|
|
146
|
+
`SKIP` and `LIMIT` need a non-negative integer, so an explicit `null`
|
|
147
|
+
`$limit` fails with
|
|
148
|
+
`LIMIT expects a non-negative integer, got null` instead of returning
|
|
149
|
+
every row.
|
|
150
|
+
|
|
151
|
+
## Where parameters can appear
|
|
152
|
+
|
|
153
|
+
| Position | Supported |
|
|
154
|
+
|---|---|
|
|
155
|
+
| Expression / literal (`p.age = $age`) | ✓ |
|
|
156
|
+
| Inline map property (`{id: $id}`) | ✓ |
|
|
157
|
+
| List expression (`$ids`) | ✓ |
|
|
158
|
+
| `UNWIND $rows AS row` | ✓ |
|
|
159
|
+
| Pattern label / relationship type | ✗ — see [Limitations](../limitations.md#parameters) |
|
|
160
|
+
| Property key name | ✗ |
|
|
161
|
+
|
|
162
|
+
The unsupported positions would let a parameter rewrite the query
|
|
163
|
+
shape. If you genuinely need a dynamic label, compose the query
|
|
164
|
+
string host-side from a trusted allow-list — never from raw input.
|
|
165
|
+
See [Limitations → Parameters](../limitations.md#parameters).
|
|
166
|
+
|
|
167
|
+
## Common patterns
|
|
168
|
+
|
|
169
|
+
### Bulk load from a list
|
|
170
|
+
|
|
171
|
+
```cypher
|
|
172
|
+
UNWIND $rows AS row
|
|
173
|
+
CREATE (:User {id: row.id, name: row.name})
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
```ts
|
|
177
|
+
await db.execute(
|
|
178
|
+
"UNWIND $rows AS row CREATE (:User {id: row.id, name: row.name})",
|
|
179
|
+
{ rows: [{ id: 1, name: 'Ada' }, { id: 2, name: 'Grace' }] }
|
|
180
|
+
);
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
See [`UNWIND` → bulk load](./unwind-merge.md#bulk-load-from-parameter).
|
|
184
|
+
|
|
185
|
+
### Dynamic `IN`-style filter
|
|
186
|
+
|
|
187
|
+
```cypher
|
|
188
|
+
MATCH (u:User) WHERE u.id IN $ids RETURN u
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
```python
|
|
192
|
+
db.execute(
|
|
193
|
+
"MATCH (u:User) WHERE u.id IN $ids RETURN u",
|
|
194
|
+
{"ids": [1, 2, 3, 4]},
|
|
195
|
+
)
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### Pass-through typed values
|
|
199
|
+
|
|
200
|
+
```ts
|
|
201
|
+
import { wgs84, duration } from '@loradb/lora-node';
|
|
202
|
+
|
|
203
|
+
await db.execute(
|
|
204
|
+
"CREATE (:Trip {origin: $here, span: $span})",
|
|
205
|
+
{ here: wgs84(4.89, 52.37), span: duration('PT90M') }
|
|
206
|
+
);
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
### Semantic retrieval with a vector parameter
|
|
210
|
+
|
|
211
|
+
Build a tagged `VECTOR` with the helper for your language, pass it as
|
|
212
|
+
an ordinary parameter, and score it against stored embeddings:
|
|
213
|
+
|
|
214
|
+
```ts
|
|
215
|
+
import { vector } from '@loradb/lora-node';
|
|
216
|
+
|
|
217
|
+
const q = vector(embedding, 384, 'FLOAT32');
|
|
218
|
+
|
|
219
|
+
await db.execute(
|
|
220
|
+
`MATCH (d:Doc)
|
|
221
|
+
RETURN d.id AS id
|
|
222
|
+
ORDER BY vector.similarity(d.embedding, $q) DESC
|
|
223
|
+
LIMIT 10`,
|
|
224
|
+
{ q },
|
|
225
|
+
);
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
The same helper exists in every in-process binding — see the
|
|
229
|
+
[Vectors → Passing vectors as parameters](../data-types/vectors.md#passing-vectors-as-parameters)
|
|
230
|
+
table for Python, Go, Ruby, and Rust shapes.
|
|
231
|
+
|
|
232
|
+
`vector.similarity` also
|
|
233
|
+
accepts a plain `LIST<NUMBER>` on either side, so for a one-off query
|
|
234
|
+
you can skip the helper and pass `{ q: [0.1, 0.2, 0.3] }` — the list
|
|
235
|
+
is coerced to a `FLOAT32` vector whose dimension equals its length.
|
|
236
|
+
The full tagged helper is required only when the vector will be
|
|
237
|
+
**stored** as a property, because property storage needs the complete
|
|
238
|
+
`{kind, dimension, coordinateType, values}` shape.
|
|
239
|
+
|
|
240
|
+
`CREATE VECTOR INDEX` and `db.index.vector.queryNodes` /
|
|
241
|
+
`queryRelationships` are supported. They are exact scans over the
|
|
242
|
+
indexed label/type scope by default, and approximate when the index uses
|
|
243
|
+
`vector.indexProvider: 'hnsw'` — see
|
|
244
|
+
[Indexes → Providers](./indexes.md#providers-flat-exact-and-hnsw-approximate).
|
|
245
|
+
When a standalone `CALL` passes the optional options map, write it as an
|
|
246
|
+
inline literal (`{restrictTo: $ids}`); a whole-map `$opts` parameter is
|
|
247
|
+
rejected there.
|
|
248
|
+
|
|
249
|
+
### Default a missing value host-side
|
|
250
|
+
|
|
251
|
+
LoraDB doesn't have "default parameter values" — bind `null`
|
|
252
|
+
explicitly (or use [`coalesce`](../functions/overview.md#type-conversion-and-checking)
|
|
253
|
+
in the query) when the caller omits a field:
|
|
254
|
+
|
|
255
|
+
```ts
|
|
256
|
+
await db.execute(
|
|
257
|
+
"MATCH (u:User) WHERE u.tier = coalesce($tier, u.tier) RETURN u",
|
|
258
|
+
{ tier: opts?.tier ?? null }
|
|
259
|
+
);
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
## HTTP API
|
|
263
|
+
|
|
264
|
+
HTTP parameters are JSON, so the wire shape is intentionally simple:
|
|
265
|
+
|
|
266
|
+
| JSON value | LoraDB value |
|
|
267
|
+
|---|---|
|
|
268
|
+
| `null` | `Null` |
|
|
269
|
+
| `true` / `false` | `Boolean` |
|
|
270
|
+
| integer number | `Integer` |
|
|
271
|
+
| decimal number | `Float` |
|
|
272
|
+
| string | `String` |
|
|
273
|
+
| array | `List` |
|
|
274
|
+
| object | `Map` |
|
|
275
|
+
|
|
276
|
+
The HTTP API does not expose host-language helper constructors such as
|
|
277
|
+
`date(...)`, `wgs84(...)`, or `vector(...)`. Pass the JSON value and
|
|
278
|
+
cast in the query when you need a typed value:
|
|
279
|
+
|
|
280
|
+
```bash
|
|
281
|
+
curl -s http://127.0.0.1:4747/query \
|
|
282
|
+
-H 'content-type: application/json' \
|
|
283
|
+
-d '{"query":"RETURN $day::DATE AS day, $q::VECTOR<FLOAT32>(3) AS q","format":"rows","params":{"day":"2026-05-26","q":[0.1,0.2,0.3]}}'
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
## Common mistakes
|
|
287
|
+
|
|
288
|
+
### Unbound parameter
|
|
289
|
+
|
|
290
|
+
The query fails before it runs with `expected parameter: $id`. Cause: the host
|
|
291
|
+
didn't bind `$id` at all. Fix: add it to the params map, as `null` if
|
|
292
|
+
it has no value.
|
|
293
|
+
|
|
294
|
+
A `null` in `SKIP` or `LIMIT` is an error too: the query fails with
|
|
295
|
+
`LIMIT expects a non-negative integer, got null` (or the `SKIP`
|
|
296
|
+
equivalent). `LIMIT null` does not mean "no limit". Bind a number, or
|
|
297
|
+
drop the clause from the query text when you want every row.
|
|
298
|
+
|
|
299
|
+
### Wrong type
|
|
300
|
+
|
|
301
|
+
`{id: $id}` with host value `"1"` (a string) won't match an integer
|
|
302
|
+
property. Use the right host type, or coerce inside the query:
|
|
303
|
+
|
|
304
|
+
```cypher
|
|
305
|
+
MATCH (n:User) WHERE toString(n.id) = $id RETURN n
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
### Inlining untrusted input
|
|
309
|
+
|
|
310
|
+
```ts
|
|
311
|
+
// Don't do this
|
|
312
|
+
await db.execute(`MATCH (u:User {name: '${req.query.name}'}) RETURN u`);
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
Use `$name` and pass `{ name: req.query.name }` instead. Parameters
|
|
316
|
+
are the only supported safe mixing mechanism.
|
|
317
|
+
|
|
318
|
+
## See also
|
|
319
|
+
|
|
320
|
+
- [Queries → Overview](./index.md) — pipeline and clauses.
|
|
321
|
+
- [Data Types → Overview](../data-types/overview.md) — every value the
|
|
322
|
+
engine understands.
|
|
323
|
+
- [UNWIND + MERGE](./unwind-merge.md) — bulk load and upserts with
|
|
324
|
+
parameters.
|
|
325
|
+
- [Troubleshooting → Parameters](../troubleshooting.md#parameters) —
|
|
326
|
+
silent filtering, invalid params, integer precision.
|
|
327
|
+
- [Limitations → Parameters](../limitations.md#parameters) — identifier
|
|
328
|
+
positions and parse-time type checks.
|