@loaders.gl/sql 5.0.0-alpha.1 → 5.0.0-alpha.11

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 (96) hide show
  1. package/LICENSE +14 -3
  2. package/README.md +107 -0
  3. package/dist/arrow-query.cjs +1404 -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 +51 -3
  22. package/dist/duckdb-sql-source.d.ts.map +1 -1
  23. package/dist/duckdb-sql-source.js +21 -7
  24. package/dist/duckdb-sql-source.js.map +1 -1
  25. package/dist/index.cjs +3352 -37
  26. package/dist/index.cjs.map +3 -4
  27. package/dist/index.d.ts +16 -1
  28. package/dist/index.d.ts.map +1 -1
  29. package/dist/index.js +9 -0
  30. package/dist/index.js.map +1 -1
  31. package/dist/parse-sql-predicate.d.ts +10 -0
  32. package/dist/parse-sql-predicate.d.ts.map +1 -0
  33. package/dist/parse-sql-predicate.js +322 -0
  34. package/dist/parse-sql-predicate.js.map +1 -0
  35. package/dist/query-arrow-table.d.ts +83 -0
  36. package/dist/query-arrow-table.d.ts.map +1 -0
  37. package/dist/query-arrow-table.js +663 -0
  38. package/dist/query-arrow-table.js.map +1 -0
  39. package/dist/snowflake-sql-source.d.ts +51 -3
  40. package/dist/snowflake-sql-source.d.ts.map +1 -1
  41. package/dist/snowflake-sql-source.js +9 -6
  42. package/dist/snowflake-sql-source.js.map +1 -1
  43. package/dist/sql-predicate-schema.d.ts +156 -0
  44. package/dist/sql-predicate-schema.d.ts.map +1 -0
  45. package/dist/sql-predicate-schema.js +226 -0
  46. package/dist/sql-predicate-schema.js.map +1 -0
  47. package/dist/sql-predicate-types.d.ts +45 -0
  48. package/dist/sql-predicate-types.d.ts.map +1 -0
  49. package/dist/sql-predicate-types.js +9 -0
  50. package/dist/sql-predicate-types.js.map +1 -0
  51. package/dist/sql-predicate-zod.cjs +54 -0
  52. package/dist/sql-predicate-zod.cjs.map +6 -0
  53. package/dist/sql-predicate-zod.d.ts +11 -0
  54. package/dist/sql-predicate-zod.d.ts.map +1 -0
  55. package/dist/sql-predicate-zod.js +45 -0
  56. package/dist/sql-predicate-zod.js.map +1 -0
  57. package/dist/sql-predicate.cjs +607 -0
  58. package/dist/sql-predicate.cjs.map +6 -0
  59. package/dist/sql-predicate.d.ts +6 -0
  60. package/dist/sql-predicate.d.ts.map +1 -0
  61. package/dist/sql-predicate.js +8 -0
  62. package/dist/sql-predicate.js.map +1 -0
  63. package/dist/sql-source.d.ts +16 -3
  64. package/dist/sql-source.d.ts.map +1 -1
  65. package/dist/sql-source.js +34 -5
  66. package/dist/sql-source.js.map +1 -1
  67. package/dist/sql-types.d.ts +3 -0
  68. package/dist/sql-types.d.ts.map +1 -1
  69. package/dist/table-query-capabilities.d.ts +6 -0
  70. package/dist/table-query-capabilities.d.ts.map +1 -0
  71. package/dist/table-query-capabilities.js +26 -0
  72. package/dist/table-query-capabilities.js.map +1 -0
  73. package/dist/table-query.cjs +286 -0
  74. package/dist/table-query.cjs.map +6 -0
  75. package/dist/table-query.d.ts +29 -0
  76. package/dist/table-query.d.ts.map +1 -0
  77. package/dist/table-query.js +30 -0
  78. package/dist/table-query.js.map +1 -0
  79. package/package.json +45 -8
  80. package/src/arrow-query.ts +17 -0
  81. package/src/arrow-table-source.ts +111 -0
  82. package/src/bind-sql-predicate.ts +21 -0
  83. package/src/compile-table-query.ts +354 -0
  84. package/src/duckdb-sql-source.ts +30 -6
  85. package/src/index.ts +57 -0
  86. package/src/parse-sql-predicate.ts +381 -0
  87. package/src/query-arrow-table.ts +846 -0
  88. package/src/snowflake-sql-source.ts +8 -5
  89. package/src/sql-predicate-schema.ts +251 -0
  90. package/src/sql-predicate-types.ts +87 -0
  91. package/src/sql-predicate-zod.ts +52 -0
  92. package/src/sql-predicate.ts +28 -0
  93. package/src/sql-source.ts +40 -5
  94. package/src/sql-types.ts +4 -0
  95. package/src/table-query-capabilities.ts +29 -0
  96. package/src/table-query.ts +78 -0
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@loaders.gl/sql",
3
3
  "description": "Framework-independent SQL data sources",
4
- "version": "5.0.0-alpha.1",
4
+ "version": "5.0.0-alpha.11",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "publishConfig": {
@@ -25,6 +25,26 @@
25
25
  "types": "./dist/index.d.ts",
26
26
  "import": "./dist/index.js",
27
27
  "require": "./dist/index.cjs"
28
+ },
29
+ "./sql-predicate": {
30
+ "types": "./dist/sql-predicate.d.ts",
31
+ "import": "./dist/sql-predicate.js",
32
+ "require": "./dist/sql-predicate.cjs"
33
+ },
34
+ "./arrow-query": {
35
+ "types": "./dist/arrow-query.d.ts",
36
+ "import": "./dist/arrow-query.js",
37
+ "require": "./dist/arrow-query.cjs"
38
+ },
39
+ "./table-query": {
40
+ "types": "./dist/table-query.d.ts",
41
+ "import": "./dist/table-query.js",
42
+ "require": "./dist/table-query.cjs"
43
+ },
44
+ "./sql-predicate-zod": {
45
+ "types": "./dist/sql-predicate-zod.d.ts",
46
+ "import": "./dist/sql-predicate-zod.js",
47
+ "require": "./dist/sql-predicate-zod.cjs"
28
48
  }
29
49
  },
30
50
  "sideEffects": false,
@@ -43,15 +63,32 @@
43
63
  "build-bundle": "# ocular-bundle ./bundle.ts --external:{util,fs,path}"
44
64
  },
45
65
  "dependencies": {
46
- "@duckdb/duckdb-wasm": "^1.33.1-dev45.0",
47
- "@duckdb/node-api": "^1.5.2-r.1",
48
- "@loaders.gl/loader-utils": "5.0.0-alpha.1",
49
- "@loaders.gl/schema": "5.0.0-alpha.1",
50
- "@loaders.gl/schema-utils": "5.0.0-alpha.1",
66
+ "@loaders.gl/loader-utils": "5.0.0-alpha.11",
67
+ "@loaders.gl/schema": "5.0.0-alpha.11",
68
+ "@loaders.gl/schema-utils": "5.0.0-alpha.11",
51
69
  "apache-arrow": ">= 17.0.0"
52
70
  },
53
71
  "peerDependencies": {
54
- "@loaders.gl/core": "~5.0.0-alpha.0"
72
+ "@duckdb/duckdb-wasm": "^1.33.1-dev45.0",
73
+ "@duckdb/node-api": "^1.5.2-r.1",
74
+ "@loaders.gl/core": "~5.0.0-alpha.0",
75
+ "zod": "^4.1.12"
76
+ },
77
+ "peerDependenciesMeta": {
78
+ "@duckdb/duckdb-wasm": {
79
+ "optional": true
80
+ },
81
+ "@duckdb/node-api": {
82
+ "optional": true
83
+ },
84
+ "zod": {
85
+ "optional": true
86
+ }
87
+ },
88
+ "devDependencies": {
89
+ "@duckdb/duckdb-wasm": "^1.33.1-dev45.0",
90
+ "@duckdb/node-api": "^1.5.2-r.1",
91
+ "zod": "^4.1.12"
55
92
  },
56
- "gitHead": "77a55028e8204e09df1258f10cb61ed35353b258"
93
+ "gitHead": "31449661e98c1c3f97bb4f8a7bcba7f19596ac00"
57
94
  }
@@ -0,0 +1,17 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ export {ARROW_TABLE_QUERY_CAPABILITIES, queryArrowTable} from './query-arrow-table';
6
+ export {getSQLPredicateColumnNames, planTableQuery} from './table-query';
7
+
8
+ export type {
9
+ TableQueryFilterStep,
10
+ TableQueryLimitStep,
11
+ TableQueryOptions,
12
+ TableQueryPlan,
13
+ TableQueryPlanStep,
14
+ TableQueryProjectStep,
15
+ TableQueryScanStep
16
+ } from './table-query';
17
+ export type {ArrowQueryOptions} from './query-arrow-table';
@@ -0,0 +1,111 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ import type {
6
+ DataSourceOptions,
7
+ ScanQueryMetadata,
8
+ ScanQueryMetadataOptions
9
+ } from '@loaders.gl/loader-utils';
10
+ import {
11
+ createScanQueryMetadata,
12
+ DataSource,
13
+ makeTableScanBatch,
14
+ type ScanColumnRole
15
+ } from '@loaders.gl/loader-utils';
16
+ import {convertArrowToSchema} from '@loaders.gl/schema-utils';
17
+ import type {ArrowTable, ArrowTableBatch} from '@loaders.gl/schema';
18
+ import {
19
+ ARROW_TABLE_QUERY_CAPABILITIES,
20
+ explainArrowTableQuery,
21
+ queryArrowTable
22
+ } from './query-arrow-table';
23
+ import type {ArrowQueryOptions} from './query-arrow-table';
24
+ import type {TableQueryExplain} from './table-query';
25
+
26
+ /** In-memory source options; the source owns the supplied Arrow table. */
27
+ export type ArrowTableSourceOptions = DataSourceOptions;
28
+
29
+ /**
30
+ * Query source for an in-memory Arrow or GeoArrow table.
31
+ *
32
+ * This is the reference source for the shared scan panel: metadata discovery is synchronous in
33
+ * practice, and query execution delegates to the existing Arrow executor without ingesting data
34
+ * into DuckDB or another intermediate representation.
35
+ */
36
+ export class ArrowTableSource extends DataSource<ArrowTable, ArrowTableSourceOptions> {
37
+ /** Creates a source over an existing Arrow table without copying its vectors. */
38
+ constructor(data: ArrowTable, options: ArrowTableSourceOptions = {}) {
39
+ super(data, options);
40
+ }
41
+
42
+ /** Discovers query-visible fields and capabilities without evaluating any rows. */
43
+ async getQueryMetadata(options: ScanQueryMetadataOptions = {}): Promise<ScanQueryMetadata> {
44
+ throwIfAborted(options.signal);
45
+ const schema = convertArrowToSchema(this.data.data.schema);
46
+ return createScanQueryMetadata({
47
+ sourceType: 'arrow-table',
48
+ queryType: 'table',
49
+ execution: {status: 'supported', method: 'read'},
50
+ schema,
51
+ capabilities: {table: ARROW_TABLE_QUERY_CAPABILITIES},
52
+ columnRoles: getArrowColumnRoles(schema.fields.map(field => field.name)),
53
+ statistics: {rowCount: this.data.data.numRows}
54
+ });
55
+ }
56
+
57
+ /** Executes a portable query and returns an Arrow table result. */
58
+ query(options: ArrowQueryOptions = {}): ArrowTable {
59
+ return queryArrowTable(this.data, options);
60
+ }
61
+
62
+ /** Explains a portable query without evaluating table rows. */
63
+ explain(options: ArrowQueryOptions = {}): TableQueryExplain {
64
+ return explainArrowTableQuery(this.data, options);
65
+ }
66
+
67
+ /** Executes a query as one bounded Arrow batch. */
68
+ async *read(options: ArrowQueryOptions = {}): AsyncIterableIterator<ArrowTableBatch> {
69
+ const result = this.query(options);
70
+ yield makeTableScanBatch(result);
71
+ }
72
+ }
73
+
74
+ /** Returns conventional semantic roles for common Arrow coordinate and time names. */
75
+ function getArrowColumnRoles(
76
+ columnNames: readonly string[]
77
+ ): Readonly<Record<string, ScanColumnRole>> {
78
+ const roles: Record<string, ScanColumnRole> = {};
79
+ for (const columnName of columnNames) {
80
+ const normalizedName = columnName.toLowerCase();
81
+ if (normalizedName === 'x' || normalizedName === 'longitude' || normalizedName === 'lon') {
82
+ roles[columnName] = normalizedName === 'x' ? 'x' : 'longitude';
83
+ } else if (
84
+ normalizedName === 'y' ||
85
+ normalizedName === 'latitude' ||
86
+ normalizedName === 'lat'
87
+ ) {
88
+ roles[columnName] = normalizedName === 'y' ? 'y' : 'latitude';
89
+ } else if (
90
+ normalizedName === 'z' ||
91
+ normalizedName === 'elevation' ||
92
+ normalizedName === 'altitude'
93
+ ) {
94
+ roles[columnName] = normalizedName === 'z' ? 'z' : 'attribute';
95
+ } else if (
96
+ normalizedName === 'time' ||
97
+ normalizedName.endsWith('_time') ||
98
+ normalizedName.endsWith('timestamp')
99
+ ) {
100
+ roles[columnName] = 'time';
101
+ }
102
+ }
103
+ return roles;
104
+ }
105
+
106
+ /** Throws the common source cancellation error before metadata or execution work begins. */
107
+ function throwIfAborted(signal: AbortSignal | undefined): void {
108
+ if (signal?.aborted) {
109
+ throw new Error('Request aborted');
110
+ }
111
+ }
@@ -0,0 +1,21 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ import {bindColumnarPredicateParameters} from '@loaders.gl/loader-utils';
6
+
7
+ import {validateSQLPredicate} from './sql-predicate-schema';
8
+ import {
9
+ type BoundSQLPredicate,
10
+ type SQLPredicate,
11
+ type SQLPredicateParameterValues
12
+ } from './sql-predicate-types';
13
+
14
+ /** Binds named parameter references in a portable SQL predicate without mutating the input AST. */
15
+ export function bindSQLPredicate(
16
+ predicate: SQLPredicate,
17
+ parameters: SQLPredicateParameterValues
18
+ ): BoundSQLPredicate {
19
+ validateSQLPredicate(predicate);
20
+ return bindColumnarPredicateParameters(predicate, parameters);
21
+ }
@@ -0,0 +1,354 @@
1
+ // loaders.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // Copyright (c) vis.gl contributors
4
+
5
+ import {validateSQLPredicate} from './sql-predicate-schema';
6
+ import {
7
+ isSQLPredicateParameter,
8
+ type SQLPredicate,
9
+ type SQLPredicateParameterValues,
10
+ type SQLPredicateScalar,
11
+ type SQLPredicateValue
12
+ } from './sql-predicate-types';
13
+ import type {TableQueryOptions} from './table-query';
14
+ import type {
15
+ RelationalAggregate,
16
+ RelationalExpression,
17
+ RelationalOrderKey
18
+ } from '@loaders.gl/loader-utils';
19
+
20
+ /** A named child relation using the SQL module's property-oriented predicate AST. */
21
+ type SQLChildQuery = Readonly<{
22
+ /** Logical source name resolved by the SQL data source. */
23
+ source: string;
24
+ /** Optional query applied to the child relation before combining it. */
25
+ query?: TableQueryOptions;
26
+ }>;
27
+
28
+ /** SQL dialects supported by the portable table-query compiler. */
29
+ export type SQLTableQueryDialect = 'duckdb' | 'snowflake';
30
+
31
+ /** A table-bound portable query accepted by SQL-backed data sources. */
32
+ export type SQLTableQuery = TableQueryOptions &
33
+ Readonly<{
34
+ /** Unqualified table name. */
35
+ tableName: string;
36
+ /** Optional schema containing the table. */
37
+ schemaName?: string;
38
+ /** Optional catalog containing the schema. */
39
+ catalogName?: string;
40
+ /** Computed columns evaluated before projection. */
41
+ expressions?: readonly RelationalExpression[];
42
+ /** Stable ordering applied before the global limit. */
43
+ orderBy?: readonly RelationalOrderKey[];
44
+ /** Grouping keys for aggregate output. */
45
+ groupBy?: readonly string[];
46
+ /** Aggregate output definitions. */
47
+ aggregates?: readonly RelationalAggregate[];
48
+ /** Additional tables concatenated with `UNION ALL`. */
49
+ union?: readonly SQLChildQuery[];
50
+ /** Optional equi-join child table and key mapping. */
51
+ join?: Readonly<{child: SQLChildQuery; left: string; right: string}>;
52
+ }>;
53
+
54
+ /** Options controlling portable table-query compilation. */
55
+ export type SQLTableQueryCompilerOptions = Readonly<{
56
+ /** Target SQL dialect. */
57
+ dialect: SQLTableQueryDialect;
58
+ /** Values used to resolve named parameter nodes retained in the predicate AST. */
59
+ parameters?: SQLPredicateParameterValues;
60
+ }>;
61
+
62
+ /** Parameterized SQL emitted from a portable table query. */
63
+ export type CompiledSQLTableQuery = Readonly<{
64
+ /** SQL statement containing positional placeholders. */
65
+ sql: string;
66
+ /** Values bound to placeholders in statement order. */
67
+ parameters: SQLPredicateScalar[];
68
+ }>;
69
+
70
+ type SQLCompilationContext = {
71
+ dialect: SQLTableQueryDialect;
72
+ namedParameters?: SQLPredicateParameterValues;
73
+ parameters: SQLPredicateScalar[];
74
+ };
75
+
76
+ /** Compiles a portable table query into parameterized DuckDB or Snowflake SQL. */
77
+ export function compileSQLTableQuery(
78
+ query: SQLTableQuery,
79
+ options: SQLTableQueryCompilerOptions
80
+ ): CompiledSQLTableQuery {
81
+ validateSQLTableQuery(query);
82
+ const context: SQLCompilationContext = {
83
+ dialect: options.dialect,
84
+ namedParameters: options.parameters,
85
+ parameters: []
86
+ };
87
+ return {
88
+ sql: compileTableStatement(query, context),
89
+ parameters: context.parameters
90
+ };
91
+ }
92
+
93
+ /** Compiles one table statement while sharing parameter bindings with child relations. */
94
+ function compileTableStatement(query: SQLTableQuery, context: SQLCompilationContext): string {
95
+ const projection = compileProjection(query);
96
+ const table = [query.catalogName, query.schemaName, query.tableName]
97
+ .filter((identifier): identifier is string => identifier !== undefined)
98
+ .map(quoteSQLIdentifier)
99
+ .join('.');
100
+ const fromClause = query.join ? compileJoinFromClause(query, table, context) : `FROM ${table}`;
101
+ const clauses = [`SELECT ${projection}`, fromClause];
102
+ if (query.predicate) {
103
+ clauses.push(`WHERE ${compileSQLPredicate(query.predicate, context)}`);
104
+ }
105
+ if (query.groupBy?.length) {
106
+ clauses.push(`GROUP BY ${query.groupBy.map(quoteSQLIdentifier).join(', ')}`);
107
+ }
108
+ let sql = clauses.join('\n');
109
+ for (const child of query.union || []) {
110
+ const childQuery: SQLTableQuery = {
111
+ tableName: child.source,
112
+ ...(child.query || {})
113
+ };
114
+ validateSQLTableQuery(childQuery);
115
+ const childSQL = compileTableStatement(childQuery, context);
116
+ const branchSQL = hasBranchLocalModifiers(childQuery) ? `(${childSQL})` : childSQL;
117
+ sql = `${sql}\nUNION ALL\n${branchSQL}`;
118
+ }
119
+ if (query.orderBy?.length) sql += `\nORDER BY ${query.orderBy.map(compileOrderKey).join(', ')}`;
120
+ if (query.limit !== undefined) sql += `\nLIMIT ${query.limit}`;
121
+ return sql;
122
+ }
123
+
124
+ /** Compiles a base table and optional child relation for an equi-join. */
125
+ function compileJoinFromClause(
126
+ query: SQLTableQuery,
127
+ table: string,
128
+ context: SQLCompilationContext
129
+ ): string {
130
+ const join = query.join;
131
+ if (!join) return `FROM ${table}`;
132
+ validateSQLIdentifier(join.child.source);
133
+ validateSQLIdentifier(join.left);
134
+ validateSQLIdentifier(join.right);
135
+ const childTable = quoteSQLIdentifier(join.child.source);
136
+ const rightRelation = join.child.query
137
+ ? `(${compileTableStatement({tableName: join.child.source, ...join.child.query}, context)})`
138
+ : childTable;
139
+ return `FROM ${table} JOIN ${rightRelation} AS ${childTable} ON ${table}.${quoteSQLIdentifier(join.left)} = ${childTable}.${quoteSQLIdentifier(join.right)}`;
140
+ }
141
+
142
+ /** Compiles the SELECT list, including computed and aggregate output columns. */
143
+ function compileProjection(query: SQLTableQuery): string {
144
+ const expressions = query.expressions || [];
145
+ const expressionByName = new Map(expressions.map(expression => [expression.name, expression]));
146
+ const aggregates = query.aggregates || [];
147
+ const aggregateByName = new Map(aggregates.map(aggregate => [aggregate.name, aggregate]));
148
+ const columns = query.columns === undefined ? undefined : [...query.columns];
149
+ const projectionColumns =
150
+ columns ||
151
+ (query.groupBy?.length || query.aggregates?.length ? [...(query.groupBy || [])] : []);
152
+ const selections = projectionColumns.map(column => {
153
+ const expression = expressionByName.get(column);
154
+ if (expression) {
155
+ return `${compileRelationalExpression(expression.expression)} AS ${quoteSQLIdentifier(expression.name)}`;
156
+ }
157
+ const aggregate = aggregateByName.get(column);
158
+ return aggregate
159
+ ? `${compileAggregate(aggregate)} AS ${quoteSQLIdentifier(aggregate.name)}`
160
+ : compileProjectionColumn(column, query);
161
+ });
162
+ if (!selections.length)
163
+ return expressions.length
164
+ ? expressions
165
+ .map(
166
+ expression =>
167
+ `${compileRelationalExpression(expression.expression)} AS ${quoteSQLIdentifier(expression.name)}`
168
+ )
169
+ .join(', ')
170
+ : aggregates.length
171
+ ? aggregates
172
+ .map(
173
+ aggregate => `${compileAggregate(aggregate)} AS ${quoteSQLIdentifier(aggregate.name)}`
174
+ )
175
+ .join(', ')
176
+ : '*';
177
+ return selections.join(', ');
178
+ }
179
+
180
+ /** Quotes a projection column, qualifying joined child fields component-wise. */
181
+ function compileProjectionColumn(column: string, query: SQLTableQuery): string {
182
+ const childSource = query.join?.child.source;
183
+ return childSource && column.startsWith(`${childSource}.`)
184
+ ? column.split('.').map(quoteSQLIdentifier).join('.')
185
+ : quoteSQLIdentifier(column);
186
+ }
187
+
188
+ /** Returns whether a UNION child contains modifiers that must remain branch-local. */
189
+ function hasBranchLocalModifiers(query: SQLTableQuery): boolean {
190
+ return Boolean(query.limit !== undefined || query.orderBy?.length || query.union?.length);
191
+ }
192
+
193
+ /** Compiles one portable scalar expression into quoted SQL. */
194
+ function compileRelationalExpression(expression: RelationalExpression['expression']): string {
195
+ switch (expression.op) {
196
+ case 'column':
197
+ return quoteSQLIdentifier(expression.column);
198
+ case 'literal':
199
+ return expression.value === null
200
+ ? 'NULL'
201
+ : typeof expression.value === 'string'
202
+ ? `'${expression.value.replace(/'/g, "''")}'`
203
+ : String(expression.value);
204
+ case 'add':
205
+ return `(${quoteSQLIdentifier(expression.left)} + ${quoteSQLIdentifier(expression.right)})`;
206
+ case 'subtract':
207
+ return `(${quoteSQLIdentifier(expression.left)} - ${quoteSQLIdentifier(expression.right)})`;
208
+ case 'multiply':
209
+ return `(${quoteSQLIdentifier(expression.left)} * ${quoteSQLIdentifier(expression.right)})`;
210
+ case 'divide':
211
+ return `(${quoteSQLIdentifier(expression.left)} / NULLIF(${quoteSQLIdentifier(expression.right)}, 0))`;
212
+ }
213
+ }
214
+
215
+ /** Compiles one portable aggregate function call. */
216
+ function compileAggregate(aggregate: RelationalAggregate): string {
217
+ const column = aggregate.column ? quoteSQLIdentifier(aggregate.column) : '*';
218
+ return `${aggregate.function.toUpperCase()}(${column})`;
219
+ }
220
+
221
+ /** Compiles one ordering key with explicit direction and null placement. */
222
+ function compileOrderKey(orderKey: RelationalOrderKey): string {
223
+ const direction = orderKey.direction?.toUpperCase() || 'ASC';
224
+ const nulls = orderKey.nulls ? ` NULLS ${orderKey.nulls.toUpperCase()}` : '';
225
+ return `${quoteSQLIdentifier(orderKey.column)} ${direction}${nulls}`;
226
+ }
227
+
228
+ /** Compiles one portable predicate node while collecting bound scalar values. */
229
+ function compileSQLPredicate(predicate: SQLPredicate, context: SQLCompilationContext): string {
230
+ switch (predicate.op) {
231
+ case 'and':
232
+ case 'or':
233
+ return `(${predicate.args
234
+ .map(child => compileSQLPredicate(child, context))
235
+ .join(` ${predicate.op.toUpperCase()} `)})`;
236
+ case 'not':
237
+ return `(NOT ${compileSQLPredicate(predicate.args[0], context)})`;
238
+ case 'isNull':
239
+ return `(${quoteSQLProperty(predicate.args[0])} IS NULL)`;
240
+ case 'in':
241
+ return `(${quoteSQLProperty(predicate.args[0])} IN (${predicate.args[1]
242
+ .map(value => compileSQLPredicateValue(value, context))
243
+ .join(', ')}))`;
244
+ default:
245
+ return `(${quoteSQLProperty(predicate.args[0])} ${predicate.op} ${compileSQLPredicateValue(
246
+ predicate.args[1],
247
+ context
248
+ )})`;
249
+ }
250
+ }
251
+
252
+ /** Adds a predicate value to the positional bindings and returns its placeholder. */
253
+ function compileSQLPredicateValue(
254
+ value: SQLPredicateValue,
255
+ context: SQLCompilationContext
256
+ ): string {
257
+ const scalar = isSQLPredicateParameter(value)
258
+ ? resolveSQLPredicateParameter(value.parameter, context.namedParameters)
259
+ : value;
260
+ context.parameters.push(scalar);
261
+ return getSQLPlaceholder(context.dialect, context.parameters.length);
262
+ }
263
+
264
+ /** Resolves one retained named parameter reference. */
265
+ function resolveSQLPredicateParameter(
266
+ parameterName: string,
267
+ parameters?: SQLPredicateParameterValues
268
+ ): SQLPredicateScalar {
269
+ if (!parameters || !Object.hasOwn(parameters, parameterName)) {
270
+ throw new Error(`SQL predicate parameter ":${parameterName}" requires a value`);
271
+ }
272
+ const value = parameters[parameterName];
273
+ validateSQLPredicate({op: '=', args: [{property: '_parameter'}, value]});
274
+ return value;
275
+ }
276
+
277
+ /** Returns the positional placeholder used by the selected SQL API. */
278
+ function getSQLPlaceholder(_dialect: SQLTableQueryDialect, _position: number): string {
279
+ return '?';
280
+ }
281
+
282
+ /** Quotes a possibly qualified predicate property one identifier component at a time. */
283
+ function quoteSQLProperty(property: {property: string; quoted?: boolean}): string {
284
+ return property.quoted
285
+ ? quoteSQLIdentifier(property.property)
286
+ : property.property.split('.').map(quoteSQLIdentifier).join('.');
287
+ }
288
+
289
+ /** Quotes one SQL identifier using standard double-quote escaping. */
290
+ function quoteSQLIdentifier(identifier: string): string {
291
+ validateSQLIdentifier(identifier);
292
+ return `"${identifier.replace(/"/g, '""')}"`;
293
+ }
294
+
295
+ /** Validates the structural fields that do not require a source schema. */
296
+ function validateSQLTableQuery(query: SQLTableQuery): void {
297
+ validateSQLIdentifier(query.tableName);
298
+ if (query.schemaName !== undefined) validateSQLIdentifier(query.schemaName);
299
+ if (query.catalogName !== undefined) validateSQLIdentifier(query.catalogName);
300
+ const seenColumns = new Set<string>();
301
+ if (query.columns?.length === 0) {
302
+ throw new Error('SQL table-query projections must select at least one column.');
303
+ }
304
+ for (const column of query.columns ?? []) {
305
+ validateSQLIdentifier(column);
306
+ if (seenColumns.has(column)) {
307
+ throw new Error(`Table query column was selected more than once: ${column}`);
308
+ }
309
+ seenColumns.add(column);
310
+ }
311
+ if (query.limit !== undefined && (!Number.isSafeInteger(query.limit) || query.limit < 0)) {
312
+ throw new Error('Table query limit must be a non-negative safe integer.');
313
+ }
314
+ if (query.predicate) validateSQLPredicate(query.predicate);
315
+ validateRelationalQuery(query);
316
+ }
317
+
318
+ /** Validates relational identifiers and enum values before SQL generation. */
319
+ function validateRelationalQuery(query: SQLTableQuery): void {
320
+ const expressionNames = new Set<string>();
321
+ for (const expression of query.expressions || []) {
322
+ validateSQLIdentifier(expression.name);
323
+ if (expressionNames.has(expression.name))
324
+ throw new Error(`Relational expression duplicates column: ${expression.name}`);
325
+ expressionNames.add(expression.name);
326
+ const definition = expression.expression;
327
+ if (definition.op === 'column') validateSQLIdentifier(definition.column);
328
+ if ('left' in definition) {
329
+ validateSQLIdentifier(definition.left);
330
+ validateSQLIdentifier(definition.right);
331
+ }
332
+ }
333
+ for (const column of query.groupBy || []) validateSQLIdentifier(column);
334
+ for (const key of query.orderBy || []) {
335
+ validateSQLIdentifier(key.column);
336
+ if (key.direction && key.direction !== 'asc' && key.direction !== 'desc')
337
+ throw new Error(`Invalid order direction: ${key.direction}`);
338
+ if (key.nulls && key.nulls !== 'first' && key.nulls !== 'last')
339
+ throw new Error(`Invalid null placement: ${key.nulls}`);
340
+ }
341
+ for (const aggregate of query.aggregates || []) {
342
+ validateSQLIdentifier(aggregate.name);
343
+ if (aggregate.function !== 'count' && !aggregate.column)
344
+ throw new Error(`Relational aggregate ${aggregate.function} requires a column.`);
345
+ if (aggregate.column) validateSQLIdentifier(aggregate.column);
346
+ }
347
+ }
348
+
349
+ /** Rejects empty or NUL-containing identifiers before quoting them. */
350
+ function validateSQLIdentifier(identifier: string): void {
351
+ if (!identifier || identifier.includes('\0')) {
352
+ throw new Error('SQL table-query identifiers must be non-empty and cannot contain NUL bytes.');
353
+ }
354
+ }
@@ -248,8 +248,11 @@ async function createDuckDBBrowserAdapter(context: SQLAdapterFactoryContext): Pr
248
248
  await database.instantiate(bundles.mainModule, bundles.pthreadWorker);
249
249
  const connection = await database.connect();
250
250
 
251
- const executeRows = async (sqlText: string): Promise<Record<string, unknown>[]> => {
252
- const result = await connection.query(sqlText);
251
+ const executeRows = async (
252
+ sqlText: string,
253
+ options: SQLQueryOptions = {}
254
+ ): Promise<Record<string, unknown>[]> => {
255
+ const result = await executeDuckDBBrowserQuery(connection, sqlText, options.parameters);
253
256
  return convertArrowToTable(result, 'object-row-table').data;
254
257
  };
255
258
 
@@ -344,16 +347,37 @@ async function createDuckDBBrowserAdapter(context: SQLAdapterFactoryContext): Pr
344
347
  );
345
348
  return convertSQLColumnsToSchema(columns);
346
349
  },
347
- async executeRows(sqlText: string): Promise<Record<string, unknown>[]> {
348
- return await executeRows(sqlText);
350
+ async executeRows(
351
+ sqlText: string,
352
+ options: SQLQueryOptions = {}
353
+ ): Promise<Record<string, unknown>[]> {
354
+ return await executeRows(sqlText, options);
349
355
  },
350
- async executeArrow(sqlText: string) {
351
- const result = await connection.query(sqlText);
356
+ async executeArrow(sqlText: string, options: SQLQueryOptions = {}) {
357
+ const result = await executeDuckDBBrowserQuery(connection, sqlText, options.parameters);
352
358
  return convertArrowToTable(result, 'arrow-table');
353
359
  }
354
360
  };
355
361
  }
356
362
 
363
+ /** Executes a DuckDB-Wasm query directly or through a prepared statement when values are bound. */
364
+ async function executeDuckDBBrowserQuery(
365
+ connection: any,
366
+ sqlText: string,
367
+ parameters?: SQLQueryOptions['parameters']
368
+ ): Promise<any> {
369
+ if (!parameters) {
370
+ return await connection.query(sqlText);
371
+ }
372
+ const values = Array.isArray(parameters) ? parameters : Object.values(parameters);
373
+ const statement = await connection.prepare(sqlText);
374
+ try {
375
+ return await statement.query(...values);
376
+ } finally {
377
+ await statement.close();
378
+ }
379
+ }
380
+
357
381
  function getDuckDBDatabasePath(url: string, options: SQLSourceOptions): string {
358
382
  if (options.duckdb?.databasePath) {
359
383
  return options.duckdb.databasePath;