@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.
- package/LICENSE +14 -3
- package/README.md +107 -0
- package/dist/arrow-query.cjs +1404 -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 +51 -3
- 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 +3352 -37
- package/dist/index.cjs.map +3 -4
- package/dist/index.d.ts +16 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +9 -0
- package/dist/index.js.map +1 -1
- package/dist/parse-sql-predicate.d.ts +10 -0
- package/dist/parse-sql-predicate.d.ts.map +1 -0
- package/dist/parse-sql-predicate.js +322 -0
- package/dist/parse-sql-predicate.js.map +1 -0
- 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 +663 -0
- package/dist/query-arrow-table.js.map +1 -0
- package/dist/snowflake-sql-source.d.ts +51 -3
- package/dist/snowflake-sql-source.d.ts.map +1 -1
- package/dist/snowflake-sql-source.js +9 -6
- package/dist/snowflake-sql-source.js.map +1 -1
- package/dist/sql-predicate-schema.d.ts +156 -0
- package/dist/sql-predicate-schema.d.ts.map +1 -0
- package/dist/sql-predicate-schema.js +226 -0
- package/dist/sql-predicate-schema.js.map +1 -0
- package/dist/sql-predicate-types.d.ts +45 -0
- package/dist/sql-predicate-types.d.ts.map +1 -0
- package/dist/sql-predicate-types.js +9 -0
- package/dist/sql-predicate-types.js.map +1 -0
- package/dist/sql-predicate-zod.cjs +54 -0
- package/dist/sql-predicate-zod.cjs.map +6 -0
- package/dist/sql-predicate-zod.d.ts +11 -0
- package/dist/sql-predicate-zod.d.ts.map +1 -0
- package/dist/sql-predicate-zod.js +45 -0
- package/dist/sql-predicate-zod.js.map +1 -0
- package/dist/sql-predicate.cjs +607 -0
- package/dist/sql-predicate.cjs.map +6 -0
- package/dist/sql-predicate.d.ts +6 -0
- package/dist/sql-predicate.d.ts.map +1 -0
- package/dist/sql-predicate.js +8 -0
- package/dist/sql-predicate.js.map +1 -0
- 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 +45 -8
- 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 +57 -0
- package/src/parse-sql-predicate.ts +381 -0
- package/src/query-arrow-table.ts +846 -0
- package/src/snowflake-sql-source.ts +8 -5
- package/src/sql-predicate-schema.ts +251 -0
- package/src/sql-predicate-types.ts +87 -0
- package/src/sql-predicate-zod.ts +52 -0
- package/src/sql-predicate.ts +28 -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
package/LICENSE
CHANGED
|
@@ -24,8 +24,20 @@ THE SOFTWARE.
|
|
|
24
24
|
|
|
25
25
|
Copyright (c) 2015 Uber Technologies, Inc.
|
|
26
26
|
|
|
27
|
-
|
|
28
|
-
|
|
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
|
+
```
|