@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,563 @@
1
+ ---
2
+ title: "Vector Values"
3
+ description: "First-class VECTOR values in LoraDB — construction in Cypher, property storage, binding round-trips, vector indexes, and built-in vector math functions."
4
+ online: "https://loradb.com/docs/data-types/vectors"
5
+ package: "@loradb/lora-node@0.36.1"
6
+ ---
7
+
8
+ # Vector Values
9
+
10
+ LoraDB treats `VECTOR` as a first-class value type. Vectors can be
11
+ constructed in Cypher, stored as node or relationship properties,
12
+ returned through every binding, indexed through `CREATE VECTOR INDEX`,
13
+ and used as input to built-in vector math functions.
14
+
15
+ A `VECTOR` has three fixed attributes:
16
+
17
+ - a **dimension** in the range `1..=4096`;
18
+ - a **coordinate type** drawn from six canonical tags;
19
+ - a **values** array whose length always equals `dimension`.
20
+
21
+ > **Info: Scope**
22
+ >
23
+ > `CREATE VECTOR INDEX` and `db.index.vector.queryNodes` /
24
+ > `queryRelationships` are supported. By default an index is exact: it
25
+ > scores every entity in its label/type scope. Opt in to approximate
26
+ > nearest-neighbour search with an HNSW graph per index via
27
+ > `vector.indexProvider: 'hnsw'` — see [Choosing a provider](#choosing-a-provider).
28
+ >
29
+ > LoraDB also has no plugin system today, so there is no built-in
30
+ > embedding generation. Produce embeddings in your application (hosted
31
+ > API, local model, batch job) and pass them in as parameters.
32
+
33
+ ## Construction
34
+
35
+ ```cypher
36
+ RETURN [1, 2, 3]::VECTOR<INTEGER>(3) AS v;
37
+ RETURN [1.05, 0.123, 5]::VECTOR<FLOAT32>(3) AS v;
38
+ RETURN $embedding::VECTOR<FLOAT32>(384) AS v;
39
+ RETURN CAST('[1.05e+00, 0.123, 5]' AS VECTOR<FLOAT>(3)) AS v
40
+ ```
41
+
42
+ Use `value::VECTOR<COORD>(DIM)` for compact handwritten Cypher, or
43
+ `CAST(value AS VECTOR<COORD>(DIM))` when that reads better in generated
44
+ or parenthesized expressions. `TRY_CAST(value AS
45
+ VECTOR<COORD>(DIM))` returns `null` instead of reporting a conversion
46
+ error. The cast input may be:
47
+
48
+ - **value** — `LIST<INTEGER | FLOAT>` **or** a string like
49
+ `"[1, 2, 3]"` (numbers separated by commas, decimal or scientific
50
+ notation). An empty string list `"[]"` parses to zero
51
+ coordinates, which then has to match a zero-dimension declaration —
52
+ but dimension `0` is rejected, so an empty vector is never
53
+ constructible.
54
+ The dimension is part of the target type and must be in `1..=4096`.
55
+ Anything outside the valid ranges is rejected at evaluation time with a
56
+ clear error.
57
+
58
+ ### Coordinate types
59
+
60
+ | Canonical tag | Aliases accepted on input |
61
+ |---|---|
62
+ | `FLOAT64` | `FLOAT` |
63
+ | `FLOAT32` | — |
64
+ | `INTEGER` | `INT`, `INT64`, `INTEGER64` |
65
+ | `INTEGER32` | `INT32` |
66
+ | `INTEGER16` | `INT16` |
67
+ | `INTEGER8` | `INT8` |
68
+
69
+ Alias matching is case-insensitive. Output always emits the canonical
70
+ tag.
71
+
72
+ `DOUBLE` is **not** accepted; typos surface as a clear
73
+ `unknown vector coordinate type '…'` error rather than silently
74
+ mapping to `FLOAT64`.
75
+
76
+ The coordinate type is written inside `VECTOR<...>`. If the coordinate
77
+ type or dimension must come from host code dynamically, build a type
78
+ string and use the lower-level dynamic helper:
79
+
80
+ ```cypher
81
+ RETURN cast.to($values, $type_name) AS v
82
+ ```
83
+
84
+ ### Coercion rules
85
+
86
+ - Integer inputs go into float-typed vectors unchanged (precision can
87
+ degrade for very large magnitudes that don't fit in the float
88
+ mantissa).
89
+ - Float inputs go into integer-typed vectors with truncation **toward
90
+ zero** (`1.9 → 1`, `-1.9 → -1`, `0.999 → 0`, `-0.999 → 0`).
91
+ - Out-of-range values error loudly —
92
+ `[128]::VECTOR<INT8>(1)` is an error because `128` does not fit in
93
+ `INTEGER8`; `[2e39]::VECTOR<FLOAT32>(1)` is rejected because the
94
+ value overflows `f32`; a float bigger than `i64::MAX` for an
95
+ integer-backed vector errors rather than saturating.
96
+ - `NaN`, `Infinity`, and `-Infinity` coordinates are errors.
97
+ - Nested-list coordinates are errors (`[[1,2]]::VECTOR<INTEGER>(1)`).
98
+ - Non-numeric coordinates are errors (`[1, 'two', 3]::VECTOR<FLOAT32>(3)`).
99
+ - An unknown `coordinateType` is an error.
100
+
101
+ ### Null propagation
102
+
103
+ - `null::VECTOR<FLOAT32>(3)` returns `null`.
104
+ - `CAST(null AS VECTOR<FLOAT32>(3))` returns `null`.
105
+
106
+ ## Storage
107
+
108
+ Vectors can be stored directly as node or relationship properties:
109
+
110
+ ```cypher
111
+ CREATE (:Doc {id: 1, embedding: [1, 2, 3]::VECTOR<INTEGER>(3)});
112
+
113
+ MATCH (a:Doc {id: 1}), (b:Doc {id: 2})
114
+ CREATE (a)-[:SIM {score: [0.9, 0.1]::VECTOR<FLOAT32>(2)}]->(b);
115
+
116
+ MATCH (d:Doc {id: 1}) SET d.embedding = [0.1, 0.2]::VECTOR<FLOAT32>(2);
117
+ MATCH (d:Doc {id: 1}) SET d += {embedding: [1, 2]::VECTOR<FLOAT32>(2)}
118
+ ```
119
+
120
+ A vector is also a legal map value — a property map containing a
121
+ vector is stored intact:
122
+
123
+ ```cypher
124
+ CREATE (:Doc {id: 1, meta: {embedding: [1, 2, 3]::VECTOR<INTEGER>(3)}})
125
+ ```
126
+
127
+ ### Restriction: no list-of-vectors as a property
128
+
129
+ A list that contains a `VECTOR` (at any depth under the list, including
130
+ inside a map nested under the list) cannot be stored as a property.
131
+ The engine rejects the write at property-conversion time — this is a
132
+ shape decision, not an oversight:
133
+
134
+ ```cypher
135
+ // Rejected:
136
+ CREATE (:Doc {embeddings: [[1,2,3]::VECTOR<INTEGER>(3)]})
137
+ CREATE (:Doc {meta: {embeddings: [[1,2,3]::VECTOR<INTEGER>(3)]}})
138
+ ```
139
+
140
+ If you need many embeddings per document, hang them off separate
141
+ nodes connected by a relationship, each with its own vector property
142
+ — that is also the shape vector indexes expect.
143
+
144
+ Lists of vectors are still perfectly legal **inside a query** (in a
145
+ `RETURN`, `WITH`, `UNWIND`, or `collect(...)`). The restriction applies
146
+ only to the write path.
147
+
148
+ ## Vector Index Search
149
+
150
+ Create a vector index on a single node or relationship property:
151
+
152
+ ```cypher
153
+ CREATE VECTOR INDEX doc_embedding
154
+ FOR (d:Doc)
155
+ ON (d.embedding)
156
+ OPTIONS {indexConfig: {
157
+ \`vector.dimensions\`: 384,
158
+ \`vector.similarity_function\`: 'cosine'
159
+ }};
160
+ ```
161
+
162
+ Required options:
163
+
164
+ - `vector.dimensions` - integer dimension in `1..=4096`;
165
+ - `vector.similarity_function` - `'cosine'`, `'euclidean'`, `'dot'`
166
+ (alias `'dot_product'`), or `'manhattan'`.
167
+
168
+ Query the indexed node scope with `db.index.vector.queryNodes`:
169
+
170
+ ```cypher
171
+ CALL db.index.vector.queryNodes('doc_embedding', 10, $query)
172
+ YIELD node, score;
173
+ ```
174
+
175
+ Relationship vector indexes use the relationship procedure and yield
176
+ `relationship`:
177
+
178
+ ```cypher
179
+ CALL db.index.vector.queryRelationships('rel_embedding', 10, [1, 0, 0]::VECTOR<FLOAT32>(3))
180
+ YIELD relationship, score;
181
+ ```
182
+
183
+ The procedure returns the yielded columns directly, sorted by
184
+ descending score. The query vector can be a `VECTOR`, a numeric list,
185
+ or a parameter containing a vector. Numeric lists
186
+ are coerced to `FLOAT32` vectors. `k` must be positive, and the query
187
+ dimension must match the configured index dimension.
188
+
189
+ An optional fourth argument, `{restrictTo: [...]}`, limits results to
190
+ the given entity ids. See
191
+ [Indexes → Restricting results](../queries/indexes.md#restricting-results).
192
+
193
+ ### Choosing a provider
194
+
195
+ The default `flat` provider scores every entity in the indexed
196
+ label/type scope, so it is exact and its cost grows linearly with the
197
+ scope. For large collections, build the index with the HNSW provider
198
+ instead — queries stay the same, results become approximate:
199
+
200
+ ```cypher
201
+ CREATE VECTOR INDEX doc_embedding_ann
202
+ FOR (d:Doc)
203
+ ON (d.embedding)
204
+ OPTIONS {indexConfig: {
205
+ \`vector.dimensions\`: 384,
206
+ \`vector.similarity_function\`: 'cosine',
207
+ \`vector.indexProvider\`: 'hnsw'
208
+ }};
209
+ ```
210
+
211
+ The tuning keys `vector.hnsw.m`, `vector.hnsw.ef_construction`,
212
+ `vector.hnsw.ef_search`, and `vector.hnsw.quantization` (`'int8'` for
213
+ cosine indexes over unit-normalised embeddings) are documented in
214
+ [Indexes → Providers](../queries/indexes.md#providers-flat-exact-and-hnsw-approximate).
215
+
216
+ ## Exhaustive kNN
217
+
218
+ You can also express similarity directly with `ORDER BY … LIMIT k`
219
+ over the full candidate set:
220
+
221
+ ```cypher
222
+ MATCH (d:Doc)
223
+ RETURN d.id AS id
224
+ ORDER BY vector.similarity(d.embedding, $query) DESC
225
+ LIMIT 10
226
+ ```
227
+
228
+ Or, using `WITH` to carry the score forward:
229
+
230
+ ```cypher
231
+ MATCH (n:Node)
232
+ WITH n, vector.similarity($query, n.vector, 'euclidean') AS score
233
+ RETURN n.id AS id, score
234
+ ORDER BY score DESC
235
+ LIMIT 2
236
+ ```
237
+
238
+ Every `MATCH` candidate is scored, so cost is `O(n)` in the number of
239
+ matched nodes.
240
+
241
+ ### Graph-filtered retrieval
242
+
243
+ The reason VECTOR lives next to the graph — score candidates by
244
+ similarity, then use relationships to explain or filter them:
245
+
246
+ ```cypher
247
+ MATCH (d:Doc)
248
+ WITH d, vector.similarity(d.embedding, $query) AS score
249
+ MATCH (d)-[:MENTIONS]->(e:Entity)
250
+ WHERE e.type = $entity_type
251
+ RETURN d.id, d.title, score, collect(e.name) AS entities
252
+ ORDER BY score DESC
253
+ LIMIT 5
254
+ ```
255
+
256
+ ### Bulk insert
257
+
258
+ Vectors load efficiently through a single `UNWIND` over a parameter
259
+ list of maps. Each row becomes a standalone `CREATE`, so each vector
260
+ flows through property conversion as a *top-level* property (not a
261
+ list entry), and the property rule is satisfied by construction:
262
+
263
+ ```cypher
264
+ UNWIND $batch AS row
265
+ CREATE (:Doc {id: row.id, title: row.title, embedding: row.embedding})
266
+ ```
267
+
268
+ ```ts
269
+ import { vector } from "@loradb/lora-node";
270
+
271
+ await db.execute(
272
+ `UNWIND $batch AS row
273
+ CREATE (:Doc {id: row.id, title: row.title, embedding: row.embedding})`,
274
+ { batch: docs.map(d => ({
275
+ id: d.id,
276
+ title: d.title,
277
+ embedding: vector(d.embedding, 384, "FLOAT32"),
278
+ })) },
279
+ );
280
+ ```
281
+
282
+ ## Introspection
283
+
284
+ | Expression | Returns |
285
+ |---|---|
286
+ | `type.of([1,2,3]::VECTOR<INTEGER>(3))` | `"VECTOR<INTEGER>(3)"` |
287
+ | `value.size([1,2,3,4]::VECTOR<FLOAT32>(4))` | `4` (dimension) |
288
+ | `vector.dimension([1,2,3]::VECTOR<INTEGER8>(3))` | `3` |
289
+ | `vector.coordinates([1.9, -1.9, 3]::VECTOR<FLOAT32>(3), INTEGER)` | `[1, -1, 3]` |
290
+ | `vector.coordinates([1, 2, 3]::VECTOR<INT8>(3), FLOAT)` | `[1.0, 2.0, 3.0]` |
291
+
292
+ `value.size` on a `VECTOR` returns its dimension — identical to
293
+ `vector.dimension` for convenience. `type.of` returns the
294
+ parameterised tag `VECTOR<TYPE>(DIMENSION)` so runtime inspection can
295
+ see both the coordinate type and the size.
296
+
297
+ `vector.coordinates` on a float vector truncates toward zero (same rule as
298
+ cast-based vector construction). Both converters propagate `null` and error
299
+ on non-`VECTOR` inputs.
300
+
301
+ ## Similarity and distance
302
+
303
+ All similarity / distance functions use `f32` arithmetic internally
304
+ (values are converted from the underlying coordinate type into `f32`
305
+ before accumulation, then widened back to `f64` for the result).
306
+
307
+ ### Bounded similarity in `[0, 1]`
308
+
309
+ ```cypher
310
+ vector.similarity(a, b)
311
+ vector.similarity(a, b, 'euclidean')
312
+ ```
313
+
314
+ Both accept a `VECTOR` **or** a `LIST<NUMBER>` on either side. Lists
315
+ are coerced on the fly to a `FLOAT32` vector whose dimension equals
316
+ the list's length. Higher = more similar.
317
+
318
+ - `cosine`: `(1 + raw_cosine) / 2`, so `1.0` is identical direction,
319
+ `0.5` is orthogonal, `0.0` is opposite. A zero-norm vector returns
320
+ `null` (cosine is undefined).
321
+ - `euclidean`: `1 / (1 + d²)`, where `d²` is the squared L2 distance.
322
+ Documented example:
323
+ `vector.similarity([4,5,6], [2,8,3], 'euclidean') ≈ 0.04348`
324
+ (because `d² = 2² + 3² + 3² = 22`, so `1 / 23 ≈ 0.0435`).
325
+
326
+ Both functions `null`-propagate: any `null` argument returns `null`.
327
+ A dimension mismatch is an error. An empty list on either side is an
328
+ error.
329
+
330
+ ### Signed distance metrics
331
+
332
+ ```cypher
333
+ vector.distance(a, b, EUCLIDEAN)
334
+ vector.distance(a, b, EUCLIDEAN_SQUARED)
335
+ vector.distance(a, b, MANHATTAN)
336
+ vector.distance(a, b, COSINE)
337
+ vector.distance(a, b, DOT)
338
+ vector.distance(a, b, HAMMING)
339
+ ```
340
+
341
+ Both operands must be `VECTOR` values with matching dimensions — a
342
+ plain list is **rejected** here (unlike the similarity functions).
343
+ Smaller = more similar. Metric tokens may be passed as bare
344
+ identifiers or quoted strings; matching is case-insensitive.
345
+
346
+ | Metric | Result |
347
+ |---|---|
348
+ | `EUCLIDEAN` | `sqrt(Σ (aᵢ - bᵢ)²)` |
349
+ | `EUCLIDEAN_SQUARED` | `Σ (aᵢ - bᵢ)²` |
350
+ | `MANHATTAN` | `Σ |aᵢ - bᵢ|` |
351
+ | `COSINE` | `1 - raw_cosine(a, b)` (raw cosine, **not** the bounded variant) |
352
+ | `DOT` | `-(a · b)` — negated so "smaller = more similar" holds |
353
+ | `HAMMING` | count of positions where `aᵢ` and `bᵢ` differ (`f32` comparison) |
354
+
355
+ `null` on either vector or the metric returns `null`. An unknown
356
+ metric name is an error. A dimension mismatch is an error.
357
+
358
+ ### Vector norms
359
+
360
+ ```cypher
361
+ vector.norm(v, EUCLIDEAN) // sqrt(Σ xᵢ²)
362
+ vector.norm(v, MANHATTAN) // Σ |xᵢ|
363
+ ```
364
+
365
+ Metric matching is case-insensitive; identifiers and quoted strings
366
+ both work. `null` vector or `null` metric returns `null`. Unknown
367
+ metric errors.
368
+
369
+ ## Equality, DISTINCT, and ordering
370
+
371
+ - **Equality** compares coordinate type, dimension, and every value.
372
+ `[1,2,3]::VECTOR<INTEGER>(3) = [1,2,3]::VECTOR<INTEGER8>(3)` is
373
+ `false` — different coordinate types are never equal, even with
374
+ numerically identical values.
375
+ - **`DISTINCT`** uses a stable key (coordinate type + dimension +
376
+ stringified values) so duplicates collapse across projection and
377
+ pipeline stages. Vectors of different coord types never collapse.
378
+ - **`ORDER BY`** on a vector column is accepted and runs without
379
+ panicking, but the ordering is implementation-defined — use it for
380
+ tie-breaking, not primary sort. Order by a scalar score
381
+ (`vector.similarity(...)`) when intent matters.
382
+
383
+ ## Passing vectors as parameters
384
+
385
+ Every in-process binding accepts the same canonical tagged shape on
386
+ input and emits it on output. Build one via the helper for your
387
+ language, or pass the literal object directly. Over HTTP, pass a JSON
388
+ numeric list and cast it in the query when you need a typed vector.
389
+
390
+ ### Wire shape
391
+
392
+ ```json
393
+ {
394
+ "kind": "vector",
395
+ "dimension": 3,
396
+ "coordinateType": "FLOAT32",
397
+ "values": [0.1, 0.2, 0.3]
398
+ }
399
+ ```
400
+
401
+ Integer-backed vectors deserialise to integers in the `values` array;
402
+ float-backed vectors deserialise to numbers that may be fractional.
403
+ `INTEGER8` / `INTEGER16` / `INTEGER32` / `FLOAT32` all widen to a
404
+ wider native type on the wire — the underlying storage stays narrow,
405
+ the JSON form uses the nearest lossless widening.
406
+
407
+ ### Binding helpers
408
+
409
+ | Language | Constructor | Guard |
410
+ |---|---|---|
411
+ | TypeScript / Node | `vector(values, dimension, coordinateType)` | `isVector(v)` |
412
+ | TypeScript / WASM | `vector(values, dimension, coordinateType)` | `isVector(v)` |
413
+ | Python | `vector(values, dimension, coordinate_type)` | `is_vector(v)` |
414
+ | Go | `lora.Vector(values, dimension, coordinateType)` | `lora.IsVector(v)` |
415
+ | Ruby | `LoraRuby.vector(values, dimension, coordinate_type)` | `LoraRuby.vector?(v)` |
416
+ | Rust | `LoraVector::try_new(raw, dimension, coordinateType)` → `LoraValue::Vector(_)` | match on `LoraValue::Vector(_)` |
417
+
418
+ The Go, Ruby, and Python helpers additionally ship coordinate-type
419
+ constants (`VectorCoordTypeFloat32`, `VECTOR_COORD_TYPES`,
420
+ `LoraVectorCoordinateType`) to avoid typing the string literals by
421
+ hand.
422
+
423
+ ### Node / TypeScript
424
+
425
+ ```ts
426
+ import { vector } from "@loradb/lora-node";
427
+
428
+ const query = vector([0.1, 0.2, 0.3], 3, "FLOAT32");
429
+
430
+ await db.execute(
431
+ `MATCH (d:Doc)
432
+ RETURN d.id AS id
433
+ ORDER BY vector.similarity(d.embedding, $q) DESC
434
+ LIMIT 10`,
435
+ { q: query },
436
+ );
437
+ ```
438
+
439
+ ### Python
440
+
441
+ ```python
442
+ from lora_python import Database, vector
443
+
444
+ db = Database.create()
445
+ q = vector([0.1, 0.2, 0.3], 3, "FLOAT32")
446
+
447
+ db.execute(
448
+ "RETURN vector.similarity($a, $b) AS s",
449
+ {"a": q, "b": [0.1, 0.2, 0.3]}, # list is coerced to FLOAT32
450
+ )
451
+ ```
452
+
453
+ ### Go
454
+
455
+ ```go
456
+ q := lora.Vector(
457
+ []any{0.1, 0.2, 0.3},
458
+ 3,
459
+ lora.VectorCoordTypeFloat32,
460
+ )
461
+ db.Execute(
462
+ "MATCH (d:Doc) RETURN d.id ORDER BY vector.similarity(d.embedding, $q) DESC LIMIT 10",
463
+ lora.Params{"q": q},
464
+ )
465
+ ```
466
+
467
+ ### Ruby
468
+
469
+ ```ruby
470
+ require "lora_ruby"
471
+
472
+ q = LoraRuby.vector([0.1, 0.2, 0.3], 3, "FLOAT32")
473
+ db.execute(
474
+ "MATCH (d:Doc) RETURN d.id ORDER BY vector.similarity(d.embedding, $q) DESC LIMIT 10",
475
+ { q: q },
476
+ )
477
+ ```
478
+
479
+ ### Rust
480
+
481
+ ```rust
482
+ use lora_database::Database;
483
+ use lora_store::{LoraVector, RawCoordinate, VectorCoordinateType};
484
+ use lora_database::LoraValue;
485
+ use std::collections::BTreeMap;
486
+
487
+ let mut params = BTreeMap::new();
488
+ params.insert(
489
+ "q".into(),
490
+ LoraValue::Vector(
491
+ LoraVector::try_new(
492
+ vec![
493
+ RawCoordinate::Float(0.1),
494
+ RawCoordinate::Float(0.2),
495
+ RawCoordinate::Float(0.3),
496
+ ],
497
+ 3,
498
+ VectorCoordinateType::Float32,
499
+ )?,
500
+ ),
501
+ );
502
+
503
+ db.execute_with_params(
504
+ "MATCH (d:Doc) RETURN d.id ORDER BY vector.similarity(d.embedding, $q) DESC LIMIT 10",
505
+ None,
506
+ params,
507
+ )?;
508
+ ```
509
+
510
+ ### HTTP
511
+
512
+ `POST /query` accepts JSON parameters. HTTP cannot construct the
513
+ binding-specific tagged `VECTOR` helper object for you, so pass the
514
+ coordinates as a JSON array and cast the parameter in the query:
515
+
516
+ ```bash
517
+ curl -s http://127.0.0.1:4747/query \
518
+ -H 'content-type: application/json' \
519
+ -d '{"query":"RETURN $q::VECTOR<FLOAT32>(3) AS v","format":"rows","params":{"q":[0.1,0.2,0.3]}}'
520
+ ```
521
+
522
+ You can still embed the vector literally in the query string for
523
+ manual probes. See [Queries → Parameters](../queries/parameters.md#http-api).
524
+
525
+ ## Limitations
526
+
527
+ - **ANN is opt-in.** Vector indexes default to the exact `flat`
528
+ provider; `vector.indexProvider: 'hnsw'` switches an index to
529
+ approximate search, which can miss some true neighbours.
530
+ - **Similarity / distance functions are exhaustive.** Direct
531
+ `vector.similarity(...)` and `vector.distance(...)` calls score every
532
+ candidate matched by the query.
533
+ - **Embedding generation — not supported.** LoraDB has no plugin
534
+ surface; generate embeddings in application code.
535
+ - **List-of-vectors as a property — not supported.** See
536
+ [Storage](#restriction-no-list-of-vectors-as-a-property).
537
+ - **Typed vector helpers over HTTP.** HTTP accepts JSON params, not
538
+ host-language helper constructors. Pass a numeric list and cast it
539
+ with `$q::VECTOR<COORD>(DIM)` when the query needs a typed vector.
540
+ - **Dimension ≤ 4096.** Hard cap at construction time.
541
+ - **Ordering by a vector column is unspecified.** Order by a scalar
542
+ score instead.
543
+
544
+ 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)
545
+ for the engine-side behaviour grid.
546
+
547
+ ## See also
548
+
549
+ - [Functions → Overview](../functions/overview.md) — includes vector functions.
550
+ - [Queries → Parameters](../queries/parameters.md#semantic-retrieval-with-a-vector-parameter)
551
+ — passing vectors as parameters.
552
+ - [Cookbook → Vector-retrieval patterns](../cookbook.md#vector-retrieval-patterns)
553
+ — top-k and graph-filtered retrieval recipes.
554
+ - [Limitations → Vectors](../limitations.md#vectors) — what's not implemented yet.
555
+ - Internal [value model](https://github.com/lora-db/lora/blob/main/docs/internals/value-model.md#vectors)
556
+ — engine-side shape and conversion rules for future contributors.
557
+
558
+ ### Background reading
559
+
560
+ - [**Vectors belong next to relationships**](https://loradb.com/blog/vectors-belong-next-to-relationships)
561
+ — why similarity lives as a value type instead of in a sidecar store.
562
+ - [**LoraDB v0.2: vector values for connected AI context**](https://loradb.com/blog/loradb-v0-2-vectors)
563
+ — the release that introduced `VECTOR`.