@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.
- package/LICENSE +1 -1
- package/README.md +60 -2
- package/dist/arrow-query.cjs +1373 -0
- package/dist/arrow-query.cjs.map +6 -0
- package/dist/arrow-query.d.ts +5 -0
- package/dist/arrow-query.d.ts.map +1 -0
- package/dist/arrow-query.js +6 -0
- package/dist/arrow-query.js.map +1 -0
- package/dist/arrow-table-source.d.ts +27 -0
- package/dist/arrow-table-source.d.ts.map +1 -0
- package/dist/arrow-table-source.js +79 -0
- package/dist/arrow-table-source.js.map +1 -0
- package/dist/bind-sql-predicate.d.ts +4 -0
- package/dist/bind-sql-predicate.d.ts.map +1 -0
- package/dist/bind-sql-predicate.js +11 -0
- package/dist/bind-sql-predicate.js.map +1 -0
- package/dist/compile-table-query.d.ts +55 -0
- package/dist/compile-table-query.d.ts.map +1 -0
- package/dist/compile-table-query.js +255 -0
- package/dist/compile-table-query.js.map +1 -0
- package/dist/duckdb-sql-source.d.ts.map +1 -1
- package/dist/duckdb-sql-source.js +21 -7
- package/dist/duckdb-sql-source.js.map +1 -1
- package/dist/index.cjs +1746 -307
- package/dist/index.cjs.map +3 -3
- package/dist/index.d.ts +14 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -0
- package/dist/index.js.map +1 -1
- package/dist/parse-sql-predicate.d.ts.map +1 -1
- package/dist/parse-sql-predicate.js +10 -4
- package/dist/parse-sql-predicate.js.map +1 -1
- package/dist/query-arrow-table.d.ts +83 -0
- package/dist/query-arrow-table.d.ts.map +1 -0
- package/dist/query-arrow-table.js +660 -0
- package/dist/query-arrow-table.js.map +1 -0
- package/dist/snowflake-sql-source.d.ts.map +1 -1
- package/dist/snowflake-sql-source.js +8 -5
- package/dist/snowflake-sql-source.js.map +1 -1
- package/dist/sql-predicate-schema.d.ts +17 -2
- package/dist/sql-predicate-schema.d.ts.map +1 -1
- package/dist/sql-predicate-schema.js +25 -4
- package/dist/sql-predicate-schema.js.map +1 -1
- package/dist/sql-predicate-types.d.ts +22 -32
- package/dist/sql-predicate-types.d.ts.map +1 -1
- package/dist/sql-predicate-types.js +5 -1
- package/dist/sql-predicate-types.js.map +1 -1
- package/dist/sql-predicate-zod.cjs +3 -2
- package/dist/sql-predicate-zod.cjs.map +1 -1
- package/dist/sql-predicate-zod.d.ts.map +1 -1
- package/dist/sql-predicate-zod.js +5 -2
- package/dist/sql-predicate-zod.js.map +1 -1
- package/dist/sql-predicate.cjs +114 -7
- package/dist/sql-predicate.cjs.map +2 -2
- package/dist/sql-predicate.d.ts +3 -1
- package/dist/sql-predicate.d.ts.map +1 -1
- package/dist/sql-predicate.js +2 -0
- package/dist/sql-predicate.js.map +1 -1
- package/dist/sql-source.d.ts +16 -3
- package/dist/sql-source.d.ts.map +1 -1
- package/dist/sql-source.js +34 -5
- package/dist/sql-source.js.map +1 -1
- package/dist/sql-types.d.ts +3 -0
- package/dist/sql-types.d.ts.map +1 -1
- package/dist/table-query-capabilities.d.ts +6 -0
- package/dist/table-query-capabilities.d.ts.map +1 -0
- package/dist/table-query-capabilities.js +26 -0
- package/dist/table-query-capabilities.js.map +1 -0
- package/dist/table-query.cjs +286 -0
- package/dist/table-query.cjs.map +6 -0
- package/dist/table-query.d.ts +29 -0
- package/dist/table-query.d.ts.map +1 -0
- package/dist/table-query.js +30 -0
- package/dist/table-query.js.map +1 -0
- package/package.json +15 -5
- package/src/arrow-query.ts +17 -0
- package/src/arrow-table-source.ts +111 -0
- package/src/bind-sql-predicate.ts +21 -0
- package/src/compile-table-query.ts +354 -0
- package/src/duckdb-sql-source.ts +30 -6
- package/src/index.ts +39 -0
- package/src/parse-sql-predicate.ts +21 -5
- package/src/query-arrow-table.ts +843 -0
- package/src/snowflake-sql-source.ts +7 -4
- package/src/sql-predicate-schema.ts +30 -5
- package/src/sql-predicate-types.ts +48 -32
- package/src/sql-predicate-zod.ts +5 -2
- package/src/sql-predicate.ts +6 -0
- package/src/sql-source.ts +40 -5
- package/src/sql-types.ts +4 -0
- package/src/table-query-capabilities.ts +29 -0
- package/src/table-query.ts +78 -0
|
@@ -265,14 +265,17 @@ async function fetchSnowflakeJson(
|
|
|
265
265
|
function normalizeSnowflakeBindings(
|
|
266
266
|
parameters: SQLQueryOptions['parameters']
|
|
267
267
|
): Record<string, {type: string; value: unknown}> | undefined {
|
|
268
|
-
if (!parameters
|
|
268
|
+
if (!parameters) {
|
|
269
269
|
return undefined;
|
|
270
270
|
}
|
|
271
271
|
const bindings: Record<string, {type: string; value: unknown}> = {};
|
|
272
|
-
|
|
272
|
+
const entries = Array.isArray(parameters)
|
|
273
|
+
? parameters.map((value, index) => [String(index + 1), value] as const)
|
|
274
|
+
: Object.entries(parameters);
|
|
275
|
+
for (const [key, value] of entries) {
|
|
273
276
|
bindings[key] = {
|
|
274
|
-
type: typeof value === 'number' ? 'FIXED' : 'TEXT',
|
|
275
|
-
value
|
|
277
|
+
type: typeof value === 'number' || typeof value === 'bigint' ? 'FIXED' : 'TEXT',
|
|
278
|
+
value: typeof value === 'bigint' ? value.toString() : value
|
|
276
279
|
};
|
|
277
280
|
}
|
|
278
281
|
return bindings;
|
|
@@ -2,7 +2,11 @@
|
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
// Copyright (c) vis.gl contributors
|
|
4
4
|
|
|
5
|
-
import
|
|
5
|
+
import {
|
|
6
|
+
isSQLPredicateParameter,
|
|
7
|
+
type SQLPredicate,
|
|
8
|
+
type SQLPredicateValue
|
|
9
|
+
} from './sql-predicate-types';
|
|
6
10
|
|
|
7
11
|
const MAXIMUM_PREDICATE_DEPTH = 64;
|
|
8
12
|
const MAXIMUM_PREDICATE_NODES = 4096;
|
|
@@ -28,10 +32,23 @@ export const SQL_PREDICATE_JSON_SCHEMA = {
|
|
|
28
32
|
property: {
|
|
29
33
|
type: 'object',
|
|
30
34
|
required: ['property'],
|
|
31
|
-
properties: {
|
|
35
|
+
properties: {
|
|
36
|
+
property: {type: 'string', minLength: 1},
|
|
37
|
+
quoted: {type: 'boolean'}
|
|
38
|
+
},
|
|
32
39
|
additionalProperties: false
|
|
33
40
|
},
|
|
34
|
-
value: {
|
|
41
|
+
value: {
|
|
42
|
+
oneOf: [
|
|
43
|
+
{type: ['boolean', 'number', 'string']},
|
|
44
|
+
{
|
|
45
|
+
type: 'object',
|
|
46
|
+
required: ['parameter'],
|
|
47
|
+
properties: {parameter: {type: 'string', minLength: 1}},
|
|
48
|
+
additionalProperties: false
|
|
49
|
+
}
|
|
50
|
+
]
|
|
51
|
+
},
|
|
35
52
|
comparison: {
|
|
36
53
|
type: 'object',
|
|
37
54
|
required: ['op', 'args'],
|
|
@@ -187,9 +204,10 @@ function validatePredicateNode(
|
|
|
187
204
|
function validatePredicateProperty(value: unknown, path: string): void {
|
|
188
205
|
if (
|
|
189
206
|
!isRecord(value) ||
|
|
190
|
-
!
|
|
207
|
+
!hasAllowedKeys(value, ['property', 'quoted']) ||
|
|
191
208
|
typeof value.property !== 'string' ||
|
|
192
|
-
value.property.length === 0
|
|
209
|
+
value.property.length === 0 ||
|
|
210
|
+
(value.quoted !== undefined && typeof value.quoted !== 'boolean')
|
|
193
211
|
) {
|
|
194
212
|
throw new Error(`SQL predicate ${path} requires a non-empty property reference`);
|
|
195
213
|
}
|
|
@@ -197,6 +215,9 @@ function validatePredicateProperty(value: unknown, path: string): void {
|
|
|
197
215
|
|
|
198
216
|
/** Validates one structured-cloneable predicate scalar. */
|
|
199
217
|
function validatePredicateValue(value: unknown, path: string): asserts value is SQLPredicateValue {
|
|
218
|
+
if (isSQLPredicateParameter(value)) {
|
|
219
|
+
return;
|
|
220
|
+
}
|
|
200
221
|
if (
|
|
201
222
|
typeof value === 'boolean' ||
|
|
202
223
|
typeof value === 'bigint' ||
|
|
@@ -224,3 +245,7 @@ function hasExactKeys(value: Record<string, unknown>, expectedKeys: readonly str
|
|
|
224
245
|
const keys = Object.keys(value);
|
|
225
246
|
return keys.length === expectedKeys.length && expectedKeys.every(key => keys.includes(key));
|
|
226
247
|
}
|
|
248
|
+
|
|
249
|
+
function hasAllowedKeys(value: Record<string, unknown>, allowedKeys: readonly string[]): boolean {
|
|
250
|
+
return Object.keys(value).every(key => allowedKeys.includes(key));
|
|
251
|
+
}
|
|
@@ -2,54 +2,60 @@
|
|
|
2
2
|
// SPDX-License-Identifier: MIT
|
|
3
3
|
// Copyright (c) vis.gl contributors
|
|
4
4
|
|
|
5
|
+
import {
|
|
6
|
+
isColumnarPredicateParameter,
|
|
7
|
+
type ColumnarComparisonPredicate,
|
|
8
|
+
type ColumnarInPredicate,
|
|
9
|
+
type ColumnarLogicalPredicate,
|
|
10
|
+
type ColumnarNotPredicate,
|
|
11
|
+
type ColumnarNullPredicate,
|
|
12
|
+
type ColumnarPredicate,
|
|
13
|
+
type ColumnarPredicateInputValue,
|
|
14
|
+
type ColumnarPredicateParameter,
|
|
15
|
+
type ColumnarPredicateParameterValues,
|
|
16
|
+
type ColumnarPredicateValue
|
|
17
|
+
} from '@loaders.gl/loader-utils';
|
|
18
|
+
|
|
5
19
|
/** Scalar values supported by portable SQL predicate expressions. */
|
|
6
|
-
export type
|
|
20
|
+
export type SQLPredicateScalar = ColumnarPredicateValue;
|
|
21
|
+
|
|
22
|
+
/** Named parameter reference retained in a portable SQL predicate until execution time. */
|
|
23
|
+
export type SQLPredicateParameter = ColumnarPredicateParameter;
|
|
24
|
+
|
|
25
|
+
/** Scalar value or unresolved named parameter accepted by a portable predicate expression. */
|
|
26
|
+
export type SQLPredicateValue = ColumnarPredicateInputValue;
|
|
27
|
+
|
|
28
|
+
/** Runtime values used to bind named predicate parameters before a backend executes them. */
|
|
29
|
+
export type SQLPredicateParameterValues = ColumnarPredicateParameterValues;
|
|
7
30
|
|
|
8
31
|
/** Reference to one column in a portable SQL predicate expression. */
|
|
9
32
|
export type SQLPredicateProperty = Readonly<{
|
|
10
33
|
/** Column or qualified column name. */
|
|
11
34
|
property: string;
|
|
35
|
+
/** Whether the complete property was a quoted SQL identifier. */
|
|
36
|
+
quoted?: boolean;
|
|
12
37
|
}>;
|
|
13
38
|
|
|
14
39
|
/** Binary comparison between a column and a scalar value. */
|
|
15
|
-
export type SQLComparisonPredicate = Readonly<
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
/** Column reference followed by the scalar value to compare. */
|
|
19
|
-
args: readonly [SQLPredicateProperty, SQLPredicateValue];
|
|
20
|
-
}>;
|
|
40
|
+
export type SQLComparisonPredicate = Readonly<
|
|
41
|
+
ColumnarComparisonPredicate<SQLPredicateValue, SQLPredicateProperty>
|
|
42
|
+
>;
|
|
21
43
|
|
|
22
44
|
/** Membership test between a column and scalar values. */
|
|
23
|
-
export type SQLInPredicate = Readonly<
|
|
24
|
-
/** CQL2-shaped membership operator. */
|
|
25
|
-
op: 'in';
|
|
26
|
-
/** Column reference followed by a non-empty list of candidate values. */
|
|
27
|
-
args: readonly [SQLPredicateProperty, readonly SQLPredicateValue[]];
|
|
28
|
-
}>;
|
|
45
|
+
export type SQLInPredicate = Readonly<ColumnarInPredicate<SQLPredicateValue, SQLPredicateProperty>>;
|
|
29
46
|
|
|
30
47
|
/** Null test for one column. */
|
|
31
|
-
export type SQLNullPredicate = Readonly<
|
|
32
|
-
/** CQL2-shaped null-test operator. */
|
|
33
|
-
op: 'isNull';
|
|
34
|
-
/** Column reference to test. */
|
|
35
|
-
args: readonly [SQLPredicateProperty];
|
|
36
|
-
}>;
|
|
48
|
+
export type SQLNullPredicate = Readonly<ColumnarNullPredicate<SQLPredicateProperty>>;
|
|
37
49
|
|
|
38
50
|
/** Conjunction or disjunction of two or more predicates. */
|
|
39
|
-
export type SQLLogicalPredicate = Readonly<
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
/** Two or more child predicates. */
|
|
43
|
-
args: readonly SQLPredicate[];
|
|
44
|
-
}>;
|
|
51
|
+
export type SQLLogicalPredicate = Readonly<
|
|
52
|
+
ColumnarLogicalPredicate<SQLPredicateValue, SQLPredicateProperty>
|
|
53
|
+
>;
|
|
45
54
|
|
|
46
55
|
/** Negation of one predicate. */
|
|
47
|
-
export type SQLNotPredicate = Readonly<
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
/** Single child predicate. */
|
|
51
|
-
args: readonly [SQLPredicate];
|
|
52
|
-
}>;
|
|
56
|
+
export type SQLNotPredicate = Readonly<
|
|
57
|
+
ColumnarNotPredicate<SQLPredicateValue, SQLPredicateProperty>
|
|
58
|
+
>;
|
|
53
59
|
|
|
54
60
|
/**
|
|
55
61
|
* Portable predicate AST emitted by the loaders.gl SQL expression parser.
|
|
@@ -64,8 +70,18 @@ export type SQLPredicate =
|
|
|
64
70
|
| SQLLogicalPredicate
|
|
65
71
|
| SQLNotPredicate;
|
|
66
72
|
|
|
73
|
+
/** Portable SQL predicate whose named parameters have all been replaced by concrete scalars. */
|
|
74
|
+
export type BoundSQLPredicate = ColumnarPredicate<SQLPredicateScalar, SQLPredicateProperty>;
|
|
75
|
+
|
|
67
76
|
/** Options for parsing one SQL predicate expression. */
|
|
68
77
|
export type SQLPredicateParserOptions = Readonly<{
|
|
69
78
|
/** Named values referenced using SQL parameters such as `:minimumFare`. */
|
|
70
|
-
parameters?:
|
|
79
|
+
parameters?: SQLPredicateParameterValues;
|
|
80
|
+
/** Retains named references in the emitted AST instead of resolving them while parsing. */
|
|
81
|
+
preserveParameters?: boolean;
|
|
71
82
|
}>;
|
|
83
|
+
|
|
84
|
+
/** Returns whether a value is a named parameter reference. */
|
|
85
|
+
export function isSQLPredicateParameter(value: unknown): value is SQLPredicateParameter {
|
|
86
|
+
return isColumnarPredicateParameter(value);
|
|
87
|
+
}
|
package/src/sql-predicate-zod.ts
CHANGED
|
@@ -13,10 +13,13 @@ export const SQLPredicateValueSchema: z.ZodType<SQLPredicateValue> = z.union([
|
|
|
13
13
|
z.bigint(),
|
|
14
14
|
z.string(),
|
|
15
15
|
z.date(),
|
|
16
|
-
z.instanceof(Uint8Array)
|
|
16
|
+
z.instanceof(Uint8Array),
|
|
17
|
+
z.object({parameter: z.string().min(1)}).strict()
|
|
17
18
|
]);
|
|
18
19
|
|
|
19
|
-
const SQLPredicatePropertySchema = z
|
|
20
|
+
const SQLPredicatePropertySchema = z
|
|
21
|
+
.object({property: z.string().min(1), quoted: z.boolean().optional()})
|
|
22
|
+
.strict();
|
|
20
23
|
|
|
21
24
|
/**
|
|
22
25
|
* Optional Zod schema for validating the portable loaders.gl SQL predicate AST.
|
package/src/sql-predicate.ts
CHANGED
|
@@ -8,15 +8,21 @@ export {
|
|
|
8
8
|
SQL_PREDICATE_JSON_SCHEMA,
|
|
9
9
|
validateSQLPredicate
|
|
10
10
|
} from './sql-predicate-schema';
|
|
11
|
+
export {bindSQLPredicate} from './bind-sql-predicate';
|
|
12
|
+
export {isSQLPredicateParameter} from './sql-predicate-types';
|
|
11
13
|
|
|
12
14
|
export type {
|
|
15
|
+
BoundSQLPredicate,
|
|
13
16
|
SQLComparisonPredicate,
|
|
14
17
|
SQLInPredicate,
|
|
15
18
|
SQLLogicalPredicate,
|
|
16
19
|
SQLNotPredicate,
|
|
17
20
|
SQLNullPredicate,
|
|
18
21
|
SQLPredicate,
|
|
22
|
+
SQLPredicateParameter,
|
|
23
|
+
SQLPredicateParameterValues,
|
|
19
24
|
SQLPredicateParserOptions,
|
|
20
25
|
SQLPredicateProperty,
|
|
26
|
+
SQLPredicateScalar,
|
|
21
27
|
SQLPredicateValue
|
|
22
28
|
} from './sql-predicate-types';
|
package/src/sql-source.ts
CHANGED
|
@@ -11,12 +11,16 @@ import type {
|
|
|
11
11
|
SQLAdapterFactory,
|
|
12
12
|
SQLCatalogInfo,
|
|
13
13
|
SQLMetadata,
|
|
14
|
+
SQLQuery,
|
|
14
15
|
SQLQueryOptions,
|
|
15
16
|
SQLSchemaInfo,
|
|
16
17
|
SQLSourceOptions,
|
|
17
18
|
SQLTableInfo
|
|
18
19
|
} from './sql-types';
|
|
20
|
+
import {compileSQLTableQuery, type SQLTableQueryDialect} from './compile-table-query';
|
|
21
|
+
import type {SQLPredicateParameterValues} from './sql-predicate-types';
|
|
19
22
|
import {convertRowsToArrowTable, isNodeRuntime} from './sql-utils';
|
|
23
|
+
import {SQL_DATA_SOURCE_TABLE_QUERY_CAPABILITIES} from './table-query-capabilities';
|
|
20
24
|
|
|
21
25
|
const SQL_ADAPTER_FACTORIES = new Map<string, SQLAdapterFactory>();
|
|
22
26
|
|
|
@@ -58,6 +62,8 @@ export const SQL_SOURCE_DEFAULT_OPTIONS: Omit<RequiredOptions<SQLSourceOptions>,
|
|
|
58
62
|
|
|
59
63
|
/** Shared SQL-backed data source implementation. */
|
|
60
64
|
export class SQLDataSource extends DataSource<string, SQLSourceOptions> {
|
|
65
|
+
/** Optimization and execution capabilities of portable table-bound queries. */
|
|
66
|
+
readonly tableQueryCapabilities = SQL_DATA_SOURCE_TABLE_QUERY_CAPABILITIES;
|
|
61
67
|
private readonly sourceType: string;
|
|
62
68
|
private readonly adapterFactory?: SQLAdapterFactory;
|
|
63
69
|
private adapterPromise: Promise<SQLAdapter> | null = null;
|
|
@@ -114,20 +120,22 @@ export class SQLDataSource extends DataSource<string, SQLSourceOptions> {
|
|
|
114
120
|
|
|
115
121
|
/** Executes a SQL query and returns object rows. */
|
|
116
122
|
async queryRows(
|
|
117
|
-
|
|
123
|
+
query: SQLQuery,
|
|
118
124
|
options: SQLQueryOptions = {}
|
|
119
125
|
): Promise<Record<string, unknown>[]> {
|
|
120
126
|
const adapter = await this.getAdapter();
|
|
121
|
-
|
|
127
|
+
const compiledQuery = this.compileQuery(query, options);
|
|
128
|
+
return await adapter.executeRows(compiledQuery.sql, compiledQuery.options);
|
|
122
129
|
}
|
|
123
130
|
|
|
124
131
|
/** Executes a SQL query and returns a loaders.gl Arrow table. */
|
|
125
|
-
async queryArrow(
|
|
132
|
+
async queryArrow(query: SQLQuery, options: SQLQueryOptions = {}): Promise<ArrowTable> {
|
|
126
133
|
const adapter = await this.getAdapter();
|
|
134
|
+
const compiledQuery = this.compileQuery(query, options);
|
|
127
135
|
if (adapter.executeArrow) {
|
|
128
|
-
return await adapter.executeArrow(
|
|
136
|
+
return await adapter.executeArrow(compiledQuery.sql, compiledQuery.options);
|
|
129
137
|
}
|
|
130
|
-
const rows = await adapter.executeRows(
|
|
138
|
+
const rows = await adapter.executeRows(compiledQuery.sql, compiledQuery.options);
|
|
131
139
|
return convertRowsToArrowTable(rows);
|
|
132
140
|
}
|
|
133
141
|
|
|
@@ -149,6 +157,26 @@ export class SQLDataSource extends DataSource<string, SQLSourceOptions> {
|
|
|
149
157
|
return await this.adapterPromise;
|
|
150
158
|
}
|
|
151
159
|
|
|
160
|
+
/** Converts a portable query object to SQL while leaving raw SQL text unchanged. */
|
|
161
|
+
private compileQuery(
|
|
162
|
+
query: SQLQuery,
|
|
163
|
+
options: SQLQueryOptions
|
|
164
|
+
): {sql: string; options: SQLQueryOptions} {
|
|
165
|
+
if (typeof query === 'string') {
|
|
166
|
+
return {sql: query, options};
|
|
167
|
+
}
|
|
168
|
+
const namedParameters =
|
|
169
|
+
options.parameters && !Array.isArray(options.parameters) ? options.parameters : undefined;
|
|
170
|
+
const compiledQuery = compileSQLTableQuery(query, {
|
|
171
|
+
dialect: getSQLTableQueryDialect(this.sourceType),
|
|
172
|
+
parameters: namedParameters as SQLPredicateParameterValues | undefined
|
|
173
|
+
});
|
|
174
|
+
return {
|
|
175
|
+
sql: compiledQuery.sql,
|
|
176
|
+
options: {signal: options.signal, parameters: compiledQuery.parameters}
|
|
177
|
+
};
|
|
178
|
+
}
|
|
179
|
+
|
|
152
180
|
private async loadAdapter(): Promise<SQLAdapter> {
|
|
153
181
|
try {
|
|
154
182
|
const runtimeFactory = isNodeRuntime()
|
|
@@ -191,3 +219,10 @@ export class SQLDataSource extends DataSource<string, SQLSourceOptions> {
|
|
|
191
219
|
};
|
|
192
220
|
}
|
|
193
221
|
}
|
|
222
|
+
|
|
223
|
+
/** Maps a SQL source adapter to the dialect used by the portable query compiler. */
|
|
224
|
+
function getSQLTableQueryDialect(sourceType: string): SQLTableQueryDialect {
|
|
225
|
+
if (sourceType === 'duckdb-sql') return 'duckdb';
|
|
226
|
+
if (sourceType === 'snowflake-sql') return 'snowflake';
|
|
227
|
+
throw new Error(`Portable table queries are not supported for SQL source type "${sourceType}".`);
|
|
228
|
+
}
|
package/src/sql-types.ts
CHANGED
|
@@ -4,9 +4,13 @@
|
|
|
4
4
|
|
|
5
5
|
import type {ArrowTable, Schema} from '@loaders.gl/schema';
|
|
6
6
|
import type {CoreAPI, DataSourceOptions} from '@loaders.gl/loader-utils';
|
|
7
|
+
import type {SQLTableQuery} from './compile-table-query';
|
|
7
8
|
|
|
8
9
|
export type SQLParameterValues = unknown[] | Record<string, unknown>;
|
|
9
10
|
|
|
11
|
+
/** Raw SQL text or a portable query bound to one database table. */
|
|
12
|
+
export type SQLQuery = string | SQLTableQuery;
|
|
13
|
+
|
|
10
14
|
/** Query-level options for SQL data sources. */
|
|
11
15
|
export type SQLQueryOptions = {
|
|
12
16
|
parameters?: SQLParameterValues;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// loaders.gl
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
// Copyright (c) vis.gl contributors
|
|
4
|
+
|
|
5
|
+
import type {TableQueryCapabilities} from '@loaders.gl/loader-utils';
|
|
6
|
+
|
|
7
|
+
/** Portable query capabilities of the in-memory Arrow executor. */
|
|
8
|
+
export const ARROW_TABLE_QUERY_CAPABILITIES: TableQueryCapabilities = Object.freeze({
|
|
9
|
+
projection: 'residual',
|
|
10
|
+
predicate: 'residual',
|
|
11
|
+
limit: 'residual',
|
|
12
|
+
streaming: false,
|
|
13
|
+
cancellation: true,
|
|
14
|
+
expressions: 'residual',
|
|
15
|
+
orderBy: 'residual',
|
|
16
|
+
aggregates: 'residual'
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
/** Portable query capabilities shared by the current SQL data-source adapters. */
|
|
20
|
+
export const SQL_DATA_SOURCE_TABLE_QUERY_CAPABILITIES: TableQueryCapabilities = Object.freeze({
|
|
21
|
+
projection: 'pushdown',
|
|
22
|
+
predicate: 'pushdown',
|
|
23
|
+
limit: 'pushdown',
|
|
24
|
+
streaming: false,
|
|
25
|
+
cancellation: false,
|
|
26
|
+
expressions: 'pushdown',
|
|
27
|
+
orderBy: 'pushdown',
|
|
28
|
+
aggregates: 'pushdown'
|
|
29
|
+
});
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
// loaders.gl
|
|
2
|
+
// SPDX-License-Identifier: MIT
|
|
3
|
+
// Copyright (c) vis.gl contributors
|
|
4
|
+
|
|
5
|
+
import {
|
|
6
|
+
getColumnarPredicateColumns,
|
|
7
|
+
explainTableQuery as explainColumnarTableQuery,
|
|
8
|
+
planTableQuery as planColumnarTableQuery,
|
|
9
|
+
type TableQueryFilterStep as ColumnarTableQueryFilterStep,
|
|
10
|
+
type TableQueryLimitStep as ColumnarTableQueryLimitStep,
|
|
11
|
+
type TableQueryOptions as ColumnarTableQueryOptions,
|
|
12
|
+
type TableQueryPlan as ColumnarTableQueryPlan,
|
|
13
|
+
type TableQueryPlanStep as ColumnarTableQueryPlanStep,
|
|
14
|
+
type TableQueryProjectStep as ColumnarTableQueryProjectStep,
|
|
15
|
+
type TableQueryScanStep as ColumnarTableQueryScanStep
|
|
16
|
+
} from '@loaders.gl/loader-utils';
|
|
17
|
+
|
|
18
|
+
import {validateSQLPredicate} from './sql-predicate-schema';
|
|
19
|
+
import type {SQLPredicate} from './sql-predicate-types';
|
|
20
|
+
|
|
21
|
+
/** Immutable, backend-neutral request for a table query. */
|
|
22
|
+
export type TableQueryOptions = ColumnarTableQueryOptions<SQLPredicate>;
|
|
23
|
+
|
|
24
|
+
/** Reads the minimum source columns required by the remaining table-query plan. */
|
|
25
|
+
export type TableQueryScanStep = ColumnarTableQueryScanStep;
|
|
26
|
+
|
|
27
|
+
/** Applies a portable SQL predicate while all predicate columns remain available. */
|
|
28
|
+
export type TableQueryFilterStep = ColumnarTableQueryFilterStep<SQLPredicate>;
|
|
29
|
+
|
|
30
|
+
/** Narrows the result to requested output columns. */
|
|
31
|
+
export type TableQueryProjectStep = ColumnarTableQueryProjectStep;
|
|
32
|
+
|
|
33
|
+
/** Retains the first rows in source order after filtering and projection. */
|
|
34
|
+
export type TableQueryLimitStep = ColumnarTableQueryLimitStep;
|
|
35
|
+
|
|
36
|
+
/** One immutable operation in a normalized table-query plan. */
|
|
37
|
+
export type TableQueryPlanStep = ColumnarTableQueryPlanStep<SQLPredicate>;
|
|
38
|
+
|
|
39
|
+
/** Immutable logical query plan shared by Arrow and GPU dataframe backends. */
|
|
40
|
+
export type TableQueryPlan = ColumnarTableQueryPlan<SQLPredicate>;
|
|
41
|
+
export type TableQueryExplain = import('@loaders.gl/loader-utils').TableQueryExplain<SQLPredicate>;
|
|
42
|
+
import {SQL_DATA_SOURCE_TABLE_QUERY_CAPABILITIES} from './table-query-capabilities';
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* Produces the canonical scan, filter, project, and limit sequence for a table query.
|
|
46
|
+
*
|
|
47
|
+
* Predicate columns are retained by the scan even if callers omit them from the output projection.
|
|
48
|
+
* This makes SQL `WHERE` semantics independent of a backend's internal API call order.
|
|
49
|
+
*/
|
|
50
|
+
export function planTableQuery(
|
|
51
|
+
sourceColumnNames: readonly string[],
|
|
52
|
+
options: TableQueryOptions = {}
|
|
53
|
+
): TableQueryPlan {
|
|
54
|
+
if (options.predicate) {
|
|
55
|
+
validateSQLPredicate(options.predicate);
|
|
56
|
+
}
|
|
57
|
+
return planColumnarTableQuery(sourceColumnNames, options);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** Explains a portable SQL table query without executing it. */
|
|
61
|
+
export function explainTableQuery(
|
|
62
|
+
sourceColumnNames: readonly string[],
|
|
63
|
+
options: TableQueryOptions = {}
|
|
64
|
+
): TableQueryExplain {
|
|
65
|
+
if (options.predicate) {
|
|
66
|
+
validateSQLPredicate(options.predicate);
|
|
67
|
+
}
|
|
68
|
+
return explainColumnarTableQuery(
|
|
69
|
+
sourceColumnNames,
|
|
70
|
+
options,
|
|
71
|
+
SQL_DATA_SOURCE_TABLE_QUERY_CAPABILITIES
|
|
72
|
+
);
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/** Returns every source column referenced by one portable predicate, in first-use order. */
|
|
76
|
+
export function getSQLPredicateColumnNames(predicate: SQLPredicate): string[] {
|
|
77
|
+
return getColumnarPredicateColumns(predicate);
|
|
78
|
+
}
|