@perspective-dev/client 5.0.0 → 5.2.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 (49) hide show
  1. package/dist/cdn/perspective.js +2 -2
  2. package/dist/cdn/perspective.js.map +3 -3
  3. package/dist/esm/perspective.inline.js +2 -2
  4. package/dist/esm/perspective.inline.js.map +3 -3
  5. package/dist/esm/perspective.js +2 -2
  6. package/dist/esm/perspective.js.map +3 -3
  7. package/dist/esm/perspective.node.js +10 -10
  8. package/dist/esm/perspective.node.js.map +2 -2
  9. package/dist/esm/ts-rs/AggSpec.d.ts +8 -0
  10. package/dist/esm/ts-rs/Features.d.ts +66 -0
  11. package/dist/esm/ts-rs/ListFlatten.d.ts +1 -0
  12. package/dist/esm/ts-rs/SplitRollupMode.d.ts +9 -0
  13. package/dist/esm/ts-rs/TableInitOptions.d.ts +9 -0
  14. package/dist/esm/ts-rs/ViewConfig.d.ts +4 -0
  15. package/dist/esm/ts-rs/ViewConfigUpdate.d.ts +24 -0
  16. package/dist/esm/ts-rs/WindowAggSpec.d.ts +25 -0
  17. package/dist/esm/ts-rs/WindowSort.d.ts +7 -0
  18. package/dist/esm/ts-rs/WindowSortDir.d.ts +6 -0
  19. package/dist/esm/ts-rs/WindowSpec.d.ts +47 -0
  20. package/dist/esm/ts-rs/Windows.d.ts +10 -0
  21. package/dist/esm/virtual_server.d.ts +8 -34
  22. package/dist/esm/virtual_servers/clickhouse.js +1 -1
  23. package/dist/esm/virtual_servers/clickhouse.js.map +3 -3
  24. package/dist/esm/virtual_servers/duckdb.d.ts +6 -26
  25. package/dist/esm/virtual_servers/duckdb.js +1 -1
  26. package/dist/esm/virtual_servers/duckdb.js.map +3 -3
  27. package/dist/wasm/perspective-js.d.ts +96 -6
  28. package/dist/wasm/perspective-js.js +11 -11
  29. package/dist/wasm/perspective-js.wasm +0 -0
  30. package/dist/wasm/perspective-js.wasm.d.ts +5 -5
  31. package/package.json +1 -1
  32. package/src/rust/lib.rs +6 -0
  33. package/src/rust/typed_array.rs +22 -3
  34. package/src/rust/virtual_server.rs +98 -2
  35. package/src/ts/ts-rs/AggSpec.ts +10 -0
  36. package/src/ts/ts-rs/Features.ts +61 -0
  37. package/src/ts/ts-rs/ListFlatten.ts +3 -0
  38. package/src/ts/ts-rs/SplitRollupMode.ts +11 -0
  39. package/src/ts/ts-rs/TableInitOptions.ts +10 -1
  40. package/src/ts/ts-rs/ViewConfig.ts +3 -1
  41. package/src/ts/ts-rs/ViewConfigUpdate.ts +24 -1
  42. package/src/ts/ts-rs/WindowAggSpec.ts +25 -0
  43. package/src/ts/ts-rs/WindowSort.ts +9 -0
  44. package/src/ts/ts-rs/WindowSortDir.ts +8 -0
  45. package/src/ts/ts-rs/WindowSpec.ts +47 -0
  46. package/src/ts/ts-rs/Windows.ts +10 -0
  47. package/src/ts/virtual_server.ts +17 -55
  48. package/src/ts/virtual_servers/clickhouse.ts +78 -4
  49. package/src/ts/virtual_servers/duckdb.ts +145 -31
@@ -5,6 +5,8 @@ import type { Filter } from "./Filter.js";
5
5
  import type { FilterReducer } from "./FilterReducer.js";
6
6
  import type { GroupRollupMode } from "./GroupRollupMode.js";
7
7
  import type { Sort } from "./Sort.js";
8
+ import type { SplitRollupMode } from "./SplitRollupMode.js";
9
+ import type { Windows } from "./Windows.js";
8
10
 
9
11
  export type ViewConfigUpdate = {
10
12
  /**
@@ -62,6 +64,12 @@ filter?: Array<Filter>,
62
64
  * name and a string sort direction. When `column-pivots` are applied,
63
65
  * the additional sort directions `"col asc"` and `"col desc"` will
64
66
  * determine the order of pivot columns groups.
67
+ *
68
+ * `sort` is the ONLY thing that orders a `View`'s rows — without it
69
+ * they keep the `Table`'s natural (insertion) order, which any
70
+ * consumer reading rows sequentially will reflect. Not to be
71
+ * confused with a window column's `order_by`, which orders rows
72
+ * WITHIN a window frame and does not reorder the `View`.
65
73
  */
66
74
  sort?: Array<Sort>,
67
75
  /**
@@ -72,6 +80,14 @@ sort?: Array<Sort>,
72
80
  * panel.
73
81
  */
74
82
  expressions?: Expressions,
83
+ /**
84
+ * The `windows` property declares ordered, partitioned rolling
85
+ * computations (moving aggregates, cumulative sums) as _new_ columns
86
+ * keyed by output alias (`{"name": {...spec}}`, symmetric with
87
+ * `expressions`), analogous to SQL window functions. See
88
+ * [`crate::config::WindowSpec`].
89
+ */
90
+ windows?: Windows,
75
91
  /**
76
92
  * Aggregates perform a calculation over an entire column, and are
77
93
  * displayed when one or more [Group By](#group-by) are applied to the
@@ -84,5 +100,12 @@ expressions?: Expressions,
84
100
  * Perspective provides a selection of aggregate functions that can be
85
101
  * applied to columns in the `View` constructor using a dictionary of
86
102
  * column name to aggregate function name.
103
+ *
104
+ * An aggregate also determines the column's RESULT TYPE, which need
105
+ * not match the input: `"count"` yields an `integer` whatever it
106
+ * counts, so a `date` column left on the default `"count"` is an
107
+ * `integer` in the resulting `View` — no longer a date. Set an
108
+ * aggregate that preserves the type (e.g. `"any"`, `"last"`) when
109
+ * the original type matters, such as a date used as a chart axis.
87
110
  */
88
- aggregates?: { [key in string]?: Aggregate }, group_by_depth?: number, filter_op?: FilterReducer, group_rollup_mode?: GroupRollupMode, };
111
+ aggregates?: { [key in string]?: Aggregate }, group_by_depth?: number, filter_op?: FilterReducer, group_rollup_mode?: GroupRollupMode, split_rollup_mode?: SplitRollupMode, };
@@ -0,0 +1,25 @@
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";
3
+
4
+ /**
5
+ * Specification for a window aggregate.
6
+ */
7
+ export type WindowAggSpec = { name: string,
8
+ /**
9
+ * Frame kinds this aggregate accepts (`rows`, `range`, `cumulative`).
10
+ * Empty means it takes no frame at all.
11
+ */
12
+ frames?: Array<string>,
13
+ /**
14
+ * Takes a row offset, as `lag` / `lead` / `diff` do.
15
+ */
16
+ offset?: boolean,
17
+ /**
18
+ * Takes a smoothing factor, as `ema` does.
19
+ */
20
+ alpha?: boolean,
21
+ /**
22
+ * The output column type. `None` means the source column's type, which
23
+ * is what `min` / `max` / `lag` do.
24
+ */
25
+ result_type?: ColumnType, };
@@ -0,0 +1,9 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+ import type { WindowSortDir } from "./WindowSortDir.js";
3
+
4
+ /**
5
+ * The `Table` column which orders each partition, with its direction -
6
+ * serialized as a two-element array (`["ts", "desc"]`), symmetric with the
7
+ * `ViewConfig`'s `sort` field.
8
+ */
9
+ export type WindowSort = [string, WindowSortDir];
@@ -0,0 +1,8 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+
3
+ /**
4
+ * A window's order direction. A dedicated two-variant enum rather than
5
+ * [`crate::config::SortDir`] - the column-sort extras (`col asc`, `abs`,
6
+ * `none`) are meaningless inside a window frame and unrepresentable here.
7
+ */
8
+ export type WindowSortDir = "asc" | "desc";
@@ -0,0 +1,47 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+ import type { WindowSort } from "./WindowSort.js";
3
+
4
+ /**
5
+ * The serialized form of [`WindowSpec`].
6
+ */
7
+ export type WindowSpec = {
8
+ /**
9
+ * The input column - either a real `Table` column or an expression
10
+ * alias from the same `ViewConfig`.
11
+ */
12
+ column: string, aggregate: string,
13
+ /**
14
+ * Columns whose distinct value tuples partition the rows; empty
15
+ * partitions the whole `Table` as one group.
16
+ */
17
+ partition_by?: Array<string>,
18
+ /**
19
+ * The `Table` column which orders each partition, and the direction.
20
+ * This orders rows WITHIN the window frame only — it does not
21
+ * reorder the `View`, which is what the view-level `sort` does.
22
+ */
23
+ order_by?: WindowSort | null,
24
+ /**
25
+ * A frame of the `rows` preceding each row, plus the row itself.
26
+ * Mutually exclusive with `range` and `cumulative`.
27
+ */
28
+ rows?: number | null,
29
+ /**
30
+ * A frame of the rows whose `order_by` value lies within `range` of
31
+ * each row's, requiring a numeric or temporal `order_by`. Mutually
32
+ * exclusive with `rows` and `cumulative`.
33
+ */
34
+ range?: number | null,
35
+ /**
36
+ * `true` frames all rows from the partition start through each row.
37
+ * Default can be omitted.
38
+ */
39
+ cumulative?: boolean | null,
40
+ /**
41
+ * Row offset for `lag`/`lead` (default 1).
42
+ */
43
+ offset?: number | null,
44
+ /**
45
+ * Smoothing factor in `(0, 1]` for `ema`.
46
+ */
47
+ alpha?: number | null, };
@@ -0,0 +1,10 @@
1
+ // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
2
+ import type { WindowSpec } from "./WindowSpec.js";
3
+
4
+ /**
5
+ * The window columns of a `ViewConfig`, keyed by output column alias -
6
+ * symmetric with `expressions` (`{"name": {...spec}}`). An alias must not
7
+ * collide with a `Table` column, expression alias, or another window's
8
+ * key.
9
+ */
10
+ export type Windows = { [key in string]?: WindowSpec };
@@ -10,10 +10,6 @@
10
10
  // ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
11
11
  // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
12
12
 
13
- import { ColumnType } from "./ts-rs/ColumnType.ts";
14
- import { ViewConfig } from "./ts-rs/ViewConfig.ts";
15
- import { ViewWindow } from "./ts-rs/ViewWindow.ts";
16
-
17
13
  import type * as perspective from "../../dist/wasm/perspective-js.js";
18
14
 
19
15
  /**
@@ -26,63 +22,29 @@ import type * as perspective from "../../dist/wasm/perspective-js.js";
26
22
  * - Implementing custom aggregation or transformation logic
27
23
  * - Creating data adapters without copying data into Perspective tables
28
24
  *
25
+ * The `VirtualServerHandler` interface and `Features` struct are declared
26
+ * in Rust alongside the bridge that invokes them (`perspective-js`'s
27
+ * `virtual_server.rs` and `perspective-client`'s `features.rs`
28
+ * respectively) and re-exported here. `ServerFeatures` is a legacy alias
29
+ * for `Features`.
30
+ *
29
31
  * @module virtual_server
30
32
  */
31
33
 
32
- export interface ServerFeatures {
33
- expressions?: boolean;
34
- }
35
-
36
- /**
37
- * Handler interface that you implement to provide custom data sources.
38
- *
39
- * All methods will be called by the VirtualServer when handling protocol
40
- * messages from Perspective clients. Methods can return values directly or
41
- * return Promises for asynchronous operations (e.g., database queries).
42
- */
43
- export interface VirtualServerHandler {
44
- getHostedTables(): string[] | Promise<string[]>;
45
- tableSchema(
46
- tableId: string,
47
- ): Record<string, ColumnType> | Promise<Record<string, ColumnType>>;
48
- tableSize(tableId: string): number | Promise<number>;
49
- tableMakeView(
50
- tableId: string,
51
- viewId: string,
52
- config: ViewConfig,
53
- ): void | Promise<void>;
54
- viewDelete(viewId: string): void | Promise<void>;
55
- viewGetData(
56
- viewId: string,
57
- config: ViewConfig,
58
- schema: Record<string, ColumnType>,
59
- viewport: ViewWindow,
60
- dataSlice: perspective.VirtualDataSlice,
61
- ): void | Promise<void>;
62
- viewSchema?(
63
- viewId: string,
64
- config?: ViewConfig,
65
- ): Record<string, ColumnType> | Promise<Record<string, ColumnType>>;
66
- viewSize?(viewId: string): number | Promise<number>;
67
- tableValidateExpression?(
68
- tableId: string,
69
- expression: string,
70
- ): ColumnType | Promise<ColumnType>;
71
- viewGetMinMax?(
72
- viewId: string,
73
- columnName: string,
74
- config: ViewConfig,
75
- ): { min: any; max: any } | Promise<{ min: any; max: any }>;
76
- getFeatures?(): ServerFeatures | Promise<ServerFeatures>;
77
- makeTable?(
78
- tableId: string,
79
- data: string | Uint8Array,
80
- ): void | Promise<void>;
81
- }
34
+ // `Features` must re-export from the wasm `.d.ts` (NOT "./ts-rs/Features.ts")
35
+ // - `perspective.browser.ts` star-exports both this module and the wasm
36
+ // `.d.ts`, and star exports of the same name only merge when they resolve to
37
+ // the same declaration.
38
+ export type {
39
+ VirtualServerHandler,
40
+ VirtualHostedTable,
41
+ Features,
42
+ Features as ServerFeatures,
43
+ } from "../../dist/wasm/perspective-js.js";
82
44
 
83
45
  export function createMessageHandler(
84
46
  mod: typeof perspective,
85
- handler: VirtualServerHandler,
47
+ handler: perspective.VirtualServerHandler,
86
48
  ) {
87
49
  let virtualServer: perspective.VirtualServer;
88
50
  async function postMessage(port: MessagePort, msg: MessageEvent) {
@@ -24,7 +24,9 @@
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 { ViewConfigUpdate } from "@perspective-dev/client/dist/esm/ts-rs/ViewConfigUpdate.d.ts";
27
28
  import type { ViewWindow } from "@perspective-dev/client/dist/esm/ts-rs/ViewWindow.d.ts";
29
+ import type { WindowAggSpec } from "@perspective-dev/client/dist/esm/ts-rs/WindowAggSpec.d.ts";
28
30
  import type * as clickhouse from "@clickhouse/client-web";
29
31
 
30
32
  const NUMBER_AGGS = [
@@ -63,16 +65,70 @@ const STRING_AGGS = [
63
65
  "string_agg",
64
66
  ];
65
67
 
68
+ // Window functions. Renamed from Perspective's `stddev`/`var` to the SQL
69
+ // standard spellings DuckDB and ClickHouse both accept, since the advertised
70
+ // name is now emitted verbatim.
71
+ //
72
+ // NOTE: this set is inherited from the DuckDB handler and has NOT been audited
73
+ // against a live ClickHouse - see the aggregate lists below, which have the
74
+ // same problem. ClickHouse's own navigation functions are `lagInFrame` /
75
+ // `leadInFrame`, and its ranking set differs; both need verifying before being
76
+ // advertised here.
77
+ const FRAMES = ["rows", "range", "cumulative"];
78
+
79
+ const WINDOW_AGGREGATES: WindowAggSpec[] = [
80
+ { name: "sum", frames: FRAMES, result_type: "float" },
81
+ { name: "avg", frames: FRAMES, result_type: "float" },
82
+ { name: "count", frames: FRAMES, result_type: "float" },
83
+ { name: "min", frames: FRAMES },
84
+ { name: "max", frames: FRAMES },
85
+ { name: "stddev_samp", frames: FRAMES, result_type: "float" },
86
+ { name: "var_samp", frames: FRAMES, result_type: "float" },
87
+ { name: "lag", offset: true },
88
+ { name: "lead", offset: true },
89
+ { name: "diff", offset: true, result_type: "float" },
90
+ { name: "rate", frames: ["range"], result_type: "float" },
91
+ ];
92
+
93
+ const WINDOW_AGGREGATES_ANY: WindowAggSpec[] = [
94
+ { name: "count", frames: FRAMES, result_type: "float" },
95
+ { name: "min", frames: FRAMES },
96
+ { name: "max", frames: FRAMES },
97
+ { name: "lag", offset: true },
98
+ { name: "lead", offset: true },
99
+ ];
100
+
66
101
  const FILTER_OPS = [
67
102
  "==",
68
103
  "!=",
69
- "LIKE",
70
104
  "IS DISTINCT FROM",
71
105
  "IS NOT DISTINCT FROM",
72
106
  ">=",
73
107
  "<=",
74
108
  ">",
75
109
  "<",
110
+ "is null",
111
+ "is not null",
112
+ ];
113
+
114
+ // Perspective's canonical string ops (translated to `ILIKE` / `match` by the
115
+ // SQL builder), plus ClickHouse's raw infix pattern ops spliced verbatim.
116
+ const STRING_FILTER_OPS = [
117
+ ...FILTER_OPS,
118
+ "begins with",
119
+ "not begins with",
120
+ "contains",
121
+ "not contains",
122
+ "ends with",
123
+ "not ends with",
124
+ "matches",
125
+ "not matches",
126
+ "in",
127
+ "not in",
128
+ "LIKE",
129
+ "NOT LIKE",
130
+ "ILIKE",
131
+ "NOT ILIKE",
76
132
  ];
77
133
 
78
134
  function duckdbTypeToPsp(name: string): ColumnType {
@@ -215,20 +271,34 @@ export class ClickhouseHandler implements perspective.VirtualServerHandler {
215
271
  create_entity: "VIEW",
216
272
  grouping_fn: "GROUPING",
217
273
  column_separator: "|",
274
+ backslash_escaped_literals: true,
275
+ regex_fn: "match",
218
276
  });
219
277
  }
220
278
 
221
- getFeatures() {
279
+ getFeatures(): perspective.Features {
222
280
  return {
223
281
  group_by: true,
224
282
  split_by: false,
225
283
  sort: true,
226
284
  expressions: true,
285
+ // ClickHouse has no stable `rowid`, so natural-order windows
286
+ // are unsupported.
287
+ unordered: true,
288
+ window_aggregates: {
289
+ // `ema` is recursive and has no SQL window translation.
290
+ integer: WINDOW_AGGREGATES,
291
+ float: WINDOW_AGGREGATES,
292
+ string: WINDOW_AGGREGATES_ANY,
293
+ date: WINDOW_AGGREGATES_ANY,
294
+ datetime: WINDOW_AGGREGATES_ANY,
295
+ boolean: WINDOW_AGGREGATES_ANY,
296
+ },
227
297
  group_rollup_mode: ["rollup", "flat", "total"],
228
298
  filter_ops: {
229
299
  integer: FILTER_OPS,
230
300
  float: FILTER_OPS,
231
- string: FILTER_OPS,
301
+ string: STRING_FILTER_OPS,
232
302
  boolean: FILTER_OPS,
233
303
  date: FILTER_OPS,
234
304
  datetime: FILTER_OPS,
@@ -284,7 +354,11 @@ export class ClickhouseHandler implements perspective.VirtualServerHandler {
284
354
  return Number(results[0]["COUNT()"]);
285
355
  }
286
356
 
287
- async tableMakeView(tableId: string, viewId: string, config: ViewConfig) {
357
+ async tableMakeView(
358
+ tableId: string,
359
+ viewId: string,
360
+ config: ViewConfigUpdate,
361
+ ) {
288
362
  const query = this.sqlBuilder.tableMakeView(tableId, viewId, config);
289
363
  await runQuery(this.db, query, { execute: true });
290
364
  }
@@ -24,7 +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 { ViewConfigUpdate } from "@perspective-dev/client/dist/esm/ts-rs/ViewConfigUpdate.d.ts";
27
28
  import type { ViewWindow } from "@perspective-dev/client/dist/esm/ts-rs/ViewWindow.d.ts";
29
+ import type { WindowAggSpec } from "@perspective-dev/client/dist/esm/ts-rs/WindowAggSpec.d.ts";
30
+ import type { Scalar } from "@perspective-dev/client/dist/esm/ts-rs/Scalar.d.ts";
28
31
  import type * as duckdb from "@duckdb/duckdb-wasm";
29
32
 
30
33
  const NUMBER_AGGS = [
@@ -63,63 +66,158 @@ const STRING_AGGS = [
63
66
  "string_agg",
64
67
  ];
65
68
 
69
+ const FRAMES = ["rows", "range", "cumulative"];
70
+
71
+ const WINDOW_AGGREGATES: WindowAggSpec[] = [
72
+ { name: "sum", frames: FRAMES, result_type: "float" },
73
+ { name: "avg", frames: FRAMES, result_type: "float" },
74
+ { name: "count", frames: FRAMES, result_type: "float" },
75
+ { name: "min", frames: FRAMES },
76
+ { name: "max", frames: FRAMES },
77
+ { name: "product", frames: FRAMES, result_type: "float" },
78
+ { name: "median", frames: FRAMES, result_type: "float" },
79
+ // DuckDB spells sample and population variants separately, so both are
80
+ // offered rather than one being picked on the user's behalf.
81
+ { name: "stddev_samp", frames: FRAMES, result_type: "float" },
82
+ { name: "stddev_pop", frames: FRAMES, result_type: "float" },
83
+ { name: "var_samp", frames: FRAMES, result_type: "float" },
84
+ { name: "var_pop", frames: FRAMES, result_type: "float" },
85
+ // Navigation.
86
+ { name: "first_value", frames: FRAMES },
87
+ { name: "last_value", frames: FRAMES },
88
+ { name: "nth_value", frames: FRAMES, offset: true },
89
+ { name: "lag", offset: true },
90
+ { name: "lead", offset: true },
91
+ // Ranking. These take no source column - the window's `order_by` is their
92
+ // input - but Perspective requires one, so the choice of source is
93
+ // immaterial for them.
94
+ { name: "row_number", result_type: "float" },
95
+ { name: "rank", result_type: "float" },
96
+ { name: "dense_rank", result_type: "float" },
97
+ { name: "percent_rank", result_type: "float" },
98
+ { name: "cume_dist", result_type: "float" },
99
+ // `ntile`'s argument is a bucket count rather than a row offset.
100
+ { name: "ntile", offset: true, result_type: "float" },
101
+ // Perspective's own, with no DuckDB equivalent - the SQL translation
102
+ // synthesizes them from `lag` and `first_value`.
103
+ { name: "diff", offset: true, result_type: "float" },
104
+ { name: "rate", frames: ["range"], result_type: "float" },
105
+ ];
106
+
107
+ // Arithmetic is undefined for the non-numeric types; ordering and navigation
108
+ // are not.
109
+ const WINDOW_AGGREGATES_ANY: WindowAggSpec[] = [
110
+ { name: "count", frames: FRAMES, result_type: "float" },
111
+ { name: "min", frames: FRAMES },
112
+ { name: "max", frames: FRAMES },
113
+ { name: "first_value", frames: FRAMES },
114
+ { name: "last_value", frames: FRAMES },
115
+ { name: "nth_value", frames: FRAMES, offset: true },
116
+ { name: "lag", offset: true },
117
+ { name: "lead", offset: true },
118
+ { name: "row_number", result_type: "float" },
119
+ { name: "rank", result_type: "float" },
120
+ { name: "dense_rank", result_type: "float" },
121
+ { name: "percent_rank", result_type: "float" },
122
+ { name: "cume_dist", result_type: "float" },
123
+ { name: "ntile", offset: true, result_type: "float" },
124
+ ];
125
+
66
126
  const FILTER_OPS = [
67
127
  "==",
68
128
  "!=",
69
- "LIKE",
70
129
  "IS DISTINCT FROM",
71
130
  "IS NOT DISTINCT FROM",
72
131
  ">=",
73
132
  "<=",
74
133
  ">",
75
134
  "<",
135
+ "is null",
136
+ "is not null",
76
137
  ];
77
138
 
139
+ // Perspective's canonical string ops (translated to `ILIKE` / `regexp_matches`
140
+ // by the SQL builder), plus DuckDB's raw infix pattern ops spliced verbatim.
141
+ const STRING_FILTER_OPS = [
142
+ ...FILTER_OPS,
143
+ "begins with",
144
+ "not begins with",
145
+ "contains",
146
+ "not contains",
147
+ "ends with",
148
+ "not ends with",
149
+ "matches",
150
+ "not matches",
151
+ "in",
152
+ "not in",
153
+ "LIKE",
154
+ "NOT LIKE",
155
+ "ILIKE",
156
+ "NOT ILIKE",
157
+ ];
158
+
159
+ /**
160
+ * Convert a DuckDB `dtype` to a Perspective `ColumnType`.
161
+ */
78
162
  function duckdbTypeToPsp(name: string): ColumnType {
79
163
  name = name.toLowerCase();
80
- if (name === "varchar" || name == "utf8") {
81
- return "string";
164
+
165
+ if (name.startsWith("bool")) {
166
+ return "boolean";
82
167
  }
83
168
 
169
+ // 32-bit and narrower - `coerce_column` widens these to `Int32`.
84
170
  if (
85
- name === "double" ||
86
- name === "bigint" ||
87
- name === "hugeint" ||
88
- name === "float64" ||
89
- name.startsWith("decimal")
171
+ ["tinyint", "smallint", "integer", "utinyint", "usmallint"].includes(
172
+ name,
173
+ ) ||
174
+ ["int8", "int16", "int32", "uint8", "uint16"].includes(name)
90
175
  ) {
91
- return "float";
176
+ return "integer";
92
177
  }
93
178
 
94
- if (name.startsWith("int")) {
95
- return "integer";
179
+ // Wider than `Int32`, or fractional - all coerce to `Float64`.
180
+ if (
181
+ ["bigint", "hugeint", "uhugeint", "uinteger", "ubigint"].includes(
182
+ name,
183
+ ) ||
184
+ ["float", "real", "double", "varint"].includes(name) ||
185
+ ["int64", "uint32", "uint64", "float32", "float64"].includes(name) ||
186
+ name.startsWith("decimal") ||
187
+ name.startsWith("numeric")
188
+ ) {
189
+ return "float";
96
190
  }
97
191
 
98
192
  if (name.startsWith("date")) {
99
193
  return "date";
100
194
  }
101
195
 
102
- if (name.startsWith("bool")) {
103
- return "boolean";
104
- }
105
-
106
- if (name.startsWith("timestamp")) {
196
+ // `timestamp`, `timestamptz`, `timestamp_ns`, and `time`/`timetz`,
197
+ // which coerce to `Timestamp(Millisecond)` rather than to a number.
198
+ if (name.startsWith("time")) {
107
199
  return "datetime";
108
200
  }
109
201
 
110
- if (name.startsWith("json")) {
111
- return "string";
112
- }
113
-
114
- if (name.startsWith("struct")) {
115
- return "string";
116
- }
117
-
118
- if (name.startsWith("time")) {
119
- return "float";
202
+ // Everything else renders as text: `varchar`, `enum(...)` (which
203
+ // arrives dictionary-encoded), `json`, `uuid`, `blob`, `interval`,
204
+ // and the nested types.
205
+ if (
206
+ !(
207
+ name.startsWith("varchar") ||
208
+ name === "utf8" ||
209
+ name.startsWith("enum") ||
210
+ ["json", "uuid", "blob", "bit", "interval"].includes(name) ||
211
+ name.startsWith("struct") ||
212
+ name.startsWith("map") ||
213
+ name.startsWith("union") ||
214
+ name.endsWith("[]")
215
+ )
216
+ ) {
217
+ // Unknown, not fatal - the column still renders, as text.
218
+ console.warn(`Unknown type '${name}'`);
120
219
  }
121
220
 
122
- console.warn(`Unknown type '${name}'`);
123
221
  return "string";
124
222
  }
125
223
 
@@ -186,20 +284,32 @@ export class DuckDBHandler implements perspective.VirtualServerHandler {
186
284
  this.db = db;
187
285
  this.sqlBuilder = new mod!.GenericSQLVirtualServerModel({
188
286
  column_separator: "|",
287
+ like_escape_clause: "\\",
288
+ regex_fn: "regexp_matches",
189
289
  });
190
290
  }
191
291
 
192
- getFeatures() {
292
+ getFeatures(): perspective.Features {
193
293
  return {
194
294
  group_by: true,
195
295
  split_by: true,
196
296
  sort: true,
197
297
  expressions: true,
298
+ window_aggregates: {
299
+ // `ema` is recursive and has no SQL window translation.
300
+ integer: WINDOW_AGGREGATES,
301
+ float: WINDOW_AGGREGATES,
302
+ string: WINDOW_AGGREGATES_ANY,
303
+ date: WINDOW_AGGREGATES_ANY,
304
+ datetime: WINDOW_AGGREGATES_ANY,
305
+ boolean: WINDOW_AGGREGATES_ANY,
306
+ },
198
307
  group_rollup_mode: ["rollup", "flat", "total"],
308
+ split_rollup_mode: ["flat", "rollup"],
199
309
  filter_ops: {
200
310
  integer: FILTER_OPS,
201
311
  float: FILTER_OPS,
202
- string: FILTER_OPS,
312
+ string: STRING_FILTER_OPS,
203
313
  boolean: FILTER_OPS,
204
314
  date: FILTER_OPS,
205
315
  datetime: FILTER_OPS,
@@ -256,7 +366,11 @@ export class DuckDBHandler implements perspective.VirtualServerHandler {
256
366
  return Number(results[0].toJSON()["count_star()"]);
257
367
  }
258
368
 
259
- async tableMakeView(tableId: string, viewId: string, config: ViewConfig) {
369
+ async tableMakeView(
370
+ tableId: string,
371
+ viewId: string,
372
+ config: ViewConfigUpdate,
373
+ ) {
260
374
  const query = this.sqlBuilder.tableMakeView(tableId, viewId, config);
261
375
  await runQuery(this.db, query);
262
376
  }
@@ -288,7 +402,7 @@ export class DuckDBHandler implements perspective.VirtualServerHandler {
288
402
  let [min, max] = Object.values(row);
289
403
  if (typeof min === "bigint") min = Number(min);
290
404
  if (typeof max === "bigint") max = Number(max);
291
- return { min: min ?? null, max: max ?? null };
405
+ return { min: (min ?? null) as Scalar, max: (max ?? null) as Scalar };
292
406
  }
293
407
 
294
408
  async viewGetData(