chloedb 0.0.1 → 0.3.5

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/index.d.ts ADDED
@@ -0,0 +1,235 @@
1
+ import { Input, Params, Plan, Result, Row, Schema, Searchable, Value } from "./common.js";
2
+
3
+ export { Field, Input, LogOptions, ExportOptions, Params, Plan, Result, Row, Schema, SearchOptions, ChloeDBError, StrataError, ErrorCode, errorCode, BadRequestError, UnauthorizedError, NotFoundError, ConflictError, PartialWriteError, BusyError, OverloadedError, DeadlineError, UnavailableError, ReadAfter, Value } from "./common.js";
4
+ export { Client, ClientOptions, Session, Written, connect } from "./client.js";
5
+
6
+ type Path = string | URL;
7
+ /** A schema: an object, JSON text, or the path of a JSON file. */
8
+ type SchemaInput = Schema | string;
9
+ type Tables = string | Iterable<string>;
10
+ type Bytes = Uint8Array | ArrayBuffer | ArrayBufferView;
11
+
12
+ export interface OpenOptions {
13
+ /** Where embedded fields' models are ($CHLOEDB_MODELS or
14
+ * ~/.local/share/strata/models by default). */
15
+ models?: Path;
16
+ /** Cores vector indexes build on and each query searches segments on
17
+ * (default: every core). */
18
+ threads?: number;
19
+ /** The deadline of each of its queries, in ms (see `setLimits`). */
20
+ timeoutMs?: number;
21
+ /** The memory budget its queries share, in bytes (see `setLimits`). */
22
+ memory?: number;
23
+ }
24
+
25
+ /** A query's limits. */
26
+ export interface QueryLimits {
27
+ /** Its deadline in ms: past it the query stops and rejects with
28
+ * DeadlineError (none or 0: the database's). */
29
+ timeoutMs?: number;
30
+ /** A memory budget of its own, in bytes, past which it rejects with a
31
+ * ChloeDBError of code "memory" (0: none; none: the database's). */
32
+ memory?: number;
33
+ /** Stops it when it aborts: it rejects with the signal's reason. */
34
+ signal?: AbortSignal;
35
+ }
36
+
37
+ export interface ReadOnlyOption {
38
+ /** Open it to read while another process writes it: it sees each of
39
+ * the writer's commits, and every write fails. Without it only one
40
+ * process may have the database open. */
41
+ readOnly?: boolean;
42
+ }
43
+
44
+ export interface CreateOptions extends OpenOptions {
45
+ /** Keep it as a directory of segment files instead of one file. */
46
+ directory?: boolean;
47
+ }
48
+
49
+ /** A ChloeDB database opened in this process, from its file: no server.
50
+ * Only one process may have a database open to write it at a time; others
51
+ * may open it with `readOnly`. */
52
+ export declare class Database extends Searchable {
53
+ private constructor();
54
+ /** Creates a database at `path` with `schema`. */
55
+ static create(path: Path, schema: SchemaInput, options?: CreateOptions): Promise<Database>;
56
+ /** Opens the database at `path`. */
57
+ static open(path: Path, options?: OpenOptions & ReadOnlyOption): Promise<Database>;
58
+
59
+ /** What the import that made it, or the last import into it, did. */
60
+ lastImport: Record<string, unknown> | null;
61
+ /** Embedded fields whose model did not open, with the reason. */
62
+ readonly embedErrors: Record<string, string>;
63
+ readonly closed: boolean;
64
+
65
+ schema(table?: string): Promise<Schema>;
66
+ tables(): Promise<Schema[]>;
67
+ /** Live rows, in every table. */
68
+ count(): Promise<number>;
69
+ addColumn(name: string, type: string, options?: { table?: string; [option: string]: unknown }): Promise<void>;
70
+ dropColumn(name: string, options?: { table?: string }): Promise<void>;
71
+ renameColumn(from: string, to: string, options?: { table?: string }): Promise<void>;
72
+
73
+ /** Limits every query from now on: a deadline of `timeoutMs` (none or
74
+ * 0: none, the default) and a memory budget of `memory` bytes its
75
+ * queries share (0: none; none, the default: the process's, a quarter of
76
+ * the machine's memory or $CHLOEDB_QUERY_MEMORY_MB MiB). */
77
+ setLimits(limits?: { timeoutMs?: number; memory?: number }): void;
78
+ /** The deadline every query gets unless it gives its own, in ms. */
79
+ readonly timeoutMs: number | null;
80
+ /** The memory budget its queries share, in bytes. */
81
+ readonly memory: number | null;
82
+ /** Stops the queries running now (they reject with DeadlineError);
83
+ * returns how many. */
84
+ interrupt(): number;
85
+
86
+ /** Runs a SELECT. */
87
+ query(sql: string, params?: Params | null, options?: QueryLimits): Promise<Result>;
88
+ /** Runs any statement: a SELECT's Result, or the rows a write wrote; a
89
+ * SELECT limited by `options`. */
90
+ sql(sql: string, params?: Params | null, options?: QueryLimits): Promise<Result | number>;
91
+ /** The plan of a statement, without running it. */
92
+ plan(sql: string, params?: Params | null): Promise<Plan>;
93
+ /** Runs a plan; a read limited by `options`. */
94
+ run(plan: Plan, options?: QueryLimits): Promise<Result | number>;
95
+
96
+ /** Inserts rows whose keys are new; all or none. Returns how many. */
97
+ insert(rows: Row | Iterable<Row>, options?: { table?: string }): Promise<number>;
98
+ /** Inserts rows, replacing the rows with their keys. Returns how many. */
99
+ upsert(rows: Row | Iterable<Row>, options?: { table?: string }): Promise<number>;
100
+ /** The row with this key, or null. */
101
+ get(key: Input, options?: { table?: string }): Promise<Record<string, Value> | null>;
102
+ getMany(keys: Iterable<Input>, options?: { table?: string }): Promise<(Record<string, Value> | null)[]>;
103
+ /** Deletes the rows with this key or these keys; returns how many. */
104
+ delete(keys: Input | Iterable<Input>, options?: { table?: string }): Promise<number>;
105
+ /** Deletes the rows whose `expire_by` time has passed. */
106
+ expire(): Promise<number>;
107
+ /** Write operations as /v1/write takes them, in one transaction. */
108
+ write(ops: Iterable<Record<string, Input>>): Promise<number>;
109
+
110
+ importFile(path: Path, options?: { format?: "jsonl" | "json" | "csv" | "tsv"; table?: string }): Promise<{ rows: number; bulk: boolean; skippedFields: string[] }>;
111
+ importSqlite(path: Path, options?: { tables?: Tables; schemas?: unknown; blobsBase64?: boolean }): Promise<Record<string, unknown>>;
112
+ exportSqlite(path: Path, options?: { tables?: Tables; fts?: boolean; indexes?: boolean; schemas?: boolean }): Promise<Record<string, unknown>>;
113
+ importParquet(path: Path, options?: { table?: string; schema?: SchemaInput; key?: string; blobsBase64?: boolean }): Promise<Record<string, unknown>>;
114
+ planParquet(path: Path, options?: { table?: string; schema?: SchemaInput; key?: string; blobsBase64?: boolean }): Promise<Record<string, unknown>>;
115
+ exportParquet(path: Path, options?: { tables?: Tables; schemas?: boolean }): Promise<Record<string, unknown>>;
116
+
117
+ /** The query vector of a text, or of an image's or a sound's bytes. */
118
+ embed(text?: string | null, options?: { field?: string; table?: string; image?: Bytes; audio?: Bytes }): Promise<number[]>;
119
+ embedTokens(text: string, field: string, options?: { table?: string }): Promise<number[][]>;
120
+ sidNext(prefixes: Iterable<string>, options: { field: string; where?: string; params?: Params; table?: string }): Promise<Record<string, Record<string, number>>>;
121
+ trainCodebook(field: string, name: string, options?: { table?: string; models?: Path; levels?: number; k?: number; iterations?: number; sample?: number; seed?: number; balanced?: boolean }): Promise<string>;
122
+
123
+ /** Writes the rows in memory into segments, merges them into as few as
124
+ * it can, drops deleted rows and returns the freed space to the file
125
+ * system. */
126
+ optimize(): Promise<void>;
127
+ /** Returns the space merges freed to the file system: the bytes the file
128
+ * shrank by. */
129
+ vacuum(): Promise<number>;
130
+ /** Opened `readOnly`: reads what the writer committed since the last
131
+ * query, now; whether anything changed. */
132
+ refresh(): Promise<boolean>;
133
+ /** Merges small segments, returns the space merges freed to the file system when it is an eighth of the file or more, and closes the database. */
134
+ close(): Promise<void>;
135
+ [Symbol.asyncDispose](): Promise<void>;
136
+ }
137
+
138
+ /** Opens the database at `path`, creating it with `schema` if it does not
139
+ * exist. */
140
+ export declare function open(path: Path, options?: CreateOptions & ReadOnlyOption & { schema?: SchemaInput }): Promise<Database>;
141
+ export declare function fromSqlite(sqlitePath: Path, path: Path, options?: CreateOptions & { tables?: Tables; schemas?: unknown; blobsBase64?: boolean }): Promise<Database>;
142
+ export declare function planSqlite(sqlitePath: Path, options?: { tables?: Tables; schemas?: unknown; blobsBase64?: boolean }): Promise<Record<string, unknown>>;
143
+ export declare function fromParquet(parquetPath: Path, path: Path, options?: CreateOptions & { table?: string; schema?: SchemaInput; key?: string; blobsBase64?: boolean }): Promise<Database>;
144
+ export declare function planParquet(parquetPath: Path, options?: { table?: string; schema?: SchemaInput; key?: string; blobsBase64?: boolean }): Promise<Record<string, unknown>>;
145
+ export declare function upgrade(path: Path): Promise<{ old: string; tables: number; rows: number } | null>;
146
+ export declare function trainCodebook(vectors: Iterable<number[] | Float32Array>, name: string, options?: { models?: Path; levels?: number; k?: number; iterations?: number; sample?: number; seed?: number; balanced?: boolean }): Promise<string>;
147
+ /** The addon's version. */
148
+ export declare const version: string;
149
+
150
+ export interface NearbyOptions {
151
+ /** The server's --token or an API key ($CHLOEDB_TOKEN, or $STRATA_TOKEN, by default). */
152
+ token?: string;
153
+ /** Tiles held each way around the user (default 2: a 5 x 5 square). */
154
+ reach?: number;
155
+ /** Milliseconds a request may take (default 30000). */
156
+ timeout?: number;
157
+ /** Milliseconds between asking the server whether the slice is the
158
+ * current one (default 30000; 0 never asks). */
159
+ statusEvery?: number;
160
+ /** Milliseconds a slice may lag a changed table and still answer
161
+ * (default 0: a changed table sends every search to the server). */
162
+ maxLag?: number;
163
+ /** Searches between usage reports to the server (default 20; 0 never). */
164
+ reportEvery?: number;
165
+ /** This device's name in the server's counts (default a random one). */
166
+ device?: string;
167
+ /** A vector slice: fetch every row's codes (default true), which prove
168
+ * far more answers on the device. */
169
+ codes?: boolean;
170
+ fetch?: typeof globalThis.fetch;
171
+ }
172
+
173
+ /** Why a search was answered where it was: "proved" and "no_match" on the
174
+ * device; "short", "bound" and "stale" by the server. */
175
+ export type NearbyWhy = "proved" | "no_match" | "short" | "bound" | "stale";
176
+
177
+ export declare class NearbyResult extends Result {
178
+ /** "device" when the device proved its answer is the server's. */
179
+ where: "device" | "server";
180
+ why: NearbyWhy;
181
+ /** The body of the request (POST /v1/query) that asks the server. */
182
+ ask: string;
183
+ readonly onDevice: boolean;
184
+ proved: boolean;
185
+ stale: boolean;
186
+ /** The most a row not held could score (null when all are held). */
187
+ bound: number | null;
188
+ /** Metres to the nearest tile with rows not held (null when all are
189
+ * held, and for a vector slice). */
190
+ edgeM: number | null;
191
+ deviceMs: number;
192
+ serverMs: number | null;
193
+ /** Clusters a vector search fetched to prove its answer. */
194
+ fetched: number;
195
+ }
196
+
197
+ /** A device's slice of a table on a chloedb-server. */
198
+ export declare class Nearby {
199
+ readonly url: string;
200
+ readonly table: string;
201
+ readonly dir: string;
202
+ readonly device: string;
203
+ reach: number;
204
+ position: [number, number] | null;
205
+ /** The taste last focused on, and the rows held for it. */
206
+ taste: [number[], { rows: number }] | null;
207
+ /** The manifest's summary: kind ("geo" or "vector"), table, version,
208
+ * built_ms, tiles, rows; a geo slice's grid, text, lat and lon; a vector
209
+ * slice's field and dim. */
210
+ info: Record<string, unknown>;
211
+ stats: { searches: number; onDevice: number; fetchedTiles: number; fetchedBytes: number };
212
+ load(): Promise<this>;
213
+ /** Asks the server whether the slice is current; fetches a newer one. */
214
+ check(): Promise<{ table: string; version: number; built_ms: number; fresh: boolean; changed_ms?: number }>;
215
+ /** Moves the user: fetches the tiles around it, drops those far behind. */
216
+ moveTo(lat: number, lon: number, options?: { reach?: number }): Promise<{ fetched: number; dropped: number; bytes: number }>;
217
+ /** A vector slice: holds the clusters whose rows could score highest
218
+ * for taste, as many as fit in rows rows (default 20,000). */
219
+ focus(taste: ArrayLike<number>, options?: { rows?: number }): Promise<{ fetched: number; dropped: number; bytes: number }>;
220
+ /** The tiles held, as [x, y, rows] (a vector slice's cluster is x). */
221
+ held(): [number, number, number][];
222
+ /** The k best places for q near the user: on the device when it can
223
+ * prove the answer is the server's, else the server's. */
224
+ search(q: string, options?: { k?: number; d0?: number; lat?: number; lon?: number }): Promise<NearbyResult>;
225
+ /** A vector slice: the k rows most similar to vector, on the device when
226
+ * it can prove the answer is the server's, else the server's (exact). */
227
+ similar(vector: ArrayLike<number>, options?: { k?: number; refine?: number }): Promise<NearbyResult>;
228
+ /** Sends the counts since the last report to the server. */
229
+ report(): Promise<void>;
230
+ close(): Promise<void>;
231
+ }
232
+
233
+ /** A device's slice of `table` on the chloedb-server at `url`, kept in
234
+ * directory `dir`. */
235
+ export declare function openNearby(url: string, table: string, dir: string, options?: NearbyOptions): Promise<Nearby>;