@loradb/lora-node 0.35.1 → 0.36.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +5 -0
- package/dist/types.d.ts +2 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +1 -0
- package/dist/types.js.map +1 -1
- package/docs/README.md +86 -0
- package/docs/concepts/graph-model.md +270 -0
- package/docs/concepts/nodes.md +285 -0
- package/docs/concepts/properties.md +348 -0
- package/docs/concepts/relationships.md +325 -0
- package/docs/concepts/result-formats.md +183 -0
- package/docs/concepts/schema-free.md +183 -0
- package/docs/cookbook.md +1081 -0
- package/docs/data-types/lists-and-maps.md +406 -0
- package/docs/data-types/overview.md +210 -0
- package/docs/data-types/scalars.md +376 -0
- package/docs/data-types/spatial.md +291 -0
- package/docs/data-types/temporal.md +349 -0
- package/docs/data-types/vectors.md +563 -0
- package/docs/errors.md +183 -0
- package/docs/functions/aggregation.md +372 -0
- package/docs/functions/list.md +522 -0
- package/docs/functions/map.md +207 -0
- package/docs/functions/math.md +421 -0
- package/docs/functions/number.md +197 -0
- package/docs/functions/overview.md +545 -0
- package/docs/functions/spatial.md +384 -0
- package/docs/functions/string.md +502 -0
- package/docs/functions/temporal.md +590 -0
- package/docs/functions/utility.md +137 -0
- package/docs/functions/vectors.md +772 -0
- package/docs/getting-started/installation.md +204 -0
- package/docs/getting-started/node.md +582 -0
- package/docs/getting-started/tutorial.md +334 -0
- package/docs/index.md +203 -0
- package/docs/limitations.md +291 -0
- package/docs/performance.md +219 -0
- package/docs/queries/aggregation.md +520 -0
- package/docs/queries/cheat-sheet.md +302 -0
- package/docs/queries/constraints.md +239 -0
- package/docs/queries/create.md +331 -0
- package/docs/queries/examples.md +453 -0
- package/docs/queries/index.md +169 -0
- package/docs/queries/indexes.md +538 -0
- package/docs/queries/match.md +429 -0
- package/docs/queries/ordering.md +359 -0
- package/docs/queries/parameters.md +328 -0
- package/docs/queries/paths.md +462 -0
- package/docs/queries/return-with.md +500 -0
- package/docs/queries/set-delete.md +369 -0
- package/docs/queries/unwind-merge.md +358 -0
- package/docs/queries/where.md +416 -0
- package/docs/snapshot.md +545 -0
- package/docs/troubleshooting.md +1158 -0
- package/docs/wal.md +570 -0
- package/docs/why.md +273 -0
- package/package.json +13 -14
|
@@ -0,0 +1,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`.
|