@loaders.gl/sql 5.0.0-alpha.2 → 5.0.0-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +60 -2
  3. package/dist/arrow-query.cjs +1373 -0
  4. package/dist/arrow-query.cjs.map +6 -0
  5. package/dist/arrow-query.d.ts +5 -0
  6. package/dist/arrow-query.d.ts.map +1 -0
  7. package/dist/arrow-query.js +6 -0
  8. package/dist/arrow-query.js.map +1 -0
  9. package/dist/arrow-table-source.d.ts +27 -0
  10. package/dist/arrow-table-source.d.ts.map +1 -0
  11. package/dist/arrow-table-source.js +79 -0
  12. package/dist/arrow-table-source.js.map +1 -0
  13. package/dist/bind-sql-predicate.d.ts +4 -0
  14. package/dist/bind-sql-predicate.d.ts.map +1 -0
  15. package/dist/bind-sql-predicate.js +11 -0
  16. package/dist/bind-sql-predicate.js.map +1 -0
  17. package/dist/compile-table-query.d.ts +55 -0
  18. package/dist/compile-table-query.d.ts.map +1 -0
  19. package/dist/compile-table-query.js +255 -0
  20. package/dist/compile-table-query.js.map +1 -0
  21. package/dist/duckdb-sql-source.d.ts.map +1 -1
  22. package/dist/duckdb-sql-source.js +21 -7
  23. package/dist/duckdb-sql-source.js.map +1 -1
  24. package/dist/index.cjs +1746 -307
  25. package/dist/index.cjs.map +3 -3
  26. package/dist/index.d.ts +14 -2
  27. package/dist/index.d.ts.map +1 -1
  28. package/dist/index.js +7 -0
  29. package/dist/index.js.map +1 -1
  30. package/dist/parse-sql-predicate.d.ts.map +1 -1
  31. package/dist/parse-sql-predicate.js +10 -4
  32. package/dist/parse-sql-predicate.js.map +1 -1
  33. package/dist/query-arrow-table.d.ts +83 -0
  34. package/dist/query-arrow-table.d.ts.map +1 -0
  35. package/dist/query-arrow-table.js +660 -0
  36. package/dist/query-arrow-table.js.map +1 -0
  37. package/dist/snowflake-sql-source.d.ts.map +1 -1
  38. package/dist/snowflake-sql-source.js +8 -5
  39. package/dist/snowflake-sql-source.js.map +1 -1
  40. package/dist/sql-predicate-schema.d.ts +17 -2
  41. package/dist/sql-predicate-schema.d.ts.map +1 -1
  42. package/dist/sql-predicate-schema.js +25 -4
  43. package/dist/sql-predicate-schema.js.map +1 -1
  44. package/dist/sql-predicate-types.d.ts +22 -32
  45. package/dist/sql-predicate-types.d.ts.map +1 -1
  46. package/dist/sql-predicate-types.js +5 -1
  47. package/dist/sql-predicate-types.js.map +1 -1
  48. package/dist/sql-predicate-zod.cjs +3 -2
  49. package/dist/sql-predicate-zod.cjs.map +1 -1
  50. package/dist/sql-predicate-zod.d.ts.map +1 -1
  51. package/dist/sql-predicate-zod.js +5 -2
  52. package/dist/sql-predicate-zod.js.map +1 -1
  53. package/dist/sql-predicate.cjs +114 -7
  54. package/dist/sql-predicate.cjs.map +2 -2
  55. package/dist/sql-predicate.d.ts +3 -1
  56. package/dist/sql-predicate.d.ts.map +1 -1
  57. package/dist/sql-predicate.js +2 -0
  58. package/dist/sql-predicate.js.map +1 -1
  59. package/dist/sql-source.d.ts +16 -3
  60. package/dist/sql-source.d.ts.map +1 -1
  61. package/dist/sql-source.js +34 -5
  62. package/dist/sql-source.js.map +1 -1
  63. package/dist/sql-types.d.ts +3 -0
  64. package/dist/sql-types.d.ts.map +1 -1
  65. package/dist/table-query-capabilities.d.ts +6 -0
  66. package/dist/table-query-capabilities.d.ts.map +1 -0
  67. package/dist/table-query-capabilities.js +26 -0
  68. package/dist/table-query-capabilities.js.map +1 -0
  69. package/dist/table-query.cjs +286 -0
  70. package/dist/table-query.cjs.map +6 -0
  71. package/dist/table-query.d.ts +29 -0
  72. package/dist/table-query.d.ts.map +1 -0
  73. package/dist/table-query.js +30 -0
  74. package/dist/table-query.js.map +1 -0
  75. package/package.json +15 -5
  76. package/src/arrow-query.ts +17 -0
  77. package/src/arrow-table-source.ts +111 -0
  78. package/src/bind-sql-predicate.ts +21 -0
  79. package/src/compile-table-query.ts +354 -0
  80. package/src/duckdb-sql-source.ts +30 -6
  81. package/src/index.ts +39 -0
  82. package/src/parse-sql-predicate.ts +21 -5
  83. package/src/query-arrow-table.ts +843 -0
  84. package/src/snowflake-sql-source.ts +7 -4
  85. package/src/sql-predicate-schema.ts +30 -5
  86. package/src/sql-predicate-types.ts +48 -32
  87. package/src/sql-predicate-zod.ts +5 -2
  88. package/src/sql-predicate.ts +6 -0
  89. package/src/sql-source.ts +40 -5
  90. package/src/sql-types.ts +4 -0
  91. package/src/table-query-capabilities.ts +29 -0
  92. package/src/table-query.ts +78 -0
package/dist/index.cjs CHANGED
@@ -30,15 +30,26 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
30
30
  // dist/index.js
31
31
  var index_exports = {};
32
32
  __export(index_exports, {
33
+ ARROW_TABLE_QUERY_CAPABILITIES: () => ARROW_TABLE_QUERY_CAPABILITIES,
34
+ ArrowTableSource: () => ArrowTableSource,
33
35
  DuckDBSQLDataSource: () => DuckDBSQLDataSource,
34
36
  DuckDBSQLSource: () => DuckDBSQLSource,
35
37
  SQLDataSource: () => SQLDataSource,
38
+ SQL_DATA_SOURCE_TABLE_QUERY_CAPABILITIES: () => SQL_DATA_SOURCE_TABLE_QUERY_CAPABILITIES,
36
39
  SQL_PREDICATE_JSON_SCHEMA: () => SQL_PREDICATE_JSON_SCHEMA,
37
40
  SnowflakeSQLDataSource: () => SnowflakeSQLDataSource,
38
41
  SnowflakeSQLSource: () => SnowflakeSQLSource,
42
+ bindSQLPredicate: () => bindSQLPredicate,
43
+ compileSQLTableQuery: () => compileSQLTableQuery,
44
+ explainArrowTableQuery: () => explainArrowTableQuery,
45
+ explainTableQuery: () => explainTableQuery2,
39
46
  getSQLAdapterFactory: () => getSQLAdapterFactory,
47
+ getSQLPredicateColumnNames: () => getSQLPredicateColumnNames,
40
48
  isSQLPredicate: () => isSQLPredicate,
49
+ isSQLPredicateParameter: () => isSQLPredicateParameter,
41
50
  parseSQLPredicate: () => parseSQLPredicate,
51
+ planTableQuery: () => planTableQuery2,
52
+ queryArrowTable: () => queryArrowTable,
42
53
  registerSQLAdapter: () => registerSQLAdapter,
43
54
  validateSQLPredicate: () => validateSQLPredicate
44
55
  });
@@ -86,6 +97,115 @@ function mergeOptionsRecursively(baseOptions, newOptions, level = 0) {
86
97
  return options;
87
98
  }
88
99
 
100
+ // ../loader-utils/src/lib/request-utils/request-credentials.ts
101
+ var AUTHENTICATED_FETCH = /* @__PURE__ */ Symbol("loaders.gl.authenticated-fetch");
102
+ var refreshPromises = /* @__PURE__ */ new WeakMap();
103
+ function createAuthenticatedFetch(options) {
104
+ const baseFetch = options.fetch || ((url, requestOptions) => fetch(url, requestOptions));
105
+ if (!options.credentials.length) return baseFetch;
106
+ const existingMetadata = baseFetch[AUTHENTICATED_FETCH];
107
+ if (existingMetadata === options.credentials) return baseFetch;
108
+ const authenticatedFetch = async (url, requestOptions = {}) => {
109
+ var _a, _b, _c;
110
+ const resolvedURL = parseHTTPURL(url);
111
+ if (!resolvedURL) return baseFetch(url, requestOptions);
112
+ const authorization = await authorizeRequest(resolvedURL, requestOptions, options.credentials);
113
+ const response = await baseFetch(authorization.url, authorization.options);
114
+ const refreshableCredentials = authorization.credentials.filter(
115
+ ({ credential }) => typeof credential.token === "function" && credential.refreshStatusCodes.includes(response.status)
116
+ );
117
+ if (!refreshableCredentials.length || !isReplayableRequest(requestOptions)) return response;
118
+ if ((_a = requestOptions.signal) == null ? void 0 : _a.aborted) throw createAbortError();
119
+ const refreshedTokens = /* @__PURE__ */ new Map();
120
+ await Promise.all(
121
+ refreshableCredentials.map(async ({ credential }) => {
122
+ const token = await refreshCredential(credential, url, response);
123
+ if (token) refreshedTokens.set(credential, token);
124
+ })
125
+ );
126
+ if (!refreshedTokens.size) return response;
127
+ await ((_b = response.body) == null ? void 0 : _b.cancel().catch(() => {
128
+ }));
129
+ if ((_c = requestOptions.signal) == null ? void 0 : _c.aborted) throw createAbortError();
130
+ const replayAuthorization = await authorizeRequest(
131
+ resolvedURL,
132
+ requestOptions,
133
+ options.credentials,
134
+ refreshedTokens,
135
+ authorization.credentials
136
+ );
137
+ return baseFetch(replayAuthorization.url, replayAuthorization.options);
138
+ };
139
+ Object.defineProperty(authenticatedFetch, AUTHENTICATED_FETCH, {
140
+ value: options.credentials
141
+ });
142
+ return authenticatedFetch;
143
+ }
144
+ async function authorizeRequest(sourceURL, requestOptions, credentials, tokenOverrides = /* @__PURE__ */ new Map(), previousCredentials = []) {
145
+ const url = new URL(sourceURL);
146
+ const headers = new Headers(requestOptions.headers);
147
+ const resolvedCredentials = [];
148
+ const previousTokens = new Map(
149
+ previousCredentials.map(({ credential, token }) => [credential, token])
150
+ );
151
+ for (const credential of credentials) {
152
+ if (!credential.origins.includes(url.origin)) continue;
153
+ const overrideToken = tokenOverrides.get(credential);
154
+ const previousToken = previousTokens.get(credential);
155
+ const ownsQueryParameter = credential.type === "query-parameter" && previousToken !== void 0;
156
+ const ownsHeader = credential.type === "header" && previousToken !== void 0;
157
+ if (credential.type === "query-parameter" && url.searchParams.has(credential.name) && !ownsQueryParameter || credential.type === "header" && headers.has(credential.name) && !ownsHeader) {
158
+ continue;
159
+ }
160
+ const token = overrideToken ?? previousToken ?? await resolveToken(credential.token, { url: sourceURL.toString(), reason: "request" });
161
+ if (!token) continue;
162
+ if (credential.type === "query-parameter") {
163
+ url.searchParams.set(credential.name, token);
164
+ } else {
165
+ headers.set(credential.name, `${credential.prefix || ""}${token}`);
166
+ }
167
+ resolvedCredentials.push({ credential, token });
168
+ }
169
+ return {
170
+ url: url.toString(),
171
+ options: { ...requestOptions, headers },
172
+ credentials: resolvedCredentials
173
+ };
174
+ }
175
+ async function refreshCredential(credential, url, response) {
176
+ const existingPromise = refreshPromises.get(credential);
177
+ if (existingPromise) return existingPromise;
178
+ const tokenProvider = credential.token;
179
+ const promise = Promise.resolve(
180
+ tokenProvider({
181
+ url,
182
+ reason: "refresh",
183
+ response: { status: response.status, headers: response.headers }
184
+ })
185
+ ).finally(() => refreshPromises.delete(credential));
186
+ refreshPromises.set(credential, promise);
187
+ return promise;
188
+ }
189
+ async function resolveToken(token, context) {
190
+ return typeof token === "function" ? token(context) : token;
191
+ }
192
+ function parseHTTPURL(url) {
193
+ try {
194
+ const parsedURL = new URL(url);
195
+ return ["http:", "https:"].includes(parsedURL.protocol) ? parsedURL : null;
196
+ } catch {
197
+ return null;
198
+ }
199
+ }
200
+ function isReplayableRequest(options) {
201
+ const method = (options.method || "GET").toUpperCase();
202
+ if (!["GET", "HEAD", "OPTIONS", "PUT", "DELETE"].includes(method)) return false;
203
+ return !(options.body && typeof ReadableStream !== "undefined" && options.body instanceof ReadableStream);
204
+ }
205
+ function createAbortError() {
206
+ return new DOMException("The operation was aborted.", "AbortError");
207
+ }
208
+
89
209
  // ../loader-utils/src/lib/path-utils/file-aliases.ts
90
210
  var pathPrefix = "";
91
211
  var fileAliases = {};
@@ -184,63 +304,840 @@ var DataSource = class _DataSource {
184
304
  }
185
305
  };
186
306
  function getFetchFunction(options) {
307
+ var _a, _b;
308
+ const fetchOption = (options == null ? void 0 : options.fetch) ?? ((_a = options == null ? void 0 : options.core) == null ? void 0 : _a.fetch);
309
+ let fetchFunction;
310
+ if (typeof fetchOption === "function") {
311
+ fetchFunction = (url, fetchOptions) => fetchOption(url, fetchOptions);
312
+ } else if (fetchOption) {
313
+ fetchFunction = (url, requestOptions) => fetch(url, mergeFetchOptions(fetchOption, requestOptions));
314
+ } else {
315
+ fetchFunction = (url, requestOptions) => fetch(url, requestOptions);
316
+ }
317
+ return createAuthenticatedFetch({
318
+ fetch: fetchFunction,
319
+ credentials: ((_b = options == null ? void 0 : options.core) == null ? void 0 : _b.credentials) || []
320
+ });
321
+ }
322
+ function mergeFetchOptions(fetchOptions, requestOptions) {
323
+ const mergedOptions = { ...fetchOptions, ...requestOptions };
324
+ if (fetchOptions.headers || (requestOptions == null ? void 0 : requestOptions.headers)) {
325
+ mergedOptions.headers = mergeHeaders(fetchOptions.headers, requestOptions == null ? void 0 : requestOptions.headers);
326
+ }
327
+ return mergedOptions;
328
+ }
329
+ function mergeHeaders(defaultHeaders, requestHeaders) {
330
+ const headers = new Headers(defaultHeaders);
331
+ if (requestHeaders) {
332
+ new Headers(requestHeaders).forEach((value, key) => headers.set(key, value));
333
+ }
334
+ return headers;
335
+ }
336
+ function normalizeDirectLoaderOptions(options) {
337
+ const loadOptions = { ...options };
338
+ if (options == null ? void 0 : options.core) {
339
+ loadOptions.core = { ...options.core };
340
+ }
341
+ const topLevelBaseUri = typeof loadOptions.baseUri === "string" ? loadOptions.baseUri : void 0;
342
+ const topLevelBaseUrl = typeof loadOptions.baseUrl === "string" ? loadOptions.baseUrl : void 0;
343
+ if (topLevelBaseUri !== void 0 || topLevelBaseUrl !== void 0) {
344
+ loadOptions.core ||= {};
345
+ if (loadOptions.core.baseUrl === void 0) {
346
+ loadOptions.core.baseUrl = topLevelBaseUrl ?? topLevelBaseUri;
347
+ }
348
+ delete loadOptions.baseUri;
349
+ delete loadOptions.baseUrl;
350
+ }
351
+ return loadOptions;
352
+ }
353
+ function normalizeError(error, message) {
354
+ if (error instanceof Error) {
355
+ return error;
356
+ }
357
+ if (typeof error === "string") {
358
+ return new Error(error);
359
+ }
360
+ return new Error(message);
361
+ }
362
+ function unavailableCoreApiMethod(methodName) {
363
+ return () => {
364
+ throw new Error(
365
+ `CoreAPI.${methodName} is unavailable. Use @loaders.gl/core.createDataSource().`
366
+ );
367
+ };
368
+ }
369
+
370
+ // ../loader-utils/src/lib/scan-utils/columnar-predicate.ts
371
+ function getColumnarPredicateColumns(predicate) {
372
+ return [...new Set(getColumnarPredicatePaths(predicate).map((path) => path[0]))];
373
+ }
374
+ function getColumnarPredicatePath(property) {
375
+ return typeof property.property === "string" ? [property.property] : [...property.property];
376
+ }
377
+ function getColumnarPredicatePaths(predicate) {
378
+ const paths = /* @__PURE__ */ new Map();
379
+ visitColumnarPredicate(predicate, (child) => {
380
+ if ("property" in child.args[0]) {
381
+ const path = getColumnarPredicatePath(child.args[0]);
382
+ paths.set(path.join("\0"), path);
383
+ }
384
+ });
385
+ return [...paths.values()];
386
+ }
387
+ function validateColumnarPredicate(predicate, availableColumns) {
388
+ visitColumnarPredicate(predicate, (child) => {
389
+ if (child.op === "and" || child.op === "or") {
390
+ if (child.args.length < 2)
391
+ throw new Error(`Columnar predicate ${child.op} requires at least two child predicates`);
392
+ return;
393
+ }
394
+ if (child.op === "not") return;
395
+ const leaf = child;
396
+ const path = getColumnarPredicatePath(leaf.args[0]);
397
+ if (!path.length || path.some((component) => !component)) {
398
+ throw new Error("Columnar predicate property path must contain non-empty strings");
399
+ }
400
+ if (!availableColumns.has(path[0]))
401
+ throw new Error(`Columnar predicate column not found: ${path.join(".")}`);
402
+ if (leaf.op === "in" && leaf.args[1].length === 0) {
403
+ throw new Error("Columnar predicate in requires at least one value");
404
+ }
405
+ });
406
+ }
407
+ function isColumnarPredicateParameter(value) {
408
+ const parameterValue = value;
409
+ return typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length === 1 && Object.hasOwn(value, "parameter") && typeof parameterValue.parameter === "string" && parameterValue.parameter.length > 0;
410
+ }
411
+ function isColumnarPredicateValue(value) {
412
+ return typeof value === "boolean" || typeof value === "bigint" || typeof value === "string" || typeof value === "number" && Number.isFinite(value) || value instanceof Date && Number.isFinite(value.getTime()) || value instanceof Uint8Array;
413
+ }
414
+ function bindColumnarPredicateParameters(predicate, parameters) {
415
+ switch (predicate.op) {
416
+ case "and":
417
+ case "or":
418
+ return {
419
+ op: predicate.op,
420
+ args: predicate.args.map((child) => bindColumnarPredicateParameters(child, parameters))
421
+ };
422
+ case "not":
423
+ return {
424
+ op: "not",
425
+ args: [bindColumnarPredicateParameters(predicate.args[0], parameters)]
426
+ };
427
+ case "isNull":
428
+ return { op: "isNull", args: [copyColumnarPredicateProperty(predicate.args[0])] };
429
+ case "in":
430
+ return {
431
+ op: "in",
432
+ args: [
433
+ copyColumnarPredicateProperty(predicate.args[0]),
434
+ predicate.args[1].map((value) => bindColumnarPredicateValue(value, parameters))
435
+ ]
436
+ };
437
+ default:
438
+ return {
439
+ op: predicate.op,
440
+ args: [
441
+ copyColumnarPredicateProperty(predicate.args[0]),
442
+ bindColumnarPredicateValue(predicate.args[1], parameters)
443
+ ]
444
+ };
445
+ }
446
+ }
447
+ function visitColumnarPredicate(predicate, visitor) {
448
+ visitor(predicate);
449
+ if (predicate.op === "and" || predicate.op === "or")
450
+ predicate.args.forEach((child) => visitColumnarPredicate(child, visitor));
451
+ else if (predicate.op === "not") visitColumnarPredicate(predicate.args[0], visitor);
452
+ }
453
+ function bindColumnarPredicateValue(value, parameters) {
454
+ if (!isColumnarPredicateParameter(value)) return value;
455
+ if (!Object.hasOwn(parameters, value.parameter)) {
456
+ throw new Error(`Columnar predicate parameter ":${value.parameter}" requires a value`);
457
+ }
458
+ const parameterValue = parameters[value.parameter];
459
+ if (isColumnarPredicateParameter(parameterValue)) {
460
+ throw new Error(
461
+ `Columnar predicate parameter ":${value.parameter}" cannot reference another parameter`
462
+ );
463
+ }
464
+ if (!isColumnarPredicateValue(parameterValue)) {
465
+ throw new Error(`Columnar predicate parameter ":${value.parameter}" has an unsupported value`);
466
+ }
467
+ return copyColumnarPredicateValue(parameterValue);
468
+ }
469
+ function copyColumnarPredicateProperty(property) {
470
+ return {
471
+ ...property,
472
+ property: typeof property.property === "string" ? property.property : [...property.property]
473
+ };
474
+ }
475
+ function copyColumnarPredicateValue(value) {
476
+ if (value instanceof Uint8Array) return value.slice();
477
+ if (value instanceof Date) return new Date(value.getTime());
478
+ return value;
479
+ }
480
+
481
+ // ../loader-utils/src/lib/scan-utils/scan-query-metadata.ts
482
+ var import_crs = require("@math.gl/crs");
483
+ function createScanQueryMetadata(options) {
484
+ validateScanExecutionSupport(options.queryType, options.execution);
485
+ const schema = Object.freeze({
486
+ fields: Object.freeze(
487
+ options.schema.fields.map(
488
+ (field) => Object.freeze({ ...field, metadata: Object.freeze({ ...field.metadata }) })
489
+ )
490
+ ),
491
+ metadata: Object.freeze({ ...options.schema.metadata })
492
+ });
493
+ const columns = schema.fields.map(
494
+ (field) => {
495
+ var _a;
496
+ return Object.freeze({
497
+ name: field.name,
498
+ type: field.type,
499
+ nullable: field.nullable !== false,
500
+ role: ((_a = options.columnRoles) == null ? void 0 : _a[field.name]) || "attribute",
501
+ title: getNonEmptyMetadataValue(field.metadata, "title"),
502
+ description: getNonEmptyMetadataValue(field.metadata, "description"),
503
+ metadata: field.metadata || Object.freeze({})
504
+ });
505
+ }
506
+ );
507
+ return Object.freeze({
508
+ sourceType: options.sourceType,
509
+ queryType: options.queryType,
510
+ execution: Object.freeze({ ...options.execution }),
511
+ name: options.name,
512
+ description: options.description,
513
+ schema,
514
+ columns: Object.freeze(columns),
515
+ capabilities: Object.freeze({ ...options.capabilities }),
516
+ spatial: options.spatial ? Object.freeze({
517
+ ...options.spatial,
518
+ bounds: options.spatial.bounds ? Object.freeze({
519
+ minimum: Object.freeze([...options.spatial.bounds.minimum]),
520
+ maximum: Object.freeze([...options.spatial.bounds.maximum])
521
+ }) : void 0,
522
+ coordinateReferenceSystems: options.spatial.coordinateReferenceSystems ? Object.freeze([...options.spatial.coordinateReferenceSystems]) : void 0,
523
+ spatialReference: options.spatial.spatialReference ? (0, import_crs.createSpatialReference)(options.spatial.spatialReference) : void 0
524
+ }) : void 0,
525
+ statistics: options.statistics ? Object.freeze({ ...options.statistics }) : void 0,
526
+ levels: options.levels ? Object.freeze(
527
+ options.levels.map(
528
+ (level) => Object.freeze({
529
+ ...level,
530
+ scale: level.scale ? Object.freeze([...level.scale]) : void 0
531
+ })
532
+ )
533
+ ) : void 0
534
+ });
535
+ }
536
+ function validateScanExecutionSupport(queryType, execution) {
537
+ if (execution.status === "metadata-only") {
538
+ if (!execution.reason.trim()) {
539
+ throw new Error("Metadata-only scan support requires a concrete reason");
540
+ }
541
+ return;
542
+ }
543
+ const validMethods = {
544
+ table: ["read", "query"],
545
+ raster: ["getRaster"],
546
+ "point-cloud": ["scan"]
547
+ };
548
+ if (!validMethods[queryType].includes(execution.method)) {
549
+ throw new Error(
550
+ `Scan execution method "${execution.method}" is not valid for ${queryType} queries`
551
+ );
552
+ }
553
+ }
554
+ function getNonEmptyMetadataValue(metadata, key) {
555
+ const value = metadata == null ? void 0 : metadata[key];
556
+ return value || void 0;
557
+ }
558
+
559
+ // ../loader-utils/src/lib/scan-utils/table-query.ts
560
+ function planTableQuery(sourceColumnNames, options = {}) {
561
+ validateTableQueryOptions(sourceColumnNames, options);
562
+ const outputColumnNames = options.columns ? [...options.columns] : [...sourceColumnNames];
563
+ const predicateColumnNames = options.predicate ? getColumnarPredicateColumns(options.predicate) : [];
564
+ const requiredColumnNames = /* @__PURE__ */ new Set([...outputColumnNames, ...predicateColumnNames]);
565
+ const scanColumnNames = sourceColumnNames.filter(
566
+ (columnName) => requiredColumnNames.has(columnName)
567
+ );
568
+ const steps = [
569
+ Object.freeze({ kind: "scan", columns: Object.freeze(scanColumnNames) })
570
+ ];
571
+ if (options.predicate) {
572
+ steps.push(Object.freeze({ kind: "filter", predicate: options.predicate }));
573
+ }
574
+ steps.push(Object.freeze({ kind: "project", columns: Object.freeze(outputColumnNames) }));
575
+ if (options.limit !== void 0) {
576
+ steps.push(Object.freeze({ kind: "limit", limit: options.limit }));
577
+ }
578
+ return Object.freeze(steps);
579
+ }
580
+ function validateTableQueryOptions(sourceColumnNames, options) {
581
+ const availableColumnNames = new Set(sourceColumnNames);
582
+ const outputColumnNames = options.columns ?? sourceColumnNames;
583
+ const seenColumnNames = /* @__PURE__ */ new Set();
584
+ for (const columnName of outputColumnNames) {
585
+ if (!availableColumnNames.has(columnName)) {
586
+ throw new Error(`Table query column not found: ${columnName}`);
587
+ }
588
+ if (seenColumnNames.has(columnName)) {
589
+ throw new Error(`Table query column was selected more than once: ${columnName}`);
590
+ }
591
+ seenColumnNames.add(columnName);
592
+ }
593
+ validateTableQueryLimit(options.limit);
594
+ if (options.predicate) {
595
+ validateColumnarPredicate(options.predicate, availableColumnNames);
596
+ }
597
+ }
598
+ function validateTableQueryLimit(limit) {
599
+ if (limit !== void 0 && (!Number.isSafeInteger(limit) || limit < 0)) {
600
+ throw new Error("Table query limit must be a non-negative safe integer.");
601
+ }
602
+ }
603
+
604
+ // ../loader-utils/src/lib/scan-utils/table-scan-batch.ts
605
+ function makeTableScanBatch(table) {
606
+ return { ...table, batchType: "data", length: table.data.numRows };
607
+ }
608
+
609
+ // ../loader-utils/src/lib/scan-utils/relational-query.ts
610
+ function planRelationalQuery(sourceColumnNames, options = {}) {
611
+ var _a, _b, _c, _d, _e, _f;
612
+ const available = new Set(sourceColumnNames);
613
+ const expressionNames = /* @__PURE__ */ new Set();
614
+ for (const expression of options.expressions || []) {
615
+ if (!expression.name) throw new Error("Relational expression names must be non-empty.");
616
+ if (available.has(expression.name) || expressionNames.has(expression.name)) {
617
+ throw new Error(`Relational expression duplicates column: ${expression.name}`);
618
+ }
619
+ expressionNames.add(expression.name);
620
+ }
621
+ const aggregateNames = new Set((options.aggregates || []).map((aggregate) => aggregate.name));
622
+ const requiredColumns = /* @__PURE__ */ new Set();
623
+ const availableColumns = new Set(sourceColumnNames);
624
+ for (const expression of options.expressions || []) {
625
+ const definition = expression.expression;
626
+ if (definition.op === "column") {
627
+ validateRelationalColumnReference(definition.column, availableColumns);
628
+ if (available.has(definition.column)) requiredColumns.add(definition.column);
629
+ }
630
+ if ("left" in definition) {
631
+ validateRelationalColumnReference(definition.left, availableColumns);
632
+ validateRelationalColumnReference(definition.right, availableColumns);
633
+ if (available.has(definition.left)) requiredColumns.add(definition.left);
634
+ if (available.has(definition.right)) requiredColumns.add(definition.right);
635
+ }
636
+ availableColumns.add(expression.name);
637
+ }
638
+ for (const key of options.orderBy || []) requiredColumns.add(key.column);
639
+ for (const key of options.groupBy || []) requiredColumns.add(key);
640
+ for (const aggregate of options.aggregates || []) {
641
+ if (aggregate.column) requiredColumns.add(aggregate.column);
642
+ }
643
+ const outputColumns = (_a = options.columns) == null ? void 0 : _a.filter(
644
+ (column) => !expressionNames.has(column) && !aggregateNames.has(column)
645
+ );
646
+ const tablePlan = [
647
+ ...planTableQuery(sourceColumnNames, {
648
+ ...options,
649
+ columns: outputColumns,
650
+ predicate: options.predicate
651
+ })
652
+ ];
653
+ const scanStep = tablePlan[0];
654
+ if ((scanStep == null ? void 0 : scanStep.kind) === "scan") {
655
+ const scanColumns = new Set(scanStep.columns);
656
+ for (const column of requiredColumns) {
657
+ if (available.has(column)) scanColumns.add(column);
658
+ }
659
+ tablePlan[0] = Object.freeze({ kind: "scan", columns: Object.freeze([...scanColumns]) });
660
+ }
661
+ for (const expression of expressionNames) available.add(expression);
662
+ for (const aggregate of aggregateNames) available.add(aggregate);
663
+ for (const key of options.orderBy || []) {
664
+ if (!available.has(key.column))
665
+ throw new Error(`Relational order column not found: ${key.column}`);
666
+ }
667
+ for (const key of options.groupBy || []) {
668
+ if (!available.has(key)) throw new Error(`Relational group column not found: ${key}`);
669
+ }
670
+ for (const aggregate of options.aggregates || []) {
671
+ if (!aggregate.name) throw new Error("Relational aggregate names must be non-empty.");
672
+ if (aggregate.function !== "count" && !aggregate.column) {
673
+ throw new Error(`Relational aggregate ${aggregate.function} requires a column.`);
674
+ }
675
+ if (aggregate.column && !available.has(aggregate.column)) {
676
+ throw new Error(`Relational aggregate column not found: ${aggregate.column}`);
677
+ }
678
+ }
679
+ const relationalSteps = [];
680
+ if ((_b = options.expressions) == null ? void 0 : _b.length)
681
+ relationalSteps.push({ kind: "expression", detail: options.expressions });
682
+ if ((_c = options.orderBy) == null ? void 0 : _c.length) relationalSteps.push({ kind: "order", detail: options.orderBy });
683
+ if (((_d = options.aggregates) == null ? void 0 : _d.length) || ((_e = options.groupBy) == null ? void 0 : _e.length)) {
684
+ relationalSteps.push({
685
+ kind: "aggregate",
686
+ detail: { groupBy: options.groupBy, aggregates: options.aggregates }
687
+ });
688
+ }
689
+ if ((_f = options.union) == null ? void 0 : _f.length) relationalSteps.push({ kind: "union", detail: options.union });
690
+ if (options.join) relationalSteps.push({ kind: "join", detail: options.join });
691
+ return { tablePlan, relationalSteps: Object.freeze(relationalSteps) };
692
+ }
693
+ function validateRelationalColumnReference(columnName, availableColumns) {
694
+ if (!availableColumns.has(columnName)) {
695
+ throw new Error(`Relational expression column not found: ${columnName}`);
696
+ }
697
+ }
698
+
699
+ // ../loader-utils/src/lib/scan-utils/table-query-explain.ts
700
+ function explainTableQuery(sourceColumnNames, options, capabilities) {
701
+ const plan = planTableQuery(sourceColumnNames, options);
702
+ const outputColumns = options.columns ? [...options.columns] : [...sourceColumnNames];
703
+ const predicateColumns = options.predicate ? getColumnarPredicateColumns(options.predicate) : [];
704
+ const requiredColumns = [...plan[0].kind === "scan" ? plan[0].columns : []];
705
+ return Object.freeze({
706
+ sourceColumns: Object.freeze([...sourceColumnNames]),
707
+ outputColumns: Object.freeze(outputColumns),
708
+ requiredColumns: Object.freeze(requiredColumns),
709
+ predicateColumns: Object.freeze(predicateColumns),
710
+ plan,
711
+ capabilities: Object.freeze({ ...capabilities }),
712
+ operators: Object.freeze({
713
+ projection: createOperatorExplanation(options.columns !== void 0, capabilities.projection),
714
+ predicate: createOperatorExplanation(options.predicate !== void 0, capabilities.predicate),
715
+ limit: createOperatorExplanation(options.limit !== void 0, capabilities.limit)
716
+ })
717
+ });
718
+ }
719
+ function createOperatorExplanation(enabled, support) {
720
+ return Object.freeze({ enabled, support });
721
+ }
722
+
723
+ // dist/sql-predicate-types.js
724
+ function isSQLPredicateParameter(value) {
725
+ return isColumnarPredicateParameter(value);
726
+ }
727
+
728
+ // dist/sql-predicate-schema.js
729
+ var MAXIMUM_PREDICATE_DEPTH = 64;
730
+ var MAXIMUM_PREDICATE_NODES = 4096;
731
+ var SQL_PREDICATE_JSON_SCHEMA = {
732
+ $schema: "https://json-schema.org/draft/2020-12/schema",
733
+ $id: "https://loaders.gl/schemas/sql-predicate.schema.json",
734
+ title: "loaders.gl SQL predicate",
735
+ oneOf: [
736
+ { $ref: "#/$defs/comparison" },
737
+ { $ref: "#/$defs/in" },
738
+ { $ref: "#/$defs/isNull" },
739
+ { $ref: "#/$defs/logical" },
740
+ { $ref: "#/$defs/not" }
741
+ ],
742
+ $defs: {
743
+ property: {
744
+ type: "object",
745
+ required: ["property"],
746
+ properties: {
747
+ property: { type: "string", minLength: 1 },
748
+ quoted: { type: "boolean" }
749
+ },
750
+ additionalProperties: false
751
+ },
752
+ value: {
753
+ oneOf: [
754
+ { type: ["boolean", "number", "string"] },
755
+ {
756
+ type: "object",
757
+ required: ["parameter"],
758
+ properties: { parameter: { type: "string", minLength: 1 } },
759
+ additionalProperties: false
760
+ }
761
+ ]
762
+ },
763
+ comparison: {
764
+ type: "object",
765
+ required: ["op", "args"],
766
+ properties: {
767
+ op: { enum: ["=", "<>", "<", "<=", ">", ">="] },
768
+ args: {
769
+ type: "array",
770
+ prefixItems: [{ $ref: "#/$defs/property" }, { $ref: "#/$defs/value" }],
771
+ minItems: 2,
772
+ maxItems: 2
773
+ }
774
+ },
775
+ additionalProperties: false
776
+ },
777
+ in: {
778
+ type: "object",
779
+ required: ["op", "args"],
780
+ properties: {
781
+ op: { const: "in" },
782
+ args: {
783
+ type: "array",
784
+ prefixItems: [
785
+ { $ref: "#/$defs/property" },
786
+ { type: "array", items: { $ref: "#/$defs/value" }, minItems: 1 }
787
+ ],
788
+ minItems: 2,
789
+ maxItems: 2
790
+ }
791
+ },
792
+ additionalProperties: false
793
+ },
794
+ isNull: {
795
+ type: "object",
796
+ required: ["op", "args"],
797
+ properties: {
798
+ op: { const: "isNull" },
799
+ args: {
800
+ type: "array",
801
+ prefixItems: [{ $ref: "#/$defs/property" }],
802
+ minItems: 1,
803
+ maxItems: 1
804
+ }
805
+ },
806
+ additionalProperties: false
807
+ },
808
+ logical: {
809
+ type: "object",
810
+ required: ["op", "args"],
811
+ properties: {
812
+ op: { enum: ["and", "or"] },
813
+ args: { type: "array", items: { $ref: "#" }, minItems: 2 }
814
+ },
815
+ additionalProperties: false
816
+ },
817
+ not: {
818
+ type: "object",
819
+ required: ["op", "args"],
820
+ properties: {
821
+ op: { const: "not" },
822
+ args: { type: "array", prefixItems: [{ $ref: "#" }], minItems: 1, maxItems: 1 }
823
+ },
824
+ additionalProperties: false
825
+ }
826
+ }
827
+ };
828
+ function isSQLPredicate(value) {
829
+ try {
830
+ validateSQLPredicate(value);
831
+ return true;
832
+ } catch {
833
+ return false;
834
+ }
835
+ }
836
+ function validateSQLPredicate(value) {
837
+ const state = { nodes: 0 };
838
+ validatePredicateNode(value, "$", 0, state);
839
+ }
840
+ function validatePredicateNode(value, path, depth, state) {
841
+ if (depth > MAXIMUM_PREDICATE_DEPTH) {
842
+ throw new Error(`SQL predicate ${path} exceeds the maximum nesting depth`);
843
+ }
844
+ state.nodes++;
845
+ if (state.nodes > MAXIMUM_PREDICATE_NODES) {
846
+ throw new Error("SQL predicate exceeds the maximum node count");
847
+ }
848
+ if (!isRecord(value) || !hasExactKeys(value, ["op", "args"])) {
849
+ throw new Error(`SQL predicate ${path} must contain only op and args`);
850
+ }
851
+ if (typeof value.op !== "string" || !Array.isArray(value.args)) {
852
+ throw new Error(`SQL predicate ${path} requires string op and array args`);
853
+ }
854
+ switch (value.op) {
855
+ case "and":
856
+ case "or":
857
+ if (value.args.length < 2) {
858
+ throw new Error(`SQL predicate ${path}.${value.op} requires at least two arguments`);
859
+ }
860
+ for (let index = 0; index < value.args.length; index++) {
861
+ validatePredicateNode(value.args[index], `${path}.args[${index}]`, depth + 1, state);
862
+ }
863
+ return;
864
+ case "not":
865
+ if (value.args.length !== 1) {
866
+ throw new Error(`SQL predicate ${path}.not requires exactly one argument`);
867
+ }
868
+ validatePredicateNode(value.args[0], `${path}.args[0]`, depth + 1, state);
869
+ return;
870
+ case "isNull":
871
+ if (value.args.length !== 1) {
872
+ throw new Error(`SQL predicate ${path}.isNull requires exactly one argument`);
873
+ }
874
+ validatePredicateProperty(value.args[0], `${path}.args[0]`);
875
+ return;
876
+ case "in":
877
+ if (value.args.length !== 2 || !Array.isArray(value.args[1]) || value.args[1].length === 0) {
878
+ throw new Error(`SQL predicate ${path}.in requires a property and non-empty value list`);
879
+ }
880
+ validatePredicateProperty(value.args[0], `${path}.args[0]`);
881
+ value.args[1].forEach((item, index) => validatePredicateValue(item, `${path}.args[1][${index}]`));
882
+ return;
883
+ case "=":
884
+ case "<>":
885
+ case "<":
886
+ case "<=":
887
+ case ">":
888
+ case ">=":
889
+ if (value.args.length !== 2) {
890
+ throw new Error(`SQL predicate ${path}.${value.op} requires exactly two arguments`);
891
+ }
892
+ validatePredicateProperty(value.args[0], `${path}.args[0]`);
893
+ validatePredicateValue(value.args[1], `${path}.args[1]`);
894
+ return;
895
+ default:
896
+ throw new Error(`SQL predicate ${path} has unsupported operator ${JSON.stringify(value.op)}`);
897
+ }
898
+ }
899
+ function validatePredicateProperty(value, path) {
900
+ if (!isRecord(value) || !hasAllowedKeys(value, ["property", "quoted"]) || typeof value.property !== "string" || value.property.length === 0 || value.quoted !== void 0 && typeof value.quoted !== "boolean") {
901
+ throw new Error(`SQL predicate ${path} requires a non-empty property reference`);
902
+ }
903
+ }
904
+ function validatePredicateValue(value, path) {
905
+ if (isSQLPredicateParameter(value)) {
906
+ return;
907
+ }
908
+ if (typeof value === "boolean" || typeof value === "bigint" || typeof value === "string" || value instanceof Uint8Array) {
909
+ return;
910
+ }
911
+ if (typeof value === "number" && Number.isFinite(value)) {
912
+ return;
913
+ }
914
+ if (value instanceof Date && Number.isFinite(value.getTime())) {
915
+ return;
916
+ }
917
+ throw new Error(`SQL predicate ${path} contains an unsupported scalar value`);
918
+ }
919
+ function isRecord(value) {
920
+ return typeof value === "object" && value !== null && !Array.isArray(value);
921
+ }
922
+ function hasExactKeys(value, expectedKeys) {
923
+ const keys = Object.keys(value);
924
+ return keys.length === expectedKeys.length && expectedKeys.every((key) => keys.includes(key));
925
+ }
926
+ function hasAllowedKeys(value, allowedKeys) {
927
+ return Object.keys(value).every((key) => allowedKeys.includes(key));
928
+ }
929
+
930
+ // dist/compile-table-query.js
931
+ function compileSQLTableQuery(query, options) {
932
+ validateSQLTableQuery(query);
933
+ const context = {
934
+ dialect: options.dialect,
935
+ namedParameters: options.parameters,
936
+ parameters: []
937
+ };
938
+ return {
939
+ sql: compileTableStatement(query, context),
940
+ parameters: context.parameters
941
+ };
942
+ }
943
+ function compileTableStatement(query, context) {
944
+ var _a, _b;
945
+ const projection = compileProjection(query);
946
+ const table = [query.catalogName, query.schemaName, query.tableName].filter((identifier) => identifier !== void 0).map(quoteSQLIdentifier).join(".");
947
+ const fromClause = query.join ? compileJoinFromClause(query, table, context) : `FROM ${table}`;
948
+ const clauses = [`SELECT ${projection}`, fromClause];
949
+ if (query.predicate) {
950
+ clauses.push(`WHERE ${compileSQLPredicate(query.predicate, context)}`);
951
+ }
952
+ if ((_a = query.groupBy) == null ? void 0 : _a.length) {
953
+ clauses.push(`GROUP BY ${query.groupBy.map(quoteSQLIdentifier).join(", ")}`);
954
+ }
955
+ let sql = clauses.join("\n");
956
+ for (const child of query.union || []) {
957
+ const childQuery = {
958
+ tableName: child.source,
959
+ ...child.query || {}
960
+ };
961
+ validateSQLTableQuery(childQuery);
962
+ const childSQL = compileTableStatement(childQuery, context);
963
+ const branchSQL = hasBranchLocalModifiers(childQuery) ? `(${childSQL})` : childSQL;
964
+ sql = `${sql}
965
+ UNION ALL
966
+ ${branchSQL}`;
967
+ }
968
+ if ((_b = query.orderBy) == null ? void 0 : _b.length)
969
+ sql += `
970
+ ORDER BY ${query.orderBy.map(compileOrderKey).join(", ")}`;
971
+ if (query.limit !== void 0)
972
+ sql += `
973
+ LIMIT ${query.limit}`;
974
+ return sql;
975
+ }
976
+ function compileJoinFromClause(query, table, context) {
977
+ const join = query.join;
978
+ if (!join)
979
+ return `FROM ${table}`;
980
+ validateSQLIdentifier(join.child.source);
981
+ validateSQLIdentifier(join.left);
982
+ validateSQLIdentifier(join.right);
983
+ const childTable = quoteSQLIdentifier(join.child.source);
984
+ const rightRelation = join.child.query ? `(${compileTableStatement({ tableName: join.child.source, ...join.child.query }, context)})` : childTable;
985
+ return `FROM ${table} JOIN ${rightRelation} AS ${childTable} ON ${table}.${quoteSQLIdentifier(join.left)} = ${childTable}.${quoteSQLIdentifier(join.right)}`;
986
+ }
987
+ function compileProjection(query) {
988
+ var _a, _b;
989
+ const expressions = query.expressions || [];
990
+ const expressionByName = new Map(expressions.map((expression) => [expression.name, expression]));
991
+ const aggregates = query.aggregates || [];
992
+ const aggregateByName = new Map(aggregates.map((aggregate) => [aggregate.name, aggregate]));
993
+ const columns = query.columns === void 0 ? void 0 : [...query.columns];
994
+ const projectionColumns = columns || (((_a = query.groupBy) == null ? void 0 : _a.length) || ((_b = query.aggregates) == null ? void 0 : _b.length) ? [...query.groupBy || []] : []);
995
+ const selections = projectionColumns.map((column) => {
996
+ const expression = expressionByName.get(column);
997
+ if (expression) {
998
+ return `${compileRelationalExpression(expression.expression)} AS ${quoteSQLIdentifier(expression.name)}`;
999
+ }
1000
+ const aggregate = aggregateByName.get(column);
1001
+ return aggregate ? `${compileAggregate(aggregate)} AS ${quoteSQLIdentifier(aggregate.name)}` : compileProjectionColumn(column, query);
1002
+ });
1003
+ if (!selections.length)
1004
+ return expressions.length ? expressions.map((expression) => `${compileRelationalExpression(expression.expression)} AS ${quoteSQLIdentifier(expression.name)}`).join(", ") : aggregates.length ? aggregates.map((aggregate) => `${compileAggregate(aggregate)} AS ${quoteSQLIdentifier(aggregate.name)}`).join(", ") : "*";
1005
+ return selections.join(", ");
1006
+ }
1007
+ function compileProjectionColumn(column, query) {
187
1008
  var _a;
188
- const fetchFunction = (_a = options == null ? void 0 : options.core) == null ? void 0 : _a.fetch;
189
- if (fetchFunction && typeof fetchFunction === "function") {
190
- return (url, fetchOptions2) => fetchFunction(url, fetchOptions2);
191
- }
192
- const fetchOptions = options == null ? void 0 : options.fetch;
193
- if (fetchOptions && typeof fetchOptions !== "function") {
194
- return (url, requestOptions) => fetch(url, mergeFetchOptions(fetchOptions, requestOptions));
195
- }
196
- return (url, requestOptions) => fetch(url, requestOptions);
1009
+ const childSource = (_a = query.join) == null ? void 0 : _a.child.source;
1010
+ return childSource && column.startsWith(`${childSource}.`) ? column.split(".").map(quoteSQLIdentifier).join(".") : quoteSQLIdentifier(column);
197
1011
  }
198
- function mergeFetchOptions(fetchOptions, requestOptions) {
199
- const mergedOptions = { ...fetchOptions, ...requestOptions };
200
- if (fetchOptions.headers || (requestOptions == null ? void 0 : requestOptions.headers)) {
201
- mergedOptions.headers = mergeHeaders(fetchOptions.headers, requestOptions == null ? void 0 : requestOptions.headers);
202
- }
203
- return mergedOptions;
1012
+ function hasBranchLocalModifiers(query) {
1013
+ var _a, _b;
1014
+ return Boolean(query.limit !== void 0 || ((_a = query.orderBy) == null ? void 0 : _a.length) || ((_b = query.union) == null ? void 0 : _b.length));
1015
+ }
1016
+ function compileRelationalExpression(expression) {
1017
+ switch (expression.op) {
1018
+ case "column":
1019
+ return quoteSQLIdentifier(expression.column);
1020
+ case "literal":
1021
+ return expression.value === null ? "NULL" : typeof expression.value === "string" ? `'${expression.value.replace(/'/g, "''")}'` : String(expression.value);
1022
+ case "add":
1023
+ return `(${quoteSQLIdentifier(expression.left)} + ${quoteSQLIdentifier(expression.right)})`;
1024
+ case "subtract":
1025
+ return `(${quoteSQLIdentifier(expression.left)} - ${quoteSQLIdentifier(expression.right)})`;
1026
+ case "multiply":
1027
+ return `(${quoteSQLIdentifier(expression.left)} * ${quoteSQLIdentifier(expression.right)})`;
1028
+ case "divide":
1029
+ return `(${quoteSQLIdentifier(expression.left)} / NULLIF(${quoteSQLIdentifier(expression.right)}, 0))`;
1030
+ }
1031
+ }
1032
+ function compileAggregate(aggregate) {
1033
+ const column = aggregate.column ? quoteSQLIdentifier(aggregate.column) : "*";
1034
+ return `${aggregate.function.toUpperCase()}(${column})`;
1035
+ }
1036
+ function compileOrderKey(orderKey) {
1037
+ var _a;
1038
+ const direction = ((_a = orderKey.direction) == null ? void 0 : _a.toUpperCase()) || "ASC";
1039
+ const nulls = orderKey.nulls ? ` NULLS ${orderKey.nulls.toUpperCase()}` : "";
1040
+ return `${quoteSQLIdentifier(orderKey.column)} ${direction}${nulls}`;
204
1041
  }
205
- function mergeHeaders(defaultHeaders, requestHeaders) {
206
- const headers = new Headers(defaultHeaders);
207
- if (requestHeaders) {
208
- new Headers(requestHeaders).forEach((value, key) => headers.set(key, value));
1042
+ function compileSQLPredicate(predicate, context) {
1043
+ switch (predicate.op) {
1044
+ case "and":
1045
+ case "or":
1046
+ return `(${predicate.args.map((child) => compileSQLPredicate(child, context)).join(` ${predicate.op.toUpperCase()} `)})`;
1047
+ case "not":
1048
+ return `(NOT ${compileSQLPredicate(predicate.args[0], context)})`;
1049
+ case "isNull":
1050
+ return `(${quoteSQLProperty(predicate.args[0])} IS NULL)`;
1051
+ case "in":
1052
+ return `(${quoteSQLProperty(predicate.args[0])} IN (${predicate.args[1].map((value) => compileSQLPredicateValue(value, context)).join(", ")}))`;
1053
+ default:
1054
+ return `(${quoteSQLProperty(predicate.args[0])} ${predicate.op} ${compileSQLPredicateValue(predicate.args[1], context)})`;
209
1055
  }
210
- return headers;
211
1056
  }
212
- function normalizeDirectLoaderOptions(options) {
213
- const loadOptions = { ...options };
214
- if (options == null ? void 0 : options.core) {
215
- loadOptions.core = { ...options.core };
1057
+ function compileSQLPredicateValue(value, context) {
1058
+ const scalar = isSQLPredicateParameter(value) ? resolveSQLPredicateParameter(value.parameter, context.namedParameters) : value;
1059
+ context.parameters.push(scalar);
1060
+ return getSQLPlaceholder(context.dialect, context.parameters.length);
1061
+ }
1062
+ function resolveSQLPredicateParameter(parameterName, parameters) {
1063
+ if (!parameters || !Object.hasOwn(parameters, parameterName)) {
1064
+ throw new Error(`SQL predicate parameter ":${parameterName}" requires a value`);
216
1065
  }
217
- const topLevelBaseUri = typeof loadOptions.baseUri === "string" ? loadOptions.baseUri : void 0;
218
- const topLevelBaseUrl = typeof loadOptions.baseUrl === "string" ? loadOptions.baseUrl : void 0;
219
- if (topLevelBaseUri !== void 0 || topLevelBaseUrl !== void 0) {
220
- loadOptions.core ||= {};
221
- if (loadOptions.core.baseUrl === void 0) {
222
- loadOptions.core.baseUrl = topLevelBaseUrl ?? topLevelBaseUri;
1066
+ const value = parameters[parameterName];
1067
+ validateSQLPredicate({ op: "=", args: [{ property: "_parameter" }, value] });
1068
+ return value;
1069
+ }
1070
+ function getSQLPlaceholder(_dialect, _position) {
1071
+ return "?";
1072
+ }
1073
+ function quoteSQLProperty(property) {
1074
+ return property.quoted ? quoteSQLIdentifier(property.property) : property.property.split(".").map(quoteSQLIdentifier).join(".");
1075
+ }
1076
+ function quoteSQLIdentifier(identifier) {
1077
+ validateSQLIdentifier(identifier);
1078
+ return `"${identifier.replace(/"/g, '""')}"`;
1079
+ }
1080
+ function validateSQLTableQuery(query) {
1081
+ var _a;
1082
+ validateSQLIdentifier(query.tableName);
1083
+ if (query.schemaName !== void 0)
1084
+ validateSQLIdentifier(query.schemaName);
1085
+ if (query.catalogName !== void 0)
1086
+ validateSQLIdentifier(query.catalogName);
1087
+ const seenColumns = /* @__PURE__ */ new Set();
1088
+ if (((_a = query.columns) == null ? void 0 : _a.length) === 0) {
1089
+ throw new Error("SQL table-query projections must select at least one column.");
1090
+ }
1091
+ for (const column of query.columns ?? []) {
1092
+ validateSQLIdentifier(column);
1093
+ if (seenColumns.has(column)) {
1094
+ throw new Error(`Table query column was selected more than once: ${column}`);
1095
+ }
1096
+ seenColumns.add(column);
1097
+ }
1098
+ if (query.limit !== void 0 && (!Number.isSafeInteger(query.limit) || query.limit < 0)) {
1099
+ throw new Error("Table query limit must be a non-negative safe integer.");
1100
+ }
1101
+ if (query.predicate)
1102
+ validateSQLPredicate(query.predicate);
1103
+ validateRelationalQuery(query);
1104
+ }
1105
+ function validateRelationalQuery(query) {
1106
+ const expressionNames = /* @__PURE__ */ new Set();
1107
+ for (const expression of query.expressions || []) {
1108
+ validateSQLIdentifier(expression.name);
1109
+ if (expressionNames.has(expression.name))
1110
+ throw new Error(`Relational expression duplicates column: ${expression.name}`);
1111
+ expressionNames.add(expression.name);
1112
+ const definition = expression.expression;
1113
+ if (definition.op === "column")
1114
+ validateSQLIdentifier(definition.column);
1115
+ if ("left" in definition) {
1116
+ validateSQLIdentifier(definition.left);
1117
+ validateSQLIdentifier(definition.right);
223
1118
  }
224
- delete loadOptions.baseUri;
225
- delete loadOptions.baseUrl;
226
1119
  }
227
- return loadOptions;
228
- }
229
- function normalizeError(error, message) {
230
- if (error instanceof Error) {
231
- return error;
1120
+ for (const column of query.groupBy || [])
1121
+ validateSQLIdentifier(column);
1122
+ for (const key of query.orderBy || []) {
1123
+ validateSQLIdentifier(key.column);
1124
+ if (key.direction && key.direction !== "asc" && key.direction !== "desc")
1125
+ throw new Error(`Invalid order direction: ${key.direction}`);
1126
+ if (key.nulls && key.nulls !== "first" && key.nulls !== "last")
1127
+ throw new Error(`Invalid null placement: ${key.nulls}`);
232
1128
  }
233
- if (typeof error === "string") {
234
- return new Error(error);
1129
+ for (const aggregate of query.aggregates || []) {
1130
+ validateSQLIdentifier(aggregate.name);
1131
+ if (aggregate.function !== "count" && !aggregate.column)
1132
+ throw new Error(`Relational aggregate ${aggregate.function} requires a column.`);
1133
+ if (aggregate.column)
1134
+ validateSQLIdentifier(aggregate.column);
235
1135
  }
236
- return new Error(message);
237
1136
  }
238
- function unavailableCoreApiMethod(methodName) {
239
- return () => {
240
- throw new Error(
241
- `CoreAPI.${methodName} is unavailable. Use @loaders.gl/core.createDataSource().`
242
- );
243
- };
1137
+ function validateSQLIdentifier(identifier) {
1138
+ if (!identifier || identifier.includes("\0")) {
1139
+ throw new Error("SQL table-query identifiers must be non-empty and cannot contain NUL bytes.");
1140
+ }
244
1141
  }
245
1142
 
246
1143
  // dist/sql-utils.js
@@ -388,7 +1285,7 @@ function serializeArrowType(arrowType) {
388
1285
  return "bool";
389
1286
  case arrow.Int:
390
1287
  const intType = arrowType;
391
- return `${intType.isSigned ? "u" : ""}int${intType.bitWidth}`;
1288
+ return `${intType.isSigned ? "" : "u"}int${intType.bitWidth}`;
392
1289
  case arrow.Int8:
393
1290
  return "int8";
394
1291
  case arrow.Int16:
@@ -547,7 +1444,7 @@ function deserializeArrowType(dataType, options) {
547
1444
  const children = dataType.children.map(
548
1445
  (arrowField) => deserializeArrowField(arrowField, options)
549
1446
  );
550
- return new arrow.Map_(children, dataType.keysSorted);
1447
+ return new arrow.Map_(children[0], dataType.keysSorted);
551
1448
  }
552
1449
  case "list": {
553
1450
  const field = deserializeArrowField(dataType.children[0], options);
@@ -967,7 +1864,7 @@ function getTableRowAsObject(table, rowIndex, target, copy) {
967
1864
  if (table.schema) {
968
1865
  const objectRow2 = target || {};
969
1866
  for (let i = 0; i < table.schema.fields.length; i++) {
970
- objectRow2[table.schema.fields[i].name] = table.features[rowIndex][i];
1867
+ objectRow2[table.schema.fields[i].name] = table.features[rowIndex][table.schema.fields[i].name];
971
1868
  }
972
1869
  return objectRow2;
973
1870
  }
@@ -1189,9 +2086,8 @@ function convertTable(table, shape) {
1189
2086
  }
1190
2087
  }
1191
2088
  function convertToColumnarTable(table) {
1192
- var _a;
1193
2089
  const schema = table.schema || deduceTableSchema(table);
1194
- const fields = ((_a = table.schema) == null ? void 0 : _a.fields) || [];
2090
+ const fields = schema.fields;
1195
2091
  if (table.shape === "columnar-table") {
1196
2092
  return { ...table, schema };
1197
2093
  }
@@ -1341,6 +2237,28 @@ function getQualifiedTableName(options) {
1341
2237
  return identifiers.map((identifier) => quoteSqlIdentifier(identifier)).join(".");
1342
2238
  }
1343
2239
 
2240
+ // dist/table-query-capabilities.js
2241
+ var ARROW_TABLE_QUERY_CAPABILITIES = Object.freeze({
2242
+ projection: "residual",
2243
+ predicate: "residual",
2244
+ limit: "residual",
2245
+ streaming: false,
2246
+ cancellation: true,
2247
+ expressions: "residual",
2248
+ orderBy: "residual",
2249
+ aggregates: "residual"
2250
+ });
2251
+ var SQL_DATA_SOURCE_TABLE_QUERY_CAPABILITIES = Object.freeze({
2252
+ projection: "pushdown",
2253
+ predicate: "pushdown",
2254
+ limit: "pushdown",
2255
+ streaming: false,
2256
+ cancellation: false,
2257
+ expressions: "pushdown",
2258
+ orderBy: "pushdown",
2259
+ aggregates: "pushdown"
2260
+ });
2261
+
1344
2262
  // dist/sql-source.js
1345
2263
  var SQL_ADAPTER_FACTORIES = /* @__PURE__ */ new Map();
1346
2264
  function registerSQLAdapter(type, factory) {
@@ -1374,6 +2292,8 @@ var SQL_SOURCE_DEFAULT_OPTIONS = {
1374
2292
  }
1375
2293
  };
1376
2294
  var SQLDataSource = class extends DataSource {
2295
+ /** Optimization and execution capabilities of portable table-bound queries. */
2296
+ tableQueryCapabilities = SQL_DATA_SOURCE_TABLE_QUERY_CAPABILITIES;
1377
2297
  sourceType;
1378
2298
  adapterFactory;
1379
2299
  adapterPromise = null;
@@ -1411,74 +2331,751 @@ var SQLDataSource = class extends DataSource {
1411
2331
  return await adapter.getTableSchema(options);
1412
2332
  }
1413
2333
  /** Executes a SQL query and returns object rows. */
1414
- async queryRows(sqlText, options = {}) {
2334
+ async queryRows(query, options = {}) {
2335
+ const adapter = await this.getAdapter();
2336
+ const compiledQuery = this.compileQuery(query, options);
2337
+ return await adapter.executeRows(compiledQuery.sql, compiledQuery.options);
2338
+ }
2339
+ /** Executes a SQL query and returns a loaders.gl Arrow table. */
2340
+ async queryArrow(query, options = {}) {
2341
+ const adapter = await this.getAdapter();
2342
+ const compiledQuery = this.compileQuery(query, options);
2343
+ if (adapter.executeArrow) {
2344
+ return await adapter.executeArrow(compiledQuery.sql, compiledQuery.options);
2345
+ }
2346
+ const rows = await adapter.executeRows(compiledQuery.sql, compiledQuery.options);
2347
+ return convertRowsToArrowTable(rows);
2348
+ }
2349
+ /** Closes any underlying adapter connection. */
2350
+ async close() {
2351
+ if (!this.adapterPromise) {
2352
+ return;
2353
+ }
2354
+ const adapter = await this.adapterPromise;
2355
+ await adapter.close();
2356
+ this.adapterPromise = null;
2357
+ this.metadataPromise = null;
2358
+ }
2359
+ async getAdapter() {
2360
+ if (!this.adapterPromise) {
2361
+ this.adapterPromise = this.loadAdapter();
2362
+ }
2363
+ return await this.adapterPromise;
2364
+ }
2365
+ /** Converts a portable query object to SQL while leaving raw SQL text unchanged. */
2366
+ compileQuery(query, options) {
2367
+ if (typeof query === "string") {
2368
+ return { sql: query, options };
2369
+ }
2370
+ const namedParameters = options.parameters && !Array.isArray(options.parameters) ? options.parameters : void 0;
2371
+ const compiledQuery = compileSQLTableQuery(query, {
2372
+ dialect: getSQLTableQueryDialect(this.sourceType),
2373
+ parameters: namedParameters
2374
+ });
2375
+ return {
2376
+ sql: compiledQuery.sql,
2377
+ options: { signal: options.signal, parameters: compiledQuery.parameters }
2378
+ };
2379
+ }
2380
+ async loadAdapter() {
2381
+ var _a, _b;
2382
+ try {
2383
+ const runtimeFactory = isNodeRuntime() ? (_a = this.options.sql) == null ? void 0 : _a.nodeAdapterFactory : (_b = this.options.sql) == null ? void 0 : _b.browserAdapterFactory;
2384
+ const factory = runtimeFactory || this.adapterFactory;
2385
+ if (!factory) {
2386
+ throw new Error(`No SQL adapter is registered for source type "${this.sourceType}".`);
2387
+ }
2388
+ const adapter = await factory({
2389
+ coreApi: this.coreApi,
2390
+ options: this.options,
2391
+ sourceType: this.sourceType,
2392
+ url: this.url
2393
+ });
2394
+ await adapter.connect();
2395
+ return adapter;
2396
+ } catch (error) {
2397
+ throw this.reportError(error, `Failed to create SQL adapter for ${this.sourceType} from ${this.url}`);
2398
+ }
2399
+ }
2400
+ async loadMetadata() {
1415
2401
  const adapter = await this.getAdapter();
1416
- return await adapter.executeRows(sqlText, options);
2402
+ const [catalogs, schemas, tables] = await Promise.all([
2403
+ adapter.listCatalogs(),
2404
+ adapter.listSchemas(),
2405
+ adapter.listTables()
2406
+ ]);
2407
+ return {
2408
+ type: this.sourceType,
2409
+ capabilities: adapter.capabilities,
2410
+ catalogs,
2411
+ schemas,
2412
+ tables
2413
+ };
2414
+ }
2415
+ };
2416
+ function getSQLTableQueryDialect(sourceType) {
2417
+ if (sourceType === "duckdb-sql")
2418
+ return "duckdb";
2419
+ if (sourceType === "snowflake-sql")
2420
+ return "snowflake";
2421
+ throw new Error(`Portable table queries are not supported for SQL source type "${sourceType}".`);
2422
+ }
2423
+
2424
+ // dist/query-arrow-table.js
2425
+ var arrow6 = __toESM(require("apache-arrow"), 1);
2426
+
2427
+ // dist/table-query.js
2428
+ function planTableQuery2(sourceColumnNames, options = {}) {
2429
+ if (options.predicate) {
2430
+ validateSQLPredicate(options.predicate);
2431
+ }
2432
+ return planTableQuery(sourceColumnNames, options);
2433
+ }
2434
+ function explainTableQuery2(sourceColumnNames, options = {}) {
2435
+ if (options.predicate) {
2436
+ validateSQLPredicate(options.predicate);
2437
+ }
2438
+ return explainTableQuery(sourceColumnNames, options, SQL_DATA_SOURCE_TABLE_QUERY_CAPABILITIES);
2439
+ }
2440
+ function getSQLPredicateColumnNames(predicate) {
2441
+ return getColumnarPredicateColumns(predicate);
2442
+ }
2443
+
2444
+ // dist/query-arrow-table.js
2445
+ function explainArrowTableQuery(sourceTable, options = {}) {
2446
+ if (options.predicate) {
2447
+ validateSQLPredicate(options.predicate);
2448
+ }
2449
+ return explainTableQuery(sourceTable.data.schema.fields.map((field) => field.name), options, ARROW_TABLE_QUERY_CAPABILITIES);
2450
+ }
2451
+ function queryArrowTable(sourceTable, options = {}) {
2452
+ var _a, _b;
2453
+ throwIfAborted(options.signal);
2454
+ if (options.join) {
2455
+ validateArrowJoinQuery(sourceTable, options);
2456
+ }
2457
+ if (options.join && hasRelationalOperatorsExceptJoin(options)) {
2458
+ throw new Error("Arrow joins cannot yet be combined with other relational operators.");
2459
+ }
2460
+ if (options.join && !hasRelationalOperatorsExceptJoin(options)) {
2461
+ return queryArrowJoin(sourceTable, options);
2462
+ }
2463
+ if (hasRelationalOperators(options)) {
2464
+ return queryArrowTableRelational(sourceTable, options);
2465
+ }
2466
+ const sourceData = sourceTable.data;
2467
+ const plan = planTableQuery2(sourceData.schema.fields.map((field) => field.name), options);
2468
+ const scannedData = sourceData.select([...getScanStep(plan).columns]);
2469
+ const projectedData = scannedData.select([...getProjectStep(plan).columns]);
2470
+ const predicate = (_a = getFilterStep(plan)) == null ? void 0 : _a.predicate;
2471
+ const limit = ((_b = getLimitStep(plan)) == null ? void 0 : _b.limit) ?? Number.POSITIVE_INFINITY;
2472
+ if (!predicate) {
2473
+ return wrapArrowTable(projectedData.slice(0, limit));
2474
+ }
2475
+ const predicateColumns = getPredicateColumns(scannedData, getSQLPredicateColumnNames(predicate));
2476
+ const matchingRowIndices = [];
2477
+ for (let rowIndex = 0; rowIndex < scannedData.numRows && matchingRowIndices.length < limit; rowIndex++) {
2478
+ throwIfAborted(options.signal);
2479
+ if (evaluatePredicate(predicate, predicateColumns, rowIndex) === true) {
2480
+ matchingRowIndices.push(rowIndex);
2481
+ }
2482
+ }
2483
+ if (matchingRowIndices.length === 0) {
2484
+ return wrapArrowTable(projectedData.slice(0, 0));
2485
+ }
2486
+ const outputColumns = {};
2487
+ for (const field of projectedData.schema.fields) {
2488
+ const sourceColumn = projectedData.getChild(field.name);
2489
+ if (!sourceColumn) {
2490
+ throw new Error(`Arrow query could not read column "${field.name}".`);
2491
+ }
2492
+ const values = matchingRowIndices.map((rowIndex) => sourceColumn.get(rowIndex));
2493
+ outputColumns[field.name] = arrow6.vectorFromArray(values, sourceColumn.type);
2494
+ }
2495
+ return wrapArrowTable(new arrow6.Table(projectedData.schema, outputColumns));
2496
+ }
2497
+ function queryArrowTableRelational(sourceTable, options) {
2498
+ var _a, _b, _c, _d, _e, _f;
2499
+ const sourceData = sourceTable.data;
2500
+ const sourceColumnNames = sourceData.schema.fields.map((field) => field.name);
2501
+ const relationalPlan = planRelationalQuery(sourceColumnNames, options);
2502
+ const scanStep = relationalPlan.tablePlan.find((step) => step.kind === "scan");
2503
+ if (!scanStep || scanStep.kind !== "scan") {
2504
+ throw new Error("Arrow relational query plan is missing a scan step.");
2505
+ }
2506
+ const scannedTable = wrapArrowTable(sourceData.select([...scanStep.columns]));
2507
+ const filteredTable = queryArrowTable(scannedTable, {
2508
+ predicate: options.predicate,
2509
+ columns: scanStep.columns,
2510
+ signal: options.signal
2511
+ });
2512
+ let rows = arrowTableToRows(filteredTable.data);
2513
+ for (const child of options.union || []) {
2514
+ const childTable = (_a = options.tables) == null ? void 0 : _a[child.source];
2515
+ if (!childTable)
2516
+ throw new Error(`Arrow union source not found: ${child.source}`);
2517
+ const childResult = queryArrowTable(childTable, {
2518
+ ...child.query || {},
2519
+ columns: getUnionChildColumns(sourceColumnNames, options),
2520
+ signal: options.signal
2521
+ });
2522
+ rows = rows.concat(arrowTableToRows(childResult.data));
2523
+ }
2524
+ for (const expression of options.expressions || []) {
2525
+ for (const row of rows) {
2526
+ row[expression.name] = evaluateRelationalExpression(expression, row);
2527
+ }
2528
+ }
2529
+ if (((_b = options.groupBy) == null ? void 0 : _b.length) || ((_c = options.aggregates) == null ? void 0 : _c.length)) {
2530
+ rows = aggregateRows(rows, options.groupBy || [], options.aggregates || []);
2531
+ }
2532
+ if ((_d = options.orderBy) == null ? void 0 : _d.length) {
2533
+ const orderBy = options.orderBy;
2534
+ rows = rows.map((row, index) => ({ row, index })).sort((left, right) => compareRows(left.row, right.row, orderBy) || left.index - right.index).map((entry) => entry.row);
2535
+ }
2536
+ const outputColumns = options.columns || (((_e = options.groupBy) == null ? void 0 : _e.length) || ((_f = options.aggregates) == null ? void 0 : _f.length) ? [...options.groupBy || [], ...(options.aggregates || []).map((aggregate) => aggregate.name)] : sourceColumnNames);
2537
+ const outputRows = rows.map((row) => {
2538
+ const output = {};
2539
+ for (const columnName of outputColumns) {
2540
+ if (!(columnName in row)) {
2541
+ throw new Error(`Arrow relational query column not found: ${columnName}`);
2542
+ }
2543
+ output[columnName] = row[columnName];
2544
+ }
2545
+ return output;
2546
+ });
2547
+ const limit = options.limit === void 0 ? outputRows.length : options.limit;
2548
+ const limitedRows = outputRows.slice(0, limit);
2549
+ return limitedRows.length ? convertRowsToArrowTable(limitedRows) : createEmptyRelationalResult(sourceData, outputColumns, options);
2550
+ }
2551
+ function getUnionChildColumns(sourceColumnNames, options) {
2552
+ var _a, _b;
2553
+ const expressionNames = new Set((options.expressions || []).map((expression) => expression.name));
2554
+ const aggregateNames = new Set((options.aggregates || []).map((aggregate) => aggregate.name));
2555
+ const outputColumns = options.columns || (((_a = options.groupBy) == null ? void 0 : _a.length) || ((_b = options.aggregates) == null ? void 0 : _b.length) ? [...options.groupBy || [], ...(options.aggregates || []).map((aggregate) => aggregate.name)] : sourceColumnNames);
2556
+ const requiredColumns = new Set(outputColumns.filter((column) => !expressionNames.has(column) && !aggregateNames.has(column)));
2557
+ for (const expression of options.expressions || []) {
2558
+ const definition = expression.expression;
2559
+ if (definition.op === "column")
2560
+ requiredColumns.add(definition.column);
2561
+ if ("left" in definition) {
2562
+ requiredColumns.add(definition.left);
2563
+ requiredColumns.add(definition.right);
2564
+ }
2565
+ }
2566
+ for (const key of options.orderBy || []) {
2567
+ if (!expressionNames.has(key.column) && !aggregateNames.has(key.column)) {
2568
+ requiredColumns.add(key.column);
2569
+ }
2570
+ }
2571
+ for (const column of options.groupBy || [])
2572
+ requiredColumns.add(column);
2573
+ for (const aggregate of options.aggregates || []) {
2574
+ if (aggregate.column)
2575
+ requiredColumns.add(aggregate.column);
2576
+ }
2577
+ return sourceColumnNames.filter((column) => requiredColumns.has(column));
2578
+ }
2579
+ function hasRelationalOperators(options) {
2580
+ var _a, _b, _c, _d, _e;
2581
+ return Boolean(((_a = options.expressions) == null ? void 0 : _a.length) || ((_b = options.orderBy) == null ? void 0 : _b.length) || ((_c = options.groupBy) == null ? void 0 : _c.length) || ((_d = options.aggregates) == null ? void 0 : _d.length) || ((_e = options.union) == null ? void 0 : _e.length) || options.join);
2582
+ }
2583
+ function hasRelationalOperatorsExceptJoin(options) {
2584
+ var _a, _b, _c, _d, _e;
2585
+ return Boolean(((_a = options.expressions) == null ? void 0 : _a.length) || ((_b = options.orderBy) == null ? void 0 : _b.length) || ((_c = options.groupBy) == null ? void 0 : _c.length) || ((_d = options.aggregates) == null ? void 0 : _d.length) || ((_e = options.union) == null ? void 0 : _e.length));
2586
+ }
2587
+ function queryArrowJoin(sourceTable, options) {
2588
+ var _a;
2589
+ const join = options.join;
2590
+ if (!join)
2591
+ throw new Error("Arrow join query is missing a join definition.");
2592
+ const childTable = (_a = options.tables) == null ? void 0 : _a[join.child.source];
2593
+ if (!childTable)
2594
+ throw new Error(`Arrow join source not found: ${join.child.source}`);
2595
+ const leftResult = queryArrowTable(sourceTable, {
2596
+ predicate: options.predicate,
2597
+ columns: void 0,
2598
+ signal: options.signal
2599
+ });
2600
+ const rightResult = queryArrowTable(childTable, {
2601
+ ...join.child.query || {},
2602
+ signal: options.signal
2603
+ });
2604
+ const leftRows = arrowTableToRows(leftResult.data);
2605
+ const rightRows = arrowTableToRows(rightResult.data);
2606
+ const rightPrefix = `${join.child.source}.`;
2607
+ const defaultOutputColumns = [
2608
+ ...sourceTable.data.schema.fields.map((field) => field.name),
2609
+ ...rightResult.data.schema.fields.map((field) => `${rightPrefix}${field.name}`)
2610
+ ];
2611
+ const rows = [];
2612
+ for (const leftRow of leftRows) {
2613
+ for (const rightRow of rightRows) {
2614
+ if (leftRow[join.left] !== null && leftRow[join.left] !== void 0 && rightRow[join.right] !== null && rightRow[join.right] !== void 0 && compareSortValues(leftRow[join.left], rightRow[join.right]) === 0) {
2615
+ rows.push({
2616
+ ...leftRow,
2617
+ ...Object.fromEntries(Object.entries(rightRow).map(([key, value]) => [`${rightPrefix}${key}`, value]))
2618
+ });
2619
+ }
2620
+ }
2621
+ }
2622
+ const outputColumns = options.columns || defaultOutputColumns;
2623
+ const outputRows = rows.map((row) => Object.fromEntries(outputColumns.map((column) => [column, row[column]])));
2624
+ const limitedRows = outputRows.slice(0, options.limit);
2625
+ return limitedRows.length ? convertRowsToArrowTable(limitedRows) : createEmptyRelationalResult(sourceTable.data, outputColumns, options, new Map(rightResult.data.schema.fields.map((field) => [
2626
+ `${rightPrefix}${field.name}`,
2627
+ new arrow6.Field(`${rightPrefix}${field.name}`, field.type, field.nullable, field.metadata)
2628
+ ])));
2629
+ }
2630
+ function validateArrowJoinQuery(sourceTable, options) {
2631
+ var _a, _b, _c;
2632
+ const join = options.join;
2633
+ if (!join)
2634
+ return;
2635
+ const sourceColumnNames = sourceTable.data.schema.fields.map((field) => field.name);
2636
+ const childTable = (_a = options.tables) == null ? void 0 : _a[join.child.source];
2637
+ if (!childTable)
2638
+ throw new Error(`Arrow join source not found: ${join.child.source}`);
2639
+ const childColumnNames = childTable.data.schema.fields.map((field) => field.name);
2640
+ if (!sourceColumnNames.includes(join.left)) {
2641
+ throw new Error(`Arrow join column not found: ${join.left}`);
2642
+ }
2643
+ if (!childColumnNames.includes(join.right)) {
2644
+ throw new Error(`Arrow join column not found: ${join.right}`);
2645
+ }
2646
+ const childPrefix = `${join.child.source}.`;
2647
+ const rootColumns = (_b = options.columns) == null ? void 0 : _b.filter((column) => !column.startsWith(childPrefix));
2648
+ planTableQuery2(sourceColumnNames, {
2649
+ predicate: options.predicate,
2650
+ columns: (rootColumns == null ? void 0 : rootColumns.length) ? rootColumns : void 0,
2651
+ limit: options.limit,
2652
+ signal: options.signal
2653
+ });
2654
+ const childQuery = join.child.query || {};
2655
+ planTableQuery2(childColumnNames, childQuery);
2656
+ const childOutputColumns = childQuery.columns || childColumnNames;
2657
+ if (!childOutputColumns.includes(join.right)) {
2658
+ throw new Error(`Arrow join child projection must include: ${join.right}`);
2659
+ }
2660
+ const projectedChildColumns = ((_c = options.columns) == null ? void 0 : _c.filter((column) => column.startsWith(childPrefix))) || [];
2661
+ const seenChildColumns = /* @__PURE__ */ new Set();
2662
+ for (const projectedColumn of projectedChildColumns) {
2663
+ const childColumn = projectedColumn.slice(childPrefix.length);
2664
+ if (!childColumnNames.includes(childColumn)) {
2665
+ throw new Error(`Arrow join column not found: ${projectedColumn}`);
2666
+ }
2667
+ if (seenChildColumns.has(childColumn)) {
2668
+ throw new Error(`Arrow query column was selected more than once: ${projectedColumn}`);
2669
+ }
2670
+ seenChildColumns.add(childColumn);
2671
+ if (!childOutputColumns.includes(childColumn)) {
2672
+ throw new Error(`Arrow join child projection does not include: ${childColumn}`);
2673
+ }
2674
+ }
2675
+ }
2676
+ function arrowTableToRows(data) {
2677
+ const columns = data.schema.fields.map((field) => ({
2678
+ name: field.name,
2679
+ vector: data.getChild(field.name)
2680
+ }));
2681
+ return Array.from({ length: data.numRows }, (_, rowIndex) => {
2682
+ const row = {};
2683
+ for (const column of columns) {
2684
+ if (!column.vector)
2685
+ throw new Error(`Arrow relational query could not read ${column.name}`);
2686
+ row[column.name] = column.vector.get(rowIndex);
2687
+ }
2688
+ return row;
2689
+ });
2690
+ }
2691
+ function evaluateRelationalExpression(expression, row) {
2692
+ const definition = expression.expression;
2693
+ if (definition.op === "literal")
2694
+ return definition.value;
2695
+ if (definition.op === "column")
2696
+ return row[definition.column];
2697
+ const left = row[definition.left];
2698
+ const right = row[definition.right];
2699
+ if (left === null || left === void 0 || right === null || right === void 0)
2700
+ return null;
2701
+ if (typeof left !== "number" || typeof right !== "number") {
2702
+ throw new Error(`Arrow relational expression ${expression.name} requires numeric operands.`);
2703
+ }
2704
+ switch (definition.op) {
2705
+ case "add":
2706
+ return left + right;
2707
+ case "subtract":
2708
+ return left - right;
2709
+ case "multiply":
2710
+ return left * right;
2711
+ case "divide":
2712
+ return right === 0 ? null : left / right;
2713
+ }
2714
+ }
2715
+ function compareRows(left, right, orderBy) {
2716
+ for (const key of orderBy) {
2717
+ const leftValue = left[key.column];
2718
+ const rightValue = right[key.column];
2719
+ const nulls = key.nulls || "last";
2720
+ if (leftValue === null || leftValue === void 0 || rightValue === null || rightValue === void 0) {
2721
+ if (leftValue === rightValue)
2722
+ continue;
2723
+ const nullResult = leftValue === null || leftValue === void 0 ? -1 : 1;
2724
+ return nulls === "first" ? nullResult : -nullResult;
2725
+ }
2726
+ const result = compareSortValues(leftValue, rightValue);
2727
+ if (result)
2728
+ return (key.direction === "desc" ? -1 : 1) * result;
2729
+ }
2730
+ return 0;
2731
+ }
2732
+ function compareSortValues(left, right) {
2733
+ if (left instanceof Date && right instanceof Date)
2734
+ return compareNumbers(left.getTime(), right.getTime());
2735
+ if (typeof left === "bigint" && typeof right === "bigint")
2736
+ return left === right ? 0 : left < right ? -1 : 1;
2737
+ if (typeof left === "number" && typeof right === "number")
2738
+ return compareNumbers(left, right);
2739
+ if (typeof left === "string" && typeof right === "string")
2740
+ return left === right ? 0 : left < right ? -1 : 1;
2741
+ if (typeof left === "boolean" && typeof right === "boolean")
2742
+ return Number(left) - Number(right);
2743
+ throw new Error(`Arrow relational order cannot compare ${getValueType(left)} with ${getValueType(right)}.`);
2744
+ }
2745
+ function aggregateRows(rows, groupBy, aggregates) {
2746
+ const groups = /* @__PURE__ */ new Map();
2747
+ for (const row of rows) {
2748
+ const key = serializeGroupKey(groupBy.map((column) => row[column]));
2749
+ const group = groups.get(key) || [];
2750
+ group.push(row);
2751
+ groups.set(key, group);
2752
+ }
2753
+ if (!groupBy.length && !rows.length)
2754
+ groups.set("[]", []);
2755
+ return [...groups.values()].map((group) => {
2756
+ var _a;
2757
+ const output = {};
2758
+ for (const column of groupBy)
2759
+ output[column] = ((_a = group[0]) == null ? void 0 : _a[column]) ?? null;
2760
+ for (const aggregate of aggregates)
2761
+ output[aggregate.name] = evaluateAggregate(aggregate, group);
2762
+ return output;
2763
+ });
2764
+ }
2765
+ function serializeGroupKey(values) {
2766
+ return values.map((value) => {
2767
+ if (value === null || value === void 0)
2768
+ return "null:";
2769
+ if (value instanceof Date)
2770
+ return `date:${value.getTime()}`;
2771
+ if (value instanceof Uint8Array)
2772
+ return `bytes:${Array.from(value).join(".")}`;
2773
+ return `${typeof value}:${String(value)}`;
2774
+ }).join("");
2775
+ }
2776
+ function createEmptyRelationalResult(sourceData, outputColumns, options, additionalFields) {
2777
+ const sourceFields = new Map(sourceData.schema.fields.map((field) => [field.name, field]));
2778
+ const expressions = new Map((options.expressions || []).map((expression) => [expression.name, expression]));
2779
+ const aggregates = new Map((options.aggregates || []).map((aggregate) => [aggregate.name, aggregate]));
2780
+ const fields = outputColumns.map((columnName) => {
2781
+ const sourceField = sourceFields.get(columnName);
2782
+ if (sourceField)
2783
+ return sourceField;
2784
+ const additionalField = additionalFields == null ? void 0 : additionalFields.get(columnName);
2785
+ if (additionalField)
2786
+ return additionalField;
2787
+ const expression = expressions.get(columnName);
2788
+ if (expression)
2789
+ return new arrow6.Field(columnName, getExpressionType(expression, sourceFields), true);
2790
+ const aggregate = aggregates.get(columnName);
2791
+ if (aggregate)
2792
+ return new arrow6.Field(columnName, getAggregateType(aggregate, sourceFields), true);
2793
+ return new arrow6.Field(columnName, new arrow6.Utf8(), true);
2794
+ });
2795
+ const columns = {};
2796
+ for (const field of fields)
2797
+ columns[field.name] = arrow6.vectorFromArray([], field.type);
2798
+ return wrapArrowTable(new arrow6.Table(new arrow6.Schema(fields), columns));
2799
+ }
2800
+ function getExpressionType(expression, sourceFields) {
2801
+ var _a;
2802
+ if (expression.expression.op === "literal") {
2803
+ const value = expression.expression.value;
2804
+ if (typeof value === "boolean")
2805
+ return new arrow6.Bool();
2806
+ if (typeof value === "number")
2807
+ return new arrow6.Float64();
2808
+ return new arrow6.Utf8();
2809
+ }
2810
+ if (expression.expression.op === "column") {
2811
+ return ((_a = sourceFields.get(expression.expression.column)) == null ? void 0 : _a.type) || new arrow6.Utf8();
2812
+ }
2813
+ return new arrow6.Float64();
2814
+ }
2815
+ function getAggregateType(aggregate, sourceFields) {
2816
+ var _a;
2817
+ if (aggregate.function === "count")
2818
+ return new arrow6.Int32();
2819
+ return aggregate.column ? ((_a = sourceFields.get(aggregate.column)) == null ? void 0 : _a.type) || new arrow6.Float64() : new arrow6.Float64();
2820
+ }
2821
+ function evaluateAggregate(aggregate, rows) {
2822
+ if (aggregate.function === "count")
2823
+ return aggregate.column ? rows.filter((row) => row[aggregate.column] != null).length : rows.length;
2824
+ const values = rows.map((row) => row[aggregate.column]).filter((value) => value != null);
2825
+ if (!values.length)
2826
+ return null;
2827
+ if (!values.every((value) => typeof value === "number"))
2828
+ throw new Error(`Arrow aggregate ${aggregate.function} requires numeric values.`);
2829
+ const numericValues = values;
2830
+ switch (aggregate.function) {
2831
+ case "sum":
2832
+ return numericValues.reduce((sum, value) => sum + value, 0);
2833
+ case "avg":
2834
+ return numericValues.reduce((sum, value) => sum + value, 0) / numericValues.length;
2835
+ case "min":
2836
+ return Math.min(...numericValues);
2837
+ case "max":
2838
+ return Math.max(...numericValues);
2839
+ }
2840
+ }
2841
+ function getPredicateColumns(sourceTable, columnNames) {
2842
+ const columns = {};
2843
+ for (const columnName of columnNames) {
2844
+ const column = sourceTable.getChild(columnName);
2845
+ if (!column) {
2846
+ throw new Error(`Arrow query column not found: ${columnName}`);
2847
+ }
2848
+ columns[columnName] = column;
2849
+ }
2850
+ return columns;
2851
+ }
2852
+ function evaluatePredicate(predicate, columns, rowIndex) {
2853
+ if (isLogicalPredicate(predicate)) {
2854
+ const values = predicate.args.map((child) => evaluatePredicate(child, columns, rowIndex));
2855
+ return predicate.op === "and" ? evaluateAnd(values) : evaluateOr(values);
2856
+ }
2857
+ if (isNotPredicate(predicate)) {
2858
+ const value2 = evaluatePredicate(predicate.args[0], columns, rowIndex);
2859
+ return value2 === null ? null : !value2;
2860
+ }
2861
+ const value = getColumnValue(columns, predicate.args[0].property, rowIndex);
2862
+ if (isNullPredicate(predicate)) {
2863
+ return value === null;
2864
+ }
2865
+ if (isInPredicate(predicate)) {
2866
+ return evaluateIn(value, predicate.args[1]);
2867
+ }
2868
+ return evaluateComparison(value, predicate);
2869
+ }
2870
+ function getColumnValue(columns, columnName, rowIndex) {
2871
+ const column = columns[columnName];
2872
+ if (!column) {
2873
+ throw new Error(`Arrow query could not read predicate column "${columnName}".`);
2874
+ }
2875
+ return column.get(rowIndex);
2876
+ }
2877
+ function evaluateAnd(values) {
2878
+ if (values.includes(false)) {
2879
+ return false;
2880
+ }
2881
+ return values.includes(null) ? null : true;
2882
+ }
2883
+ function evaluateOr(values) {
2884
+ if (values.includes(true)) {
2885
+ return true;
2886
+ }
2887
+ return values.includes(null) ? null : false;
2888
+ }
2889
+ function evaluateIn(value, candidates) {
2890
+ if (value === null || value === void 0) {
2891
+ return null;
2892
+ }
2893
+ for (const candidate of candidates) {
2894
+ if (compareValues(value, candidate) === 0) {
2895
+ return true;
2896
+ }
2897
+ }
2898
+ return false;
2899
+ }
2900
+ function evaluateComparison(value, predicate) {
2901
+ if (value === null || value === void 0) {
2902
+ return null;
2903
+ }
2904
+ const comparison = compareValues(value, predicate.args[1]);
2905
+ switch (predicate.op) {
2906
+ case "=":
2907
+ return comparison === 0;
2908
+ case "<>":
2909
+ return comparison !== 0;
2910
+ case "<":
2911
+ return comparison < 0;
2912
+ case "<=":
2913
+ return comparison <= 0;
2914
+ case ">":
2915
+ return comparison > 0;
2916
+ case ">=":
2917
+ return comparison >= 0;
2918
+ }
2919
+ }
2920
+ function compareValues(left, right) {
2921
+ if (isSQLPredicateParameter(right)) {
2922
+ throw new Error(`Arrow query parameter ":${right.parameter}" must be bound before query execution.`);
2923
+ }
2924
+ if (left instanceof Date && right instanceof Date) {
2925
+ return compareNumbers(left.getTime(), right.getTime());
2926
+ }
2927
+ if (left instanceof Uint8Array && right instanceof Uint8Array) {
2928
+ return compareBinary(left, right);
2929
+ }
2930
+ if (typeof left === "bigint" && typeof right === "bigint") {
2931
+ return left === right ? 0 : left < right ? -1 : 1;
2932
+ }
2933
+ if (typeof left === "bigint" && typeof right === "number" && Number.isSafeInteger(right)) {
2934
+ return compareValues(left, BigInt(right));
2935
+ }
2936
+ if (typeof left === "number" && typeof right === "bigint" && Number.isSafeInteger(left)) {
2937
+ return compareValues(BigInt(left), right);
2938
+ }
2939
+ if (typeof left === "number" && typeof right === "number") {
2940
+ return compareNumbers(left, right);
2941
+ }
2942
+ if (typeof left === "string" && typeof right === "string") {
2943
+ return left === right ? 0 : left < right ? -1 : 1;
2944
+ }
2945
+ if (typeof left === "boolean" && typeof right === "boolean") {
2946
+ return Number(left) - Number(right);
2947
+ }
2948
+ throw new Error(`Arrow query cannot compare ${getValueType(left)} with ${getValueType(right)} values.`);
2949
+ }
2950
+ function compareNumbers(left, right) {
2951
+ if (!Number.isFinite(left) || !Number.isFinite(right)) {
2952
+ throw new Error("Arrow query cannot compare non-finite numbers.");
2953
+ }
2954
+ return left === right ? 0 : left < right ? -1 : 1;
2955
+ }
2956
+ function compareBinary(left, right) {
2957
+ const commonLength = Math.min(left.length, right.length);
2958
+ for (let index = 0; index < commonLength; index++) {
2959
+ if (left[index] !== right[index]) {
2960
+ return left[index] < right[index] ? -1 : 1;
2961
+ }
2962
+ }
2963
+ return left.length === right.length ? 0 : left.length < right.length ? -1 : 1;
2964
+ }
2965
+ function getValueType(value) {
2966
+ if (value instanceof Date) {
2967
+ return "Date";
2968
+ }
2969
+ if (value instanceof Uint8Array) {
2970
+ return "Uint8Array";
2971
+ }
2972
+ return typeof value;
2973
+ }
2974
+ function isLogicalPredicate(predicate) {
2975
+ return predicate.op === "and" || predicate.op === "or";
2976
+ }
2977
+ function isNotPredicate(predicate) {
2978
+ return predicate.op === "not";
2979
+ }
2980
+ function isNullPredicate(predicate) {
2981
+ return predicate.op === "isNull";
2982
+ }
2983
+ function isInPredicate(predicate) {
2984
+ return predicate.op === "in";
2985
+ }
2986
+ function getScanStep(plan) {
2987
+ const step = plan.find((candidate) => candidate.kind === "scan");
2988
+ if (!step) {
2989
+ throw new Error("Arrow query plan is missing a scan step.");
2990
+ }
2991
+ return step;
2992
+ }
2993
+ function getFilterStep(plan) {
2994
+ return plan.find((candidate) => candidate.kind === "filter");
2995
+ }
2996
+ function getProjectStep(plan) {
2997
+ const step = plan.find((candidate) => candidate.kind === "project");
2998
+ if (!step) {
2999
+ throw new Error("Arrow query plan is missing a project step.");
3000
+ }
3001
+ return step;
3002
+ }
3003
+ function getLimitStep(plan) {
3004
+ return plan.find((candidate) => candidate.kind === "limit");
3005
+ }
3006
+ function throwIfAborted(signal) {
3007
+ if (signal == null ? void 0 : signal.aborted) {
3008
+ const error = new Error("Arrow query was aborted.");
3009
+ error.name = "AbortError";
3010
+ throw error;
3011
+ }
3012
+ }
3013
+ function wrapArrowTable(data) {
3014
+ return {
3015
+ shape: "arrow-table",
3016
+ schema: convertArrowToSchema(data.schema),
3017
+ data
3018
+ };
3019
+ }
3020
+
3021
+ // dist/arrow-table-source.js
3022
+ var ArrowTableSource = class extends DataSource {
3023
+ /** Creates a source over an existing Arrow table without copying its vectors. */
3024
+ constructor(data, options = {}) {
3025
+ super(data, options);
3026
+ }
3027
+ /** Discovers query-visible fields and capabilities without evaluating any rows. */
3028
+ async getQueryMetadata(options = {}) {
3029
+ throwIfAborted2(options.signal);
3030
+ const schema = convertArrowToSchema(this.data.data.schema);
3031
+ return createScanQueryMetadata({
3032
+ sourceType: "arrow-table",
3033
+ queryType: "table",
3034
+ execution: { status: "supported", method: "read" },
3035
+ schema,
3036
+ capabilities: { table: ARROW_TABLE_QUERY_CAPABILITIES },
3037
+ columnRoles: getArrowColumnRoles(schema.fields.map((field) => field.name)),
3038
+ statistics: { rowCount: this.data.data.numRows }
3039
+ });
1417
3040
  }
1418
- /** Executes a SQL query and returns a loaders.gl Arrow table. */
1419
- async queryArrow(sqlText, options = {}) {
1420
- const adapter = await this.getAdapter();
1421
- if (adapter.executeArrow) {
1422
- return await adapter.executeArrow(sqlText, options);
1423
- }
1424
- const rows = await adapter.executeRows(sqlText, options);
1425
- return convertRowsToArrowTable(rows);
3041
+ /** Executes a portable query and returns an Arrow table result. */
3042
+ query(options = {}) {
3043
+ return queryArrowTable(this.data, options);
1426
3044
  }
1427
- /** Closes any underlying adapter connection. */
1428
- async close() {
1429
- if (!this.adapterPromise) {
1430
- return;
1431
- }
1432
- const adapter = await this.adapterPromise;
1433
- await adapter.close();
1434
- this.adapterPromise = null;
1435
- this.metadataPromise = null;
3045
+ /** Explains a portable query without evaluating table rows. */
3046
+ explain(options = {}) {
3047
+ return explainArrowTableQuery(this.data, options);
1436
3048
  }
1437
- async getAdapter() {
1438
- if (!this.adapterPromise) {
1439
- this.adapterPromise = this.loadAdapter();
1440
- }
1441
- return await this.adapterPromise;
3049
+ /** Executes a query as one bounded Arrow batch. */
3050
+ async *read(options = {}) {
3051
+ const result = this.query(options);
3052
+ yield makeTableScanBatch(result);
1442
3053
  }
1443
- async loadAdapter() {
1444
- var _a, _b;
1445
- try {
1446
- const runtimeFactory = isNodeRuntime() ? (_a = this.options.sql) == null ? void 0 : _a.nodeAdapterFactory : (_b = this.options.sql) == null ? void 0 : _b.browserAdapterFactory;
1447
- const factory = runtimeFactory || this.adapterFactory;
1448
- if (!factory) {
1449
- throw new Error(`No SQL adapter is registered for source type "${this.sourceType}".`);
1450
- }
1451
- const adapter = await factory({
1452
- coreApi: this.coreApi,
1453
- options: this.options,
1454
- sourceType: this.sourceType,
1455
- url: this.url
1456
- });
1457
- await adapter.connect();
1458
- return adapter;
1459
- } catch (error) {
1460
- throw this.reportError(error, `Failed to create SQL adapter for ${this.sourceType} from ${this.url}`);
3054
+ };
3055
+ function getArrowColumnRoles(columnNames) {
3056
+ const roles = {};
3057
+ for (const columnName of columnNames) {
3058
+ const normalizedName = columnName.toLowerCase();
3059
+ if (normalizedName === "x" || normalizedName === "longitude" || normalizedName === "lon") {
3060
+ roles[columnName] = normalizedName === "x" ? "x" : "longitude";
3061
+ } else if (normalizedName === "y" || normalizedName === "latitude" || normalizedName === "lat") {
3062
+ roles[columnName] = normalizedName === "y" ? "y" : "latitude";
3063
+ } else if (normalizedName === "z" || normalizedName === "elevation" || normalizedName === "altitude") {
3064
+ roles[columnName] = normalizedName === "z" ? "z" : "attribute";
3065
+ } else if (normalizedName === "time" || normalizedName.endsWith("_time") || normalizedName.endsWith("timestamp")) {
3066
+ roles[columnName] = "time";
1461
3067
  }
1462
3068
  }
1463
- async loadMetadata() {
1464
- const adapter = await this.getAdapter();
1465
- const [catalogs, schemas, tables] = await Promise.all([
1466
- adapter.listCatalogs(),
1467
- adapter.listSchemas(),
1468
- adapter.listTables()
1469
- ]);
1470
- return {
1471
- type: this.sourceType,
1472
- capabilities: adapter.capabilities,
1473
- catalogs,
1474
- schemas,
1475
- tables
1476
- };
3069
+ return roles;
3070
+ }
3071
+ function throwIfAborted2(signal) {
3072
+ if (signal == null ? void 0 : signal.aborted) {
3073
+ throw new Error("Request aborted");
1477
3074
  }
1478
- };
3075
+ }
1479
3076
 
1480
3077
  // dist/duckdb-sql-source.js
1481
- var VERSION2 = true ? "5.0.0-alpha.2" : "latest";
3078
+ var VERSION2 = true ? "5.0.0-alpha.3" : "latest";
1482
3079
  var DuckDBSQLSource = {
1483
3080
  dataType: null,
1484
3081
  batchType: null,
@@ -1657,8 +3254,8 @@ async function createDuckDBBrowserAdapter(context) {
1657
3254
  const database = new duckdb.AsyncDuckDB(logger, worker);
1658
3255
  await database.instantiate(bundles.mainModule, bundles.pthreadWorker);
1659
3256
  const connection = await database.connect();
1660
- const executeRows = async (sqlText) => {
1661
- const result = await connection.query(sqlText);
3257
+ const executeRows = async (sqlText, options = {}) => {
3258
+ const result = await executeDuckDBBrowserQuery(connection, sqlText, options.parameters);
1662
3259
  return convertArrowToTable2(result, "object-row-table").data;
1663
3260
  };
1664
3261
  return {
@@ -1739,15 +3336,27 @@ async function createDuckDBBrowserAdapter(context) {
1739
3336
  }));
1740
3337
  return convertSQLColumnsToSchema(columns);
1741
3338
  },
1742
- async executeRows(sqlText) {
1743
- return await executeRows(sqlText);
3339
+ async executeRows(sqlText, options = {}) {
3340
+ return await executeRows(sqlText, options);
1744
3341
  },
1745
- async executeArrow(sqlText) {
1746
- const result = await connection.query(sqlText);
3342
+ async executeArrow(sqlText, options = {}) {
3343
+ const result = await executeDuckDBBrowserQuery(connection, sqlText, options.parameters);
1747
3344
  return convertArrowToTable2(result, "arrow-table");
1748
3345
  }
1749
3346
  };
1750
3347
  }
3348
+ async function executeDuckDBBrowserQuery(connection, sqlText, parameters) {
3349
+ if (!parameters) {
3350
+ return await connection.query(sqlText);
3351
+ }
3352
+ const values = Array.isArray(parameters) ? parameters : Object.values(parameters);
3353
+ const statement = await connection.prepare(sqlText);
3354
+ try {
3355
+ return await statement.query(...values);
3356
+ } finally {
3357
+ await statement.close();
3358
+ }
3359
+ }
1751
3360
  function getDuckDBDatabasePath(url, options) {
1752
3361
  var _a;
1753
3362
  if ((_a = options.duckdb) == null ? void 0 : _a.databasePath) {
@@ -1762,7 +3371,7 @@ function getDuckDBDatabasePath(url, options) {
1762
3371
  }
1763
3372
 
1764
3373
  // dist/snowflake-sql-source.js
1765
- var VERSION3 = true ? "5.0.0-alpha.2" : "latest";
3374
+ var VERSION3 = true ? "5.0.0-alpha.3" : "latest";
1766
3375
  var SnowflakeSQLSource = {
1767
3376
  dataType: null,
1768
3377
  batchType: null,
@@ -1938,14 +3547,15 @@ async function fetchSnowflakeJson(context, url, authorization, requestInit) {
1938
3547
  return json;
1939
3548
  }
1940
3549
  function normalizeSnowflakeBindings(parameters) {
1941
- if (!parameters || Array.isArray(parameters)) {
3550
+ if (!parameters) {
1942
3551
  return void 0;
1943
3552
  }
1944
3553
  const bindings = {};
1945
- for (const [key, value] of Object.entries(parameters)) {
3554
+ const entries = Array.isArray(parameters) ? parameters.map((value, index) => [String(index + 1), value]) : Object.entries(parameters);
3555
+ for (const [key, value] of entries) {
1946
3556
  bindings[key] = {
1947
- type: typeof value === "number" ? "FIXED" : "TEXT",
1948
- value
3557
+ type: typeof value === "number" || typeof value === "bigint" ? "FIXED" : "TEXT",
3558
+ value: typeof value === "bigint" ? value.toString() : value
1949
3559
  };
1950
3560
  }
1951
3561
  return bindings;
@@ -1966,195 +3576,12 @@ function getSnowflakeBaseUrl(url, options) {
1966
3576
  return `https://${account}.snowflakecomputing.com`;
1967
3577
  }
1968
3578
 
1969
- // dist/sql-predicate-schema.js
1970
- var MAXIMUM_PREDICATE_DEPTH = 64;
1971
- var MAXIMUM_PREDICATE_NODES = 4096;
1972
- var SQL_PREDICATE_JSON_SCHEMA = {
1973
- $schema: "https://json-schema.org/draft/2020-12/schema",
1974
- $id: "https://loaders.gl/schemas/sql-predicate.schema.json",
1975
- title: "loaders.gl SQL predicate",
1976
- oneOf: [
1977
- { $ref: "#/$defs/comparison" },
1978
- { $ref: "#/$defs/in" },
1979
- { $ref: "#/$defs/isNull" },
1980
- { $ref: "#/$defs/logical" },
1981
- { $ref: "#/$defs/not" }
1982
- ],
1983
- $defs: {
1984
- property: {
1985
- type: "object",
1986
- required: ["property"],
1987
- properties: { property: { type: "string", minLength: 1 } },
1988
- additionalProperties: false
1989
- },
1990
- value: { type: ["boolean", "number", "string"] },
1991
- comparison: {
1992
- type: "object",
1993
- required: ["op", "args"],
1994
- properties: {
1995
- op: { enum: ["=", "<>", "<", "<=", ">", ">="] },
1996
- args: {
1997
- type: "array",
1998
- prefixItems: [{ $ref: "#/$defs/property" }, { $ref: "#/$defs/value" }],
1999
- minItems: 2,
2000
- maxItems: 2
2001
- }
2002
- },
2003
- additionalProperties: false
2004
- },
2005
- in: {
2006
- type: "object",
2007
- required: ["op", "args"],
2008
- properties: {
2009
- op: { const: "in" },
2010
- args: {
2011
- type: "array",
2012
- prefixItems: [
2013
- { $ref: "#/$defs/property" },
2014
- { type: "array", items: { $ref: "#/$defs/value" }, minItems: 1 }
2015
- ],
2016
- minItems: 2,
2017
- maxItems: 2
2018
- }
2019
- },
2020
- additionalProperties: false
2021
- },
2022
- isNull: {
2023
- type: "object",
2024
- required: ["op", "args"],
2025
- properties: {
2026
- op: { const: "isNull" },
2027
- args: {
2028
- type: "array",
2029
- prefixItems: [{ $ref: "#/$defs/property" }],
2030
- minItems: 1,
2031
- maxItems: 1
2032
- }
2033
- },
2034
- additionalProperties: false
2035
- },
2036
- logical: {
2037
- type: "object",
2038
- required: ["op", "args"],
2039
- properties: {
2040
- op: { enum: ["and", "or"] },
2041
- args: { type: "array", items: { $ref: "#" }, minItems: 2 }
2042
- },
2043
- additionalProperties: false
2044
- },
2045
- not: {
2046
- type: "object",
2047
- required: ["op", "args"],
2048
- properties: {
2049
- op: { const: "not" },
2050
- args: { type: "array", prefixItems: [{ $ref: "#" }], minItems: 1, maxItems: 1 }
2051
- },
2052
- additionalProperties: false
2053
- }
2054
- }
2055
- };
2056
- function isSQLPredicate(value) {
2057
- try {
2058
- validateSQLPredicate(value);
2059
- return true;
2060
- } catch {
2061
- return false;
2062
- }
2063
- }
2064
- function validateSQLPredicate(value) {
2065
- const state = { nodes: 0 };
2066
- validatePredicateNode(value, "$", 0, state);
2067
- }
2068
- function validatePredicateNode(value, path, depth, state) {
2069
- if (depth > MAXIMUM_PREDICATE_DEPTH) {
2070
- throw new Error(`SQL predicate ${path} exceeds the maximum nesting depth`);
2071
- }
2072
- state.nodes++;
2073
- if (state.nodes > MAXIMUM_PREDICATE_NODES) {
2074
- throw new Error("SQL predicate exceeds the maximum node count");
2075
- }
2076
- if (!isRecord(value) || !hasExactKeys(value, ["op", "args"])) {
2077
- throw new Error(`SQL predicate ${path} must contain only op and args`);
2078
- }
2079
- if (typeof value.op !== "string" || !Array.isArray(value.args)) {
2080
- throw new Error(`SQL predicate ${path} requires string op and array args`);
2081
- }
2082
- switch (value.op) {
2083
- case "and":
2084
- case "or":
2085
- if (value.args.length < 2) {
2086
- throw new Error(`SQL predicate ${path}.${value.op} requires at least two arguments`);
2087
- }
2088
- for (let index = 0; index < value.args.length; index++) {
2089
- validatePredicateNode(value.args[index], `${path}.args[${index}]`, depth + 1, state);
2090
- }
2091
- return;
2092
- case "not":
2093
- if (value.args.length !== 1) {
2094
- throw new Error(`SQL predicate ${path}.not requires exactly one argument`);
2095
- }
2096
- validatePredicateNode(value.args[0], `${path}.args[0]`, depth + 1, state);
2097
- return;
2098
- case "isNull":
2099
- if (value.args.length !== 1) {
2100
- throw new Error(`SQL predicate ${path}.isNull requires exactly one argument`);
2101
- }
2102
- validatePredicateProperty(value.args[0], `${path}.args[0]`);
2103
- return;
2104
- case "in":
2105
- if (value.args.length !== 2 || !Array.isArray(value.args[1]) || value.args[1].length === 0) {
2106
- throw new Error(`SQL predicate ${path}.in requires a property and non-empty value list`);
2107
- }
2108
- validatePredicateProperty(value.args[0], `${path}.args[0]`);
2109
- value.args[1].forEach((item, index) => validatePredicateValue(item, `${path}.args[1][${index}]`));
2110
- return;
2111
- case "=":
2112
- case "<>":
2113
- case "<":
2114
- case "<=":
2115
- case ">":
2116
- case ">=":
2117
- if (value.args.length !== 2) {
2118
- throw new Error(`SQL predicate ${path}.${value.op} requires exactly two arguments`);
2119
- }
2120
- validatePredicateProperty(value.args[0], `${path}.args[0]`);
2121
- validatePredicateValue(value.args[1], `${path}.args[1]`);
2122
- return;
2123
- default:
2124
- throw new Error(`SQL predicate ${path} has unsupported operator ${JSON.stringify(value.op)}`);
2125
- }
2126
- }
2127
- function validatePredicateProperty(value, path) {
2128
- if (!isRecord(value) || !hasExactKeys(value, ["property"]) || typeof value.property !== "string" || value.property.length === 0) {
2129
- throw new Error(`SQL predicate ${path} requires a non-empty property reference`);
2130
- }
2131
- }
2132
- function validatePredicateValue(value, path) {
2133
- if (typeof value === "boolean" || typeof value === "bigint" || typeof value === "string" || value instanceof Uint8Array) {
2134
- return;
2135
- }
2136
- if (typeof value === "number" && Number.isFinite(value)) {
2137
- return;
2138
- }
2139
- if (value instanceof Date && Number.isFinite(value.getTime())) {
2140
- return;
2141
- }
2142
- throw new Error(`SQL predicate ${path} contains an unsupported scalar value`);
2143
- }
2144
- function isRecord(value) {
2145
- return typeof value === "object" && value !== null && !Array.isArray(value);
2146
- }
2147
- function hasExactKeys(value, expectedKeys) {
2148
- const keys = Object.keys(value);
2149
- return keys.length === expectedKeys.length && expectedKeys.every((key) => keys.includes(key));
2150
- }
2151
-
2152
3579
  // dist/parse-sql-predicate.js
2153
3580
  var MAXIMUM_SQL_LENGTH = 65536;
2154
3581
  var MAXIMUM_SQL_TOKENS = 4096;
2155
3582
  var MAXIMUM_EXPRESSION_DEPTH = 64;
2156
3583
  function parseSQLPredicate(source, options = {}) {
2157
- const parser = new SQLPredicateParser(source, options.parameters ?? {});
3584
+ const parser = new SQLPredicateParser(source, options.parameters ?? {}, options.preserveParameters === true);
2158
3585
  const predicate = parser.parse();
2159
3586
  validateSQLPredicate(predicate);
2160
3587
  return predicate;
@@ -2164,11 +3591,14 @@ var SQLPredicateParser = class {
2164
3591
  tokens;
2165
3592
  /** Named scalar parameters available to the expression. */
2166
3593
  parameters;
3594
+ /** Whether named parameters remain references in the parsed AST. */
3595
+ preserveParameters;
2167
3596
  /** Current index in the token stream. */
2168
3597
  position = 0;
2169
- constructor(source, parameters) {
3598
+ constructor(source, parameters, preserveParameters) {
2170
3599
  this.tokens = tokenizeSQLPredicate(source);
2171
3600
  this.parameters = parameters;
3601
+ this.preserveParameters = preserveParameters;
2172
3602
  }
2173
3603
  /** Parses the complete token stream. */
2174
3604
  parse() {
@@ -2250,7 +3680,7 @@ var SQLPredicateParser = class {
2250
3680
  if ((token == null ? void 0 : token.kind) !== "identifier") {
2251
3681
  throw new Error("SQL predicate expected a column identifier");
2252
3682
  }
2253
- return { property: token.value };
3683
+ return token.quoted ? { property: token.value, quoted: true } : { property: token.value };
2254
3684
  }
2255
3685
  /** Parses one scalar literal or named parameter. */
2256
3686
  parseValue() {
@@ -2272,6 +3702,9 @@ var SQLPredicateParser = class {
2272
3702
  return token.value;
2273
3703
  }
2274
3704
  if (token.kind === "parameter") {
3705
+ if (this.preserveParameters) {
3706
+ return { parameter: token.value };
3707
+ }
2275
3708
  if (!Object.hasOwn(this.parameters, token.value)) {
2276
3709
  throw new Error(`SQL predicate parameter ":${token.value}" requires a value`);
2277
3710
  }
@@ -2382,7 +3815,7 @@ function tokenizeSQLPredicate(source) {
2382
3815
  position = result.position;
2383
3816
  } else if (character === '"') {
2384
3817
  const result = readQuotedToken(source, position, '"', '"');
2385
- tokens.push({ kind: "identifier", value: result.value });
3818
+ tokens.push({ kind: "identifier", value: result.value, quoted: true });
2386
3819
  position = result.position;
2387
3820
  } else if (character === ":") {
2388
3821
  const match = /^[A-Za-z_][A-Za-z0-9_]*/.exec(source.slice(position + 1));
@@ -2436,4 +3869,10 @@ function readQuotedToken(source, start, quote, escapedQuote) {
2436
3869
  }
2437
3870
  throw new Error(`SQL predicate contains an unterminated quoted value at character ${start}`);
2438
3871
  }
3872
+
3873
+ // dist/bind-sql-predicate.js
3874
+ function bindSQLPredicate(predicate, parameters) {
3875
+ validateSQLPredicate(predicate);
3876
+ return bindColumnarPredicateParameters(predicate, parameters);
3877
+ }
2439
3878
  //# sourceMappingURL=index.cjs.map