@loradb/lora-node 0.36.0 → 0.36.2

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 (53) hide show
  1. package/README.md +5 -0
  2. package/docs/README.md +86 -0
  3. package/docs/concepts/graph-model.md +270 -0
  4. package/docs/concepts/nodes.md +285 -0
  5. package/docs/concepts/properties.md +348 -0
  6. package/docs/concepts/relationships.md +325 -0
  7. package/docs/concepts/result-formats.md +183 -0
  8. package/docs/concepts/schema-free.md +183 -0
  9. package/docs/cookbook.md +1081 -0
  10. package/docs/data-types/lists-and-maps.md +406 -0
  11. package/docs/data-types/overview.md +210 -0
  12. package/docs/data-types/scalars.md +376 -0
  13. package/docs/data-types/spatial.md +291 -0
  14. package/docs/data-types/temporal.md +355 -0
  15. package/docs/data-types/vectors.md +563 -0
  16. package/docs/errors.md +183 -0
  17. package/docs/functions/aggregation.md +372 -0
  18. package/docs/functions/list.md +522 -0
  19. package/docs/functions/map.md +207 -0
  20. package/docs/functions/math.md +421 -0
  21. package/docs/functions/number.md +197 -0
  22. package/docs/functions/overview.md +545 -0
  23. package/docs/functions/spatial.md +384 -0
  24. package/docs/functions/string.md +502 -0
  25. package/docs/functions/temporal.md +590 -0
  26. package/docs/functions/utility.md +137 -0
  27. package/docs/functions/vectors.md +772 -0
  28. package/docs/getting-started/installation.md +204 -0
  29. package/docs/getting-started/node.md +582 -0
  30. package/docs/getting-started/tutorial.md +334 -0
  31. package/docs/index.md +203 -0
  32. package/docs/limitations.md +291 -0
  33. package/docs/performance.md +219 -0
  34. package/docs/queries/aggregation.md +520 -0
  35. package/docs/queries/cheat-sheet.md +302 -0
  36. package/docs/queries/constraints.md +239 -0
  37. package/docs/queries/create.md +331 -0
  38. package/docs/queries/examples.md +453 -0
  39. package/docs/queries/index.md +169 -0
  40. package/docs/queries/indexes.md +546 -0
  41. package/docs/queries/match.md +429 -0
  42. package/docs/queries/ordering.md +359 -0
  43. package/docs/queries/parameters.md +328 -0
  44. package/docs/queries/paths.md +462 -0
  45. package/docs/queries/return-with.md +500 -0
  46. package/docs/queries/set-delete.md +369 -0
  47. package/docs/queries/unwind-merge.md +358 -0
  48. package/docs/queries/where.md +416 -0
  49. package/docs/snapshot.md +545 -0
  50. package/docs/troubleshooting.md +1158 -0
  51. package/docs/wal.md +570 -0
  52. package/docs/why.md +273 -0
  53. package/package.json +13 -14
@@ -0,0 +1,772 @@
1
+ ---
2
+ title: "Vector Functions (Similarity, Distance, Norms)"
3
+ description: "Vector functions in LoraDB — cast-based vector construction, cosine and Euclidean similarity, signed distance metrics, vector.norm, dimension introspection, and vector retrieval examples."
4
+ online: "https://loradb.com/docs/functions/vectors"
5
+ package: "@loradb/lora-node@0.36.2"
6
+ ---
7
+
8
+ # Vector Functions (Similarity, Distance, Norms)
9
+
10
+ LoraDB has a first-class [`VECTOR`](../data-types/vectors.md) value type
11
+ with a compact set of built-in functions for measuring similarity,
12
+ computing signed distances under standard metrics, and inspecting
13
+ shape. Vector values are constructed with casts. Every similarity / distance
14
+ computation is **exhaustive** when called directly in a query. For a
15
+ cataloged vector search surface, use
16
+ [`CREATE VECTOR INDEX`](../queries/indexes.md#vector-indexes) with
17
+ `db.index.vector.queryNodes` or `queryRelationships`; those procedures
18
+ are exact by default and approximate (HNSW) when the index is created
19
+ with `vector.indexProvider: 'hnsw'`.
20
+
21
+ All similarity / distance math uses `f32` internally: coordinates
22
+ are converted into `f32` before accumulation, then the scalar result
23
+ widens back to `f64`. This is stable regardless of the underlying
24
+ coordinate type.
25
+
26
+ ## Overview
27
+
28
+ | Goal | Function |
29
+ |---|---|
30
+ | Construct a vector | [`[1, 2, 3]::VECTOR<INTEGER>(3)`, `vector(list, dim, FLOAT32)`](#construction) |
31
+ | Bounded similarity (higher = closer, in `[0, 1]`) | [`vector.similarity(a, b)`, `vector.similarity(a, b, 'euclidean')`](#bounded-similarity) |
32
+ | Signed distance under a named metric (smaller = closer) | [`vector.distance(a, b, METRIC)`](#signed-distance) |
33
+ | Magnitude of a vector | [`vector.norm(v, METRIC)`](#norms) |
34
+ | Dimension | [`vector.dimension(v)`](#introspection), `value.size(v)` |
35
+ | Runtime type tag | [`type.of(v)`](#introspection) |
36
+ | Back to a `LIST` | [`vector.coordinates(v)`, `vector.coordinates(v, INTEGER)`, `vector.coordinates(v, FLOAT)`](#list-conversion) |
37
+
38
+ `vector.similarity` also accepts a plain `LIST<NUMBER>` on either
39
+ side — the list is coerced to a `FLOAT32` vector of the same length.
40
+ `vector.distance` and `vector.norm` require real `VECTOR` values.
41
+
42
+ ## Construction
43
+
44
+ Construct vectors with `value::VECTOR<COORD>(DIM)` or
45
+ `CAST(value AS VECTOR<COORD>(DIM))`. See [Data Types → Vectors →
46
+ Construction](../data-types/vectors.md#construction) for the full rules;
47
+ the examples below cover the common shapes.
48
+
49
+ ```cypher
50
+ // Integer-backed
51
+ RETURN [1, 2, 3]::VECTOR<INTEGER>(3) AS v; // VECTOR<INTEGER>(3)
52
+ RETURN [1, 2, 3]::VECTOR<INT8>(3) AS v; // VECTOR<INTEGER8>(3)
53
+ RETURN [1, 2, 3]::VECTOR<INT16>(3) AS v; // VECTOR<INTEGER16>(3)
54
+ RETURN [1, 2, 3]::VECTOR<INT32>(3) AS v // VECTOR<INTEGER32>(3)
55
+
56
+ ;// Float-backed
57
+ RETURN [0.1, 0.2, 0.3]::VECTOR<FLOAT32>(3) AS v; // VECTOR<FLOAT32>(3)
58
+ RETURN [0.1, 0.2, 0.3]::VECTOR<FLOAT64>(3) AS v; // VECTOR<FLOAT64>(3)
59
+ RETURN [0.1, 0.2, 0.3]::VECTOR<FLOAT>(3) AS v // FLOAT is an alias for FLOAT64
60
+
61
+ ;// CAST(...) form, useful when the value is already parenthesized
62
+ RETURN CAST('[1.05, 0.123, 5]' AS VECTOR<FLOAT64>(3)) AS v;
63
+ RETURN CAST('[1e-2, 2e-2, 3e-2]' AS VECTOR<FLOAT32>(3)) AS v
64
+ ```
65
+
66
+ ### The `vector()` function
67
+
68
+ `vector(value, dimension, coordinateType)` builds the same value as the
69
+ cast, but the dimension is an ordinary expression, so it can come from
70
+ `size(list)` or a parameter. `value` is a `LIST<NUMBER>` or a string
71
+ such as `'[1, 2, 3]'`. A null argument gives null; a value that does not
72
+ fit (wrong length, a non-number, an unknown coordinate type, an
73
+ overflow) is an error, where the cast gives null.
74
+
75
+ ```cypher
76
+ WITH [0.5, 1, 2] AS l
77
+ RETURN vector(l, size(l), FLOAT32) AS v; // VECTOR<FLOAT32>(3)
78
+ RETURN vector('[1, 2, 3]', 3, INTEGER8) AS v; // VECTOR<INTEGER8>(3)
79
+ RETURN vector([1, 2, 3], 2, FLOAT32) AS v // error: 3 coordinates, dimension 2
80
+ ```
81
+
82
+ `vector.of` is the namespaced name of the same function.
83
+
84
+ ### Coordinate-type tag forms
85
+
86
+ The coordinate tag appears inside the `VECTOR<...>(...)` type. Matching
87
+ is case-insensitive and accepts aliases such as `FLOAT` for `FLOAT64`
88
+ and `INT8` for `INTEGER8`.
89
+
90
+ ```cypher
91
+ RETURN [1, 2, 3]::VECTOR<INTEGER>(3);
92
+ RETURN [1, 2, 3]::VECTOR<INT8>(3);
93
+ RETURN [1, 2, 3]::VECTOR<FLOAT>(3) // FLOAT aliases FLOAT64
94
+ ```
95
+
96
+ ### From a parameter
97
+
98
+ ```cypher
99
+ RETURN $embedding::VECTOR<FLOAT32>(384) AS query_vec;
100
+ RETURN CAST($embedding AS VECTOR<FLOAT32>(384)) AS query_vec
101
+ ```
102
+
103
+ ```ts
104
+ // Node / TypeScript
105
+ await db.execute(
106
+ 'RETURN $embedding::VECTOR<FLOAT32>(384) AS q',
107
+ { embedding: myFloat32Array },
108
+ );
109
+ ```
110
+
111
+ ```python
112
+ # Python
113
+ db.execute(
114
+ "RETURN $embedding::VECTOR<FLOAT32>(384) AS q",
115
+ {"embedding": embedding_list},
116
+ )
117
+ ```
118
+
119
+ ### Coercion quick reference
120
+
121
+ ```cypher
122
+ // Integers promoted to float-backed vectors (exact for small magnitudes)
123
+ RETURN [1, 2, 3]::VECTOR<FLOAT32>(3) // [1.0, 2.0, 3.0]
124
+
125
+ ;// Floats truncate toward zero into integer-backed vectors
126
+ RETURN [1.9, -1.9, 0.999, -0.999]::VECTOR<INTEGER>(4)
127
+ // [1, -1, 0, 0]
128
+
129
+ ;// Out-of-range errors loudly (no silent saturation)
130
+ RETURN [128]::VECTOR<INT8>(1); // error: value 128 overflows INTEGER8
131
+ RETURN [2e39]::VECTOR<FLOAT32>(1) // error: value overflows FLOAT32
132
+
133
+ ;// NaN / Infinity / mixed types / nested lists all error
134
+ RETURN [1, 'two', 3]::VECTOR<FLOAT32>(3) // error: non-numeric coordinate
135
+ ```
136
+
137
+ ### Null propagation
138
+
139
+ ```cypher
140
+ RETURN null::VECTOR<FLOAT32>(3); // null
141
+ RETURN CAST(null AS VECTOR<FLOAT32>(3)) // null
142
+ ```
143
+
144
+ ## Bounded similarity
145
+
146
+ `vector.similarity(a, b)` defaults to cosine. Pass `'euclidean'` as the
147
+ third argument for bounded Euclidean similarity. Both forms return a
148
+ scalar in `[0, 1]` where **higher = more similar** and accept a `VECTOR`
149
+ or a `LIST<NUMBER>` on either side.
150
+
151
+ The cosine form is **not** the raw cosine. It returns `(1 + cos) / 2`,
152
+ so orthogonal vectors score `0.5` and opposite vectors `0`. This is the
153
+ same score `db.index.vector.queryNodes` reports for a cosine index. To
154
+ get the raw cosine back, compute `2 * vector.similarity(a, b) - 1`, or
155
+ use `1 - vector.distance(a, b, COSINE)` on two `VECTOR` values.
156
+
157
+ It returns null, not `0`, when either side is null (a missing property
158
+ reads as null) or when either vector has zero length under cosine.
159
+ Wrap it in `coalesce(..., 0.0)` when a missing embedding should rank
160
+ last instead of dropping out of a comparison.
161
+
162
+ ```cypher
163
+ // Cosine: (1 + raw_cosine) / 2
164
+ RETURN vector.similarity([1, 0, 0], [1, 0, 0]); // 1.0 (identical direction)
165
+ RETURN vector.similarity([1, 0, 0], [0, 1, 0]); // 0.5 (orthogonal)
166
+ RETURN vector.similarity([1, 0, 0], [-1, 0, 0]); // 0.0 (opposite)
167
+ RETURN vector.similarity([1, 2, 3], [2, 4, 6]) // 1.0 (colinear)
168
+
169
+ ;// Euclidean: 1 / (1 + d²)
170
+ RETURN vector.similarity([4, 5, 6], [2, 8, 3], 'euclidean'); // ≈ 0.04348
171
+ RETURN vector.similarity([0, 0, 0], [0, 0, 0], 'euclidean') // 1.0
172
+ ```
173
+
174
+ ### Mixing lists and vectors
175
+
176
+ ```cypher
177
+ // Pure VECTOR on both sides
178
+ WITH [0.1, 0.2, 0.3]::VECTOR<FLOAT32>(3) AS a,
179
+ [0.2, 0.2, 0.2]::VECTOR<FLOAT32>(3) AS b
180
+ RETURN vector.similarity(a, b) AS score
181
+
182
+ ;// VECTOR vs LIST: list is coerced to FLOAT32
183
+ MATCH (d:Doc)
184
+ RETURN d.id,
185
+ vector.similarity(d.embedding, [0.1, 0.2, 0.3]) AS score
186
+ ORDER BY score DESC
187
+ LIMIT 10
188
+
189
+ ;// LIST vs LIST: both coerced, useful for ad-hoc debugging
190
+ RETURN vector.similarity([1, 2, 3], [1, 2, 3]) AS score
191
+ ```
192
+
193
+ ### Null / error semantics
194
+
195
+ ```cypher
196
+ // null on either side → null
197
+ RETURN vector.similarity(null, [1, 2, 3]); // null
198
+ RETURN vector.similarity([1,2]::VECTOR<FLOAT32>(2), null) // null
199
+
200
+ ;// zero-norm argument to cosine → null (cosine is undefined)
201
+ RETURN vector.similarity([0, 0, 0], [1, 2, 3]) // null
202
+
203
+ ;// dimension mismatch → error
204
+ RETURN vector.similarity([1, 2, 3], [1, 2]) // error
205
+
206
+ ;// empty list → error
207
+ RETURN vector.similarity([], [1, 2, 3]) // error
208
+ ```
209
+
210
+ ## Signed distance
211
+
212
+ `vector.distance(a, b, METRIC)` — **smaller = more similar**. Both
213
+ arguments must be real `VECTOR` values with matching dimensions; a
214
+ plain list is rejected here (unlike the bounded-similarity functions).
215
+
216
+ | Metric | Formula | Range |
217
+ |---|---|---|
218
+ | `EUCLIDEAN` | `sqrt(Σ (aᵢ - bᵢ)²)` | `[0, ∞)` |
219
+ | `EUCLIDEAN_SQUARED` | `Σ (aᵢ - bᵢ)²` | `[0, ∞)` — skip the `sqrt` for pure ranking |
220
+ | `MANHATTAN` | `Σ \|aᵢ - bᵢ\|` | `[0, ∞)` |
221
+ | `COSINE` | `1 - raw_cosine(a, b)` (raw, not bounded) | `[0, 2]` — identical = `0`, opposite = `2` |
222
+ | `DOT` | `-(a · b)` — negated so smaller = closer | `(-∞, ∞)` |
223
+ | `HAMMING` | count of positions where `aᵢ ≠ bᵢ` (`f32` compare) | `[0, dim]` |
224
+
225
+ Metric names are case-insensitive and may be passed as bare
226
+ identifiers or quoted strings.
227
+
228
+ ```cypher
229
+ WITH [1, 2, 3]::VECTOR<FLOAT32>(3) AS a,
230
+ [4, 6, 8]::VECTOR<FLOAT32>(3) AS b
231
+ RETURN vector.distance(a, b, EUCLIDEAN) AS l2, // ≈ 7.0711
232
+ vector.distance(a, b, EUCLIDEAN_SQUARED) AS l2_squared, // 50.0
233
+ vector.distance(a, b, MANHATTAN) AS l1, // 12.0
234
+ vector.distance(a, b, COSINE) AS cos_dist,
235
+ vector.distance(a, b, DOT) AS neg_dot,
236
+ vector.distance(a, b, HAMMING) AS hamming // 3 (all positions differ)
237
+ ```
238
+
239
+ ### Pick the right metric
240
+
241
+ ```cypher
242
+ // L2 / Euclidean — generic "closeness", respects magnitude.
243
+ WITH [1, 0]::VECTOR<FLOAT32>(2) AS a, [3, 0]::VECTOR<FLOAT32>(2) AS b
244
+ RETURN vector.distance(a, b, EUCLIDEAN) // 2.0
245
+
246
+ ;// Squared L2 — same ranking as L2, cheaper (no sqrt). Use for ORDER BY.
247
+ WITH [1, 0]::VECTOR<FLOAT32>(2) AS a, [3, 0]::VECTOR<FLOAT32>(2) AS b
248
+ RETURN vector.distance(a, b, EUCLIDEAN_SQUARED) // 4.0
249
+
250
+ ;// Cosine — magnitude-invariant; parallel vectors are "the same".
251
+ WITH [1, 2, 3]::VECTOR<FLOAT32>(3) AS a,
252
+ [2, 4, 6]::VECTOR<FLOAT32>(3) AS b
253
+ RETURN vector.distance(a, b, COSINE) // ≈ 0.0 (colinear)
254
+
255
+ // Dot — raw inner product, negated so "smaller is closer".
256
+ ;// Useful when embeddings are already unit-normalised.
257
+ WITH [1, 0]::VECTOR<FLOAT32>(2) AS a, [1, 0]::VECTOR<FLOAT32>(2) AS b
258
+ RETURN vector.distance(a, b, DOT) // -1.0
259
+
260
+ ;// Hamming — positionwise difference count. Handy for binary / quantised vectors.
261
+ WITH [1, 0, 1, 1]::VECTOR<INT8>(4) AS a,
262
+ [1, 1, 1, 0]::VECTOR<INT8>(4) AS b
263
+ RETURN vector.distance(a, b, HAMMING) // 2
264
+ ```
265
+
266
+ ### Null / error semantics
267
+
268
+ ```cypher
269
+ // null vectors or null metric → null
270
+ RETURN vector.distance(null, [1,2,3]::VECTOR<FLOAT32>(3), EUCLIDEAN); // null
271
+ RETURN vector.distance([1,2,3]::VECTOR<FLOAT32>(3), null, EUCLIDEAN); // null
272
+ RETURN vector.distance([1,2,3]::VECTOR<FLOAT32>(3),
273
+ [4,5,6]::VECTOR<FLOAT32>(3), null) // null
274
+
275
+ ;// Plain list → error (unlike vector.similarity)
276
+ RETURN vector.distance([1,2,3], [4,5,6]::VECTOR<FLOAT32>(3), EUCLIDEAN) // error
277
+
278
+ ;// Dimension mismatch → error
279
+ RETURN vector.distance([1,2]::VECTOR<FLOAT32>(2),
280
+ [1,2,3]::VECTOR<FLOAT32>(3), EUCLIDEAN) // error
281
+
282
+ ;// Unknown metric → error
283
+ RETURN vector.distance([1,2,3]::VECTOR<FLOAT32>(3),
284
+ [4,5,6]::VECTOR<FLOAT32>(3), 'MAHALANOBIS') // error
285
+ ```
286
+
287
+ ## Norms
288
+
289
+ `vector.norm(v, METRIC)` — magnitude of a single vector.
290
+
291
+ | Metric | Formula |
292
+ |---|---|
293
+ | `EUCLIDEAN` | `sqrt(Σ xᵢ²)` — L2 length |
294
+ | `MANHATTAN` | `Σ \|xᵢ\|` — L1 length |
295
+
296
+ ```cypher
297
+ WITH [3, 4]::VECTOR<FLOAT32>(2) AS v
298
+ RETURN vector.norm(v, EUCLIDEAN); // 5.0 (3² + 4² = 25)
299
+ WITH [3, 4]::VECTOR<FLOAT32>(2) AS v
300
+ RETURN vector.norm(v, MANHATTAN); // 7.0
301
+
302
+ WITH [1, -2, 2]::VECTOR<FLOAT32>(3) AS v
303
+ RETURN vector.norm(v, EUCLIDEAN) // 3.0 (sqrt(9))
304
+
305
+ ;// null propagates
306
+ RETURN vector.norm(null, EUCLIDEAN); // null
307
+ RETURN vector.norm([1,2,3]::VECTOR<FLOAT32>(3), null); // null
308
+ RETURN vector.norm([1,2,3]::VECTOR<FLOAT32>(3), 'MAHALANOBIS') // error
309
+ ```
310
+
311
+ ### Unit-normalisation pattern
312
+
313
+ There's no built-in `vector.normalize` — compose with a list and cast
314
+ the rebuilt coordinates:
315
+
316
+ ```cypher
317
+ WITH [3, 0, 4]::VECTOR<FLOAT32>(3) AS v
318
+ WITH v, vector.norm(v, EUCLIDEAN) AS n, vector.coordinates(v, FLOAT) AS coords
319
+ RETURN [coords[0] / n, coords[1] / n, coords[2] / n]::VECTOR<FLOAT32>(3) AS unit
320
+ // [0.6, 0.0, 0.8]
321
+ ```
322
+
323
+ For variable-dimension unit-normalisation, this is easier to keep
324
+ host-side — the client languages all ship vector parameter helpers.
325
+
326
+ ## Introspection
327
+
328
+ | Expression | Returns | Notes |
329
+ |---|---|---|
330
+ | `type.of(v)` | `String` — `"VECTOR<TYPE>(DIM)"` | Only type whose tag encodes structure |
331
+ | `value.size(v)` | `Int` — dimension | Same as `vector.dimension` |
332
+ | `vector.dimension(v)` | `Int` — dimension | Explicit name |
333
+
334
+ ```cypher
335
+ WITH [1, 2, 3, 4]::VECTOR<FLOAT32>(4) AS v
336
+ RETURN type.of(v) AS t, // 'VECTOR<FLOAT32>(4)'
337
+ value.size(v) AS s, // 4
338
+ vector.dimension(v) AS d // 4
339
+
340
+ ;// Coordinate type is part of the type tag
341
+ RETURN type.of([1,2,3]::VECTOR<INTEGER>(3)); // 'VECTOR<INTEGER>(3)'
342
+ RETURN type.of([1,2,3]::VECTOR<INT8>(3)) // 'VECTOR<INTEGER8>(3)'
343
+ ```
344
+
345
+ ### Guarding by shape
346
+
347
+ ```cypher
348
+ MATCH (d:Doc)
349
+ WHERE type.of(d.embedding) = 'VECTOR<FLOAT32>(384)'
350
+ RETURN d.id AS id
351
+ ```
352
+
353
+ ```cypher
354
+ MATCH (d:Doc)
355
+ WHERE vector.dimension(d.embedding) = 384
356
+ RETURN count(*) AS docs_with_384d
357
+ ```
358
+
359
+ ## List conversion
360
+
361
+ | Function | From | To |
362
+ |---|---|---|
363
+ | `vector.coordinates(v)` | any `VECTOR` | `LIST<FLOAT>` for a float vector, `LIST<INTEGER>` for an integer one |
364
+ | `vector.coordinates(v, INTEGER)` | any `VECTOR` | `LIST<INTEGER>` — truncates toward zero |
365
+ | `vector.coordinates(v, FLOAT)` | any `VECTOR` | `LIST<FLOAT>` — widens exact |
366
+
367
+ ```cypher
368
+ RETURN vector.coordinates([1.9, -1.9, 3.0]::VECTOR<FLOAT32>(3), INTEGER)
369
+ ; // [1, -1, 3]
370
+ RETURN vector.coordinates([1, 2, 3]::VECTOR<INT8>(3), FLOAT)
371
+ ; // [1.0, 2.0, 3.0]
372
+ RETURN vector.coordinates(vector([0.5, 1], 2, FLOAT32))
373
+ // [0.5, 1.0]
374
+
375
+ ;// null propagates
376
+ RETURN vector.coordinates(null, INTEGER); // null
377
+ RETURN vector.coordinates(null, FLOAT) // null
378
+
379
+ ;// non-VECTOR input errors
380
+ RETURN vector.coordinates([1, 2, 3], FLOAT) // error
381
+ ```
382
+
383
+ Both converters round-trip cleanly through the binding layer — use
384
+ them when you need to hand off to a caller that wants a plain array.
385
+
386
+ ## kNN and retrieval patterns
387
+
388
+ ### Top-k by cosine similarity
389
+
390
+ ```cypher
391
+ MATCH (d:Doc)
392
+ RETURN d.id AS id, d.title AS title
393
+ ORDER BY vector.similarity(d.embedding, $query) DESC
394
+ LIMIT 10
395
+ ```
396
+
397
+ ### Top-k carrying the score forward
398
+
399
+ ```cypher
400
+ MATCH (d:Doc)
401
+ WITH d, vector.similarity(d.embedding, $query) AS score
402
+ RETURN d.id AS id, d.title AS title, score
403
+ ORDER BY score DESC
404
+ LIMIT 10
405
+ ```
406
+
407
+ ### Top-k by signed distance (smaller = closer)
408
+
409
+ ```cypher
410
+ MATCH (d:Doc)
411
+ WITH d, vector.distance(d.embedding, $query, EUCLIDEAN) AS dist
412
+ RETURN d.id AS id, dist
413
+ ORDER BY dist ASC
414
+ LIMIT 10
415
+ ```
416
+
417
+ ### Cheaper ranking with `EUCLIDEAN_SQUARED`
418
+
419
+ The rankings are identical; `EUCLIDEAN_SQUARED` skips the `sqrt`.
420
+
421
+ ```cypher
422
+ MATCH (d:Doc)
423
+ WITH d, vector.distance(d.embedding, $query, EUCLIDEAN_SQUARED) AS d2
424
+ RETURN d.id AS id
425
+ ORDER BY d2 ASC
426
+ LIMIT 20
427
+ ```
428
+
429
+ ### Narrow the candidate set first
430
+
431
+ Similarity is `O(n)` over matched nodes — push filters into `MATCH`
432
+ and `WHERE` before scoring.
433
+
434
+ ```cypher
435
+ MATCH (d:Doc {tenant: $tenant})
436
+ WHERE d.language = 'en' AND d.published_at >= '2026-01-01'::DATE
437
+ WITH d, vector.similarity(d.embedding, $query) AS score
438
+ RETURN d.id, score
439
+ ORDER BY score DESC
440
+ LIMIT 10
441
+ ```
442
+
443
+ ### Score threshold
444
+
445
+ ```cypher
446
+ MATCH (d:Doc)
447
+ WITH d, vector.similarity(d.embedding, $query) AS score
448
+ WHERE score >= 0.75
449
+ RETURN d.id, score
450
+ ORDER BY score DESC
451
+ ```
452
+
453
+ ### Graph-filtered retrieval
454
+
455
+ The reason `VECTOR` lives next to the graph — score first, then use
456
+ relationships to explain or filter.
457
+
458
+ ```cypher
459
+ MATCH (d:Doc)
460
+ WITH d, vector.similarity(d.embedding, $query) AS score
461
+ MATCH (d)-[:MENTIONS]->(e:Entity)
462
+ WHERE e.type = $entity_type
463
+ RETURN d.id, d.title, score, collect(e.name) AS entities
464
+ ORDER BY score DESC
465
+ LIMIT 5
466
+ ```
467
+
468
+ ### Neighbour-expansion after retrieval
469
+
470
+ Pull the local graph context around each hit:
471
+
472
+ ```cypher
473
+ MATCH (d:Doc)
474
+ WITH d, vector.similarity(d.embedding, $query) AS score
475
+ ORDER BY score DESC
476
+ LIMIT 10
477
+ MATCH (d)-[:CITED_BY]->(citing:Doc)
478
+ RETURN d.id AS hit, score, collect(citing.id) AS citations
479
+ ```
480
+
481
+ ### Per-category nearest
482
+
483
+ ```cypher
484
+ MATCH (d:Doc)
485
+ WITH d, d.category AS category,
486
+ vector.similarity(d.embedding, $query) AS score
487
+ ORDER BY score DESC
488
+ WITH category, collect({d: d, score: score})[0] AS top
489
+ RETURN category, top.d.id AS id, top.score AS score
490
+ ORDER BY score DESC
491
+ ```
492
+
493
+ ### Hybrid: keyword + vector
494
+
495
+ Blend a lexical boost into a vector score — straight arithmetic, no
496
+ special function required:
497
+
498
+ ```cypher
499
+ MATCH (d:Doc)
500
+ WHERE string.lower(d.title) CONTAINS string.lower($q)
501
+ OR string.lower(d.body) CONTAINS string.lower($q)
502
+ WITH d,
503
+ vector.similarity(d.embedding, $query) AS vec_score,
504
+ CASE WHEN string.lower(d.title) CONTAINS string.lower($q) THEN 0.2 ELSE 0.0 END AS title_boost
505
+ RETURN d.id AS id,
506
+ vec_score + title_boost AS score
507
+ ORDER BY score DESC
508
+ LIMIT 10
509
+ ```
510
+
511
+ ### Expand candidates via relationships, then rank
512
+
513
+ Start from a seed node, hop to candidates through the graph, then
514
+ rank by similarity to the query vector:
515
+
516
+ ```cypher
517
+ MATCH (seed:Doc {id: $seed_id})-[:SIMILAR_TO*1..2]-(candidate:Doc)
518
+ WHERE candidate.id <> $seed_id
519
+ WITH DISTINCT candidate,
520
+ vector.similarity(candidate.embedding, $query) AS score
521
+ RETURN candidate.id, score
522
+ ORDER BY score DESC
523
+ LIMIT 10
524
+ ```
525
+
526
+ ### Multi-vector query (best-of / max-sim)
527
+
528
+ Score each document against several query vectors and keep the best:
529
+
530
+ ```cypher
531
+ UNWIND $queries AS q
532
+ MATCH (d:Doc)
533
+ WITH d, max(vector.similarity(d.embedding, q)) AS best
534
+ RETURN d.id, best
535
+ ORDER BY best DESC
536
+ LIMIT 10
537
+ ```
538
+
539
+ ### Average query (query centroid)
540
+
541
+ If you have several positive examples, a host-side average is usually
542
+ clearer than a Cypher fold. For a small fixed number, you can also
543
+ stay in Cypher:
544
+
545
+ ```cypher
546
+ WITH [$q1, $q2, $q3] AS qs
547
+ MATCH (d:Doc)
548
+ WITH d, reduce(acc = 0.0,
549
+ q IN qs |
550
+ acc + vector.similarity(d.embedding, q) / value.size(qs)) AS score
551
+ RETURN d.id, score
552
+ ORDER BY score DESC
553
+ LIMIT 10
554
+ ```
555
+
556
+ ### Metric comparison side-by-side
557
+
558
+ Useful during debugging — show every metric for one candidate:
559
+
560
+ ```cypher
561
+ WITH [0.10, 0.20, 0.30]::VECTOR<FLOAT32>(3) AS q
562
+ MATCH (d:Doc {id: $id})
563
+ RETURN d.id,
564
+ vector.similarity (d.embedding, q) AS cos_bounded,
565
+ vector.similarity(d.embedding, q, 'euclidean') AS euc_bounded,
566
+ vector.distance(d.embedding, q, EUCLIDEAN) AS l2,
567
+ vector.distance(d.embedding, q, EUCLIDEAN_SQUARED) AS l2_sq,
568
+ vector.distance(d.embedding, q, MANHATTAN) AS l1,
569
+ vector.distance(d.embedding, q, COSINE) AS cos_dist,
570
+ vector.distance(d.embedding, q, DOT) AS neg_dot
571
+ ```
572
+
573
+ ### Count above threshold
574
+
575
+ ```cypher
576
+ MATCH (d:Doc)
577
+ WITH d, vector.similarity(d.embedding, $query) AS score
578
+ WHERE score >= $threshold
579
+ RETURN count(*) AS hits
580
+ ```
581
+
582
+ ### Bucket by similarity band
583
+
584
+ ```cypher
585
+ MATCH (d:Doc)
586
+ WITH vector.similarity(d.embedding, $query) AS score
587
+ WITH CASE
588
+ WHEN score >= 0.9 THEN 'very-close'
589
+ WHEN score >= 0.7 THEN 'close'
590
+ WHEN score >= 0.5 THEN 'related'
591
+ ELSE 'distant'
592
+ END AS band
593
+ RETURN band, count(*) AS n
594
+ ORDER BY n DESC
595
+ ```
596
+
597
+ ### Dedup by identity and keep the best match
598
+
599
+ ```cypher
600
+ MATCH (d:Doc)
601
+ WITH d, vector.similarity(d.embedding, $query) AS score
602
+ ORDER BY score DESC
603
+ WITH d.fingerprint AS fp, collect({d: d, score: score})[0] AS best
604
+ RETURN best.d.id AS id, best.score AS score
605
+ ORDER BY score DESC
606
+ LIMIT 10
607
+ ```
608
+
609
+ ## Bulk insert
610
+
611
+ Vectors load efficiently through a single `UNWIND` over a parameter
612
+ list. Each row becomes a standalone `CREATE`, so each vector flows
613
+ through property conversion as a *top-level* property.
614
+
615
+ ```cypher
616
+ UNWIND $batch AS row
617
+ CREATE (:Doc {id: row.id, title: row.title, embedding: row.embedding})
618
+ ```
619
+
620
+ ```ts
621
+ import { vector } from "@loradb/lora-node";
622
+
623
+ await db.execute(
624
+ `UNWIND $batch AS row
625
+ CREATE (:Doc {id: row.id, title: row.title, embedding: row.embedding})`,
626
+ { batch: docs.map(d => ({
627
+ id: d.id,
628
+ title: d.title,
629
+ embedding: vector(d.embedding, 384, "FLOAT32"),
630
+ })) },
631
+ );
632
+ ```
633
+
634
+ ## Edge cases
635
+
636
+ ### DISTINCT keys coordinate type
637
+
638
+ `DISTINCT` collapses duplicates by coordinate type + dimension +
639
+ values; vectors of different coord types never dedup to each other
640
+ even with numerically identical values:
641
+
642
+ ```cypher
643
+ UNWIND [
644
+ [1, 2, 3]::VECTOR<INTEGER>(3),
645
+ [1, 2, 3]::VECTOR<INTEGER>(3),
646
+ [1, 2, 3]::VECTOR<INTEGER8>(3)
647
+ ] AS v
648
+ RETURN DISTINCT v
649
+ // returns two rows: one INTEGER, one INTEGER8
650
+ ```
651
+
652
+ ### Ordering by a vector column
653
+
654
+ `ORDER BY some_vector_column` is accepted and stable, but the order
655
+ is **implementation-defined**. Order by a scalar score when intent
656
+ matters:
657
+
658
+ ```cypher
659
+ // Works, but meaningless as a primary sort.
660
+ MATCH (d:Doc) RETURN d ORDER BY d.embedding LIMIT 5
661
+
662
+ ;// Use this instead.
663
+ MATCH (d:Doc)
664
+ RETURN d
665
+ ORDER BY vector.similarity(d.embedding, $query) DESC
666
+ LIMIT 5
667
+ ```
668
+
669
+ ### Zero vectors and cosine
670
+
671
+ Cosine on a zero-norm vector is undefined, so
672
+ `vector.similarity([0,…], anything)` returns `null`. Filter
673
+ or coalesce explicitly:
674
+
675
+ ```cypher
676
+ MATCH (d:Doc)
677
+ WITH d, coalesce(vector.similarity(d.embedding, $query), 0.0) AS score
678
+ RETURN d.id, score
679
+ ORDER BY score DESC
680
+ LIMIT 10
681
+ ```
682
+
683
+ ### Integer-backed vectors in similarity
684
+
685
+ Integer coordinates widen to `f32` before accumulation — identical
686
+ ranking behaviour to a `FLOAT32` vector with the same values, modulo
687
+ precision loss for magnitudes that don't fit in the mantissa.
688
+
689
+ ```cypher
690
+ RETURN vector.similarity([1,2,3]::VECTOR<INT8>(3),
691
+ [2,4,6]::VECTOR<INT8>(3))
692
+ // 1.0 (colinear, same result as FLOAT32)
693
+ ```
694
+
695
+ ### HTTP and parameters
696
+
697
+ `POST /query` accepts JSON parameters. Because HTTP has no
698
+ host-language `vector(...)` helper, pass the coordinates as a JSON
699
+ array and cast the parameter in the query:
700
+
701
+ ```bash
702
+ curl -s http://127.0.0.1:4747/query \
703
+ -H 'content-type: application/json' \
704
+ -d '{"query":"RETURN $q::VECTOR<FLOAT32>(3) AS v","format":"rows","params":{"q":[0.1,0.2,0.3]}}'
705
+ ```
706
+
707
+ You can still embed a vector literal directly in the query for quick
708
+ manual probes.
709
+
710
+ ## Index-backed retrieval
711
+
712
+ For the supported index procedure surface, create a vector index and
713
+ query it with `CALL`:
714
+
715
+ ```cypher
716
+ CREATE VECTOR INDEX doc_embedding
717
+ FOR (d:Doc)
718
+ ON (d.embedding)
719
+ OPTIONS {indexConfig: {
720
+ \`vector.dimensions\`: 384,
721
+ \`vector.similarity_function\`: 'cosine'
722
+ }};
723
+
724
+ CALL db.index.vector.queryNodes('doc_embedding', 10, $query)
725
+ YIELD node, score;
726
+ ```
727
+
728
+ This returns the top `k` rows by descending score. `k` must be
729
+ positive, and the query vector dimension must match the index
730
+ configuration. See [Queries → Indexes → Vector indexes](../queries/indexes.md#vector-indexes)
731
+ for relationship indexes, the `restrictTo` option, and the HNSW
732
+ provider for approximate search on large collections.
733
+
734
+ ## Limitations
735
+
736
+ - **ANN is opt-in** — vector indexes are exact (`flat`) by default and
737
+ scan their label/type scope; create them with
738
+ `vector.indexProvider: 'hnsw'` for approximate search.
739
+ - **Direct vector function calls are exhaustive** — keep `MATCH`
740
+ filters tight when using `ORDER BY vector.similarity(...) LIMIT k`.
741
+ - **No embedding generation** — LoraDB has no plugin surface. Produce
742
+ embeddings host-side and pass them in.
743
+ - **No list-of-vectors as a property** — store each vector on its own
744
+ node or relationship. Lists of vectors inside a query are fine.
745
+ - **Typed vector helpers over HTTP** — HTTP accepts JSON params, not
746
+ host-language helper constructors. Pass a numeric list and cast it
747
+ with `$q::VECTOR<COORD>(DIM)` when the query needs a typed vector.
748
+ - **Dimension ≤ 4096** — enforced at construction.
749
+ - **Ordering by a vector column is unspecified** — order by a scalar
750
+ score instead.
751
+
752
+ See also the [Cypher support matrix (§13b)](https://github.com/lora-db/lora/blob/main/docs/reference/cypher-support-matrix.md#13b-vector-types-and-functions)
753
+ for the engine-side behaviour grid.
754
+
755
+ ## See also
756
+
757
+ - [**Vectors (data type)**](../data-types/vectors.md) — full reference for
758
+ the `VECTOR` value type: storage, coercion, parameter binding.
759
+ - [**Cookbook → Vector-retrieval patterns**](../cookbook.md#vector-retrieval-patterns)
760
+ — top-k and graph-filtered retrieval recipes.
761
+ - [**Queries → Parameters**](../queries/parameters.md#semantic-retrieval-with-a-vector-parameter)
762
+ — passing vectors as parameters.
763
+ - [**Math**](./math.md) — scalar arithmetic used alongside vector scores.
764
+ - [**Aggregation**](./aggregation.md) — `max`, `min`, `collect`, used
765
+ after ranking.
766
+
767
+ ### Background reading
768
+
769
+ - [**Vectors belong next to relationships**](https://loradb.com/blog/vectors-belong-next-to-relationships)
770
+ — why similarity lives as a value type instead of in a sidecar store.
771
+ - [**LoraDB v0.2: vector values for connected AI context**](https://loradb.com/blog/loradb-v0-2-vectors)
772
+ — the release that introduced `VECTOR`.