@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
package/LICENSE
CHANGED
|
@@ -37,7 +37,7 @@ License reproduced above.
|
|
|
37
37
|
Copyright (c) 2016 Axel Rauschmayer
|
|
38
38
|
|
|
39
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
|
|
40
|
+
under the Apache 2.0 License, including files in modules/3d-tiles.
|
|
41
41
|
|
|
42
42
|
Copyright 2011-2018 CesiumJS Contributors
|
|
43
43
|
|
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
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
|
|
4
|
+
It also provides a database-runtime-free parser for turning a small SQL `WHERE` expression into a
|
|
5
5
|
portable predicate AST.
|
|
6
6
|
|
|
7
7
|
## Included sources
|
|
@@ -34,11 +34,69 @@ await dataSource.queryRows('CREATE TABLE numbers AS SELECT 1 AS value');
|
|
|
34
34
|
const rows = await dataSource.queryRows('SELECT * FROM numbers');
|
|
35
35
|
```
|
|
36
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
|
+
|
|
37
54
|
## Arrow queries
|
|
38
55
|
|
|
39
56
|
Use `queryArrow()` when the backing adapter supports Arrow-native results, or when you want
|
|
40
57
|
loaders.gl to convert row results into an Arrow table.
|
|
41
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
|
+
|
|
42
100
|
## SQL predicate expressions
|
|
43
101
|
|
|
44
102
|
`parseSQLPredicate()` accepts the expression after `WHERE`, not a complete `SELECT` statement. It
|
|
@@ -61,7 +119,7 @@ for await (const batch of parquetSource.read({
|
|
|
61
119
|
}
|
|
62
120
|
```
|
|
63
121
|
|
|
64
|
-
The
|
|
122
|
+
The `sql-predicate` subpath does not load or traverse the optional database
|
|
65
123
|
adapters. The resulting `op`/`args` representation is directionally aligned with CQL2 JSON but does not
|
|
66
124
|
claim CQL2 conformance. `SQL_PREDICATE_JSON_SCHEMA`, `validateSQLPredicate()`, and
|
|
67
125
|
`isSQLPredicate()` support dependency-free payload validation.
|