@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
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 and modules/math.
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 dependency-free parser for turning a small SQL `WHERE` expression into 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 dependency-free `sql-predicate` subpath does not load or traverse the optional database
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.