@statewalker/db-sqlite-index 0.0.0-stage → 0.1.0
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/LICENSE +21 -0
- package/README.md +289 -2
- package/dist/ngram.d.mts +93 -0
- package/dist/ngram.d.mts.map +1 -0
- package/dist/ngram.mjs +615 -0
- package/dist/ngram.mjs.map +1 -0
- package/dist/vector.d.mts +103 -0
- package/dist/vector.d.mts.map +1 -0
- package/dist/vector.mjs +1061 -0
- package/dist/vector.mjs.map +1 -0
- package/package.json +63 -3
- package/src/ngram/do-smoke.ts +46 -0
- package/src/ngram/fold.test.ts +50 -0
- package/src/ngram/fold.ts +21 -0
- package/src/ngram/fts5-backend.ts +55 -0
- package/src/ngram/index.ts +12 -0
- package/src/ngram/json-chunks.test.ts +23 -0
- package/src/ngram/json-chunks.ts +23 -0
- package/src/ngram/ngram-store.test.ts +291 -0
- package/src/ngram/ngram-store.ts +183 -0
- package/src/ngram/plan-query.test.ts +141 -0
- package/src/ngram/plan-query.ts +42 -0
- package/src/ngram/postings-backend.ts +53 -0
- package/src/ngram/regex-literals.ts +359 -0
- package/src/ngram/trigrams.test.ts +28 -0
- package/src/ngram/trigrams.ts +25 -0
- package/src/vector/auto-compact.test.ts +28 -0
- package/src/vector/do-smoke.ts +39 -0
- package/src/vector/index.ts +9 -0
- package/src/vector/kmeans.ts +131 -0
- package/src/vector/math.ts +185 -0
- package/src/vector/segment.test.ts +61 -0
- package/src/vector/segment.ts +256 -0
- package/src/vector/sql-segment-store.ts +218 -0
- package/src/vector/test-fixtures.ts +64 -0
- package/src/vector/types.ts +30 -0
- package/src/vector/vector-index.test.ts +105 -0
- package/src/vector/vector-index.ts +586 -0
- package/src/vector/vector-lifecycle.test.ts +171 -0
package/dist/vector.mjs
ADDED
|
@@ -0,0 +1,1061 @@
|
|
|
1
|
+
import { inTransaction } from "@statewalker/db-sqlite";
|
|
2
|
+
//#region src/vector/math.ts
|
|
3
|
+
function normalize(v) {
|
|
4
|
+
let n = 0;
|
|
5
|
+
for (let i = 0; i < v.length; i++) n += v[i] * v[i];
|
|
6
|
+
n = Math.sqrt(n);
|
|
7
|
+
const out = new Float32Array(v.length);
|
|
8
|
+
if (n === 0) return out;
|
|
9
|
+
for (let i = 0; i < v.length; i++) out[i] = v[i] / n;
|
|
10
|
+
return out;
|
|
11
|
+
}
|
|
12
|
+
/** Vectors are stored pre-normalized for cosine, so cosine reduces to dot. */
|
|
13
|
+
function prepare(v, dims, metric) {
|
|
14
|
+
if (v.length !== dims) throw new Error(`vector-index: expected ${dims} dims, got ${v.length}`);
|
|
15
|
+
const f = v instanceof Float32Array ? v : Float32Array.from(v);
|
|
16
|
+
for (let i = 0; i < f.length; i++) if (!Number.isFinite(f[i])) throw new Error("vector-index: vector contains a non-finite value");
|
|
17
|
+
return metric === "cosine" ? normalize(f) : f.slice();
|
|
18
|
+
}
|
|
19
|
+
/** Distance between two float vectors at offsets; lower is closer. */
|
|
20
|
+
function distance(metric, a, ao, b, bo, d) {
|
|
21
|
+
if (metric === "l2") {
|
|
22
|
+
let s = 0;
|
|
23
|
+
for (let i = 0; i < d; i++) {
|
|
24
|
+
const x = a[ao + i] - b[bo + i];
|
|
25
|
+
s += x * x;
|
|
26
|
+
}
|
|
27
|
+
return s;
|
|
28
|
+
}
|
|
29
|
+
let s = 0;
|
|
30
|
+
for (let i = 0; i < d; i++) s += a[ao + i] * b[bo + i];
|
|
31
|
+
return metric === "cosine" ? 1 - s : -s;
|
|
32
|
+
}
|
|
33
|
+
/** Symmetric per-vector int8: x ≈ q * scale / 127. Returns the scale. */
|
|
34
|
+
function quantizeInt8(v, vo, d, out, oo) {
|
|
35
|
+
let max = 0;
|
|
36
|
+
for (let i = 0; i < d; i++) max = Math.max(max, Math.abs(v[vo + i]));
|
|
37
|
+
const inv = max === 0 ? 0 : 127 / max;
|
|
38
|
+
for (let i = 0; i < d; i++) out[oo + i] = Math.round(v[vo + i] * inv);
|
|
39
|
+
return max;
|
|
40
|
+
}
|
|
41
|
+
/** Distance between a float query and an int8-coded vector. */
|
|
42
|
+
function distanceInt8(metric, q, codes, co, scale, d) {
|
|
43
|
+
const f = scale / 127;
|
|
44
|
+
if (metric === "l2") {
|
|
45
|
+
let s = 0;
|
|
46
|
+
for (let i = 0; i < d; i++) {
|
|
47
|
+
const x = q[i] - codes[co + i] * f;
|
|
48
|
+
s += x * x;
|
|
49
|
+
}
|
|
50
|
+
return s;
|
|
51
|
+
}
|
|
52
|
+
let s = 0;
|
|
53
|
+
for (let i = 0; i < d; i++) s += q[i] * codes[co + i];
|
|
54
|
+
s *= f;
|
|
55
|
+
return metric === "cosine" ? 1 - s : -s;
|
|
56
|
+
}
|
|
57
|
+
const wordsFor = (d) => d + 31 >>> 5;
|
|
58
|
+
/** Sign bits of (v - centroid): residual binarization, meaningful for every metric. */
|
|
59
|
+
function residualBits(v, vo, c, co, d, out, oo) {
|
|
60
|
+
const w = wordsFor(d);
|
|
61
|
+
out.fill(0, oo, oo + w);
|
|
62
|
+
for (let i = 0; i < d; i++) if (v[vo + i] > c[co + i]) out[oo + (i >>> 5)] |= 1 << (i & 31);
|
|
63
|
+
}
|
|
64
|
+
function hamming(a, b, bo, w) {
|
|
65
|
+
let n = 0;
|
|
66
|
+
for (let i = 0; i < w; i++) {
|
|
67
|
+
let x = a[i] ^ b[bo + i];
|
|
68
|
+
x -= x >>> 1 & 1431655765;
|
|
69
|
+
x = (x & 858993459) + (x >>> 2 & 858993459);
|
|
70
|
+
n += Math.imul(x + (x >>> 4) & 252645135, 16843009) >>> 24;
|
|
71
|
+
}
|
|
72
|
+
return n;
|
|
73
|
+
}
|
|
74
|
+
/** Keeps the `k` smallest scores. A binary max-heap over parallel arrays. */
|
|
75
|
+
var TopK = class {
|
|
76
|
+
#k;
|
|
77
|
+
#scores = [];
|
|
78
|
+
#items = [];
|
|
79
|
+
constructor(k) {
|
|
80
|
+
this.#k = Math.max(0, k);
|
|
81
|
+
}
|
|
82
|
+
get size() {
|
|
83
|
+
return this.#scores.length;
|
|
84
|
+
}
|
|
85
|
+
/** The score a new item must beat, or Infinity while not full. */
|
|
86
|
+
get bound() {
|
|
87
|
+
return this.#scores.length < this.#k ? Number.POSITIVE_INFINITY : this.#scores[0];
|
|
88
|
+
}
|
|
89
|
+
push(score, item) {
|
|
90
|
+
if (this.#k === 0) return;
|
|
91
|
+
const s = this.#scores;
|
|
92
|
+
const it = this.#items;
|
|
93
|
+
if (s.length < this.#k) {
|
|
94
|
+
s.push(score);
|
|
95
|
+
it.push(item);
|
|
96
|
+
let i = s.length - 1;
|
|
97
|
+
while (i > 0) {
|
|
98
|
+
const p = i - 1 >> 1;
|
|
99
|
+
if (s[p] >= s[i]) break;
|
|
100
|
+
this.#swap(i, p);
|
|
101
|
+
i = p;
|
|
102
|
+
}
|
|
103
|
+
return;
|
|
104
|
+
}
|
|
105
|
+
if (score >= s[0]) return;
|
|
106
|
+
s[0] = score;
|
|
107
|
+
it[0] = item;
|
|
108
|
+
let i = 0;
|
|
109
|
+
for (;;) {
|
|
110
|
+
const l = 2 * i + 1;
|
|
111
|
+
const r = l + 1;
|
|
112
|
+
let m = i;
|
|
113
|
+
if (l < s.length && s[l] > s[m]) m = l;
|
|
114
|
+
if (r < s.length && s[r] > s[m]) m = r;
|
|
115
|
+
if (m === i) break;
|
|
116
|
+
this.#swap(i, m);
|
|
117
|
+
i = m;
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
/** Ascending by score. */
|
|
121
|
+
sorted() {
|
|
122
|
+
return this.#scores.map((score, i) => ({
|
|
123
|
+
score,
|
|
124
|
+
item: this.#items[i]
|
|
125
|
+
})).sort((a, b) => a.score - b.score);
|
|
126
|
+
}
|
|
127
|
+
#swap(i, j) {
|
|
128
|
+
const s = this.#scores;
|
|
129
|
+
const it = this.#items;
|
|
130
|
+
[s[i], s[j]] = [s[j], s[i]];
|
|
131
|
+
[it[i], it[j]] = [it[j], it[i]];
|
|
132
|
+
}
|
|
133
|
+
};
|
|
134
|
+
//#endregion
|
|
135
|
+
//#region src/vector/kmeans.ts
|
|
136
|
+
/** Small deterministic PRNG so segment builds are reproducible. */
|
|
137
|
+
function mulberry32(seed) {
|
|
138
|
+
let a = seed >>> 0;
|
|
139
|
+
return () => {
|
|
140
|
+
a = a + 1831565813 >>> 0;
|
|
141
|
+
let t = a;
|
|
142
|
+
t = Math.imul(t ^ t >>> 15, t | 1);
|
|
143
|
+
t ^= t + Math.imul(t ^ t >>> 7, t | 61);
|
|
144
|
+
return ((t ^ t >>> 14) >>> 0) / 4294967296;
|
|
145
|
+
};
|
|
146
|
+
}
|
|
147
|
+
/** Index of the closest centroid. */
|
|
148
|
+
function nearest(metric, data, offset, centroids, k, d) {
|
|
149
|
+
let best = 0;
|
|
150
|
+
let bestD = Number.POSITIVE_INFINITY;
|
|
151
|
+
const m = metric === "l2" ? "l2" : "dot";
|
|
152
|
+
for (let c = 0; c < k; c++) {
|
|
153
|
+
const dist = distance(m, data, offset, centroids, c * d, d);
|
|
154
|
+
if (dist < bestD) {
|
|
155
|
+
bestD = dist;
|
|
156
|
+
best = c;
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
return best;
|
|
160
|
+
}
|
|
161
|
+
/**
|
|
162
|
+
* k-means++ seeding plus Lloyd iterations on a sample. `data` is n × d, flat.
|
|
163
|
+
* For cosine and dot, centroids are re-normalized (spherical k-means).
|
|
164
|
+
*/
|
|
165
|
+
function kmeans(data, n, d, k, metric, opts = {}) {
|
|
166
|
+
const rand = mulberry32(opts.seed ?? 42);
|
|
167
|
+
k = Math.max(1, Math.min(k, n));
|
|
168
|
+
const sampleSize = Math.min(n, opts.sampleSize ?? Math.min(32 * k, 25e3));
|
|
169
|
+
const idx = new Uint32Array(n);
|
|
170
|
+
for (let i = 0; i < n; i++) idx[i] = i;
|
|
171
|
+
for (let i = 0; i < sampleSize; i++) {
|
|
172
|
+
const j = i + Math.floor(rand() * (n - i));
|
|
173
|
+
[idx[i], idx[j]] = [idx[j], idx[i]];
|
|
174
|
+
}
|
|
175
|
+
const sample = new Float32Array(sampleSize * d);
|
|
176
|
+
for (let i = 0; i < sampleSize; i++) sample.set(data.subarray(idx[i] * d, idx[i] * d + d), i * d);
|
|
177
|
+
const spherical = metric !== "l2";
|
|
178
|
+
const centroids = new Float32Array(k * d);
|
|
179
|
+
centroids.set(sample.subarray(0, d), 0);
|
|
180
|
+
const minD = new Float64Array(sampleSize).fill(Number.POSITIVE_INFINITY);
|
|
181
|
+
for (let c = 1; c < k; c++) {
|
|
182
|
+
let total = 0;
|
|
183
|
+
for (let i = 0; i < sampleSize; i++) {
|
|
184
|
+
const dd = distance("l2", sample, i * d, centroids, (c - 1) * d, d);
|
|
185
|
+
if (dd < minD[i]) minD[i] = dd;
|
|
186
|
+
total += minD[i];
|
|
187
|
+
}
|
|
188
|
+
let r = rand() * total;
|
|
189
|
+
let pick = sampleSize - 1;
|
|
190
|
+
for (let i = 0; i < sampleSize; i++) {
|
|
191
|
+
r -= minD[i];
|
|
192
|
+
if (r <= 0) {
|
|
193
|
+
pick = i;
|
|
194
|
+
break;
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
centroids.set(sample.subarray(pick * d, pick * d + d), c * d);
|
|
198
|
+
}
|
|
199
|
+
const assign = new Uint32Array(sampleSize);
|
|
200
|
+
const counts = new Uint32Array(k);
|
|
201
|
+
const iterations = opts.iterations ?? 10;
|
|
202
|
+
for (let it = 0; it < iterations; it++) {
|
|
203
|
+
let moved = 0;
|
|
204
|
+
for (let i = 0; i < sampleSize; i++) {
|
|
205
|
+
const c = nearest(metric, sample, i * d, centroids, k, d);
|
|
206
|
+
if (c !== assign[i] || it === 0) moved++;
|
|
207
|
+
assign[i] = c;
|
|
208
|
+
}
|
|
209
|
+
const sums = new Float64Array(k * d);
|
|
210
|
+
counts.fill(0);
|
|
211
|
+
for (let i = 0; i < sampleSize; i++) {
|
|
212
|
+
const c = assign[i];
|
|
213
|
+
counts[c]++;
|
|
214
|
+
for (let j = 0; j < d; j++) sums[c * d + j] += sample[i * d + j];
|
|
215
|
+
}
|
|
216
|
+
for (let c = 0; c < k; c++) {
|
|
217
|
+
if (counts[c] === 0) {
|
|
218
|
+
const p = Math.floor(rand() * sampleSize);
|
|
219
|
+
centroids.set(sample.subarray(p * d, p * d + d), c * d);
|
|
220
|
+
continue;
|
|
221
|
+
}
|
|
222
|
+
for (let j = 0; j < d; j++) centroids[c * d + j] = sums[c * d + j] / counts[c];
|
|
223
|
+
}
|
|
224
|
+
if (spherical) for (let c = 0; c < k; c++) centroids.set(normalize(centroids.subarray(c * d, c * d + d)), c * d);
|
|
225
|
+
if (it > 0 && moved === 0) break;
|
|
226
|
+
}
|
|
227
|
+
return centroids;
|
|
228
|
+
}
|
|
229
|
+
//#endregion
|
|
230
|
+
//#region src/vector/segment.ts
|
|
231
|
+
/**
|
|
232
|
+
* An IVF segment as storage-neutral parts. This module does no I/O; a store
|
|
233
|
+
* decides where the parts live.
|
|
234
|
+
*
|
|
235
|
+
* per list: a centroid f32[dims] and a row count
|
|
236
|
+
* per list, the searchable block (little-endian, each section padded to 8 bytes):
|
|
237
|
+
* ids f64[count] | bits u32[count × words] | rnorm f32[count] | cdot f32[count]
|
|
238
|
+
* scales f32[count] | codes i8[count × dims]
|
|
239
|
+
* per list, the float block f32[count × dims] (exact re-rank, lossless merge, read-back)
|
|
240
|
+
*
|
|
241
|
+
* bits = signs of the residual r = x - c (c = the list centroid)
|
|
242
|
+
* rnorm = |r|, cdot = c·r. With them the 1-bit stage estimates the real
|
|
243
|
+
* metric, RaBitQ-style: r_q·r ≈ |r_q| |r| cos(π · hamming / dims).
|
|
244
|
+
*/
|
|
245
|
+
const align8 = (n) => n + 7 & -8;
|
|
246
|
+
function listLayout(count, dims) {
|
|
247
|
+
const w = wordsFor(dims);
|
|
248
|
+
const idsAt = 0;
|
|
249
|
+
const bitsAt = align8(idsAt + 8 * count);
|
|
250
|
+
const rnormAt = align8(bitsAt + 4 * w * count);
|
|
251
|
+
const cdotAt = align8(rnormAt + 4 * count);
|
|
252
|
+
const scalesAt = align8(cdotAt + 4 * count);
|
|
253
|
+
const codesAt = align8(scalesAt + 4 * count);
|
|
254
|
+
return {
|
|
255
|
+
count,
|
|
256
|
+
idsAt,
|
|
257
|
+
bitsAt,
|
|
258
|
+
rnormAt,
|
|
259
|
+
cdotAt,
|
|
260
|
+
scalesAt,
|
|
261
|
+
codesAt,
|
|
262
|
+
length: align8(codesAt + dims * count)
|
|
263
|
+
};
|
|
264
|
+
}
|
|
265
|
+
function defaultNlist(n) {
|
|
266
|
+
if (n < 2048) return 1;
|
|
267
|
+
return Math.max(1, Math.min(1024, Math.round(Math.sqrt(n))));
|
|
268
|
+
}
|
|
269
|
+
function buildSegment(input) {
|
|
270
|
+
const { dims: d, metric, ids, vectors } = input;
|
|
271
|
+
const n = ids.length;
|
|
272
|
+
const nlist = Math.max(1, Math.min(input.nlist ?? defaultNlist(n), Math.max(1, n)));
|
|
273
|
+
let centroids;
|
|
274
|
+
if (nlist === 1) {
|
|
275
|
+
centroids = new Float32Array(d);
|
|
276
|
+
for (let i = 0; i < n; i++) for (let j = 0; j < d; j++) centroids[j] += vectors[i * d + j];
|
|
277
|
+
if (n > 0) for (let j = 0; j < d; j++) centroids[j] /= n;
|
|
278
|
+
} else centroids = kmeans(vectors, n, d, nlist, metric, { seed: input.seed });
|
|
279
|
+
const assign = new Uint32Array(n);
|
|
280
|
+
const counts = new Uint32Array(nlist);
|
|
281
|
+
for (let i = 0; i < n; i++) {
|
|
282
|
+
const c = nlist === 1 ? 0 : nearest(metric, vectors, i * d, centroids, nlist, d);
|
|
283
|
+
assign[i] = c;
|
|
284
|
+
counts[c]++;
|
|
285
|
+
}
|
|
286
|
+
const w = wordsFor(d);
|
|
287
|
+
const layouts = Array.from(counts, (count) => listLayout(count, d));
|
|
288
|
+
const lists = layouts.map((l) => new Uint8Array(l.length));
|
|
289
|
+
const floats = Array.from(counts, (count) => new Uint8Array(4 * count * d));
|
|
290
|
+
const views = layouts.map((l, c) => {
|
|
291
|
+
const buf = lists[c].buffer;
|
|
292
|
+
return {
|
|
293
|
+
ids: new Float64Array(buf, l.idsAt, l.count),
|
|
294
|
+
bits: new Uint32Array(buf, l.bitsAt, l.count * w),
|
|
295
|
+
rnorm: new Float32Array(buf, l.rnormAt, l.count),
|
|
296
|
+
cdot: new Float32Array(buf, l.cdotAt, l.count),
|
|
297
|
+
scales: new Float32Array(buf, l.scalesAt, l.count),
|
|
298
|
+
codes: new Int8Array(buf, l.codesAt, l.count * d),
|
|
299
|
+
floats: new Float32Array(floats[c].buffer, 0, l.count * d)
|
|
300
|
+
};
|
|
301
|
+
});
|
|
302
|
+
const fill = new Uint32Array(nlist);
|
|
303
|
+
for (let i = 0; i < n; i++) {
|
|
304
|
+
const c = assign[i];
|
|
305
|
+
const j = fill[c]++;
|
|
306
|
+
const v = views[c];
|
|
307
|
+
v.ids[j] = ids[i];
|
|
308
|
+
residualBits(vectors, i * d, centroids, c * d, d, v.bits, j * w);
|
|
309
|
+
const [rn, cd] = residualStats(vectors, i * d, centroids, c * d, d);
|
|
310
|
+
v.rnorm[j] = rn;
|
|
311
|
+
v.cdot[j] = cd;
|
|
312
|
+
v.scales[j] = quantizeInt8(vectors, i * d, d, v.codes, j * d);
|
|
313
|
+
v.floats.set(vectors.subarray(i * d, i * d + d), j * d);
|
|
314
|
+
}
|
|
315
|
+
return {
|
|
316
|
+
nlist,
|
|
317
|
+
counts,
|
|
318
|
+
centroids,
|
|
319
|
+
lists,
|
|
320
|
+
floats
|
|
321
|
+
};
|
|
322
|
+
}
|
|
323
|
+
/** [|x - c|, c·(x - c)] */
|
|
324
|
+
function residualStats(x, xo, c, co, d) {
|
|
325
|
+
let nn = 0;
|
|
326
|
+
let cd = 0;
|
|
327
|
+
for (let i = 0; i < d; i++) {
|
|
328
|
+
const r = x[xo + i] - c[co + i];
|
|
329
|
+
nn += r * r;
|
|
330
|
+
cd += c[co + i] * r;
|
|
331
|
+
}
|
|
332
|
+
return [Math.sqrt(nn), cd];
|
|
333
|
+
}
|
|
334
|
+
/** Typed views over a searchable block (copied only when it does not start at offset 0). */
|
|
335
|
+
function parseList(bytes, count, dims) {
|
|
336
|
+
const l = listLayout(count, dims);
|
|
337
|
+
if (bytes.byteLength !== l.length) throw new Error(`vector-index: list block has ${bytes.byteLength} bytes, expected ${l.length}`);
|
|
338
|
+
const buf = bytes.byteOffset === 0 ? bytes.buffer : bytes.slice().buffer;
|
|
339
|
+
const w = wordsFor(dims);
|
|
340
|
+
return {
|
|
341
|
+
ids: new Float64Array(buf, l.idsAt, count),
|
|
342
|
+
bits: new Uint32Array(buf, l.bitsAt, count * w),
|
|
343
|
+
rnorm: new Float32Array(buf, l.rnormAt, count),
|
|
344
|
+
cdot: new Float32Array(buf, l.cdotAt, count),
|
|
345
|
+
scales: new Float32Array(buf, l.scalesAt, count),
|
|
346
|
+
codes: new Int8Array(buf, l.codesAt, count * dims)
|
|
347
|
+
};
|
|
348
|
+
}
|
|
349
|
+
/** The in-memory part of a segment: centroids and list sizes. List blocks are fetched by the caller. */
|
|
350
|
+
var SegmentIndex = class {
|
|
351
|
+
gen;
|
|
352
|
+
dims;
|
|
353
|
+
metric;
|
|
354
|
+
centroids;
|
|
355
|
+
counts;
|
|
356
|
+
constructor(gen, dims, metric, centroids, counts) {
|
|
357
|
+
this.gen = gen;
|
|
358
|
+
this.dims = dims;
|
|
359
|
+
this.metric = metric;
|
|
360
|
+
this.centroids = centroids;
|
|
361
|
+
this.counts = counts;
|
|
362
|
+
}
|
|
363
|
+
get nlist() {
|
|
364
|
+
return this.counts.length;
|
|
365
|
+
}
|
|
366
|
+
/** The `nprobe` non-empty lists whose centroids are closest to the query. */
|
|
367
|
+
probe(query, nprobe) {
|
|
368
|
+
const m = this.metric === "l2" ? "l2" : "dot";
|
|
369
|
+
const top = new TopK(Math.min(nprobe, this.nlist));
|
|
370
|
+
for (let c = 0; c < this.nlist; c++) {
|
|
371
|
+
if (this.counts[c] === 0) continue;
|
|
372
|
+
top.push(distance(m, query, 0, this.centroids, c * this.dims, this.dims), c);
|
|
373
|
+
}
|
|
374
|
+
return top.sorted().map((e) => e.item);
|
|
375
|
+
}
|
|
376
|
+
/**
|
|
377
|
+
* Stage 1: the `limit` rows of a list with the best estimated distance, from
|
|
378
|
+
* residual sign bits plus the stored residual norm and centroid projection.
|
|
379
|
+
*/
|
|
380
|
+
filterList(query, c, data, limit, keep) {
|
|
381
|
+
const d = this.dims;
|
|
382
|
+
const w = wordsFor(d);
|
|
383
|
+
const co = c * d;
|
|
384
|
+
const qb = new Uint32Array(w);
|
|
385
|
+
residualBits(query, 0, this.centroids, co, d, qb, 0);
|
|
386
|
+
const [qn, qcd] = residualStats(query, 0, this.centroids, co, d);
|
|
387
|
+
let cc = 0;
|
|
388
|
+
for (let i = 0; i < d; i++) cc += this.centroids[co + i] * this.centroids[co + i];
|
|
389
|
+
const qc = cc + qcd;
|
|
390
|
+
const angle = Math.PI / d;
|
|
391
|
+
const l2 = this.metric === "l2";
|
|
392
|
+
const top = new TopK(limit);
|
|
393
|
+
for (let r = 0; r < data.ids.length; r++) {
|
|
394
|
+
const id = data.ids[r];
|
|
395
|
+
if (keep && !keep(id)) continue;
|
|
396
|
+
const rr = qn * data.rnorm[r] * Math.cos(angle * hamming(qb, data.bits, r * w, w));
|
|
397
|
+
const est = l2 ? qn * qn + data.rnorm[r] * data.rnorm[r] - 2 * rr : -(qc + data.cdot[r] + rr);
|
|
398
|
+
if (est < top.bound) top.push(est, {
|
|
399
|
+
list: c,
|
|
400
|
+
row: r,
|
|
401
|
+
id
|
|
402
|
+
});
|
|
403
|
+
}
|
|
404
|
+
return top.sorted().map((e) => e.item);
|
|
405
|
+
}
|
|
406
|
+
/** Stage 2: approximate distance from the int8 codes. */
|
|
407
|
+
scoreInt8(query, data, row) {
|
|
408
|
+
return distanceInt8(this.metric, query, data.codes, row * this.dims, data.scales[row], this.dims);
|
|
409
|
+
}
|
|
410
|
+
};
|
|
411
|
+
//#endregion
|
|
412
|
+
//#region src/vector/types.ts
|
|
413
|
+
/** An aligned Float32Array copy of BLOB bytes (views over arbitrary offsets are unsafe). */
|
|
414
|
+
function toFloat32(bytes) {
|
|
415
|
+
const copy = bytes.slice();
|
|
416
|
+
return new Float32Array(copy.buffer, 0, copy.byteLength >> 2);
|
|
417
|
+
}
|
|
418
|
+
function float32Bytes(v) {
|
|
419
|
+
return new Uint8Array(v.buffer, v.byteOffset, v.byteLength).slice();
|
|
420
|
+
}
|
|
421
|
+
//#endregion
|
|
422
|
+
//#region src/vector/sql-segment-store.ts
|
|
423
|
+
/**
|
|
424
|
+
* Largest BLOB written in one row. Durable Object SQLite rejects values over
|
|
425
|
+
* ~2 MB ("string or blob too big"); 1 MiB leaves headroom.
|
|
426
|
+
*/
|
|
427
|
+
const PART_BYTES = 1048576;
|
|
428
|
+
/**
|
|
429
|
+
* Segment rows: one centroid row per list, and each list's searchable and
|
|
430
|
+
* float32 blocks split into parts. Reads go through an LRU cache: a
|
|
431
|
+
* generation is immutable, so cached blocks never go stale.
|
|
432
|
+
*/
|
|
433
|
+
var SqlSegmentStore = class {
|
|
434
|
+
#db;
|
|
435
|
+
#dims;
|
|
436
|
+
#t;
|
|
437
|
+
#cache;
|
|
438
|
+
constructor(db, prefix, dims, cacheBytes = 67108864) {
|
|
439
|
+
this.#db = db;
|
|
440
|
+
this.#dims = dims;
|
|
441
|
+
this.#t = {
|
|
442
|
+
centroids: `${prefix}centroids`,
|
|
443
|
+
seg: `${prefix}seg`,
|
|
444
|
+
f32: `${prefix}f32`
|
|
445
|
+
};
|
|
446
|
+
this.#cache = new Lru(cacheBytes);
|
|
447
|
+
}
|
|
448
|
+
schema() {
|
|
449
|
+
const { centroids, seg, f32 } = this.#t;
|
|
450
|
+
return [
|
|
451
|
+
`CREATE TABLE IF NOT EXISTS ${centroids}(gen INTEGER, list INTEGER, count INTEGER NOT NULL,
|
|
452
|
+
centroid BLOB NOT NULL, PRIMARY KEY (gen, list)) WITHOUT ROWID`,
|
|
453
|
+
`CREATE TABLE IF NOT EXISTS ${seg}(gen INTEGER, list INTEGER, part INTEGER,
|
|
454
|
+
bytes BLOB NOT NULL, PRIMARY KEY (gen, list, part)) WITHOUT ROWID`,
|
|
455
|
+
`CREATE TABLE IF NOT EXISTS ${f32}(gen INTEGER, list INTEGER, part INTEGER,
|
|
456
|
+
bytes BLOB NOT NULL, PRIMARY KEY (gen, list, part)) WITHOUT ROWID`
|
|
457
|
+
];
|
|
458
|
+
}
|
|
459
|
+
/** Writes every row of a built segment. Call inside `inTransaction`. */
|
|
460
|
+
async write(tx, gen, built) {
|
|
461
|
+
const d = this.#dims;
|
|
462
|
+
for (let c = 0; c < built.nlist; c++) {
|
|
463
|
+
await tx.query(`INSERT INTO ${this.#t.centroids}(gen, list, count, centroid) VALUES (?, ?, ?, ?)`, [
|
|
464
|
+
gen,
|
|
465
|
+
c,
|
|
466
|
+
built.counts[c],
|
|
467
|
+
float32Bytes(built.centroids.subarray(c * d, (c + 1) * d))
|
|
468
|
+
]);
|
|
469
|
+
await writeParts(tx, this.#t.seg, gen, c, built.lists[c]);
|
|
470
|
+
await writeParts(tx, this.#t.f32, gen, c, built.floats[c]);
|
|
471
|
+
}
|
|
472
|
+
}
|
|
473
|
+
/** Loads the in-memory part (centroids, list sizes) of a committed segment. */
|
|
474
|
+
async open(ref, metric) {
|
|
475
|
+
const d = this.#dims;
|
|
476
|
+
const rows = await this.#db.query(`SELECT list, count, centroid FROM ${this.#t.centroids} WHERE gen = ? ORDER BY list`, [ref.gen]);
|
|
477
|
+
if (rows.length !== ref.nlist) throw new Error(`vector-index: segment ${ref.gen} has ${rows.length} lists, expected ${ref.nlist}`);
|
|
478
|
+
const centroids = new Float32Array(ref.nlist * d);
|
|
479
|
+
const counts = new Uint32Array(ref.nlist);
|
|
480
|
+
for (const r of rows) {
|
|
481
|
+
const c = Number(r.list);
|
|
482
|
+
centroids.set(toFloat32(r.centroid), c * d);
|
|
483
|
+
counts[c] = Number(r.count);
|
|
484
|
+
}
|
|
485
|
+
return new SegmentIndex(ref.gen, d, metric, centroids, counts);
|
|
486
|
+
}
|
|
487
|
+
/** Searchable blocks of lists `cs`: cached ones from memory, the rest in one query. */
|
|
488
|
+
async lists(seg, cs) {
|
|
489
|
+
const out = /* @__PURE__ */ new Map();
|
|
490
|
+
const missing = [];
|
|
491
|
+
for (const c of cs) {
|
|
492
|
+
const hit = this.#cache.get(`s:${seg.gen}:${c}`);
|
|
493
|
+
if (hit) out.set(c, hit);
|
|
494
|
+
else missing.push(c);
|
|
495
|
+
}
|
|
496
|
+
if (missing.length > 0) {
|
|
497
|
+
const blocks = await readParts(this.#db, this.#t.seg, seg.gen, missing);
|
|
498
|
+
for (const c of missing) {
|
|
499
|
+
const bytes = blocks.get(c) ?? /* @__PURE__ */ new Uint8Array(0);
|
|
500
|
+
const data = parseList(bytes, seg.counts[c], this.#dims);
|
|
501
|
+
this.#cache.set(`s:${seg.gen}:${c}`, data, bytes.byteLength);
|
|
502
|
+
out.set(c, data);
|
|
503
|
+
}
|
|
504
|
+
}
|
|
505
|
+
return cs.map((c) => out.get(c));
|
|
506
|
+
}
|
|
507
|
+
/** Every float32 vector of list `c` (count × dims). */
|
|
508
|
+
async floats(seg, c) {
|
|
509
|
+
const key = `f:${seg.gen}:${c}`;
|
|
510
|
+
const hit = this.#cache.get(key);
|
|
511
|
+
if (hit) return hit;
|
|
512
|
+
const floats = toFloat32((await readParts(this.#db, this.#t.f32, seg.gen, [c])).get(c) ?? /* @__PURE__ */ new Uint8Array(0));
|
|
513
|
+
this.#cache.set(key, floats, floats.byteLength);
|
|
514
|
+
return floats;
|
|
515
|
+
}
|
|
516
|
+
/** Deletes the rows of `gens`. Call inside `inTransaction`. */
|
|
517
|
+
async drop(tx, gens) {
|
|
518
|
+
const json = JSON.stringify(gens);
|
|
519
|
+
for (const table of Object.values(this.#t)) await tx.query(`DELETE FROM ${table} WHERE gen IN (SELECT value FROM json_each(?))`, [json]);
|
|
520
|
+
for (const gen of gens) this.#cache.deletePrefix(`s:${gen}:`, `f:${gen}:`);
|
|
521
|
+
}
|
|
522
|
+
/** Deletes rows of every generation not in `live` (left by a crash before a reap). */
|
|
523
|
+
async sweep(tx, live) {
|
|
524
|
+
const json = JSON.stringify(live);
|
|
525
|
+
for (const table of Object.values(this.#t)) await tx.query(`DELETE FROM ${table} WHERE gen NOT IN (SELECT value FROM json_each(?))`, [json]);
|
|
526
|
+
}
|
|
527
|
+
};
|
|
528
|
+
async function writeParts(tx, table, gen, list, bytes) {
|
|
529
|
+
for (let part = 0, at = 0; at < bytes.byteLength; part++, at += PART_BYTES) await tx.query(`INSERT INTO ${table}(gen, list, part, bytes) VALUES (?, ?, ?, ?)`, [
|
|
530
|
+
gen,
|
|
531
|
+
list,
|
|
532
|
+
part,
|
|
533
|
+
bytes.slice(at, at + PART_BYTES)
|
|
534
|
+
]);
|
|
535
|
+
}
|
|
536
|
+
/** The joined parts of each list in `lists`, as fresh arrays starting at offset 0. */
|
|
537
|
+
async function readParts(db, table, gen, lists) {
|
|
538
|
+
const rows = await db.query(`SELECT list, bytes FROM ${table}
|
|
539
|
+
WHERE gen = ? AND list IN (SELECT value FROM json_each(?)) ORDER BY list, part`, [gen, JSON.stringify(lists)]);
|
|
540
|
+
const parts = /* @__PURE__ */ new Map();
|
|
541
|
+
for (const r of rows) {
|
|
542
|
+
const list = Number(r.list);
|
|
543
|
+
const acc = parts.get(list) ?? [];
|
|
544
|
+
acc.push(r.bytes);
|
|
545
|
+
parts.set(list, acc);
|
|
546
|
+
}
|
|
547
|
+
const out = /* @__PURE__ */ new Map();
|
|
548
|
+
for (const [list, ps] of parts) {
|
|
549
|
+
const joined = new Uint8Array(ps.reduce((n, p) => n + p.byteLength, 0));
|
|
550
|
+
let at = 0;
|
|
551
|
+
for (const p of ps) {
|
|
552
|
+
joined.set(p, at);
|
|
553
|
+
at += p.byteLength;
|
|
554
|
+
}
|
|
555
|
+
out.set(list, joined);
|
|
556
|
+
}
|
|
557
|
+
return out;
|
|
558
|
+
}
|
|
559
|
+
/** Byte-budgeted LRU; Map order is LRU order (re-inserted on every hit). */
|
|
560
|
+
var Lru = class {
|
|
561
|
+
#max;
|
|
562
|
+
#map = /* @__PURE__ */ new Map();
|
|
563
|
+
#bytes = 0;
|
|
564
|
+
constructor(maxBytes) {
|
|
565
|
+
this.#max = maxBytes;
|
|
566
|
+
}
|
|
567
|
+
get(key) {
|
|
568
|
+
const e = this.#map.get(key);
|
|
569
|
+
if (!e) return void 0;
|
|
570
|
+
this.#map.delete(key);
|
|
571
|
+
this.#map.set(key, e);
|
|
572
|
+
return e.value;
|
|
573
|
+
}
|
|
574
|
+
set(key, value, size) {
|
|
575
|
+
const old = this.#map.get(key);
|
|
576
|
+
if (old) {
|
|
577
|
+
this.#map.delete(key);
|
|
578
|
+
this.#bytes -= old.size;
|
|
579
|
+
}
|
|
580
|
+
this.#map.set(key, {
|
|
581
|
+
value,
|
|
582
|
+
size
|
|
583
|
+
});
|
|
584
|
+
this.#bytes += size;
|
|
585
|
+
for (const [k, e] of this.#map) {
|
|
586
|
+
if (this.#bytes <= this.#max) break;
|
|
587
|
+
this.#map.delete(k);
|
|
588
|
+
this.#bytes -= e.size;
|
|
589
|
+
}
|
|
590
|
+
}
|
|
591
|
+
deletePrefix(...prefixes) {
|
|
592
|
+
for (const [k, e] of this.#map) if (prefixes.some((p) => k.startsWith(p))) {
|
|
593
|
+
this.#map.delete(k);
|
|
594
|
+
this.#bytes -= e.size;
|
|
595
|
+
}
|
|
596
|
+
}
|
|
597
|
+
};
|
|
598
|
+
//#endregion
|
|
599
|
+
//#region src/vector/vector-index.ts
|
|
600
|
+
/** Ids per lookup (bound as one JSON parameter). */
|
|
601
|
+
const VALIDATE_BATCH = 2e3;
|
|
602
|
+
/** Upserted rows per transaction. */
|
|
603
|
+
const WRITE_BATCH = 200;
|
|
604
|
+
/**
|
|
605
|
+
* An LSM-style vector index over a `Db`.
|
|
606
|
+
*
|
|
607
|
+
* - The mutable tail lives in `{p}tail`, mirrored in memory and searched exactly.
|
|
608
|
+
* - `compact()` seals the tail into an immutable IVF segment (1-bit residual
|
|
609
|
+
* filter → int8 re-rank → float32 re-rank on `exact`), written as rows in the
|
|
610
|
+
* same transaction that moves the ids out of the tail.
|
|
611
|
+
* - `{p}ids(id, gen)` says which generation holds the live copy of each id
|
|
612
|
+
* (0 = tail). A segment hit counts only if its generation matches, so deletes
|
|
613
|
+
* and overwrites never touch segment rows. `merge()` rewrites all segments
|
|
614
|
+
* into one, dropping dead rows.
|
|
615
|
+
*
|
|
616
|
+
* One writer per database is assumed (a Durable Object, a worker, one tab);
|
|
617
|
+
* within an instance, writes are serialized.
|
|
618
|
+
*/
|
|
619
|
+
var VectorIndex = class {
|
|
620
|
+
dims;
|
|
621
|
+
metric;
|
|
622
|
+
/** `{prefix}ids`: its `id` column holds exactly the live ids. Callers may join it in SQL. */
|
|
623
|
+
idTable;
|
|
624
|
+
#db;
|
|
625
|
+
#store;
|
|
626
|
+
#nlist;
|
|
627
|
+
#autoCompactAt;
|
|
628
|
+
#t;
|
|
629
|
+
#state = {
|
|
630
|
+
seq: 0,
|
|
631
|
+
nextGen: 1,
|
|
632
|
+
segments: []
|
|
633
|
+
};
|
|
634
|
+
#tail = /* @__PURE__ */ new Map();
|
|
635
|
+
#segments = [];
|
|
636
|
+
#refs = /* @__PURE__ */ new Map();
|
|
637
|
+
#retired = [];
|
|
638
|
+
#queue = Promise.resolve();
|
|
639
|
+
#maintaining = false;
|
|
640
|
+
#ready = false;
|
|
641
|
+
/** Bumped before and after each commit that changes the segment list: odd while one runs. */
|
|
642
|
+
#epoch = 0;
|
|
643
|
+
constructor(opts) {
|
|
644
|
+
if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(opts.prefix)) throw new Error(`vector-index: bad prefix ${opts.prefix}`);
|
|
645
|
+
if (!Number.isInteger(opts.dims) || opts.dims < 1) throw new Error("vector-index: dims must be a positive integer");
|
|
646
|
+
this.dims = opts.dims;
|
|
647
|
+
this.metric = opts.metric ?? "cosine";
|
|
648
|
+
this.#db = opts.db;
|
|
649
|
+
this.#store = new SqlSegmentStore(opts.db, opts.prefix, opts.dims, opts.cacheBytes);
|
|
650
|
+
this.#nlist = opts.nlist;
|
|
651
|
+
this.#autoCompactAt = opts.autoCompactAt ?? 4096;
|
|
652
|
+
const p = opts.prefix;
|
|
653
|
+
this.#t = {
|
|
654
|
+
meta: `${p}meta`,
|
|
655
|
+
ids: `${p}ids`,
|
|
656
|
+
tail: `${p}tail`
|
|
657
|
+
};
|
|
658
|
+
this.idTable = this.#t.ids;
|
|
659
|
+
}
|
|
660
|
+
/** Creates tables if missing, loads state and sweeps rows of crashed maintenance. */
|
|
661
|
+
async init() {
|
|
662
|
+
const { meta, ids, tail } = this.#t;
|
|
663
|
+
for (const s of [
|
|
664
|
+
`CREATE TABLE IF NOT EXISTS ${meta}(k TEXT PRIMARY KEY, v TEXT NOT NULL)`,
|
|
665
|
+
`CREATE TABLE IF NOT EXISTS ${ids}(id INTEGER PRIMARY KEY, gen INTEGER NOT NULL)`,
|
|
666
|
+
`CREATE INDEX IF NOT EXISTS ${ids}_gen ON ${ids}(gen)`,
|
|
667
|
+
`CREATE TABLE IF NOT EXISTS ${tail}(id INTEGER PRIMARY KEY, seq INTEGER NOT NULL, vec BLOB NOT NULL)`,
|
|
668
|
+
`CREATE INDEX IF NOT EXISTS ${tail}_seq ON ${tail}(seq)`,
|
|
669
|
+
...this.#store.schema()
|
|
670
|
+
]) await this.#db.exec(s);
|
|
671
|
+
const config = JSON.stringify({
|
|
672
|
+
dims: this.dims,
|
|
673
|
+
metric: this.metric
|
|
674
|
+
});
|
|
675
|
+
await this.#db.query(`INSERT INTO ${meta}(k, v) VALUES ('config', ?) ON CONFLICT(k) DO NOTHING`, [config]);
|
|
676
|
+
const [stored] = await this.#db.query(`SELECT v FROM ${meta} WHERE k = 'config'`);
|
|
677
|
+
if (stored?.v !== config) throw new Error(`vector-index: tables were created with ${stored?.v}, not ${config}`);
|
|
678
|
+
await this.refresh();
|
|
679
|
+
const live = this.#state.segments.map((s) => s.gen);
|
|
680
|
+
await inTransaction(this.#db, (tx) => this.#store.sweep(tx, live));
|
|
681
|
+
this.#ready = true;
|
|
682
|
+
}
|
|
683
|
+
/** Reloads state, tail and segments from storage (e.g. after another writer changed them). */
|
|
684
|
+
async refresh() {
|
|
685
|
+
const [row] = await this.#db.query(`SELECT v FROM ${this.#t.meta} WHERE k = 'state'`);
|
|
686
|
+
const state = row ? JSON.parse(row.v) : {
|
|
687
|
+
seq: 0,
|
|
688
|
+
nextGen: 1,
|
|
689
|
+
segments: []
|
|
690
|
+
};
|
|
691
|
+
const tail = /* @__PURE__ */ new Map();
|
|
692
|
+
const rows = await this.#db.query(`SELECT id, seq, vec FROM ${this.#t.tail}`);
|
|
693
|
+
for (const r of rows) tail.set(Number(r.id), {
|
|
694
|
+
seq: Number(r.seq),
|
|
695
|
+
vector: toFloat32(r.vec)
|
|
696
|
+
});
|
|
697
|
+
const known = new Map(this.#segments.map((s) => [s.gen, s]));
|
|
698
|
+
const segments = await Promise.all(state.segments.map((s) => known.get(s.gen) ?? this.#store.open(s, this.metric)));
|
|
699
|
+
this.#state = state;
|
|
700
|
+
this.#tail = tail;
|
|
701
|
+
this.#segments = segments;
|
|
702
|
+
}
|
|
703
|
+
get stats() {
|
|
704
|
+
return {
|
|
705
|
+
tail: this.#tail.size,
|
|
706
|
+
segments: this.#state.segments.map((s) => ({ ...s })),
|
|
707
|
+
seq: this.#state.seq
|
|
708
|
+
};
|
|
709
|
+
}
|
|
710
|
+
async upsert(items) {
|
|
711
|
+
this.#assertReady();
|
|
712
|
+
const prepared = items.map((it) => {
|
|
713
|
+
assertId(it.id);
|
|
714
|
+
return {
|
|
715
|
+
id: it.id,
|
|
716
|
+
vector: prepare(it.vector, this.dims, this.metric)
|
|
717
|
+
};
|
|
718
|
+
});
|
|
719
|
+
const { tail, ids } = this.#t;
|
|
720
|
+
for (let i = 0; i < prepared.length; i += WRITE_BATCH) {
|
|
721
|
+
const batch = prepared.slice(i, i + WRITE_BATCH);
|
|
722
|
+
await this.#exclusive(async () => {
|
|
723
|
+
const seq = this.#state.seq + 1;
|
|
724
|
+
const next = {
|
|
725
|
+
...this.#state,
|
|
726
|
+
seq
|
|
727
|
+
};
|
|
728
|
+
await inTransaction(this.#db, async (tx) => {
|
|
729
|
+
for (const { id, vector } of batch) {
|
|
730
|
+
await tx.query(`INSERT INTO ${tail}(id, seq, vec) VALUES (?, ?, ?)
|
|
731
|
+
ON CONFLICT(id) DO UPDATE SET seq = excluded.seq, vec = excluded.vec`, [
|
|
732
|
+
id,
|
|
733
|
+
seq,
|
|
734
|
+
float32Bytes(vector)
|
|
735
|
+
]);
|
|
736
|
+
await tx.query(`INSERT INTO ${ids}(id, gen) VALUES (?, 0) ON CONFLICT(id) DO UPDATE SET gen = 0`, [id]);
|
|
737
|
+
}
|
|
738
|
+
await this.#saveState(tx, next);
|
|
739
|
+
});
|
|
740
|
+
this.#state = next;
|
|
741
|
+
for (const { id, vector } of batch) this.#tail.set(id, {
|
|
742
|
+
seq,
|
|
743
|
+
vector
|
|
744
|
+
});
|
|
745
|
+
});
|
|
746
|
+
if (this.#tail.size >= this.#autoCompactAt && !this.#maintaining) await this.compact();
|
|
747
|
+
}
|
|
748
|
+
}
|
|
749
|
+
async delete(ids) {
|
|
750
|
+
this.#assertReady();
|
|
751
|
+
ids.forEach(assertId);
|
|
752
|
+
await this.#exclusive(async () => {
|
|
753
|
+
for (let i = 0; i < ids.length; i += VALIDATE_BATCH) {
|
|
754
|
+
const chunk = ids.slice(i, i + VALIDATE_BATCH);
|
|
755
|
+
const json = JSON.stringify(chunk);
|
|
756
|
+
await inTransaction(this.#db, async (tx) => {
|
|
757
|
+
await tx.query(`DELETE FROM ${this.#t.tail} WHERE id IN (SELECT value FROM json_each(?))`, [json]);
|
|
758
|
+
await tx.query(`DELETE FROM ${this.#t.ids} WHERE id IN (SELECT value FROM json_each(?))`, [json]);
|
|
759
|
+
});
|
|
760
|
+
for (const id of chunk) this.#tail.delete(id);
|
|
761
|
+
}
|
|
762
|
+
});
|
|
763
|
+
}
|
|
764
|
+
async search(query, opts = {}) {
|
|
765
|
+
this.#assertReady();
|
|
766
|
+
const k = opts.k ?? 10;
|
|
767
|
+
const nprobe = opts.nprobe ?? 8;
|
|
768
|
+
const perList = k * (opts.oversample ?? 8);
|
|
769
|
+
const q = prepare(query, this.dims, this.metric);
|
|
770
|
+
const d = this.dims;
|
|
771
|
+
const filter = opts.filter;
|
|
772
|
+
return this.#read(async (segments) => {
|
|
773
|
+
const tailTop = new TopK(k);
|
|
774
|
+
for (const [id, { vector }] of this.#tail) {
|
|
775
|
+
if (filter && !filter(id)) continue;
|
|
776
|
+
tailTop.push(distance(this.metric, q, 0, vector, 0, d), id);
|
|
777
|
+
}
|
|
778
|
+
const hits = [];
|
|
779
|
+
const keep = (id) => !this.#tail.has(id) && (!filter || filter(id));
|
|
780
|
+
await Promise.all(segments.map(async (seg) => {
|
|
781
|
+
const lists = seg.probe(q, nprobe);
|
|
782
|
+
const datas = await this.#store.lists(seg, lists);
|
|
783
|
+
opts.signal?.throwIfAborted();
|
|
784
|
+
lists.forEach((c, i) => {
|
|
785
|
+
const data = datas[i];
|
|
786
|
+
for (const cand of seg.filterList(q, c, data, perList, keep)) hits.push({
|
|
787
|
+
...cand,
|
|
788
|
+
seg,
|
|
789
|
+
data
|
|
790
|
+
});
|
|
791
|
+
});
|
|
792
|
+
}));
|
|
793
|
+
const live = await this.#generations(hits.map((h) => h.id));
|
|
794
|
+
const segTop = new TopK(opts.exact ? k * 4 : k);
|
|
795
|
+
for (const h of hits) {
|
|
796
|
+
if (live.get(h.id) !== h.seg.gen) continue;
|
|
797
|
+
segTop.push(h.seg.scoreInt8(q, h.data, h.row), h);
|
|
798
|
+
}
|
|
799
|
+
let segResults = segTop.sorted().map((e) => ({
|
|
800
|
+
id: e.item.id,
|
|
801
|
+
distance: e.score,
|
|
802
|
+
hit: e.item
|
|
803
|
+
}));
|
|
804
|
+
if (opts.exact) segResults = await Promise.all(segResults.map(async (r) => {
|
|
805
|
+
const v = (await this.#store.floats(r.hit.seg, r.hit.list)).subarray(r.hit.row * d, (r.hit.row + 1) * d);
|
|
806
|
+
return {
|
|
807
|
+
...r,
|
|
808
|
+
distance: distance(this.metric, q, 0, v, 0, d)
|
|
809
|
+
};
|
|
810
|
+
}));
|
|
811
|
+
const final = new TopK(k);
|
|
812
|
+
for (const r of segResults) final.push(r.distance, r.id);
|
|
813
|
+
for (const e of tailTop.sorted()) final.push(e.score, e.item);
|
|
814
|
+
return final.sorted().map((e) => ({
|
|
815
|
+
id: e.item,
|
|
816
|
+
distance: e.score
|
|
817
|
+
}));
|
|
818
|
+
});
|
|
819
|
+
}
|
|
820
|
+
/** The stored vectors of the live `ids` (normalised for cosine); unknown or deleted ids are absent. */
|
|
821
|
+
async getVectors(ids) {
|
|
822
|
+
this.#assertReady();
|
|
823
|
+
ids.forEach(assertId);
|
|
824
|
+
return this.#read(async (segments) => {
|
|
825
|
+
const out = /* @__PURE__ */ new Map();
|
|
826
|
+
const gens = await this.#generations(ids);
|
|
827
|
+
const wanted = /* @__PURE__ */ new Map();
|
|
828
|
+
for (const [id, gen] of gens) {
|
|
829
|
+
if (gen === 0) {
|
|
830
|
+
const entry = this.#tail.get(id);
|
|
831
|
+
if (entry) out.set(id, entry.vector.slice());
|
|
832
|
+
continue;
|
|
833
|
+
}
|
|
834
|
+
const set = wanted.get(gen) ?? /* @__PURE__ */ new Set();
|
|
835
|
+
set.add(id);
|
|
836
|
+
wanted.set(gen, set);
|
|
837
|
+
}
|
|
838
|
+
for (const seg of segments) {
|
|
839
|
+
const set = wanted.get(seg.gen);
|
|
840
|
+
if (!set) continue;
|
|
841
|
+
for (let c = 0; c < seg.nlist && set.size > 0; c++) {
|
|
842
|
+
if (seg.counts[c] === 0) continue;
|
|
843
|
+
const [data] = await this.#store.lists(seg, [c]);
|
|
844
|
+
let floats = null;
|
|
845
|
+
for (let r = 0; r < data.ids.length; r++) {
|
|
846
|
+
const id = data.ids[r];
|
|
847
|
+
if (!set.has(id)) continue;
|
|
848
|
+
floats ??= await this.#store.floats(seg, c);
|
|
849
|
+
out.set(id, floats.slice(r * this.dims, (r + 1) * this.dims));
|
|
850
|
+
set.delete(id);
|
|
851
|
+
}
|
|
852
|
+
}
|
|
853
|
+
}
|
|
854
|
+
return out;
|
|
855
|
+
});
|
|
856
|
+
}
|
|
857
|
+
/** Seals the current tail into a new segment. Returns the number of vectors sealed. */
|
|
858
|
+
async compact() {
|
|
859
|
+
this.#assertReady();
|
|
860
|
+
return this.#maintenance(async () => {
|
|
861
|
+
const snapshot = await this.#exclusive(async () => ({
|
|
862
|
+
maxSeq: this.#state.seq,
|
|
863
|
+
entries: [...this.#tail.entries()]
|
|
864
|
+
}));
|
|
865
|
+
if (snapshot.entries.length === 0) return 0;
|
|
866
|
+
const n = snapshot.entries.length;
|
|
867
|
+
const ids = new Float64Array(n);
|
|
868
|
+
const vectors = new Float32Array(n * this.dims);
|
|
869
|
+
snapshot.entries.forEach(([id, e], i) => {
|
|
870
|
+
ids[i] = id;
|
|
871
|
+
vectors.set(e.vector, i * this.dims);
|
|
872
|
+
});
|
|
873
|
+
const built = this.#build(ids, vectors);
|
|
874
|
+
await this.#exclusive(() => this.#swapSegments(async () => {
|
|
875
|
+
const ref = this.#refOf(built, n);
|
|
876
|
+
const next = {
|
|
877
|
+
...this.#state,
|
|
878
|
+
nextGen: ref.gen + 1,
|
|
879
|
+
segments: [...this.#state.segments, ref]
|
|
880
|
+
};
|
|
881
|
+
const { ids: idsT, tail } = this.#t;
|
|
882
|
+
await inTransaction(this.#db, async (tx) => {
|
|
883
|
+
await this.#store.write(tx, ref.gen, built);
|
|
884
|
+
await tx.query(`UPDATE ${idsT} SET gen = ? WHERE gen = 0
|
|
885
|
+
AND id IN (SELECT id FROM ${tail} WHERE seq <= ?)`, [ref.gen, snapshot.maxSeq]);
|
|
886
|
+
await tx.query(`DELETE FROM ${tail} WHERE seq <= ?`, [snapshot.maxSeq]);
|
|
887
|
+
await this.#saveState(tx, next);
|
|
888
|
+
});
|
|
889
|
+
this.#state = next;
|
|
890
|
+
for (const [id, e] of this.#tail) if (e.seq <= snapshot.maxSeq) this.#tail.delete(id);
|
|
891
|
+
this.#segments = [...this.#segments, this.#segmentOf(ref, built)];
|
|
892
|
+
}));
|
|
893
|
+
return n;
|
|
894
|
+
});
|
|
895
|
+
}
|
|
896
|
+
/**
|
|
897
|
+
* Rewrites all segments into one (retraining the IVF lists) and drops dead
|
|
898
|
+
* rows. Holds all live segment vectors in memory while it runs.
|
|
899
|
+
*/
|
|
900
|
+
async merge() {
|
|
901
|
+
this.#assertReady();
|
|
902
|
+
return this.#maintenance(async () => {
|
|
903
|
+
const old = this.#segments;
|
|
904
|
+
if (old.length === 0) return 0;
|
|
905
|
+
const oldGens = old.map((s) => s.gen);
|
|
906
|
+
const idList = [];
|
|
907
|
+
const chunks = [];
|
|
908
|
+
for (const seg of old) for (let c = 0; c < seg.nlist; c++) {
|
|
909
|
+
if (seg.counts[c] === 0) continue;
|
|
910
|
+
const [data] = await this.#store.lists(seg, [c]);
|
|
911
|
+
const floats = await this.#store.floats(seg, c);
|
|
912
|
+
const live = await this.#generations(Array.from(data.ids));
|
|
913
|
+
for (let r = 0; r < data.ids.length; r++) {
|
|
914
|
+
const id = data.ids[r];
|
|
915
|
+
if (live.get(id) !== seg.gen) continue;
|
|
916
|
+
idList.push(id);
|
|
917
|
+
chunks.push(floats.subarray(r * this.dims, (r + 1) * this.dims));
|
|
918
|
+
}
|
|
919
|
+
}
|
|
920
|
+
const n = idList.length;
|
|
921
|
+
const vectors = new Float32Array(n * this.dims);
|
|
922
|
+
chunks.forEach((v, i) => {
|
|
923
|
+
vectors.set(v, i * this.dims);
|
|
924
|
+
});
|
|
925
|
+
const built = n > 0 ? this.#build(Float64Array.from(idList), vectors) : null;
|
|
926
|
+
await this.#exclusive(() => this.#swapSegments(async () => {
|
|
927
|
+
const ref = built ? this.#refOf(built, n) : null;
|
|
928
|
+
const kept = this.#state.segments.filter((s) => !oldGens.includes(s.gen));
|
|
929
|
+
const next = {
|
|
930
|
+
...this.#state,
|
|
931
|
+
nextGen: ref ? ref.gen + 1 : this.#state.nextGen,
|
|
932
|
+
segments: ref ? [...kept, ref] : kept
|
|
933
|
+
};
|
|
934
|
+
await inTransaction(this.#db, async (tx) => {
|
|
935
|
+
if (ref && built) {
|
|
936
|
+
await this.#store.write(tx, ref.gen, built);
|
|
937
|
+
await tx.query(`UPDATE ${this.#t.ids} SET gen = ? WHERE gen IN (SELECT value FROM json_each(?))`, [ref.gen, JSON.stringify(oldGens)]);
|
|
938
|
+
}
|
|
939
|
+
await this.#saveState(tx, next);
|
|
940
|
+
});
|
|
941
|
+
this.#state = next;
|
|
942
|
+
this.#segments = [...this.#segments.filter((s) => !oldGens.includes(s.gen)), ...ref && built ? [this.#segmentOf(ref, built)] : []];
|
|
943
|
+
this.#retired.push(...old);
|
|
944
|
+
}));
|
|
945
|
+
await this.#reap();
|
|
946
|
+
return n;
|
|
947
|
+
});
|
|
948
|
+
}
|
|
949
|
+
/** compact() then merge(). */
|
|
950
|
+
async optimize() {
|
|
951
|
+
await this.compact();
|
|
952
|
+
await this.merge();
|
|
953
|
+
}
|
|
954
|
+
#build(ids, vectors) {
|
|
955
|
+
return buildSegment({
|
|
956
|
+
dims: this.dims,
|
|
957
|
+
metric: this.metric,
|
|
958
|
+
ids,
|
|
959
|
+
vectors,
|
|
960
|
+
nlist: this.#nlist?.(ids.length)
|
|
961
|
+
});
|
|
962
|
+
}
|
|
963
|
+
#refOf(built, count) {
|
|
964
|
+
return {
|
|
965
|
+
gen: this.#state.nextGen,
|
|
966
|
+
count,
|
|
967
|
+
nlist: built.nlist
|
|
968
|
+
};
|
|
969
|
+
}
|
|
970
|
+
#segmentOf(ref, built) {
|
|
971
|
+
return new SegmentIndex(ref.gen, this.dims, this.metric, built.centroids, built.counts);
|
|
972
|
+
}
|
|
973
|
+
async #generations(ids) {
|
|
974
|
+
const out = /* @__PURE__ */ new Map();
|
|
975
|
+
const unique = [...new Set(ids)];
|
|
976
|
+
for (let i = 0; i < unique.length; i += VALIDATE_BATCH) {
|
|
977
|
+
const rows = await this.#db.query(`SELECT id, gen FROM ${this.#t.ids} WHERE id IN (SELECT value FROM json_each(?))`, [JSON.stringify(unique.slice(i, i + VALIDATE_BATCH))]);
|
|
978
|
+
for (const r of rows) out.set(Number(r.id), Number(r.gen));
|
|
979
|
+
}
|
|
980
|
+
return out;
|
|
981
|
+
}
|
|
982
|
+
async #saveState(tx, state) {
|
|
983
|
+
await tx.query(`INSERT INTO ${this.#t.meta}(k, v) VALUES ('state', ?)
|
|
984
|
+
ON CONFLICT(k) DO UPDATE SET v = excluded.v`, [JSON.stringify(state)]);
|
|
985
|
+
}
|
|
986
|
+
/** Deletes the rows of retired segments once no search is reading them. */
|
|
987
|
+
async #reap() {
|
|
988
|
+
const ready = this.#retired.filter((s) => (this.#refs.get(s) ?? 0) === 0);
|
|
989
|
+
if (ready.length === 0) return;
|
|
990
|
+
this.#retired = this.#retired.filter((s) => !ready.includes(s));
|
|
991
|
+
for (const s of ready) this.#refs.delete(s);
|
|
992
|
+
const gens = ready.map((s) => s.gen);
|
|
993
|
+
await inTransaction(this.#db, (tx) => this.#store.drop(tx, gens));
|
|
994
|
+
}
|
|
995
|
+
/**
|
|
996
|
+
* Runs `read` over a snapshot of the segments, held against reaping. A read
|
|
997
|
+
* whose liveness lookup straddles a compact or merge commit may not match its
|
|
998
|
+
* snapshot, so it runs again on the new one; the third attempt stands.
|
|
999
|
+
*/
|
|
1000
|
+
async #read(read) {
|
|
1001
|
+
for (let attempt = 1;; attempt++) {
|
|
1002
|
+
const epoch = this.#epoch;
|
|
1003
|
+
const segments = this.#segments;
|
|
1004
|
+
for (const s of segments) this.#refs.set(s, (this.#refs.get(s) ?? 0) + 1);
|
|
1005
|
+
try {
|
|
1006
|
+
const result = await read(segments);
|
|
1007
|
+
if (attempt === 3 || epoch % 2 === 0 && epoch === this.#epoch) return result;
|
|
1008
|
+
} finally {
|
|
1009
|
+
for (const s of segments) this.#refs.set(s, (this.#refs.get(s) ?? 1) - 1);
|
|
1010
|
+
this.#reap().catch(() => {});
|
|
1011
|
+
}
|
|
1012
|
+
}
|
|
1013
|
+
}
|
|
1014
|
+
/** Commits a segment-list change; readers that overlap it retry (see `#read`). */
|
|
1015
|
+
async #swapSegments(fn) {
|
|
1016
|
+
this.#epoch++;
|
|
1017
|
+
try {
|
|
1018
|
+
await fn();
|
|
1019
|
+
} finally {
|
|
1020
|
+
this.#epoch++;
|
|
1021
|
+
}
|
|
1022
|
+
}
|
|
1023
|
+
#exclusive(fn) {
|
|
1024
|
+
const run = this.#queue.then(fn, fn);
|
|
1025
|
+
this.#queue = run.catch(() => {});
|
|
1026
|
+
return run;
|
|
1027
|
+
}
|
|
1028
|
+
async #maintenance(fn) {
|
|
1029
|
+
if (this.#maintaining) throw new Error("vector-index: compact or merge already running");
|
|
1030
|
+
this.#maintaining = true;
|
|
1031
|
+
try {
|
|
1032
|
+
return await fn();
|
|
1033
|
+
} finally {
|
|
1034
|
+
this.#maintaining = false;
|
|
1035
|
+
}
|
|
1036
|
+
}
|
|
1037
|
+
#assertReady() {
|
|
1038
|
+
if (!this.#ready) throw new Error("vector-index: call init() first");
|
|
1039
|
+
}
|
|
1040
|
+
};
|
|
1041
|
+
function assertId(id) {
|
|
1042
|
+
if (!Number.isSafeInteger(id)) throw new Error(`vector-index: id must be a safe integer, got ${id}`);
|
|
1043
|
+
}
|
|
1044
|
+
/** Drops every table of the index under `prefix`, in one transaction. Needs no dims or metric. */
|
|
1045
|
+
async function dropVectorIndex(db, prefix) {
|
|
1046
|
+
if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(prefix)) throw new Error(`vector-index: bad prefix ${prefix}`);
|
|
1047
|
+
await inTransaction(db, async (tx) => {
|
|
1048
|
+
for (const t of [
|
|
1049
|
+
"meta",
|
|
1050
|
+
"ids",
|
|
1051
|
+
"tail",
|
|
1052
|
+
"centroids",
|
|
1053
|
+
"seg",
|
|
1054
|
+
"f32"
|
|
1055
|
+
]) await tx.exec(`DROP TABLE IF EXISTS ${prefix}${t}`);
|
|
1056
|
+
});
|
|
1057
|
+
}
|
|
1058
|
+
//#endregion
|
|
1059
|
+
export { VectorIndex, dropVectorIndex };
|
|
1060
|
+
|
|
1061
|
+
//# sourceMappingURL=vector.mjs.map
|