@loaders.gl/sql 5.0.0-alpha.1 → 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 (94) hide show
  1. package/LICENSE +14 -3
  2. package/README.md +107 -0
  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 +3154 -35
  25. package/dist/index.cjs.map +3 -4
  26. package/dist/index.d.ts +16 -1
  27. package/dist/index.d.ts.map +1 -1
  28. package/dist/index.js +9 -0
  29. package/dist/index.js.map +1 -1
  30. package/dist/parse-sql-predicate.d.ts +10 -0
  31. package/dist/parse-sql-predicate.d.ts.map +1 -0
  32. package/dist/parse-sql-predicate.js +322 -0
  33. package/dist/parse-sql-predicate.js.map +1 -0
  34. package/dist/query-arrow-table.d.ts +83 -0
  35. package/dist/query-arrow-table.d.ts.map +1 -0
  36. package/dist/query-arrow-table.js +660 -0
  37. package/dist/query-arrow-table.js.map +1 -0
  38. package/dist/snowflake-sql-source.d.ts.map +1 -1
  39. package/dist/snowflake-sql-source.js +8 -5
  40. package/dist/snowflake-sql-source.js.map +1 -1
  41. package/dist/sql-predicate-schema.d.ts +156 -0
  42. package/dist/sql-predicate-schema.d.ts.map +1 -0
  43. package/dist/sql-predicate-schema.js +226 -0
  44. package/dist/sql-predicate-schema.js.map +1 -0
  45. package/dist/sql-predicate-types.d.ts +45 -0
  46. package/dist/sql-predicate-types.d.ts.map +1 -0
  47. package/dist/sql-predicate-types.js +9 -0
  48. package/dist/sql-predicate-types.js.map +1 -0
  49. package/dist/sql-predicate-zod.cjs +54 -0
  50. package/dist/sql-predicate-zod.cjs.map +6 -0
  51. package/dist/sql-predicate-zod.d.ts +11 -0
  52. package/dist/sql-predicate-zod.d.ts.map +1 -0
  53. package/dist/sql-predicate-zod.js +45 -0
  54. package/dist/sql-predicate-zod.js.map +1 -0
  55. package/dist/sql-predicate.cjs +607 -0
  56. package/dist/sql-predicate.cjs.map +6 -0
  57. package/dist/sql-predicate.d.ts +6 -0
  58. package/dist/sql-predicate.d.ts.map +1 -0
  59. package/dist/sql-predicate.js +8 -0
  60. package/dist/sql-predicate.js.map +1 -0
  61. package/dist/sql-source.d.ts +16 -3
  62. package/dist/sql-source.d.ts.map +1 -1
  63. package/dist/sql-source.js +34 -5
  64. package/dist/sql-source.js.map +1 -1
  65. package/dist/sql-types.d.ts +3 -0
  66. package/dist/sql-types.d.ts.map +1 -1
  67. package/dist/table-query-capabilities.d.ts +6 -0
  68. package/dist/table-query-capabilities.d.ts.map +1 -0
  69. package/dist/table-query-capabilities.js +26 -0
  70. package/dist/table-query-capabilities.js.map +1 -0
  71. package/dist/table-query.cjs +286 -0
  72. package/dist/table-query.cjs.map +6 -0
  73. package/dist/table-query.d.ts +29 -0
  74. package/dist/table-query.d.ts.map +1 -0
  75. package/dist/table-query.js +30 -0
  76. package/dist/table-query.js.map +1 -0
  77. package/package.json +45 -8
  78. package/src/arrow-query.ts +17 -0
  79. package/src/arrow-table-source.ts +111 -0
  80. package/src/bind-sql-predicate.ts +21 -0
  81. package/src/compile-table-query.ts +354 -0
  82. package/src/duckdb-sql-source.ts +30 -6
  83. package/src/index.ts +57 -0
  84. package/src/parse-sql-predicate.ts +381 -0
  85. package/src/query-arrow-table.ts +843 -0
  86. package/src/snowflake-sql-source.ts +7 -4
  87. package/src/sql-predicate-schema.ts +251 -0
  88. package/src/sql-predicate-types.ts +87 -0
  89. package/src/sql-predicate-zod.ts +52 -0
  90. package/src/sql-predicate.ts +28 -0
  91. package/src/sql-source.ts +40 -5
  92. package/src/sql-types.ts +4 -0
  93. package/src/table-query-capabilities.ts +29 -0
  94. package/src/table-query.ts +78 -0
package/LICENSE CHANGED
@@ -24,8 +24,20 @@ THE SOFTWARE.
24
24
 
25
25
  Copyright (c) 2015 Uber Technologies, Inc.
26
26
 
27
- loaders.gl includes certain files from Cesium (https://github.com/AnalyticalGraphicsInc/cesium)
28
- under the Apache 2 License (found in the submodule: modules/3d-tiles):)
27
+ Portions of modules/images/src/lib/category-api/binary-image-api.ts are based on
28
+ binary-gltf-utils (https://github.com/Qantas94Heavy/binary-gltf-utils) under the
29
+ MIT License reproduced above.
30
+
31
+ Copyright (c) 2016-17 Karl Cheng
32
+
33
+ Portions of modules/schema-utils/src/lib/utils/async-queue.ts are adapted from
34
+ async-iter-demo (https://github.com/rauschma/async-iter-demo) under the MIT
35
+ License reproduced above.
36
+
37
+ Copyright (c) 2016 Axel Rauschmayer
38
+
39
+ loaders.gl includes certain files from Cesium (https://github.com/CesiumGS/cesium)
40
+ under the Apache 2.0 License, including files in modules/3d-tiles.
29
41
 
30
42
  Copyright 2011-2018 CesiumJS Contributors
31
43
 
@@ -38,4 +50,3 @@ Unless required by applicable law or agreed to in writing, software
38
50
  distributed under the License is distributed on an "AS IS" BASIS,
39
51
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
40
52
  See the License for the specific language governing permissions and limitations under the License.
41
-
package/README.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # @loaders.gl/sql
2
2
 
3
3
  This module contains SQL-oriented `DataSource` implementations for external and embedded databases.
4
+ It also provides a database-runtime-free parser for turning a small SQL `WHERE` expression into a
5
+ portable predicate AST.
4
6
 
5
7
  ## Included sources
6
8
 
@@ -9,6 +11,17 @@ This module contains SQL-oriented `DataSource` implementations for external and
9
11
 
10
12
  ## Usage
11
13
 
14
+ Install the DuckDB runtime needed by your application in addition to `@loaders.gl/sql`:
15
+
16
+ ```bash
17
+ yarn add @duckdb/node-api
18
+ # or, for browsers
19
+ yarn add @duckdb/duckdb-wasm
20
+ ```
21
+
22
+ Both DuckDB packages are optional peers and are dynamically imported only when a DuckDB source
23
+ connects. Importing the SQL predicate parser does not load or install either runtime.
24
+
12
25
  ```ts
13
26
  import {createDataSource} from '@loaders.gl/core';
14
27
  import {DuckDBSQLSource} from '@loaders.gl/sql';
@@ -21,7 +34,101 @@ await dataSource.queryRows('CREATE TABLE numbers AS SELECT 1 AS value');
21
34
  const rows = await dataSource.queryRows('SELECT * FROM numbers');
22
35
  ```
23
36
 
37
+ SQL data sources also accept a portable table query. The source compiles its predicate, projection,
38
+ and limit to quoted SQL with bound parameters:
39
+
40
+ ```ts
41
+ import {parseSQLPredicate} from '@loaders.gl/sql/sql-predicate';
42
+
43
+ const rows = await dataSource.queryRows(
44
+ {
45
+ tableName: 'numbers',
46
+ columns: ['value'],
47
+ predicate: parseSQLPredicate('value >= :minimum', {preserveParameters: true}),
48
+ limit: 100
49
+ },
50
+ {parameters: {minimum: 1}}
51
+ );
52
+ ```
53
+
24
54
  ## Arrow queries
25
55
 
26
56
  Use `queryArrow()` when the backing adapter supports Arrow-native results, or when you want
27
57
  loaders.gl to convert row results into an Arrow table.
58
+
59
+ ## Lightweight Arrow queries
60
+
61
+ `@loaders.gl/sql/arrow-query` provides an experimental in-memory query path for Arrow tables. It
62
+ uses the shared `TableQueryOptions` planner, which always orders operations as scan, filter,
63
+ project, then limit. The same immutable plan can be lowered by GPU dataframe implementations
64
+ without adopting Arrow's materialization strategy. This is useful for lightweight local filtering;
65
+ it is not a replacement for DuckDB and does not yet implement SQL `SELECT` parsing, aggregation,
66
+ or joins.
67
+
68
+ The generic contract and planner live in `@loaders.gl/loader-utils`; SQL-specialized compatibility
69
+ exports remain available from `@loaders.gl/sql/table-query`:
70
+
71
+ ```ts
72
+ import {planTableQuery, type TableQueryOptions} from '@loaders.gl/loader-utils';
73
+ ```
74
+
75
+ ```ts
76
+ import {parseSQLPredicate} from '@loaders.gl/sql/sql-predicate';
77
+ import {queryArrowTable} from '@loaders.gl/sql/arrow-query';
78
+
79
+ const flights = queryArrowTable(arrowTable, {
80
+ predicate: parseSQLPredicate('year >= 2024 AND cancelled = FALSE'),
81
+ columns: ['carrier', 'fare'],
82
+ limit: 100
83
+ });
84
+ ```
85
+
86
+ Projection and limit-only queries preserve Arrow's zero-copy table views. Predicate queries
87
+ currently materialize matching rows while keeping predicate columns out of the result unless
88
+ selected explicitly.
89
+
90
+ Named SQL parameters can remain unresolved while a caller builds or compiles a query. Bind them
91
+ immediately before an Arrow backend executes the predicate:
92
+
93
+ ```ts
94
+ import {bindSQLPredicate, parseSQLPredicate} from '@loaders.gl/sql/sql-predicate';
95
+
96
+ const predicate = parseSQLPredicate('fare >= :minimumFare', {preserveParameters: true});
97
+ const boundPredicate = bindSQLPredicate(predicate, {minimumFare: 250});
98
+ ```
99
+
100
+ ## SQL predicate expressions
101
+
102
+ `parseSQLPredicate()` accepts the expression after `WHERE`, not a complete `SELECT` statement. It
103
+ supports comparisons, `IN`, `IS [NOT] NULL`, `AND`, `OR`, `NOT`, parentheses, scalar literals, and
104
+ named parameters.
105
+
106
+ ```ts
107
+ import {parseSQLPredicate} from '@loaders.gl/sql/sql-predicate';
108
+
109
+ const predicate = parseSQLPredicate(
110
+ "timestamp >= :start AND status IN ('valid', 'estimated')",
111
+ {parameters: {start: new Date('2026-01-01T00:00:00Z')}}
112
+ );
113
+
114
+ for await (const batch of parquetSource.read({
115
+ columns: ['timestamp', 'value'],
116
+ predicate
117
+ })) {
118
+ // SQLPredicate is structurally compatible with the experimental Parquet predicate subset.
119
+ }
120
+ ```
121
+
122
+ The `sql-predicate` subpath does not load or traverse the optional database
123
+ adapters. The resulting `op`/`args` representation is directionally aligned with CQL2 JSON but does not
124
+ claim CQL2 conformance. `SQL_PREDICATE_JSON_SCHEMA`, `validateSQLPredicate()`, and
125
+ `isSQLPredicate()` support dependency-free payload validation.
126
+
127
+ Applications already using Zod can opt into the separate subpath without adding Zod to the root
128
+ bundle:
129
+
130
+ ```ts
131
+ import {SQLPredicateSchema} from '@loaders.gl/sql/sql-predicate-zod';
132
+
133
+ const predicate = SQLPredicateSchema.parse(untrustedPayload);
134
+ ```