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

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
@@ -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 || Array.isArray(parameters)) {
268
+ if (!parameters) {
269
269
  return undefined;
270
270
  }
271
271
  const bindings: Record<string, {type: string; value: unknown}> = {};
272
- for (const [key, value] of Object.entries(parameters)) {
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 type {SQLPredicate, SQLPredicateValue} from './sql-predicate-types';
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: {property: {type: 'string', minLength: 1}},
35
+ properties: {
36
+ property: {type: 'string', minLength: 1},
37
+ quoted: {type: 'boolean'}
38
+ },
32
39
  additionalProperties: false
33
40
  },
34
- value: {type: ['boolean', 'number', 'string']},
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
- !hasExactKeys(value, ['property']) ||
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 SQLPredicateValue = boolean | number | bigint | string | Date | Uint8Array;
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
- /** CQL2-shaped comparison operator. */
17
- op: '=' | '<>' | '<' | '<=' | '>' | '>=';
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
- /** CQL2-shaped logical operator. */
41
- op: 'and' | 'or';
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
- /** CQL2-shaped negation operator. */
49
- op: 'not';
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?: Readonly<Record<string, SQLPredicateValue>>;
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
+ }
@@ -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.object({property: z.string().min(1)}).strict();
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.
@@ -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
- sqlText: string,
123
+ query: SQLQuery,
118
124
  options: SQLQueryOptions = {}
119
125
  ): Promise<Record<string, unknown>[]> {
120
126
  const adapter = await this.getAdapter();
121
- return await adapter.executeRows(sqlText, options);
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(sqlText: string, options: SQLQueryOptions = {}): Promise<ArrowTable> {
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(sqlText, options);
136
+ return await adapter.executeArrow(compiledQuery.sql, compiledQuery.options);
129
137
  }
130
- const rows = await adapter.executeRows(sqlText, options);
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
+ }