@perspective-dev/client 5.5.1 → 5.6.0

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 (38) hide show
  1. package/README.md +66 -2
  2. package/dist/cdn/perspective-server.worker.js +1 -1
  3. package/dist/cdn/perspective-server.worker.js.map +3 -3
  4. package/dist/cdn/perspective.js +2 -2
  5. package/dist/cdn/perspective.js.map +4 -4
  6. package/dist/esm/perspective.js +2 -2
  7. package/dist/esm/perspective.js.map +4 -4
  8. package/dist/esm/perspective.node.js +200 -66
  9. package/dist/esm/perspective.node.js.map +2 -2
  10. package/dist/esm/ts-rs/Features.d.ts +5 -0
  11. package/dist/esm/ts-rs/TableInitOptions.d.ts +8 -0
  12. package/dist/esm/ts-rs/TypedArrayWindow.d.ts +5 -4
  13. package/dist/esm/ts-rs/ViewWindow.d.ts +5 -4
  14. package/dist/esm/virtual_servers/clickhouse.js +1 -1
  15. package/dist/esm/virtual_servers/clickhouse.js.map +3 -3
  16. package/dist/esm/virtual_servers/duckdb.d.ts +7 -1
  17. package/dist/esm/virtual_servers/duckdb.js +1 -1
  18. package/dist/esm/virtual_servers/duckdb.js.map +3 -3
  19. package/dist/wasm/perspective-js.d.ts +97 -19
  20. package/dist/wasm/perspective-js.js +172 -45
  21. package/dist/wasm/perspective-js.wasm +0 -0
  22. package/dist/wasm/perspective-js.wasm.d.ts +11 -7
  23. package/package.json +20 -15
  24. package/src/rust/client.rs +2 -1
  25. package/src/rust/generic_sql_model.rs +70 -6
  26. package/src/rust/table.rs +33 -1
  27. package/src/rust/view.rs +14 -5
  28. package/src/rust/virtual_server.rs +101 -23
  29. package/src/ts/ts-rs/Features.ts +6 -1
  30. package/src/ts/ts-rs/TableInitOptions.ts +7 -1
  31. package/src/ts/ts-rs/TypedArrayWindow.ts +5 -4
  32. package/src/ts/ts-rs/ViewWindow.ts +5 -4
  33. package/src/ts/virtual_servers/clickhouse.ts +99 -4
  34. package/src/ts/virtual_servers/duckdb.ts +116 -6
  35. package/src/ts/wasm/engine.ts +26 -35
  36. package/dist/esm/perspective.inline.js +0 -3
  37. package/dist/esm/perspective.inline.js.map +0 -7
  38. package/src/ts/perspective.inline.ts +0 -27
package/package.json CHANGED
@@ -1,16 +1,26 @@
1
1
  {
2
2
  "name": "@perspective-dev/client",
3
- "version": "5.5.1",
4
- "description": "Client for Perspective, a high-performance WASM engine with reactive Tables, Views, and joins.",
3
+ "version": "5.6.0",
4
+ "description": "Streaming query engine for data grids, pivot tables and charts over large, real-time datasets — WebAssembly in the browser, native in Node.js, or remote over WebSocket.",
5
5
  "keywords": [
6
6
  "perspective",
7
- "data",
7
+ "datagrid",
8
+ "data-grid",
9
+ "pivot-table",
10
+ "pivot",
11
+ "charts",
12
+ "visualization",
13
+ "dashboard",
8
14
  "analytics",
15
+ "bi",
9
16
  "streaming",
17
+ "real-time",
10
18
  "wasm",
19
+ "webassembly",
11
20
  "arrow",
12
21
  "duckdb",
13
- "clickhouse"
22
+ "clickhouse",
23
+ "websocket"
14
24
  ],
15
25
  "homepage": "https://perspective-dev.github.io",
16
26
  "repository": {
@@ -38,11 +48,6 @@
38
48
  "import": "./dist/esm/perspective.node.js",
39
49
  "default": "./dist/esm/perspective.node.js"
40
50
  },
41
- "./inline": {
42
- "types": "./dist/esm/perspective.browser.d.ts",
43
- "import": "./dist/esm/perspective.inline.js",
44
- "default": "./dist/esm/perspective.inline.js"
45
- },
46
51
  "./virtual_servers/*": {
47
52
  "types": "./dist/esm/virtual_servers/*.d.ts",
48
53
  "import": "./dist/esm/virtual_servers/*.js",
@@ -63,12 +68,15 @@
63
68
  "access": "public"
64
69
  },
65
70
  "dependencies": {
71
+ "@perspective-dev/server": "^5.6.0",
66
72
  "pro_self_extracting_wasm": "0.0.9",
67
73
  "stoppable": "=1.1.0",
68
- "ws": "^8.17.0",
69
- "@perspective-dev/server": "^5.5.1"
74
+ "ws": "^8.17.0"
70
75
  },
71
76
  "devDependencies": {
77
+ "@perspective-dev/esbuild-plugin": "^5.6.0",
78
+ "@perspective-dev/metadata": "^5.6.0",
79
+ "@perspective-dev/test": "^5.6.0",
72
80
  "@clickhouse/client-web": "^1.12.0",
73
81
  "@duckdb/duckdb-wasm": "1.33.1-dev18.0",
74
82
  "@playwright/experimental-ct-react": "=1.62.0",
@@ -83,10 +91,7 @@
83
91
  "typedoc": "^0.28.7",
84
92
  "typescript": ">=5 <6",
85
93
  "web-worker": "1.4.1",
86
- "zx": ">=8 <9",
87
- "@perspective-dev/esbuild-plugin": "^5.5.1",
88
- "@perspective-dev/metadata": "^5.5.1",
89
- "@perspective-dev/test": "^5.5.1"
94
+ "zx": ">=8 <9"
90
95
  },
91
96
  "scripts": {
92
97
  "build": "node ./build.mjs",
@@ -261,7 +261,8 @@ impl Client {
261
261
  JsReconnect::from(move |()| match reconnect.call0(&JsValue::UNDEFINED) {
262
262
  Ok(x) => x.unchecked_into::<js_sys::Promise>(),
263
263
  Err(e) => {
264
- // This error may occur when _invoking_ the function
264
+ // This error may occur when _invoking_ the
265
+ // function
265
266
  tracing::warn!("{:?}", e);
266
267
  js_sys::Promise::reject(&format!("C {e:?}").into())
267
268
  },
@@ -83,15 +83,54 @@ impl GenericSQLVirtualServerModel {
83
83
  .map_err(|e| JsValue::from_str(&e.to_string()))
84
84
  }
85
85
 
86
- /// Returns the SQL query to validate an expression against a table.
87
- #[wasm_bindgen(js_name = "tableValidateExpression")]
88
- pub fn table_validate_expression(
86
+ /// Returns the SQL query that plans every expression of `config` at once
87
+ /// against a table, one result column per expression alias, or `undefined`
88
+ /// when the config has no expressions.
89
+ #[wasm_bindgen(js_name = "expressionsDescribe")]
90
+ pub fn expressions_describe(
89
91
  &self,
90
92
  table_id: &str,
91
- expression: &str,
92
- ) -> Result<String, JsValue> {
93
+ config: JsValue,
94
+ ) -> Result<Option<String>, JsValue> {
95
+ let config: ViewConfig = serde_wasm_bindgen::from_value(config)
96
+ .map_err(|e| JsValue::from_str(&e.to_string()))?;
97
+
93
98
  self.inner
94
- .table_validate_expression(table_id, expression)
99
+ .expressions_describe(table_id, &config)
100
+ .map_err(|e| JsValue::from_str(&e.to_string()))
101
+ }
102
+
103
+ /// Returns the SQL query that plans ONE expression against a table - for
104
+ /// attributing a failed `expressionsDescribe` to the expressions at fault.
105
+ #[wasm_bindgen(js_name = "expressionDescribe")]
106
+ pub fn expression_describe(&self, table_id: &str, expression: &str) -> Result<String, JsValue> {
107
+ self.inner
108
+ .expression_describe(table_id, expression)
109
+ .map_err(|e| JsValue::from_str(&e.to_string()))
110
+ }
111
+
112
+ /// Returns the SQL query that plans the view `config` would build and
113
+ /// reports its result columns without materializing it (`split_by` folded
114
+ /// into `group_by`, no `PIVOT`), or `undefined` when the config selects no
115
+ /// columns.
116
+ #[wasm_bindgen(js_name = "tableDescribe")]
117
+ pub fn table_describe(
118
+ &self,
119
+ table_id: &str,
120
+ config: JsValue,
121
+ schema: JsValue,
122
+ ) -> Result<Option<String>, JsValue> {
123
+ let config: ViewConfig = serde_wasm_bindgen::from_value(config)
124
+ .map_err(|e| JsValue::from_str(&e.to_string()))?;
125
+
126
+ let schema = if schema.is_undefined() || schema.is_null() {
127
+ IndexMap::new()
128
+ } else {
129
+ self.parse_schema(schema)?
130
+ };
131
+
132
+ self.inner
133
+ .table_describe(table_id, &config, &schema)
95
134
  .map_err(|e| JsValue::from_str(&e.to_string()))
96
135
  }
97
136
 
@@ -127,6 +166,31 @@ impl GenericSQLVirtualServerModel {
127
166
  .map_err(|e| JsValue::from_str(&e.to_string()))
128
167
  }
129
168
 
169
+ /// Returns the SQL query to create a table from a view.
170
+ #[wasm_bindgen(js_name = "viewMakeTable")]
171
+ pub fn view_make_table(
172
+ &self,
173
+ view_id: &str,
174
+ table_id: &str,
175
+ config: JsValue,
176
+ view_schema: JsValue,
177
+ schema: JsValue,
178
+ ) -> Result<String, JsValue> {
179
+ let config: ViewConfig = serde_wasm_bindgen::from_value(config)
180
+ .map_err(|e| JsValue::from_str(&e.to_string()))?;
181
+
182
+ let view_schema = self.parse_schema(view_schema)?;
183
+ let schema = if schema.is_undefined() || schema.is_null() {
184
+ None
185
+ } else {
186
+ Some(self.parse_schema(schema)?)
187
+ };
188
+
189
+ self.inner
190
+ .view_make_table(view_id, table_id, &config, &view_schema, schema.as_ref())
191
+ .map_err(|e| JsValue::from_str(&e.to_string()))
192
+ }
193
+
130
194
  /// Returns the SQL query to fetch data from a view with the given viewport.
131
195
  #[wasm_bindgen(js_name = "viewGetData")]
132
196
  pub fn view_get_data(
package/src/rust/table.rs CHANGED
@@ -12,7 +12,9 @@
12
12
 
13
13
  use js_sys::Function;
14
14
  use perspective_client::config::*;
15
- use perspective_client::{DeleteOptions, UpdateData, UpdateOptions, assert_table_api};
15
+ use perspective_client::{
16
+ DeleteOptions, DescribeVerdict, UpdateData, UpdateOptions, assert_table_api,
17
+ };
16
18
  use wasm_bindgen::prelude::*;
17
19
  use wasm_bindgen_derive::TryFromJsValue;
18
20
  use wasm_bindgen_futures::spawn_local;
@@ -355,6 +357,36 @@ impl Table {
355
357
  Ok(View(view))
356
358
  }
357
359
 
360
+ /// Validate a complete view config against this table and report the
361
+ /// schema a [`View`] built from it would have, WITHOUT creating one.
362
+ ///
363
+ /// # JavaScript Examples
364
+ ///
365
+ /// ```javascript
366
+ /// const verdict = await table.describe({
367
+ /// columns: ["Sales", "margin"],
368
+ /// group_by: ["Region"],
369
+ /// expressions: { margin: '"Profit" / "Sales"' },
370
+ /// });
371
+ ///
372
+ /// if ("view_schema" in verdict) {
373
+ /// const view = await table.view(config);
374
+ /// }
375
+ /// ```
376
+ #[wasm_bindgen]
377
+ pub async fn describe(&self, config: Option<JsViewConfig>) -> ApiResult<JsValue> {
378
+ let config = config
379
+ .map(|config| js_sys::JSON::stringify(&config))
380
+ .transpose()?
381
+ .and_then(|x| x.as_string())
382
+ .map(|x| serde_json::from_str(x.as_str()))
383
+ .transpose()?
384
+ .unwrap_or_default();
385
+
386
+ let verdict: DescribeVerdict = self.0.describe(config).await?.into();
387
+ Ok(JsValue::from_serde_ext(&verdict)?)
388
+ }
389
+
358
390
  /// Validates the given expressions.
359
391
  #[wasm_bindgen]
360
392
  pub async fn validate_expressions(&self, exprs: &JsValue) -> ApiResult<JsValue> {
package/src/rust/view.rs CHANGED
@@ -94,12 +94,21 @@ impl View {
94
94
  self.0.name.clone()
95
95
  }
96
96
 
97
- /// Returns an array of strings containing the column paths of the [`View`]
98
- /// without any of the source columns.
97
+ /// Returns this [`View`]'s column header area for `window`, transposed as
98
+ /// `area[level][column]`.
99
99
  ///
100
100
  /// A column path shows the columns that a given cell belongs to after
101
- /// pivots are applied.
102
- #[wasm_bindgen]
101
+ /// pivots are applied. The area is rectangular with one level per
102
+ /// `split_by` plus one: a column's split values occupy the leading levels
103
+ /// and its name always occupies the last, so a subtotal or grand total
104
+ /// under `split_rollup_mode: "rollup"` reads `null` at the levels it does
105
+ /// not pivot on. Values keep their column's type - a `datetime` split value
106
+ /// is epoch milliseconds, not text - so formatting them is the caller's
107
+ /// choice.
108
+ ///
109
+ /// `window` slices the *column* axis; the number of levels does not depend
110
+ /// on it.
111
+ #[wasm_bindgen(unchecked_return_type = "(string | number | boolean | null)[][]")]
103
112
  pub async fn column_paths(&self, window: Option<JsColumnWindow>) -> ApiResult<JsValue> {
104
113
  let window = window.into_serde_ext::<Option<ColumnWindow>>()?;
105
114
  let columns = self.0.column_paths(window.unwrap_or_default()).await?;
@@ -290,7 +299,7 @@ impl View {
290
299
 
291
300
  let float32 = opts.float32;
292
301
  let mut view_window: ViewWindow = opts.into();
293
- view_window.emit_legacy_row_path_names = Some(false);
302
+ view_window.machine_column_names = Some(true);
294
303
  let arrow = self.0.to_arrow(view_window).await?;
295
304
  crate::typed_array::decode_and_call(&arrow, float32, &callback).await?;
296
305
  Ok(())
@@ -20,8 +20,8 @@ use std::sync::{Arc, Mutex};
20
20
  use indexmap::IndexMap;
21
21
  use js_sys::{Array, Date, Object, Reflect, Uint8Array};
22
22
  use perspective_client::proto::{ColumnType, HostedTable};
23
- use perspective_client::virtual_server;
24
23
  use perspective_client::virtual_server::{Features, ResultExt, VirtualServerHandler};
24
+ use perspective_client::{DescribeError, DescribeVerdict, Description, virtual_server};
25
25
  use serde::Serialize;
26
26
  use wasm_bindgen::prelude::*;
27
27
  use wasm_bindgen_futures::JsFuture;
@@ -91,6 +91,25 @@ export interface VirtualHostedTable {
91
91
  limit?: number;
92
92
  }
93
93
 
94
+ /** One expression's compile error, as reported by `tableDescribe`. */
95
+ export interface ExpressionError {
96
+ error_message: string;
97
+ line: number;
98
+ column: number;
99
+ }
100
+
101
+ /** The verdict of `VirtualServerHandler.tableDescribe`. */
102
+ export type TableDescription =
103
+ | {
104
+ expression_schema: Record<string, ColumnType>;
105
+ view_schema: Record<string, ColumnType>;
106
+ }
107
+ | {
108
+ expression_schema?: Record<string, ColumnType>;
109
+ expression_errors: Record<string, ExpressionError>;
110
+ }
111
+ | { config_error: string };
112
+
94
113
  /**
95
114
  * Handler interface that you implement to provide custom data sources.
96
115
  *
@@ -139,11 +158,14 @@ export interface VirtualServerHandler {
139
158
  config: ViewConfig,
140
159
  ): number | Promise<number>;
141
160
 
142
- /** Required when `getFeatures()` reports `expressions: true`. */
143
- tableValidateExpression?(
161
+ /**
162
+ * Validate a complete view config against a table and report the schema
163
+ * a view built from it would have, without creating one.
164
+ */
165
+ tableDescribe(
144
166
  tableId: string,
145
- expression: string,
146
- ): ColumnType | Promise<ColumnType>;
167
+ config: ViewConfig,
168
+ ): TableDescription | Promise<TableDescription>;
147
169
 
148
170
  viewGetMinMax?(
149
171
  viewId: string,
@@ -161,6 +183,12 @@ export interface VirtualServerHandler {
161
183
  tableId: string,
162
184
  data: string | Uint8Array,
163
185
  ): void | Promise<void>;
186
+ viewMakeTable?(
187
+ viewId: string,
188
+ tableId: string,
189
+ config: ViewConfig,
190
+ schema?: Record<string, ColumnType>,
191
+ ): void | Promise<void>;
164
192
  }
165
193
  "#;
166
194
 
@@ -323,39 +351,39 @@ impl VirtualServerHandler for JsServerHandler {
323
351
  })
324
352
  }
325
353
 
326
- fn table_validate_expression(
327
- &self,
354
+ fn table_describe(
355
+ &mut self,
328
356
  table_id: &str,
329
- expression: &str,
330
- ) -> HandlerFuture<Result<ColumnType, Self::Error>> {
331
- // TODO Cache these inspection calls
332
- let has_method = Reflect::get(&self.0, &JsValue::from_str("tableValidateExpression"))
357
+ config: &perspective_client::config::ViewConfig,
358
+ ) -> HandlerFuture<Result<Result<Description, DescribeError>, Self::Error>> {
359
+ let has_method = Reflect::get(&self.0, &JsValue::from_str("tableDescribe"))
333
360
  .map(|val| !val.is_undefined())
334
361
  .unwrap_or(false);
335
362
 
336
363
  let handler = self.0.clone();
337
364
  let table_id = table_id.to_string();
338
- let expression = expression.to_string();
365
+ let config_value = JsValue::from_serde_ext(config);
339
366
  Box::pin(async move {
340
367
  if !has_method {
341
368
  return Err(JsError(JsValue::from_str(
342
- "feature `table_validate_expression` not implemented",
369
+ "`tableDescribe` is required of a `VirtualServerHandler`",
343
370
  )));
344
371
  }
345
372
 
346
373
  let this = JsServerHandler(handler);
347
374
  let args = Array::new();
348
375
  args.push(&JsValue::from_str(&table_id));
349
- args.push(&JsValue::from_str(&expression));
350
- let result = this
351
- .call_method_js_async("tableValidateExpression", &args)
352
- .await?;
353
-
354
- let type_str = result
355
- .as_string()
356
- .ok_or_else(|| JsError(JsValue::from_str("Must return a string")))?;
376
+ args.push(&config_value?);
377
+ let result = this.call_method_js_async("tableDescribe", &args).await?;
378
+ let verdict: DescribeVerdict = result.into_serde_ext().map_err(|e| {
379
+ JsError(JsValue::from_str(&format!(
380
+ "`tableDescribe` must return a `TableDescription`: {}",
381
+ e
382
+ )))
383
+ })?;
357
384
 
358
- Ok(ColumnType::from_str(&type_str).unwrap())
385
+ Result::<Description, DescribeError>::try_from(verdict)
386
+ .map_err(|e| JsError(JsValue::from_str(&e.to_string())))
359
387
  })
360
388
  }
361
389
 
@@ -522,6 +550,55 @@ impl VirtualServerHandler for JsServerHandler {
522
550
  })
523
551
  }
524
552
 
553
+ fn view_make_table(
554
+ &mut self,
555
+ view_id: &str,
556
+ table_id: &str,
557
+ config: &perspective_client::config::ViewConfig,
558
+ schema: Option<&IndexMap<String, ColumnType>>,
559
+ ) -> HandlerFuture<Result<(), Self::Error>> {
560
+ let has_method = Reflect::get(&self.0, &JsValue::from_str("viewMakeTable"))
561
+ .map(|val| !val.is_undefined())
562
+ .unwrap_or(false);
563
+
564
+ if !has_method {
565
+ return Box::pin(async {
566
+ Err(JsError(JsValue::from_str("viewMakeTable not implemented")))
567
+ });
568
+ }
569
+
570
+ let handler = self.0.clone();
571
+ let view_id = view_id.to_string();
572
+ let table_id = table_id.to_string();
573
+ let config_value = JsValue::from_serde_ext(config);
574
+ let schema_value = schema.map(|schema| {
575
+ let object = Object::new();
576
+ for (name, ty) in schema {
577
+ let _ = Reflect::set(
578
+ &object,
579
+ &JsValue::from_str(name),
580
+ &JsValue::from_str(&ty.to_string()),
581
+ );
582
+ }
583
+
584
+ JsValue::from(object)
585
+ });
586
+
587
+ Box::pin(async move {
588
+ let this = JsServerHandler(handler);
589
+ let args = Array::new();
590
+ args.push(&JsValue::from_str(&view_id));
591
+ args.push(&JsValue::from_str(&table_id));
592
+ args.push(&config_value?);
593
+ if let Some(schema_value) = schema_value {
594
+ args.push(&schema_value);
595
+ }
596
+
597
+ this.call_method_js_async("viewMakeTable", &args).await?;
598
+ Ok(())
599
+ })
600
+ }
601
+
525
602
  fn make_table(
526
603
  &mut self,
527
604
  table_id: &str,
@@ -633,7 +710,8 @@ impl VirtualServerHandler for JsServerHandler {
633
710
  }
634
711
 
635
712
  // Lock the mutex and take ownership of the inner data
636
- // We can't unwrap the Arc because the JsValue might still hold a reference
713
+ // We can't unwrap the Arc because the JsValue might still hold a
714
+ // reference
637
715
  let VirtualDataSlice(_obj, arc) = data;
638
716
  let slice = std::mem::take(&mut *arc.lock().unwrap()).unwrap();
639
717
  Ok(slice)
@@ -58,4 +58,9 @@ on_update?: boolean,
58
58
  /**
59
59
  * The data store has no reliable natural row order
60
60
  */
61
- unordered?: boolean, };
61
+ unordered?: boolean,
62
+ /**
63
+ * Whether a `Table` can be derived from a `View`, which requires
64
+ * [`VirtualServerHandler::view_make_table`](super::VirtualServerHandler::view_make_table).
65
+ */
66
+ view_derivations?: boolean, };
@@ -1,4 +1,5 @@
1
1
  // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+ import type { ColumnType } from "./ColumnType.js";
2
3
  import type { ListFlatten } from "./ListFlatten.js";
3
4
  import type { TableReadFormat } from "./TableReadFormat.js";
4
5
 
@@ -33,4 +34,9 @@ page_to_disk?: boolean,
33
34
  * repeat their index. `stringify` encodes each list as a JSON array in
34
35
  * a single string column instead.
35
36
  */
36
- list_flatten?: ListFlatten, };
37
+ list_flatten?: ListFlatten,
38
+ /**
39
+ * The columns of a [`Table`] made from a [`View`], in place of the ones
40
+ * inferred from it.
41
+ */
42
+ schema?: { [key in string]?: ColumnType }, };
@@ -20,8 +20,9 @@ formatted?: boolean,
20
20
  */
21
21
  compression?: "lz4" | "zstd",
22
22
  /**
23
- * When `true`, group-by columns use legacy `"colname (Group by N)"`
24
- * naming. When `false`, they use `__ROW_PATH_N__` naming consistent
25
- * with the SQL backend. Defaults to `true` for backwards compatibility.
23
+ * When `true`, [`View::to_arrow`] names `group_by` key columns
24
+ * `__ROW_PATH_N__` and never qualifies an aggregate, instead of the
25
+ * human-readable names a key column and its aggregate would otherwise
26
+ * take.
26
27
  */
27
- emit_legacy_row_path_names?: boolean, };
28
+ machine_column_names?: boolean, };
@@ -17,8 +17,9 @@ formatted?: boolean,
17
17
  */
18
18
  compression?: "lz4" | "zstd",
19
19
  /**
20
- * When `true`, group-by columns use legacy `"colname (Group by N)"`
21
- * naming. When `false`, they use `__ROW_PATH_N__` naming consistent
22
- * with the SQL backend. Defaults to `true` for backwards compatibility.
20
+ * When `true`, [`View::to_arrow`] names `group_by` key columns
21
+ * `__ROW_PATH_N__` and never qualifies an aggregate, instead of the
22
+ * human-readable names a key column and its aggregate would otherwise
23
+ * take.
23
24
  */
24
- emit_legacy_row_path_names?: boolean, };
25
+ machine_column_names?: boolean, };
@@ -24,6 +24,10 @@
24
24
  import type * as perspective from "@perspective-dev/client";
25
25
  import type { ColumnType } from "@perspective-dev/client/dist/esm/ts-rs/ColumnType.d.ts";
26
26
  import type { ViewConfig } from "@perspective-dev/client/dist/esm/ts-rs/ViewConfig.d.ts";
27
+ import type {
28
+ ExpressionError,
29
+ TableDescription,
30
+ } from "@perspective-dev/client";
27
31
  import type { ViewConfigUpdate } from "@perspective-dev/client/dist/esm/ts-rs/ViewConfigUpdate.d.ts";
28
32
  import type { ViewWindow } from "@perspective-dev/client/dist/esm/ts-rs/ViewWindow.d.ts";
29
33
  import type { WindowAggSpec } from "@perspective-dev/client/dist/esm/ts-rs/WindowAggSpec.d.ts";
@@ -88,6 +92,7 @@ const WINDOW_AGGREGATES: WindowAggSpec[] = [
88
92
  { name: "lead", offset: true },
89
93
  { name: "diff", offset: true, result_type: "float" },
90
94
  { name: "rate", frames: ["range"], result_type: "float" },
95
+ { name: "row_number", result_type: "float" },
91
96
  ];
92
97
 
93
98
  const WINDOW_AGGREGATES_ANY: WindowAggSpec[] = [
@@ -96,6 +101,7 @@ const WINDOW_AGGREGATES_ANY: WindowAggSpec[] = [
96
101
  { name: "max", frames: FRAMES },
97
102
  { name: "lag", offset: true },
98
103
  { name: "lead", offset: true },
104
+ { name: "row_number", result_type: "float" },
99
105
  ];
100
106
 
101
107
  const FILTER_OPS = [
@@ -374,13 +380,98 @@ export class ClickhouseHandler implements perspective.VirtualServerHandler {
374
380
  await runQuery(this.db, query, { execute: true });
375
381
  }
376
382
 
377
- async tableValidateExpression(tableId: string, expression: string) {
378
- const query = this.sqlBuilder.tableValidateExpression(
383
+ async tableDescribe(
384
+ tableId: string,
385
+ config: ViewConfig,
386
+ ): Promise<TableDescription> {
387
+ let expression_schema = {} as Record<string, ColumnType>;
388
+ const expressions_query = this.sqlBuilder.expressionsDescribe(
389
+ tableId,
390
+ config,
391
+ );
392
+
393
+ if (expressions_query !== undefined) {
394
+ try {
395
+ expression_schema = await this.describeQuery(expressions_query);
396
+ } catch (error) {
397
+ return await this.attributeExpressionErrors(
398
+ tableId,
399
+ config,
400
+ error,
401
+ );
402
+ }
403
+ }
404
+
405
+ const schema = Object.keys(config.windows ?? {}).length
406
+ ? await this.tableSchema(tableId)
407
+ : undefined;
408
+
409
+ const view_query = this.sqlBuilder.tableDescribe(
379
410
  tableId,
380
- expression,
411
+ config,
412
+ schema,
381
413
  );
414
+
415
+ let view_schema = {} as Record<string, ColumnType>;
416
+ if (view_query !== undefined) {
417
+ try {
418
+ view_schema = await this.describeQuery(view_query);
419
+ } catch (error) {
420
+ return { config_error: errorMessage(error) };
421
+ }
422
+ }
423
+
424
+ return { expression_schema, view_schema };
425
+ }
426
+
427
+ /** The planned result columns of one `DESCRIBE` query. */
428
+ private async describeQuery(query: string) {
382
429
  const results = await runQuery(this.db, query);
383
- return duckdbTypeToPsp(results[0]["type"]) as ColumnType;
430
+ const schema = {} as Record<string, ColumnType>;
431
+ for (const result of results) {
432
+ if (!result.name.startsWith("__")) {
433
+ schema[result.name] = duckdbTypeToPsp(
434
+ result.type,
435
+ ) as ColumnType;
436
+ }
437
+ }
438
+
439
+ return schema;
440
+ }
441
+
442
+ /** Plans each expression on its own to name the ones at fault. */
443
+ private async attributeExpressionErrors(
444
+ tableId: string,
445
+ config: ViewConfig,
446
+ error: unknown,
447
+ ): Promise<TableDescription> {
448
+ const expression_schema = {} as Record<string, ColumnType>;
449
+ const expression_errors = {} as Record<string, ExpressionError>;
450
+ for (const [name, expression] of Object.entries(config.expressions)) {
451
+ const query = this.sqlBuilder.expressionDescribe(
452
+ tableId,
453
+ expression,
454
+ );
455
+
456
+ try {
457
+ const results = await runQuery(this.db, query);
458
+ expression_schema[name] = duckdbTypeToPsp(
459
+ results[0]["type"],
460
+ ) as ColumnType;
461
+ } catch (error) {
462
+ expression_errors[name] = {
463
+ error_message: errorMessage(error),
464
+ line: 0,
465
+ column: 0,
466
+ };
467
+ }
468
+ }
469
+
470
+ if (Object.keys(expression_errors).length === 0) {
471
+ return { config_error: errorMessage(error) };
472
+ }
473
+
474
+ return { expression_schema, expression_errors };
384
475
  }
385
476
 
386
477
  async viewDelete(viewId: string) {
@@ -436,3 +527,7 @@ export class ClickhouseHandler implements perspective.VirtualServerHandler {
436
527
  }
437
528
  }
438
529
  }
530
+
531
+ function errorMessage(error: unknown): string {
532
+ return error instanceof Error ? error.message : String(error);
533
+ }