lance-csr 0.0.0 → 0.13.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/dist/cypher.js ADDED
@@ -0,0 +1,436 @@
1
+ /**
2
+ * Running Cypher queries: one at a time, or many through a cached engine.
3
+ *
4
+ * @module
5
+ */
6
+ import { tableFromIPC } from "apache-arrow";
7
+ import * as native from "../native.js";
8
+ import { GraphConfig } from "./config.js";
9
+ import { DirNamespace } from "./namespace.js";
10
+ import { call, callSync, datasetInputs, parametersJson, timeoutOption, toTable, } from "./types.js";
11
+ import { VectorSearch } from "./vector.js";
12
+ /**
13
+ * How `CypherQuery.execute` runs a query. `DataFusion` (the default and only implemented
14
+ * one) plans and runs it with DataFusion; `LanceNative` is reserved and fails with
15
+ * `NotImplemented`.
16
+ */
17
+ export const ExecutionStrategy = native.ExecutionStrategy;
18
+ /**
19
+ * A query result read one batch at a time: an async iterable of Arrow record batches.
20
+ *
21
+ * Batches are computed as they are read. Scans, filters and projections stream with
22
+ * bounded memory; joins, sorts and aggregations may still buffer. The stream keeps its
23
+ * snapshot alive, so a concurrent `checkoutLatest` doesn't affect it. Breaking out of
24
+ * a `for await` loop, or calling {@link RecordBatchStream.close}, stops the query.
25
+ *
26
+ * @example
27
+ * ```ts
28
+ * const stream = await engine.executeBatches("MATCH (p:Person) RETURN p.name");
29
+ * for await (const batch of stream) {
30
+ * console.log(batch.numRows);
31
+ * }
32
+ * ```
33
+ */
34
+ export class RecordBatchStream {
35
+ #inner;
36
+ /** The schema of every batch. */
37
+ schema;
38
+ /** @internal */
39
+ constructor(inner) {
40
+ this.#inner = inner;
41
+ this.schema = tableFromIPC(inner.schema()).schema;
42
+ }
43
+ /**
44
+ * The next batch, or `null` at the end.
45
+ *
46
+ * @throws {@link LanceCsrError} with code `Timeout` once the query's deadline has
47
+ * passed, or `Runtime` if execution fails.
48
+ */
49
+ async next() {
50
+ const ipc = await call(() => this.#inner.next());
51
+ if (ipc === null) {
52
+ return null;
53
+ }
54
+ // A batch with no rows still arrives as one (empty) batch.
55
+ return tableFromIPC(ipc).batches[0] ?? null;
56
+ }
57
+ /** Stop the query and release what it holds. Reading afterwards returns `null`. */
58
+ async close() {
59
+ await this.#inner.close();
60
+ }
61
+ async *[Symbol.asyncIterator]() {
62
+ try {
63
+ for (let batch = await this.next(); batch !== null; batch = await this.next()) {
64
+ yield batch;
65
+ }
66
+ }
67
+ finally {
68
+ await this.close();
69
+ }
70
+ }
71
+ }
72
+ function configSpec(config, name) {
73
+ if (!(config instanceof GraphConfig)) {
74
+ throw new TypeError(`${name} must be a GraphConfig`);
75
+ }
76
+ return config._spec();
77
+ }
78
+ function vectorSpec(search) {
79
+ if (!(search instanceof VectorSearch)) {
80
+ throw new TypeError("vectorSearch must be a VectorSearch");
81
+ }
82
+ return search._spec();
83
+ }
84
+ /**
85
+ * Run many Cypher queries over the same datasets.
86
+ *
87
+ * The engine registers `datasets` once and reuses the catalog, the DataFusion session
88
+ * and (with `useCsr`) the CSR index across queries. Queries can run concurrently.
89
+ *
90
+ * Lance datasets are read lazily, pinned to the version given (the latest when left
91
+ * out): later writes, by this or another process, aren't visible until
92
+ * {@link CypherEngine.checkoutLatest}. Each dataset is pinned separately, so versions
93
+ * across tables are not a transactional snapshot. Arrow inputs are held in memory and
94
+ * never change; create a new engine to replace them.
95
+ *
96
+ * `execute` and `executeBatches` reuse up to 128 unoptimized query templates per
97
+ * snapshot, keyed by the exact query text and the names and types of scalar
98
+ * parameters. Values are bound before optimization on every call. A successful
99
+ * `checkoutLatest` clears the cache. See
100
+ * [Repeated queries](https://lance-csr.hdclabs.ai/lance/#repeated-queries).
101
+ *
102
+ * @example
103
+ * ```ts
104
+ * import { tableFromArrays } from "apache-arrow";
105
+ * import { CypherEngine, GraphConfig } from "lance-csr";
106
+ *
107
+ * const config = GraphConfig.builder()
108
+ * .nodeTable("Person", "id")
109
+ * .relTable("KNOWS", "Person", "Person", "src_id", "dst_id")
110
+ * .build();
111
+ * const engine = await CypherEngine.create(config, {
112
+ * Person: tableFromArrays({ id: Int32Array.from([1, 2]), name: ["Alice", "Bob"] }),
113
+ * KNOWS: tableFromArrays({ src_id: Int32Array.from([1]), dst_id: Int32Array.from([2]) }),
114
+ * });
115
+ * const result = await engine.execute(
116
+ * "MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name",
117
+ * );
118
+ * result.toArray().map((row) => row.toJSON()); // [{ "a.name": "Alice", "b.name": "Bob" }]
119
+ * ```
120
+ */
121
+ export class CypherEngine {
122
+ #inner;
123
+ #config;
124
+ constructor(inner, config) {
125
+ this.#inner = inner;
126
+ this.#config = config;
127
+ }
128
+ /**
129
+ * Open the datasets and build the engine. Lance datasets are pinned, not read; with
130
+ * `useCsr` the indexes are built here, on a background thread.
131
+ *
132
+ * @param config - The graph mapping.
133
+ * @param datasets - The tables, keyed by node label or relationship type.
134
+ * @param options - CSR and partitioning options.
135
+ * @throws {@link LanceCsrError} with code `InvalidArgument` if `datasets` is empty, a
136
+ * configured key or endpoint column is missing, `targetPartitions` is outside 1 to
137
+ * 1024, or `persistCsr` is set without `useCsr`; `Runtime` if a dataset can't be
138
+ * opened.
139
+ * @throws `TypeError` if `config` isn't a `GraphConfig` or a dataset has an
140
+ * unsupported type.
141
+ */
142
+ static async create(config, datasets, options = {}) {
143
+ const spec = configSpec(config, "config");
144
+ const inputs = datasetInputs(datasets);
145
+ const { useCsr = false, targetPartitions, persistCsr = false } = options;
146
+ if (targetPartitions !== undefined && typeof targetPartitions !== "number") {
147
+ throw new TypeError("targetPartitions must be a number or undefined");
148
+ }
149
+ const inner = await call(() => native.openCypherEngine(spec, inputs, useCsr, targetPartitions, persistCsr));
150
+ return new CypherEngine(inner, config);
151
+ }
152
+ /** @internal The native engine, for `SqlEngine.fromEngine`. */
153
+ _inner() {
154
+ return this.#inner;
155
+ }
156
+ /**
157
+ * Run a Cypher query and return the whole result.
158
+ *
159
+ * The result is held in memory; use {@link CypherEngine.executeBatches} for large
160
+ * outputs.
161
+ *
162
+ * @param query - The Cypher query.
163
+ * @param params - Values for `$name` parameters; see {@link Parameter}.
164
+ * @param options - `timeoutMs`: milliseconds for the whole query.
165
+ * @returns The query result.
166
+ * @throws {@link LanceCsrError} with code `InvalidArgument` if the query is invalid,
167
+ * refers to an unknown label, compares or combines incompatible types, or a parameter
168
+ * is unsupported, nested beyond 128 levels or cyclic; `NotImplemented` if the query
169
+ * uses a Cypher feature that parses but isn't supported; `Timeout` if it runs past
170
+ * `timeoutMs`; `Runtime` if execution fails.
171
+ */
172
+ async execute(query, params, options = {}) {
173
+ const json = parametersJson(params);
174
+ const timeout = timeoutOption(options.timeoutMs);
175
+ return toTable(await call(() => this.#inner.execute(query, json, timeout)));
176
+ }
177
+ /**
178
+ * Run a Cypher query and stream the result.
179
+ *
180
+ * Planning errors reject the returned promise; execution errors reject while reading.
181
+ *
182
+ * @param query - The Cypher query.
183
+ * @param params - Values for `$name` parameters, as for {@link CypherEngine.execute}.
184
+ * @param options - `timeoutMs`: milliseconds for the whole query, including pauses
185
+ * between reads.
186
+ * @returns The result, one batch at a time.
187
+ */
188
+ async executeBatches(query, params, options = {}) {
189
+ const json = parametersJson(params);
190
+ const timeout = timeoutOption(options.timeoutMs);
191
+ return new RecordBatchStream(await call(() => this.#inner.executeBatches(query, json, timeout)));
192
+ }
193
+ /**
194
+ * The plans for a query, without running it unless `analyze` is set.
195
+ *
196
+ * @param query - The Cypher query.
197
+ * @param params - Values for `$name` parameters, as for {@link CypherEngine.execute}.
198
+ * @param options - `analyze`: run the query and show each operator's metrics.
199
+ * @returns The graph logical plan, the DataFusion logical plan and the physical plan,
200
+ * including pushed-down scans. With `analyze`, the physical plan's row is labelled
201
+ * `physical_plan_with_metrics`.
202
+ */
203
+ async explain(query, params, options = {}) {
204
+ const json = parametersJson(params);
205
+ return call(() => this.#inner.explain(query, json, options.analyze ?? false));
206
+ }
207
+ /**
208
+ * Move every Lance dataset to its latest version.
209
+ *
210
+ * Updates the CSR, node indexes and statistics to match. Datasets whose version and
211
+ * commit time are unchanged keep their open handle. The replacement is validated in
212
+ * full before it's swapped in: on error nothing changes and the previous snapshot
213
+ * stays usable. Queries already running finish on the snapshot they started with.
214
+ * Arrow inputs are unchanged. Concurrent calls run one at a time, and
215
+ * `targetPartitions` is preserved. See
216
+ * [Lance datasets](https://lance-csr.hdclabs.ai/lance/#checkout-latest).
217
+ */
218
+ async checkoutLatest() {
219
+ await call(() => this.#inner.checkoutLatest());
220
+ }
221
+ /**
222
+ * Rebuild each CSR that carries a delta (experimental; needs `useCsr`).
223
+ *
224
+ * `checkoutLatest` applies Lance writes as a delta over the base CSR, and rebuilds on
225
+ * its own only once pending changes pass 25% of the base. This rebuilds every CSR that
226
+ * carries a delta now, at the version the engine is pinned to. It scans every edge
227
+ * again, so call it after a bulk load or at a quiet time. It doesn't move to newer
228
+ * versions: call `checkoutLatest` first for that. Query results never change. See
229
+ * [Rebuilding the CSR](https://lance-csr.hdclabs.ai/csr/#rebuilding-the-csr).
230
+ */
231
+ async optimizeCsr() {
232
+ await call(() => this.#inner.optimizeCsr());
233
+ }
234
+ /**
235
+ * Delete the CSR files stored with `persistCsr` (experimental).
236
+ *
237
+ * Removes the `_lance_csr` folder of every Lance relationship dataset this engine
238
+ * reads. The engine keeps the CSR it already holds in memory, so queries aren't
239
+ * affected. See [Storing the CSR](https://lance-csr.hdclabs.ai/csr/#storing-the-csr).
240
+ *
241
+ * @returns The number of files deleted; 0 when nothing was stored.
242
+ */
243
+ async deleteStoredCsr() {
244
+ return call(() => this.#inner.deleteStoredCsr());
245
+ }
246
+ /**
247
+ * Statistics for each node index (experimental; needs `useCsr`).
248
+ *
249
+ * A label is missing when its keys aren't unique integers; relationships that end at
250
+ * it then use a join.
251
+ */
252
+ nodeIndexStats() {
253
+ return callSync(() => this.#inner.nodeIndexStats());
254
+ }
255
+ /**
256
+ * Statistics for each CSR adjacency index (experimental; needs `useCsr`), keyed by
257
+ * relationship type; empty without `useCsr`. An identical result after
258
+ * `checkoutLatest` means the snapshot itself didn't change. See
259
+ * [Inspecting the CSR](https://lance-csr.hdclabs.ai/csr/#inspecting-the-csr).
260
+ */
261
+ csrStats() {
262
+ return callSync(() => this.#inner.csrStats());
263
+ }
264
+ /** The pinned version of each Lance dataset, keyed by dataset name. Arrow inputs aren't listed. */
265
+ datasetVersions() {
266
+ return callSync(() => this.#inner.datasetVersions());
267
+ }
268
+ /** The engine's graph config. */
269
+ config() {
270
+ return this.#config;
271
+ }
272
+ /**
273
+ * Run a Cypher query, then rank its rows by vector similarity.
274
+ *
275
+ * @param query - The Cypher query. It must return the column `vectorSearch` ranks by.
276
+ * @param vectorSearch - The ranking.
277
+ * @returns At most `topK` rows, closest first.
278
+ */
279
+ async executeWithVectorRerank(query, vectorSearch) {
280
+ const spec = vectorSpec(vectorSearch);
281
+ return toTable(await call(() => this.#inner.executeWithVectorRerank(query, spec)));
282
+ }
283
+ }
284
+ /**
285
+ * One parsed Cypher query, run against the datasets passed to each call.
286
+ *
287
+ * Builder methods return a new query. Datasets are read into memory for each call; use
288
+ * {@link CypherEngine} to register them once and run many queries.
289
+ *
290
+ * @example
291
+ * ```ts
292
+ * const result = await new CypherQuery("MATCH (p:Person) WHERE p.age > $min RETURN p.name")
293
+ * .withConfig(config)
294
+ * .withParameter("min", 30)
295
+ * .execute({ Person: people });
296
+ * ```
297
+ */
298
+ export class CypherQuery {
299
+ #query;
300
+ #parsed;
301
+ #config;
302
+ #parameters;
303
+ constructor(queryText, parsed, config, parameters = {}) {
304
+ if (typeof queryText !== "string") {
305
+ throw new TypeError("queryText must be a string");
306
+ }
307
+ this.#query = queryText;
308
+ this.#parsed = parsed ?? callSync(() => native.parseCypher(queryText));
309
+ this.#config = config;
310
+ this.#parameters = parameters;
311
+ }
312
+ #spec() {
313
+ return {
314
+ query: this.#query,
315
+ config: this.#config?._spec(),
316
+ parameters: parametersJson(this.#parameters),
317
+ };
318
+ }
319
+ /**
320
+ * Set the graph config. Required before running the query.
321
+ *
322
+ * @returns A new query with the config set.
323
+ */
324
+ withConfig(config) {
325
+ configSpec(config, "config");
326
+ return new CypherQuery(this.#query, this.#parsed, config, this.#parameters);
327
+ }
328
+ /**
329
+ * Bind `$key` to `value`.
330
+ *
331
+ * @param key - The parameter name, without `$`.
332
+ * @param value - The value, of a type that {@link CypherEngine.execute} accepts in `params`.
333
+ * @returns A new query with the parameter bound.
334
+ */
335
+ withParameter(key, value) {
336
+ const parameters = { ...this.#parameters, [key]: value };
337
+ parametersJson(parameters);
338
+ return new CypherQuery(this.#query, this.#parsed, this.#config, parameters);
339
+ }
340
+ /** The query text. */
341
+ queryText() {
342
+ return this.#query;
343
+ }
344
+ /** The bound parameters, as the engine receives them (a `Date` becomes ISO text). */
345
+ parameters() {
346
+ return JSON.parse(parametersJson(this.#parameters) ?? "{}");
347
+ }
348
+ /**
349
+ * Run the query.
350
+ *
351
+ * @param datasets - The tables, keyed by node label or relationship type. They are
352
+ * read into memory for this call.
353
+ * @param options - `strategy` (default `ExecutionStrategy.DataFusion`) and `timeoutMs`.
354
+ * @returns The query result.
355
+ * @throws {@link LanceCsrError} with code `InvalidArgument` if the query is invalid or a
356
+ * dataset is missing; `NotImplemented` for an unsupported Cypher feature or
357
+ * `ExecutionStrategy.LanceNative`; `Timeout` past `timeoutMs`; `Runtime` if execution
358
+ * fails.
359
+ */
360
+ async execute(datasets, options = {}) {
361
+ const spec = this.#spec();
362
+ const inputs = datasetInputs(datasets);
363
+ const timeout = timeoutOption(options.timeoutMs);
364
+ return toTable(await call(() => native.cypherQueryExecute(spec, inputs, options.strategy, timeout)));
365
+ }
366
+ /**
367
+ * Run the query, reading each label from `<baseUri>/<label>.lance`.
368
+ *
369
+ * @param namespace - Where the datasets are.
370
+ * @param strategy - How to run the query; the default is `ExecutionStrategy.DataFusion`.
371
+ */
372
+ async executeWithNamespace(namespace, strategy) {
373
+ if (!(namespace instanceof DirNamespace)) {
374
+ throw new TypeError("namespace must be a DirNamespace");
375
+ }
376
+ const spec = this.#spec();
377
+ return toTable(await call(() => native.cypherQueryExecuteWithNamespace(spec, namespace.baseUri, strategy)));
378
+ }
379
+ /**
380
+ * The plans for the query, without running it.
381
+ *
382
+ * @returns The graph logical plan, the DataFusion logical plan and the physical plan.
383
+ */
384
+ async explain(datasets) {
385
+ const spec = this.#spec();
386
+ const inputs = datasetInputs(datasets);
387
+ return call(() => native.cypherQueryExplain(spec, inputs));
388
+ }
389
+ /**
390
+ * Export the query as SQL joins. Only supported expressions are exported. See
391
+ * [From Cypher to SQL](https://lance-csr.hdclabs.ai/sql/#from-cypher-to-sql).
392
+ *
393
+ * @param datasets - The tables, keyed by node label or relationship type; their
394
+ * schemas shape the SQL.
395
+ * @param dialect - The SQL dialect; the default is `SqlDialect.Default`.
396
+ * @throws {@link LanceCsrError} with code `NotImplemented` if a runtime-only Cypher
397
+ * function has no faithful SQL translation.
398
+ */
399
+ async toSql(datasets, dialect) {
400
+ const spec = this.#spec();
401
+ const inputs = datasetInputs(datasets);
402
+ return call(() => native.cypherQueryToSql(spec, inputs, dialect));
403
+ }
404
+ /**
405
+ * Run the query, then rank its rows by vector similarity.
406
+ *
407
+ * This is the common GraphRAG pattern: find candidates by graph traversal, then rerank
408
+ * them by similarity. With `VectorSearch.useLanceIndex(true)` and Lance datasets, the
409
+ * Lance index is searched first instead. See
410
+ * [Vector search](https://lance-csr.hdclabs.ai/vector-search/).
411
+ *
412
+ * @param vectorSearch - The ranking. Its column is a returned column, such as `"d.embedding"`.
413
+ * @returns At most `topK` rows, closest first.
414
+ */
415
+ async executeWithVectorRerank(datasets, vectorSearch) {
416
+ const spec = this.#spec();
417
+ const inputs = datasetInputs(datasets);
418
+ const search = vectorSpec(vectorSearch);
419
+ return toTable(await call(() => native.cypherQueryExecuteWithVectorRerank(spec, inputs, search)));
420
+ }
421
+ /** The variables the query uses, including `UNION` branches, unordered. */
422
+ variables() {
423
+ return [...this.#parsed.variables];
424
+ }
425
+ /** The node labels the query uses, including `UNION` branches, unordered. */
426
+ nodeLabels() {
427
+ return [...this.#parsed.nodeLabels];
428
+ }
429
+ /** The relationship types the query uses, with `UNION` branches, unordered. */
430
+ relationshipTypes() {
431
+ return [...this.#parsed.relationshipTypes];
432
+ }
433
+ toString() {
434
+ return `CypherQuery(${JSON.stringify(this.#query)})`;
435
+ }
436
+ }
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Node.js bindings for the `lance-csr` crate.
3
+ *
4
+ * Provides two query interfaces:
5
+ *
6
+ * - **Cypher**: `CypherQuery` and `CypherEngine` for graph-pattern queries (requires a
7
+ * `GraphConfig` with node and relationship mappings).
8
+ * - **SQL**: `SqlQuery` and `SqlEngine` for standard SQL queries executed directly
9
+ * against datasets via DataFusion (no `GraphConfig` needed).
10
+ *
11
+ * Results are [apache-arrow](https://arrow.apache.org/docs/js/) tables.
12
+ *
13
+ * @module
14
+ */
15
+ export { GraphConfig, GraphConfigBuilder } from "./config.ts";
16
+ export { CypherEngine, type CypherEngineOptions, CypherQuery, type ExecuteOptions, ExecutionStrategy, type ExplainOptions, RecordBatchStream, } from "./cypher.ts";
17
+ export { DirNamespace } from "./namespace.ts";
18
+ export { SqlDialect, SqlEngine, type SqlEngineOptions, SqlQuery } from "./sql.ts";
19
+ export { type CsrStats, type Dataset, type ErrorCode, type LanceDataset, LanceCsrError, type NodeIndexStats, type Parameter, type Scalar, } from "./types.ts";
20
+ export { DistanceMetric, VectorSearch } from "./vector.ts";
21
+ /** The package version. */
22
+ export declare const version: string;
package/dist/index.js ADDED
@@ -0,0 +1,23 @@
1
+ /**
2
+ * Node.js bindings for the `lance-csr` crate.
3
+ *
4
+ * Provides two query interfaces:
5
+ *
6
+ * - **Cypher**: `CypherQuery` and `CypherEngine` for graph-pattern queries (requires a
7
+ * `GraphConfig` with node and relationship mappings).
8
+ * - **SQL**: `SqlQuery` and `SqlEngine` for standard SQL queries executed directly
9
+ * against datasets via DataFusion (no `GraphConfig` needed).
10
+ *
11
+ * Results are [apache-arrow](https://arrow.apache.org/docs/js/) tables.
12
+ *
13
+ * @module
14
+ */
15
+ import { VERSION } from "../native.js";
16
+ export { GraphConfig, GraphConfigBuilder } from "./config.js";
17
+ export { CypherEngine, CypherQuery, ExecutionStrategy, RecordBatchStream, } from "./cypher.js";
18
+ export { DirNamespace } from "./namespace.js";
19
+ export { SqlDialect, SqlEngine, SqlQuery } from "./sql.js";
20
+ export { LanceCsrError, } from "./types.js";
21
+ export { DistanceMetric, VectorSearch } from "./vector.js";
22
+ /** The package version. */
23
+ export const version = VERSION;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Resolving table names to Lance datasets in a directory.
3
+ *
4
+ * @module
5
+ */
6
+ /**
7
+ * Resolves each table name to the Lance dataset `<baseUri>/<name>.lance`.
8
+ *
9
+ * Use it with `CypherQuery.executeWithNamespace`.
10
+ */
11
+ export declare class DirNamespace {
12
+ /** The directory that holds the datasets. */
13
+ readonly baseUri: string;
14
+ /** @param baseUri - The directory that holds the datasets. */
15
+ constructor(baseUri: string);
16
+ }
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Resolving table names to Lance datasets in a directory.
3
+ *
4
+ * @module
5
+ */
6
+ /**
7
+ * Resolves each table name to the Lance dataset `<baseUri>/<name>.lance`.
8
+ *
9
+ * Use it with `CypherQuery.executeWithNamespace`.
10
+ */
11
+ export class DirNamespace {
12
+ /** The directory that holds the datasets. */
13
+ baseUri;
14
+ /** @param baseUri - The directory that holds the datasets. */
15
+ constructor(baseUri) {
16
+ if (typeof baseUri !== "string") {
17
+ throw new TypeError("baseUri must be a string");
18
+ }
19
+ this.baseUri = baseUri;
20
+ }
21
+ }
package/dist/sql.d.ts ADDED
@@ -0,0 +1,109 @@
1
+ /**
2
+ * Running SQL queries: one at a time, or many through a cached engine.
3
+ *
4
+ * @module
5
+ */
6
+ import type { Table } from "apache-arrow";
7
+ import * as native from "../native.js";
8
+ import { GraphConfig } from "./config.ts";
9
+ import type { CypherEngine, ExecuteOptions, ExplainOptions } from "./cypher.ts";
10
+ import { type Dataset, type Parameter } from "./types.ts";
11
+ /**
12
+ * The SQL dialect `CypherQuery.toSql` writes: `Default` (generic DataFusion SQL),
13
+ * `Spark`, `PostgreSql`, `MySql` or `Sqlite`.
14
+ */
15
+ export declare const SqlDialect: typeof native.SqlDialect;
16
+ export type SqlDialect = native.SqlDialect;
17
+ /**
18
+ * One SQL query, run against the datasets passed to each call.
19
+ *
20
+ * Each dataset is a table under its lower-cased name, read into memory for the call.
21
+ * Use {@link SqlEngine} to register datasets once and run many queries.
22
+ */
23
+ export declare class SqlQuery {
24
+ #private;
25
+ /** @param sql - The SQL query. */
26
+ constructor(sql: string);
27
+ /** The query text. */
28
+ sql(): string;
29
+ /**
30
+ * Run the query.
31
+ *
32
+ * @param datasets - The tables, keyed by the names the query uses.
33
+ * @throws {@link LanceCsrError} with code `InvalidArgument` if the query is invalid, or
34
+ * `Runtime` if execution fails.
35
+ */
36
+ execute(datasets: Record<string, Dataset>): Promise<Table>;
37
+ /** The logical and physical plans for the query, without running it. */
38
+ explain(datasets: Record<string, Dataset>): Promise<string>;
39
+ toString(): string;
40
+ }
41
+ /** Options for {@link SqlEngine.create}. */
42
+ export interface SqlEngineOptions {
43
+ /** The graph `GRAPH_TABLE` patterns match. Without one, `GRAPH_TABLE` fails with `InvalidArgument`. */
44
+ config?: GraphConfig;
45
+ /** Build the experimental CSR index, as for `CypherEngine`. Needs a `config`. */
46
+ useCsr?: boolean;
47
+ }
48
+ /**
49
+ * Run many SQL queries on the same datasets, with graph patterns given a graph.
50
+ *
51
+ * Each dataset is a table under its lower-cased name. Lance datasets are scanned in
52
+ * place, pinned to the version given, with column and filter pushdown; Arrow inputs are
53
+ * held in memory. With a `config`, a `GRAPH_TABLE` clause embeds a Cypher graph pattern,
54
+ * and with `useCsr` its hops run on the CSR. See
55
+ * [Graph patterns in SQL](https://lance-csr.hdclabs.ai/sql/#graph-patterns-in-sql).
56
+ *
57
+ * Plans are cached per snapshot, as `CypherEngine` caches Cypher templates.
58
+ *
59
+ * @example
60
+ * ```ts
61
+ * const engine = await SqlEngine.create({
62
+ * person: tableFromArrays({ id: Int32Array.from([1, 2]), name: ["Alice", "Bob"] }),
63
+ * knows: tableFromArrays({ src: Int32Array.from([1]), dst: Int32Array.from([2]) }),
64
+ * });
65
+ * const result = await engine.execute(
66
+ * "SELECT p.name FROM person p JOIN knows k ON p.id = k.src WHERE k.dst = $dst",
67
+ * { dst: 2 },
68
+ * );
69
+ * ```
70
+ */
71
+ export declare class SqlEngine {
72
+ #private;
73
+ private constructor();
74
+ /**
75
+ * Open the datasets and build the engine.
76
+ *
77
+ * @param datasets - The tables, keyed by the names queries use; with a `config`, also
78
+ * by node label or relationship type, as for `CypherEngine`.
79
+ * @throws {@link LanceCsrError} with code `InvalidArgument` if `datasets` is empty,
80
+ * `useCsr` is set without a `config`, or a configured column is missing.
81
+ */
82
+ static create(datasets: Record<string, Dataset>, options?: SqlEngineOptions): Promise<SqlEngine>;
83
+ /**
84
+ * SQL over a `CypherEngine`'s snapshot, sharing its datasets, CSR and statistics.
85
+ *
86
+ * `checkoutLatest` on either engine moves only that engine: the other keeps the
87
+ * snapshot it holds.
88
+ */
89
+ static fromEngine(engine: CypherEngine): SqlEngine;
90
+ /**
91
+ * Run a SQL query and return the whole result.
92
+ *
93
+ * @param sql - The SQL query.
94
+ * @param params - Values for `$name` parameters, as for `CypherEngine.execute`.
95
+ * @param options - `timeoutMs`: milliseconds for the whole query.
96
+ * @throws {@link LanceCsrError} with code `InvalidArgument` if the query is invalid,
97
+ * `Timeout` past `timeoutMs`, or `Runtime` if execution fails.
98
+ */
99
+ execute(sql: string, params?: Record<string, Parameter> | null, options?: ExecuteOptions): Promise<Table>;
100
+ /**
101
+ * The plans for a SQL query, without running it unless `analyze` is set.
102
+ *
103
+ * @returns The logical and physical plans; with `analyze`, the physical plan with
104
+ * each operator's metrics.
105
+ */
106
+ explain(sql: string, params?: Record<string, Parameter> | null, options?: ExplainOptions): Promise<string>;
107
+ /** Move every Lance dataset to its latest version, as `CypherEngine.checkoutLatest` does. */
108
+ checkoutLatest(): Promise<void>;
109
+ }