@loradb/lora-node 0.35.1 → 0.36.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (57) hide show
  1. package/README.md +5 -0
  2. package/dist/types.d.ts +2 -1
  3. package/dist/types.d.ts.map +1 -1
  4. package/dist/types.js +1 -0
  5. package/dist/types.js.map +1 -1
  6. package/docs/README.md +86 -0
  7. package/docs/concepts/graph-model.md +270 -0
  8. package/docs/concepts/nodes.md +285 -0
  9. package/docs/concepts/properties.md +348 -0
  10. package/docs/concepts/relationships.md +325 -0
  11. package/docs/concepts/result-formats.md +183 -0
  12. package/docs/concepts/schema-free.md +183 -0
  13. package/docs/cookbook.md +1081 -0
  14. package/docs/data-types/lists-and-maps.md +406 -0
  15. package/docs/data-types/overview.md +210 -0
  16. package/docs/data-types/scalars.md +376 -0
  17. package/docs/data-types/spatial.md +291 -0
  18. package/docs/data-types/temporal.md +349 -0
  19. package/docs/data-types/vectors.md +563 -0
  20. package/docs/errors.md +183 -0
  21. package/docs/functions/aggregation.md +372 -0
  22. package/docs/functions/list.md +522 -0
  23. package/docs/functions/map.md +207 -0
  24. package/docs/functions/math.md +421 -0
  25. package/docs/functions/number.md +197 -0
  26. package/docs/functions/overview.md +545 -0
  27. package/docs/functions/spatial.md +384 -0
  28. package/docs/functions/string.md +502 -0
  29. package/docs/functions/temporal.md +590 -0
  30. package/docs/functions/utility.md +137 -0
  31. package/docs/functions/vectors.md +772 -0
  32. package/docs/getting-started/installation.md +204 -0
  33. package/docs/getting-started/node.md +582 -0
  34. package/docs/getting-started/tutorial.md +334 -0
  35. package/docs/index.md +203 -0
  36. package/docs/limitations.md +291 -0
  37. package/docs/performance.md +219 -0
  38. package/docs/queries/aggregation.md +520 -0
  39. package/docs/queries/cheat-sheet.md +302 -0
  40. package/docs/queries/constraints.md +239 -0
  41. package/docs/queries/create.md +331 -0
  42. package/docs/queries/examples.md +453 -0
  43. package/docs/queries/index.md +169 -0
  44. package/docs/queries/indexes.md +538 -0
  45. package/docs/queries/match.md +429 -0
  46. package/docs/queries/ordering.md +359 -0
  47. package/docs/queries/parameters.md +328 -0
  48. package/docs/queries/paths.md +462 -0
  49. package/docs/queries/return-with.md +500 -0
  50. package/docs/queries/set-delete.md +369 -0
  51. package/docs/queries/unwind-merge.md +358 -0
  52. package/docs/queries/where.md +416 -0
  53. package/docs/snapshot.md +545 -0
  54. package/docs/troubleshooting.md +1158 -0
  55. package/docs/wal.md +570 -0
  56. package/docs/why.md +273 -0
  57. package/package.json +13 -14
@@ -0,0 +1,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.