@akohn/dashql 0.0.19-dev.247 → 0.0.19-dev.261.g8742d37fb

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.
@@ -160,6 +160,459 @@ export enum TaskStatus {
160
160
  TASK_FAILED = 3,
161
161
  TASK_CANCELLED = 4,
162
162
  }
163
+ /**
164
+ * The error of a failed or cancelled query
165
+ */
166
+ export interface QueryErrorView {
167
+ message: string;
168
+ details: string | null;
169
+ }
170
+
171
+ /**
172
+ * A query, the slice `query` of the runtime: its text, what it is, its status and its latest progress. The field names
173
+ * are the ones the app reads. The result table is a table of the handle table of the platform.
174
+ */
175
+ export interface QueryView {
176
+ queryId: number;
177
+ /**
178
+ * The connection of the query
179
+ */
180
+ connectionId: string;
181
+ /**
182
+ * The trace of the log messages of the query
183
+ */
184
+ traceId: number;
185
+ queryText: string;
186
+ queryMetadata: QueryMetadataView;
187
+ status: QueryExecutionStatus;
188
+ metrics: QueryMetricsView;
189
+ error: QueryErrorView | null;
190
+ resultTable: QueryResultTableView | null;
191
+ cacheKey: string | null;
192
+ servedFromCache: boolean;
193
+ cacheDeleted: boolean;
194
+ cachedAt: number | null;
195
+ latestProgressUpdate: QueryLatestProgressView | null;
196
+ revision: number;
197
+ /**
198
+ * The handle of the record of the query at the host
199
+ */
200
+ handle: number | null;
201
+ }
202
+
203
+ /**
204
+ * A progress update of a channel of the host: the plain fields and the raw progress payload of the engine, e.g.
205
+ * `{ kind: 'hyper_query_status', status, receivedAt }`. The progress model of the query in the executor turns the
206
+ * payload into the structured progress.
207
+ */
208
+ export interface QueryProgressView {
209
+ isQueued: boolean | null;
210
+ progressPercent: number | null;
211
+ resultRows: number | null;
212
+ rowsProcessed: number | null;
213
+ executionTimeMs: number | null;
214
+ /**
215
+ * The metrics of the response stream, none counts nothing
216
+ */
217
+ metrics?: QueryStreamMetrics | null;
218
+ phase?: string | null;
219
+ /**
220
+ * The raw progress payload of the engine, a payload of an unknown kind is dropped
221
+ */
222
+ engineProgress?: unknown;
223
+ }
224
+
225
+ /**
226
+ * What a query is and who issued it. A planned statement of a run of a workbook is opaque JSON
227
+ * (`PlannedStatement` of the app).
228
+ */
229
+ export interface QueryMetadataView {
230
+ queryType: QueryType;
231
+ title: string | null;
232
+ description: string | null;
233
+ issuer: string | null;
234
+ userProvided: boolean;
235
+ workbookId?: string;
236
+ resultOwner?: string;
237
+ planned?: unknown;
238
+ }
239
+
240
+ /**
241
+ * The metrics of the finished queries of a history, internal queries don't count
242
+ */
243
+ export interface QueryHistoryMetrics {
244
+ successfulQueries: QueryOutcomeMetrics;
245
+ canceledQueries: QueryOutcomeMetrics;
246
+ failedQueries: QueryOutcomeMetrics;
247
+ }
248
+
249
+ /**
250
+ * The metrics of the finished queries of one outcome
251
+ */
252
+ export interface QueryOutcomeMetrics {
253
+ totalQueries: number;
254
+ totalBatchesReceived: number;
255
+ totalRowsReceived: number;
256
+ accumulatedTimeUntilFirstBatch: number;
257
+ accumulatedQueryDuration: number;
258
+ }
259
+
260
+ /**
261
+ * The keys of the structured progress of a query that the host holds, their payloads don't cross again
262
+ */
263
+ export interface QueryProfileKeys {
264
+ /**
265
+ * The revision of the progress, the execution state crosses when it differs
266
+ */
267
+ revision: number | null;
268
+ /**
269
+ * The version of the structure, the structure crosses when it differs
270
+ */
271
+ structureVersion: number | null;
272
+ }
273
+
274
+ /**
275
+ * The structured progress of a query: the plan with its stages and their execution state. A payload is null when the
276
+ * host holds it already, its key names it.
277
+ */
278
+ export interface QueryProfileProgressView {
279
+ /**
280
+ * The revision of the progress, it changes with the structure or the execution state
281
+ */
282
+ revision: number;
283
+ /**
284
+ * The version of the structure
285
+ */
286
+ structureVersion: number;
287
+ /**
288
+ * The packed `QueryProfile`, null while the host holds its version
289
+ */
290
+ structure: FlatBuffer<buffers_profile.QueryProfile> | null;
291
+ /**
292
+ * The execution state as packed `QueryProfileEvents`, one event per entity with state, null while the host holds
293
+ * the revision
294
+ */
295
+ execution: FlatBuffer<buffers_profile.QueryProfileEvents> | null;
296
+ }
297
+
298
+ /**
299
+ * The result table of a query, the host keeps it under its handle
300
+ */
301
+ export interface QueryResultTableView {
302
+ id: number;
303
+ rows: number;
304
+ }
305
+
306
+ /**
307
+ * The metrics of the response stream of a query, as the connector counts them
308
+ */
309
+ export interface QueryStreamMetrics {
310
+ totalDataBytesReceived: number;
311
+ totalBatchesReceived: number;
312
+ totalRowsReceived: number;
313
+ totalQueryRequestsStarted: number;
314
+ totalQueryRequestsSucceeded: number;
315
+ totalQueryRequestsFailed: number;
316
+ totalQueryRequestDurationMs: number;
317
+ durationUntilFirstBatchMs: number | null;
318
+ }
319
+
320
+ /**
321
+ * The latest progress update of a query: the plain fields and the structured progress
322
+ */
323
+ export interface QueryLatestProgressView {
324
+ isQueued: boolean | null;
325
+ progressPercent: number | null;
326
+ resultRows: number | null;
327
+ rowsProcessed: number | null;
328
+ executionTimeMs: number | null;
329
+ metrics: QueryStreamMetrics;
330
+ phase: string | null;
331
+ profile: QueryProfileProgressView | null;
332
+ }
333
+
334
+ /**
335
+ * The layout of the plans of query profiles, the fields of `ProfileLayoutConfigT` of the generated FlatBuffer code
336
+ */
337
+ export interface ProfileLayoutView {
338
+ levelHeight: number;
339
+ nodeHeight: number;
340
+ nodeMarginHorizontal: number;
341
+ nodePaddingLeft: number;
342
+ nodePaddingRight: number;
343
+ iconWidth: number;
344
+ iconMarginRight: number;
345
+ maxLabelChars: number;
346
+ widthPerLabelChar: number;
347
+ nodeMinWidth: number;
348
+ nodeMarginVertical: number;
349
+ /**
350
+ * A `ProfileLayoutOrientation`
351
+ */
352
+ orientation: number;
353
+ symbolWidth: number;
354
+ }
355
+
356
+ /**
357
+ * The points in time of a query in milliseconds since epoch and its counters
358
+ */
359
+ export interface QueryMetricsView {
360
+ queryRequestedAt: number | null;
361
+ querySendingStartedAt: number | null;
362
+ queryQueuedStartedAt: number | null;
363
+ queryRunningStartedAt: number | null;
364
+ receivedFirstBatchAt: number | null;
365
+ receivedLastBatchAt: number | null;
366
+ receivedAllBatchesAt: number | null;
367
+ processingResultsStartedAt: number | null;
368
+ processedResultsAt: number | null;
369
+ querySucceededAt: number | null;
370
+ queryFailedAt: number | null;
371
+ queryCancelledAt: number | null;
372
+ lastUpdatedAt: number | null;
373
+ progressUpdatesReceived: number;
374
+ queryDurationMs: number | null;
375
+ textLength: number | null;
376
+ streamMetrics: QueryStreamMetrics;
377
+ }
378
+
379
+ /**
380
+ * The outcome of saving a connection
381
+ */
382
+ export interface ConnectionSaveOutcome {
383
+ /**
384
+ * The saved params
385
+ */
386
+ params: JsonParams;
387
+ /**
388
+ * The outcome of writing the app manifest
389
+ */
390
+ manifest: StorageWriteOutcome;
391
+ /**
392
+ * The outcomes of writing the copies of the workbooks, none if the manifest wasn't written
393
+ */
394
+ workbooks: ConnectionCopyOutcome[];
395
+ }
396
+
397
+ /**
398
+ * The outcome of writing the copy of a connection into a workbook
399
+ */
400
+ export interface ConnectionCopyOutcome {
401
+ workbookId: string;
402
+ result: StorageWriteOutcome;
403
+ }
404
+
405
+
406
+ import type * as buffers_editor from '../gen/flatbuffers/dashql/buffers/editor.js';
407
+ import type * as buffers_diff from '../gen/flatbuffers/dashql/buffers/diff.js';
408
+ import type * as buffers_execution from '../gen/flatbuffers/dashql/buffers/execution.js';
409
+ import type * as buffers_profile from '../gen/flatbuffers/dashql/buffers/profile.js';
410
+ /** The bytes of a packed FlatBuffer whose root table is `T`, read with the generated accessors */
411
+ export type FlatBuffer<T> = Uint8Array & { readonly __flatbufferRoot?: T };
412
+
413
+
414
+ /**
415
+ * Opaque JSON in a view: a workbook file, a connection entry, the params of a connection. It crosses as a plain JS
416
+ * value and is read the way `JSON.stringify` reads it: members that are undefined or functions are left out, `toJSON`
417
+ * is called, numbers that are not finite are null.
418
+ */
419
+ export type JsonValue = unknown;
420
+
421
+ /**
422
+ * How a setup runs
423
+ */
424
+ export interface SetupOptions {
425
+ /**
426
+ * The params of the setup, the params of the connection by default
427
+ */
428
+ params?: JsonParams;
429
+ /**
430
+ * The params that the channel connects with when they differ from the ones that the connection keeps, e.g. the
431
+ * credentials of the environment that are never written
432
+ */
433
+ channelParams?: JsonParams;
434
+ /**
435
+ * Log in again instead of using a session of the browser
436
+ */
437
+ forceRelogin?: boolean;
438
+ /**
439
+ * The redirect page of the app that an OAuth flow of Salesforce returns to
440
+ */
441
+ oauthRedirect?: string;
442
+ }
443
+
444
+ /**
445
+ * The tokens and the user of a login
446
+ */
447
+ export interface SetupAuthentication {
448
+ tokens: { core: any; dataCloud: any };
449
+ userInfo: any | null;
450
+ }
451
+
452
+ /**
453
+ * How a setup or a login ended
454
+ */
455
+ export interface SetupOutcome {
456
+ status: 'succeeded' | 'failed' | 'cancelled';
457
+ /**
458
+ * The error of a setup that didn't succeed
459
+ */
460
+ message: string | null;
461
+ /**
462
+ * The details of the error, e.g. the status of a rejected request
463
+ */
464
+ data: Record<string, string>;
465
+ /**
466
+ * The tokens of a login
467
+ */
468
+ authentication: SetupAuthentication | null;
469
+ }
470
+
471
+ /**
472
+ * What the executor does around a query besides running its text
473
+ */
474
+ export interface QueryOptions {
475
+ /**
476
+ * Analyze the result on the compute database, false by default
477
+ */
478
+ analyzeResults?: boolean;
479
+ /**
480
+ * Collect the result, true by default. A statement whose output nothing reads drains it.
481
+ */
482
+ publishResults?: boolean;
483
+ /**
484
+ * Reject with the error of a failed query instead of resolving
485
+ */
486
+ throwOnError?: boolean;
487
+ /**
488
+ * A call of a client function that runs instead of the text, as the core describes it
489
+ */
490
+ clientFunctionCall?: JsonValue;
491
+ /**
492
+ * The time to wait for the next batch of a channel of the host, the default of the channel without
493
+ */
494
+ readTimeoutMs?: number;
495
+ /**
496
+ * The query result cache, none for a query that never reads or writes it
497
+ */
498
+ cache?: QueryCacheOptions;
499
+ }
500
+
501
+ /**
502
+ * How a query uses the query result cache
503
+ */
504
+ export interface QueryCacheOptions {
505
+ /**
506
+ * The semantic signature of the script that the key of the result derives from, with the params of the connection
507
+ */
508
+ signature: string;
509
+ /**
510
+ * Run the query instead of serving a cached result, the result becomes the newest file of its key
511
+ */
512
+ refresh?: boolean;
513
+ /**
514
+ * Serve the cached result or fail with a cache miss instead of running the query
515
+ */
516
+ only?: boolean;
517
+ }
518
+
519
+ /**
520
+ * The failure of a query, `hostValue` tells whether `value` of the outcome is what the host failed with
521
+ */
522
+ export interface QueryRunFailure {
523
+ kind: QueryRunFailureKind;
524
+ message: string;
525
+ details: Record<string, string>;
526
+ target: string;
527
+ hostValue: boolean;
528
+ }
529
+
530
+ /**
531
+ * A query that runs: its id and its outcome
532
+ */
533
+ export interface QueryTicket {
534
+ queryId: number;
535
+ done: Promise<QueryRunOutcome>;
536
+ }
537
+
538
+ /**
539
+ * A query that the runtime runs
540
+ */
541
+ export interface QueryArgs {
542
+ /**
543
+ * The text of the query as the history shows it
544
+ */
545
+ text: string;
546
+ metadata: QueryMetadataView;
547
+ /**
548
+ * The trace and the span of the log messages of the query
549
+ */
550
+ traceId: number;
551
+ spanId?: number;
552
+ /**
553
+ * What the executor does around the query
554
+ */
555
+ options?: QueryOptions;
556
+ }
557
+
558
+ /**
559
+ * The kind of the failure of a query
560
+ */
561
+ export type QueryRunFailureKind = "error" | "cancelled" | "cacheMiss" | "processing";
562
+
563
+ /**
564
+ * What the caller of a query hears while it runs: the timings and the result before its analysis
565
+ */
566
+ export type QueryCallerEvent = { type: "timing"; label: string; elapsedMs: number } | { type: "resultsReady" };
567
+
568
+ /**
569
+ * How a query ended for its caller: resolved with the result table, or rejected with the failure and what the host
570
+ * failed with
571
+ */
572
+ export type QueryRunOutcome = { status: "resolved"; hasResult: boolean; table: unknown } | { status: "rejected"; failure: QueryRunFailure; value: unknown };
573
+
574
+ /**
575
+ * The storage of the runtime: what holds the writes, the writes that failed, and the questions about workbook folders
576
+ * that changed outside the app. The workbooks whose writes a change outside the app holds are the holds with the
577
+ * reason `externalChange`.
578
+ */
579
+ export interface StorageView {
580
+ /**
581
+ * The holds of the writer (no workbook) and of the workbooks, with their reasons
582
+ */
583
+ holds: StorageHoldView[];
584
+ /**
585
+ * The writes that failed, with their last errors
586
+ */
587
+ failedWrites: FailedStorageWriteView[];
588
+ /**
589
+ * The workbooks whose scripts changed on disk, the app asks the user whether to reload them
590
+ * (`answerExternalChange`)
591
+ */
592
+ externalChanges: ExternalChangeView[];
593
+ }
594
+
595
+ /**
596
+ * A question about a workbook folder whose scripts changed outside the app
597
+ */
598
+ export interface ExternalChangeView {
599
+ workbookId: string;
600
+ /**
601
+ * The number of the question, the answer names it. A second question about the same change has a new number.
602
+ */
603
+ prompt: number;
604
+ /**
605
+ * Does the app hold writes of the scripts that a reload discards?
606
+ */
607
+ pendingWrites: boolean;
608
+ }
609
+
610
+ /**
611
+ * A command of the storage writer that waits for writes. The commands that change the writer right away are methods
612
+ * of the runtime (`storageHold`, `storageRelease`, `storageDiscardWrites`).
613
+ */
614
+ export type StorageCommand = { kind: "flush"; closing?: boolean } | { kind: "settle" } | { kind: "flushWorkbook"; workbookId: string } | { kind: "deleteWorkbook"; workbookId: string } | { kind: "handOver" };
615
+
163
616
 
164
617
  /** The I/O of the runtime, one object of the host (docs/design/dashql_runtime.md). The members return promises where the runtime awaits them. */
165
618
  export interface RuntimePlatform {
@@ -533,95 +986,167 @@ export interface ComputePlatform {
533
986
 
534
987
 
535
988
  /**
536
- * A cached result that the query result cache read into a table of the handle table
989
+ * A cached result that the query result cache read into a table of the handle table
990
+ */
991
+ export interface RuntimeCachedTable {
992
+ table: number;
993
+ rows: number;
994
+ columns: number;
995
+ }
996
+
997
+ /**
998
+ * Where a query of a channel of the host runs, as the platform describes it: the channel of the host. The connections
999
+ * own the channels that the module speaks itself (Trino, Hyper over HTTP, the Hyper of Salesforce), the platform never
1000
+ * describes them.
1001
+ */
1002
+ export type RuntimeChannelTarget = { type: "host" };
1003
+
1004
+ /**
1005
+ * An effect of the runtime on a handle of the host, applied by the store when it takes the changes
1006
+ */
1007
+ export type HandleEffect = { type: "release"; handle: number } | { type: "close"; handle: number } | { type: "abort"; handle: number; reason: string };
1008
+
1009
+ /**
1010
+ * An event of a script of a run
1011
+ */
1012
+ export type WorkbookScriptRunEvent = { type: "planned"; follows: string[] } | { type: "cached"; key: string; queryId: number } | { type: "skipped"; reason: string } | { type: "started" } | { type: "done"; key: string | null; queryId: number | null } | { type: "failed"; failure: WorkbookRunFailure } | { type: "cancelled" };
1013
+
1014
+ /**
1015
+ * How a run ended
1016
+ */
1017
+ export interface RunOutcome {
1018
+ /**
1019
+ * Why the run didn't start, e.g. another run holds the workbook, null for a run that started
1020
+ */
1021
+ refused: string | null;
1022
+ /**
1023
+ * The queries of the last outputs of the scripts in feed order
1024
+ */
1025
+ outputs: (number | null)[];
1026
+ failure: WorkbookRunFailure | null;
1027
+ /**
1028
+ * Did the run hand a statement to the executor?
1029
+ */
1030
+ launched: boolean;
1031
+ }
1032
+
1033
+ /**
1034
+ * The options of a run of a script
537
1035
  */
538
- export interface RuntimeCachedTable {
539
- table: number;
540
- rows: number;
541
- columns: number;
1036
+ export interface RunScriptOptions {
1037
+ /**
1038
+ * Read no cached results, neither of the script nor of the scripts it references
1039
+ */
1040
+ refresh?: boolean;
542
1041
  }
543
1042
 
544
1043
  /**
545
- * Where a query of a channel of the host runs, as the platform describes it: the channel of the host. The connections
546
- * own the channels that the module speaks itself (Trino, Hyper over HTTP, the Hyper of Salesforce), the platform never
547
- * describes them.
1044
+ * The state of a run of a workbook
548
1045
  */
549
- export type RuntimeChannelTarget = { type: "host" };
1046
+ export interface WorkbookRunState {
1047
+ phase: WorkbookRunPhase;
1048
+ totalScripts: number;
1049
+ completedScripts: number;
1050
+ /**
1051
+ * The planned statements that run
1052
+ */
1053
+ totalStatements: number;
1054
+ completedStatements: number;
1055
+ /**
1056
+ * The script of the statement that started last
1057
+ */
1058
+ activeFileName: string | null;
1059
+ activeStatementIndex: number | null;
1060
+ activeStatementCount: number | null;
1061
+ error: string | null;
1062
+ /**
1063
+ * The scripts that the run left out: their connection can't run or could not be set up, they have no cached
1064
+ * result or follow a script that runs on such a connection
1065
+ */
1066
+ skippedScripts: number;
1067
+ skippedFiles: string[];
1068
+ }
550
1069
 
551
1070
  /**
552
- * An effect of the runtime on a handle of the host, applied by the store when it takes the changes
1071
+ * The runs of a workbook, the slice `run` of the runtime
553
1072
  */
554
- export type HandleEffect = { type: "release"; handle: number } | { type: "close"; handle: number } | { type: "abort"; handle: number; reason: string };
1073
+ export interface WorkbookRunView {
1074
+ workbookId: string;
1075
+ /**
1076
+ * The run that holds the workbook, null while none does. The workbook starts no other run then.
1077
+ */
1078
+ held: WorkbookRunKind | null;
1079
+ /**
1080
+ * The state of the last run of the whole workbook, it stays once the run ended
1081
+ */
1082
+ state: WorkbookRunState | null;
1083
+ /**
1084
+ * The inputs whose change waits for the workbook
1085
+ */
1086
+ pendingInputs: string[];
1087
+ }
555
1088
 
556
1089
  /**
557
- * A hold of the writer (no workbook) or of a workbook
1090
+ * The phase of a run
558
1091
  */
559
- export interface StorageHoldView {
560
- workbookId: string | null;
561
- reason: StorageHoldReason;
562
- count: number;
563
- }
1092
+ export type WorkbookRunPhase = "planning" | "running" | "stopping" | "succeeded" | "failed" | "cancelled";
564
1093
 
565
1094
  /**
566
- * A write that failed. One that failed for a moment runs again after a backoff, one whose target is gone stops
567
- * (`permanent`) until a newer write of its key or until the app discards it (`storageDiscardWrites`).
1095
+ * The failure of a run or of a script, what the platform failed with goes next to it
568
1096
  */
569
- export interface FailedStorageWriteView {
570
- key: string;
1097
+ export interface WorkbookRunFailure {
1098
+ kind: WorkbookRunFailureKind;
1099
+ message: string;
571
1100
  /**
572
- * The workbook of the key, null for the files of the app
1101
+ * The details of the error of a failed statement, e.g. what Trino said
573
1102
  */
574
- workbookId: string | null;
1103
+ details: Record<string, string>;
575
1104
  /**
576
- * The last error
1105
+ * The target of the log messages of the error of a failed statement
577
1106
  */
578
- error: string;
1107
+ target: string | null;
579
1108
  /**
580
- * The failed attempts in a row
1109
+ * The query of the statement that failed, null for a failure of no statement
581
1110
  */
582
- attempts: number;
1111
+ queryId: number | null;
583
1112
  /**
584
- * The target of the write is gone, e.g. a moved workbook folder: the writer stopped retrying it
1113
+ * Did the platform fail with a value? It goes next to the failure.
585
1114
  */
586
- permanent: boolean;
1115
+ hostValue: boolean;
587
1116
  }
588
1117
 
589
1118
  /**
590
- * The statistics of a key: the scheduled writes of the key and the writes of its file
1119
+ * The options of a run of the scripts of a workbook
591
1120
  */
592
- export interface StorageWriteStatistics {
593
- scheduledWrites: number;
594
- writes: number;
595
- writtenBytes: number;
596
- writeTimeMs: number;
1121
+ export interface RunWorkbookOptions {
597
1122
  /**
598
- * The time of the last write in milliseconds since the epoch
1123
+ * Run the scripts that a change of these inputs affects. A run that holds the workbook stops, the run starts once
1124
+ * the workbook is free, with the inputs of every change since.
599
1125
  */
600
- lastWriteMs: number | null;
1126
+ inputs?: string[];
1127
+ /**
1128
+ * Run these scripts with what they need, by their indexes in feed order, every script without
1129
+ */
1130
+ targets?: number[];
1131
+ /**
1132
+ * Read no cached results: the scripts run, the results with reusable keys become the newest files of their keys
1133
+ */
1134
+ refresh?: boolean;
1135
+ /**
1136
+ * Analyze the results of the outputs on the compute database, true by default. The command line tool prints them.
1137
+ */
1138
+ analyze?: boolean;
601
1139
  }
602
1140
 
603
1141
  /**
604
- * The outcome of a write. A failed write carries what the host failed with, a patch of a workbook file that is not
605
- * available names the workbook.
606
- */
607
- export type StorageWriteOutcome = { status: "written" } | { status: "superseded" } | { status: "cancelled" } | { status: "deferred" } | { status: "failed"; error: unknown; unavailableWorkbook?: string };
608
-
609
- /**
610
- * The statistics of the writes of a key, with the key within its workbook for display
1142
+ * The run that holds a workbook: a run of the whole workbook or of one of its scripts
611
1143
  */
612
- export interface StorageKeyStatistics {
613
- key: string;
614
- /**
615
- * The key without the prefix of its workbook, e.g. `scripts/a.sql:delete`
616
- */
617
- label: string;
618
- statistics: StorageWriteStatistics;
619
- }
1144
+ export type WorkbookRunKind = "workbook" | "script";
620
1145
 
621
1146
  /**
622
- * Why the writes of the writer or of a workbook are held
1147
+ * Why a run failed
623
1148
  */
624
- export type StorageHoldReason = "externalChange" | "reload" | "import" | "handover" | "pause";
1149
+ export type WorkbookRunFailureKind = "plan" | "cancelled" | "error";
625
1150
 
626
1151
  /**
627
1152
  * A workbook of the list of the workbooks
@@ -946,1636 +1471,1196 @@ export interface WorkbookDataFile {
946
1471
  name: string;
947
1472
  sizeBytes: number;
948
1473
  /**
949
- * The time of the last modification, 0 without one
950
- */
951
- mtimeMs?: number;
952
- }
953
-
954
- /**
955
- * The update of an editor event for the editor, with its key (`WorkbookScriptView.editorUpdateKey`)
956
- */
957
- export interface EditorEventOutcome {
958
- update: FlatBuffer<buffers_editor.EditorUpdate>;
959
- /**
960
- * Names the update, the next event of the editor names it as the update that the editor holds
961
- */
962
- key: string;
963
- }
964
-
965
- /**
966
- * An event of a script of a run
967
- */
968
- export type WorkbookScriptRunEvent = { type: "planned"; follows: string[] } | { type: "cached"; key: string; queryId: number } | { type: "skipped"; reason: string } | { type: "started" } | { type: "done"; key: string | null; queryId: number | null } | { type: "failed"; failure: WorkbookRunFailure } | { type: "cancelled" };
969
-
970
- /**
971
- * How a run ended
972
- */
973
- export interface RunOutcome {
974
- /**
975
- * Why the run didn't start, e.g. another run holds the workbook, null for a run that started
976
- */
977
- refused: string | null;
978
- /**
979
- * The queries of the last outputs of the scripts in feed order
980
- */
981
- outputs: (number | null)[];
982
- failure: WorkbookRunFailure | null;
983
- /**
984
- * Did the run hand a statement to the executor?
985
- */
986
- launched: boolean;
987
- }
988
-
989
- /**
990
- * The options of a run of a script
991
- */
992
- export interface RunScriptOptions {
993
- /**
994
- * Read no cached results, neither of the script nor of the scripts it references
995
- */
996
- refresh?: boolean;
997
- }
998
-
999
- /**
1000
- * The state of a run of a workbook
1001
- */
1002
- export interface WorkbookRunState {
1003
- phase: WorkbookRunPhase;
1004
- totalScripts: number;
1005
- completedScripts: number;
1006
- /**
1007
- * The planned statements that run
1008
- */
1009
- totalStatements: number;
1010
- completedStatements: number;
1011
- /**
1012
- * The script of the statement that started last
1013
- */
1014
- activeFileName: string | null;
1015
- activeStatementIndex: number | null;
1016
- activeStatementCount: number | null;
1017
- error: string | null;
1018
- /**
1019
- * The scripts that the run left out: their connection can't run or could not be set up, they have no cached
1020
- * result or follow a script that runs on such a connection
1021
- */
1022
- skippedScripts: number;
1023
- skippedFiles: string[];
1024
- }
1025
-
1026
- /**
1027
- * The runs of a workbook, the slice `run` of the runtime
1028
- */
1029
- export interface WorkbookRunView {
1030
- workbookId: string;
1031
- /**
1032
- * The run that holds the workbook, null while none does. The workbook starts no other run then.
1033
- */
1034
- held: WorkbookRunKind | null;
1035
- /**
1036
- * The state of the last run of the whole workbook, it stays once the run ended
1037
- */
1038
- state: WorkbookRunState | null;
1039
- /**
1040
- * The inputs whose change waits for the workbook
1041
- */
1042
- pendingInputs: string[];
1043
- }
1044
-
1045
- /**
1046
- * The phase of a run
1047
- */
1048
- export type WorkbookRunPhase = "planning" | "running" | "stopping" | "succeeded" | "failed" | "cancelled";
1049
-
1050
- /**
1051
- * The failure of a run or of a script, what the platform failed with goes next to it
1052
- */
1053
- export interface WorkbookRunFailure {
1054
- kind: WorkbookRunFailureKind;
1055
- message: string;
1056
- /**
1057
- * The details of the error of a failed statement, e.g. what Trino said
1058
- */
1059
- details: Record<string, string>;
1060
- /**
1061
- * The target of the log messages of the error of a failed statement
1062
- */
1063
- target: string | null;
1064
- /**
1065
- * The query of the statement that failed, null for a failure of no statement
1066
- */
1067
- queryId: number | null;
1068
- /**
1069
- * Did the platform fail with a value? It goes next to the failure.
1474
+ * The time of the last modification, 0 without one
1070
1475
  */
1071
- hostValue: boolean;
1476
+ mtimeMs?: number;
1072
1477
  }
1073
1478
 
1074
1479
  /**
1075
- * The options of a run of the scripts of a workbook
1480
+ * The update of an editor event for the editor, with its key (`WorkbookScriptView.editorUpdateKey`)
1076
1481
  */
1077
- export interface RunWorkbookOptions {
1078
- /**
1079
- * Run the scripts that a change of these inputs affects. A run that holds the workbook stops, the run starts once
1080
- * the workbook is free, with the inputs of every change since.
1081
- */
1082
- inputs?: string[];
1083
- /**
1084
- * Run these scripts with what they need, by their indexes in feed order, every script without
1085
- */
1086
- targets?: number[];
1087
- /**
1088
- * Read no cached results: the scripts run, the results with reusable keys become the newest files of their keys
1089
- */
1090
- refresh?: boolean;
1482
+ export interface EditorEventOutcome {
1483
+ update: FlatBuffer<buffers_editor.EditorUpdate>;
1091
1484
  /**
1092
- * Analyze the results of the outputs on the compute database, true by default. The command line tool prints them.
1485
+ * Names the update, the next event of the editor names it as the update that the editor holds
1093
1486
  */
1094
- analyze?: boolean;
1487
+ key: string;
1095
1488
  }
1096
1489
 
1097
1490
  /**
1098
- * The run that holds a workbook: a run of the whole workbook or of one of its scripts
1491
+ * What a restore restored: the connections and the workbooks that the runtime took, in order, the workbooks that were
1492
+ * refused a load and the progress
1099
1493
  */
1100
- export type WorkbookRunKind = "workbook" | "script";
1494
+ export interface RestoreOutcome {
1495
+ connectionIds: string[];
1496
+ workbookIds: string[];
1497
+ invalidWorkbooks: RestoredInvalidWorkbook[];
1498
+ progress: RestoreProgress;
1499
+ }
1101
1500
 
1102
1501
  /**
1103
- * Why a run failed
1502
+ * A counter of the progress of a step of a restore
1104
1503
  */
1105
- export type WorkbookRunFailureKind = "plan" | "cancelled" | "error";
1504
+ export interface RestoreProgressCounter {
1505
+ started: number;
1506
+ succeeded: number;
1507
+ skipped: number;
1508
+ failed: number;
1509
+ /**
1510
+ * Null until the total is known
1511
+ */
1512
+ total: number | null;
1513
+ }
1106
1514
 
1107
1515
  /**
1108
- * The versions of the storage format of the module: of the storage root and of workbook files
1516
+ * A script file of a workbook
1109
1517
  */
1110
- export interface StorageVersions {
1111
- /**
1112
- * The storage version of the app, `storageVersion` of the manifest
1113
- */
1114
- storageVersion: number;
1115
- /**
1116
- * The workbook format version of the app, `formatVersion` of a workbook file
1117
- */
1118
- formatVersion: number;
1518
+ export interface RestoreScriptFile {
1519
+ name: string;
1520
+ sql: string;
1119
1521
  }
1120
1522
 
1121
1523
  /**
1122
- * What a migration of the storage changed, with the versions it migrated to
1524
+ * The progress of a restore
1123
1525
  */
1124
- export interface StorageMigrationOutcome {
1125
- /**
1126
- * The storage steps that ran
1127
- */
1128
- steps: number;
1129
- /**
1130
- * The workbook folders that were brought to the current workbook format
1131
- */
1132
- workbooks: number;
1526
+ export interface RestoreProgress {
1527
+ restoreConnections: RestoreProgressCounter;
1528
+ restoreCatalogs: RestoreProgressCounter;
1529
+ restoreWorkbookScripts: RestoreProgressCounter;
1530
+ }
1531
+
1532
+ /**
1533
+ * A workbook that failed its validation or couldn't be restored
1534
+ */
1535
+ export interface RestoredInvalidWorkbook {
1536
+ workbookId: string;
1537
+ title: string;
1538
+ connectorType: ConnectorType | null;
1133
1539
  /**
1134
- * The storage version of the app
1540
+ * The code of the validation error, e.g. `unsupported_format_version`
1135
1541
  */
1136
- storageVersion: number;
1542
+ error: string;
1137
1543
  /**
1138
- * The workbook format version of the app
1544
+ * A short explanation of the error for the user
1139
1545
  */
1140
- formatVersion: number;
1546
+ description: string;
1141
1547
  }
1142
1548
 
1143
-
1144
- /** A file to attach to a workbook, with the name it was dropped with */
1145
- export interface AttachedFile {
1146
- name: string;
1147
- file: Blob | Uint8Array;
1549
+ /**
1550
+ * A hold of the writer (no workbook) or of a workbook
1551
+ */
1552
+ export interface StorageHoldView {
1553
+ workbookId: string | null;
1554
+ reason: StorageHoldReason;
1555
+ count: number;
1148
1556
  }
1149
1557
 
1150
-
1151
1558
  /**
1152
- * What an attach did
1559
+ * A write that failed. One that failed for a moment runs again after a backoff, one whose target is gone stops
1560
+ * (`permanent`) until a newer write of its key or until the app discards it (`storageDiscardWrites`).
1153
1561
  */
1154
- export interface AttachFilesOutcome {
1562
+ export interface FailedStorageWriteView {
1563
+ key: string;
1155
1564
  /**
1156
- * The attachments that were written or wait for a hold of the workbook, in the order of the files
1565
+ * The workbook of the key, null for the files of the app
1157
1566
  */
1158
- attached: AttachedFileName[];
1567
+ workbookId: string | null;
1159
1568
  /**
1160
- * The files that are no attachments (Parquet files only), by their names
1569
+ * The last error
1161
1570
  */
1162
- refused: string[];
1163
- }
1164
-
1165
- /**
1166
- * A file that was attached, with the name it got
1167
- */
1168
- export interface AttachedFileName {
1571
+ error: string;
1169
1572
  /**
1170
- * The name the file was dropped with
1573
+ * The failed attempts in a row
1171
1574
  */
1172
- name: string;
1575
+ attempts: number;
1173
1576
  /**
1174
- * The file name of the attachment, its table parameter takes no name of a script or another attachment
1577
+ * The target of the write is gone, e.g. a moved workbook folder: the writer stopped retrying it
1175
1578
  */
1176
- fileName: string;
1177
- }
1178
-
1179
-
1180
- /** The slices of the runtime by kind: the id of a slice, its view, and the keys of the payloads of its view that the host holds */
1181
- export interface RuntimeViews {
1182
- computation: { id: number; view: ComputationView; known: undefined };
1183
- connectionList: { id: 'root'; view: ConnectionListView; known: undefined };
1184
- connection: { id: string; view: ConnectionView; known: undefined };
1185
- query: { id: number; view: QueryView; known: (QueryProfileKeys | null)[] };
1186
- workbookList: { id: 'root'; view: WorkbookListView; known: undefined };
1187
- workbook: { id: string; view: WorkbookView; known: undefined };
1188
- script: { id: number; view: WorkbookScriptView; known: (WorkbookScriptKeys | null)[] };
1189
- workbookDerived: { id: string; view: WorkbookDerivedView; known: undefined };
1190
- storage: { id: 'root'; view: StorageView; known: undefined };
1191
- run: { id: string; view: WorkbookRunView; known: undefined };
1192
- }
1193
- /** A kind of slices of the runtime */
1194
- export type ViewKind = keyof RuntimeViews;
1195
- /** The id of a slice of a kind */
1196
- export type ViewId<K extends ViewKind> = RuntimeViews[K]['id'];
1197
- /** The view of a slice of a kind */
1198
- export type ViewOf<K extends ViewKind> = RuntimeViews[K]['view'];
1199
- /** The keys of the payloads that the host holds, they don't cross again */
1200
- export type KnownKeys<K extends ViewKind> = RuntimeViews[K]['known'];
1201
- /** The read of a slice that a task of the runtime holds: it moves with the next changes, the host keeps its view */
1202
- export type BusyView = 'busy';
1203
- export interface Runtime {
1204
- /** The views of the slices of a kind, null for a slice that is gone, `'busy'` for one that a task holds. One crossing per kind and flush. */
1205
- views<K extends ViewKind>(kind: K, ids: ViewId<K>[], known?: KnownKeys<K>): (ViewOf<K> | BusyView | null)[];
1579
+ permanent: boolean;
1206
1580
  }
1207
1581
 
1208
-
1209
1582
  /**
1210
- * The slice that an action changes
1583
+ * The statistics of a key: the scheduled writes of the key and the writes of its file
1211
1584
  */
1212
- export type Target = { computation: number } | { connection: string } | { workbook: string } | "app";
1585
+ export interface StorageWriteStatistics {
1586
+ scheduledWrites: number;
1587
+ writes: number;
1588
+ writtenBytes: number;
1589
+ writeTimeMs: number;
1590
+ /**
1591
+ * The time of the last write in milliseconds since the epoch
1592
+ */
1593
+ lastWriteMs: number | null;
1594
+ }
1213
1595
 
1214
1596
  /**
1215
- * The actions of the runtime. An action changes the state in the call and returns its outcome; a failed action leaves
1216
- * the state as it was.
1597
+ * The outcome of a write. A failed write carries what the host failed with, a patch of a workbook file that is not
1598
+ * available names the workbook.
1217
1599
  */
1218
- export type RuntimeAction = { kind: "deleteComputation" } | { kind: "orderBy"; value: { constraints: ComputationOrderBy[] } } | { kind: "histogramFilter"; value: { columnGroup: number; selection: [number, number] | null } } | { kind: "mostFrequentValueFilter"; value: { columnGroup: number; valueId: number | null } } | { kind: "clearCrossFilters" } | { kind: "setResultSearchPattern"; value: { search: ComputationSearchKind; pattern: string } } | { kind: "requestFilteredColumnAggregation"; value: { columnGroup: number } } | { kind: "createConnection"; value: { connectionId?: string; connectorType: ConnectorType; setupParams?: JsonParams; active?: boolean; params?: JsonParams; paramsDraft?: JsonParams; name?: string; cacheQueryResults?: boolean } } | { kind: "createWorkbook"; value: { workbookId?: string; connectionId: string; name?: string; ephemeral?: boolean; originalFileName?: string } } | { kind: "deleteWorkbook"; value: { workbookId: string } } | { kind: "createScript"; value: { index?: number; text?: string; base: string; connectionId?: string } } | { kind: "deleteScript"; value: { fileName: string } } | { kind: "renameScript"; value: { fileName: string; newName: string } } | { kind: "reorderScripts"; value: { order: string[] } } | { kind: "setScriptText"; value: { scriptKey: number; text: string; withDiff?: boolean } } | { kind: "acceptPendingDiff"; value: { scriptKey: number } } | { kind: "rejectPendingDiff"; value: { scriptKey: number } } | { kind: "setScriptVisSpec"; value: { scriptKey: number; spec: string } } | { kind: "setWorkbookInput"; value: { name: string; literal: string; scriptKeys: number[] } } | { kind: "analyzeOutdatedScript"; value: { scriptKey: number } } | { kind: "showScript"; value: { scriptKey: number; selected: boolean } } | { kind: "hideScript"; value: { scriptKey: number; selected: boolean } } | { kind: "renameWorkbook"; value: { name?: string } } | { kind: "setScriptConnection"; value: { fileName: string; connectionId: string } } | { kind: "setPendingConnection"; value: { connectionId: string } } | { kind: "replaceConnection"; value: { from: string; into: string } } | { kind: "detachConnection"; value: { from: string; into: string } } | { kind: "setWorkbookAttachments"; value: { files: WorkbookDataFile[] } } | { kind: "setCloudLink"; value: { link?: JsonValue } } | { kind: "setDraft"; value: { params: JsonParams } } | { kind: "discardDraft" } | { kind: "rename"; value: { name: string } } | { kind: "setQueryResultCaching"; value: { caching: boolean } } | { kind: "deleteConnection" } | { kind: "resetConnection" } | { kind: "relationsTouched"; value: { names: ConnectionTableName[] } } | { kind: "queryCacheDeleted"; value: { queryId: number } };
1600
+ export type StorageWriteOutcome = { status: "written" } | { status: "superseded" } | { status: "cancelled" } | { status: "deferred" } | { status: "failed"; error: unknown; unavailableWorkbook?: string };
1219
1601
 
1220
1602
  /**
1221
- * The id of a slice or of what an action created: a number or a string
1603
+ * The statistics of the writes of a key, with the key within its workbook for display
1222
1604
  */
1223
- export type SliceId = number | string;
1605
+ export interface StorageKeyStatistics {
1606
+ key: string;
1607
+ /**
1608
+ * The key without the prefix of its workbook, e.g. `scripts/a.sql:delete`
1609
+ */
1610
+ label: string;
1611
+ statistics: StorageWriteStatistics;
1612
+ }
1224
1613
 
1225
1614
  /**
1226
- * A slice that changed since the host took the changes, its revision is null if it went
1615
+ * Why the writes of the writer or of a workbook are held
1227
1616
  */
1228
- export interface SliceChange {
1229
- kind: ViewKind;
1230
- id: SliceId;
1231
- revision: number | null;
1232
- }
1617
+ export type StorageHoldReason = "externalChange" | "reload" | "import" | "handover" | "pause";
1233
1618
 
1234
1619
  /**
1235
- * The changes since the host took them last: the changed slices and the effects on handles, in order
1620
+ * The rows that a data search matched with their matching columns, the table by its handle
1236
1621
  */
1237
- export interface ChangeSet {
1238
- changes: SliceChange[];
1239
- effects: HandleEffect[];
1622
+ export interface ComputationDataSearchTable {
1623
+ dataTable: number;
1624
+ rows: number;
1625
+ dataFrame: number;
1626
+ inputRowNumberColumnName: string;
1627
+ version: ComputationVersionValue;
1628
+ requestId: number;
1240
1629
  }
1241
1630
 
1242
1631
  /**
1243
- * What a dispatch did
1632
+ * A key of an ordering, ascending and nulls last without
1244
1633
  */
1245
- export interface DispatchOutcome {
1246
- /**
1247
- * Was the action applied? A failed action leaves the state as it was.
1248
- */
1249
- ok: boolean;
1250
- /**
1251
- * Did the action change the state?
1252
- */
1253
- changed: boolean;
1254
- /**
1255
- * The error of a failed action
1256
- */
1257
- error: string | null;
1258
- /**
1259
- * What the action created: the id of a connection or of a query
1260
- */
1261
- id: SliceId | null;
1634
+ export interface ComputationOrderBy {
1635
+ field: string;
1636
+ ascending?: boolean;
1637
+ nullsFirst?: boolean;
1262
1638
  }
1263
1639
 
1264
1640
  /**
1265
- * The storage of the runtime: what holds the writes, the writes that failed, and the questions about workbook folders
1266
- * that changed outside the app. The workbooks whose writes a change outside the app holds are the holds with the
1267
- * reason `externalChange`.
1641
+ * The version of a computation: the data changes with a new data frame, the filter with every scheduled filtering
1268
1642
  */
1269
- export interface StorageView {
1270
- /**
1271
- * The holds of the writer (no workbook) and of the workbooks, with their reasons
1272
- */
1273
- holds: StorageHoldView[];
1274
- /**
1275
- * The writes that failed, with their last errors
1276
- */
1277
- failedWrites: FailedStorageWriteView[];
1278
- /**
1279
- * The workbooks whose scripts changed on disk, the app asks the user whether to reload them
1280
- * (`answerExternalChange`)
1281
- */
1282
- externalChanges: ExternalChangeView[];
1643
+ export interface ComputationVersionValue {
1644
+ data: number;
1645
+ filter: number;
1283
1646
  }
1284
1647
 
1285
1648
  /**
1286
- * A question about a workbook folder whose scripts changed outside the app
1649
+ * The context of a call of the compute platform: the computation, the title of its task in the query history, the
1650
+ * connection and the client context of the computation, and the run that `cancel` aborts
1287
1651
  */
1288
- export interface ExternalChangeView {
1289
- workbookId: string;
1290
- /**
1291
- * The number of the question, the answer names it. A second question about the same change has a new number.
1292
- */
1293
- prompt: number;
1652
+ export interface ComputeCallContext {
1653
+ tableId: number;
1654
+ title: string;
1655
+ connectionId: string | null;
1294
1656
  /**
1295
- * Does the app hold writes of the scripts that a reload discards?
1657
+ * The client context of the queries of a computation without a connection, opaque JSON
1296
1658
  */
1297
- pendingWrites: boolean;
1659
+ clientContext: string | null;
1660
+ run: number;
1298
1661
  }
1299
1662
 
1300
1663
  /**
1301
- * A command of the storage writer that waits for writes. The commands that change the writer right away are methods
1302
- * of the runtime (`storageHold`, `storageRelease`, `storageDiscardWrites`).
1664
+ * The selection in the summary of a column group
1303
1665
  */
1304
- export type StorageCommand = { kind: "flush"; closing?: boolean } | { kind: "settle" } | { kind: "flushWorkbook"; workbookId: string } | { kind: "deleteWorkbook"; workbookId: string } | { kind: "handOver" };
1666
+ export type ComputationCrossFilter = { kind: "histogram"; column: number; selection: [number, number] } | { kind: "mostFrequent"; column: number; valueId: number };
1305
1667
 
1306
1668
  /**
1307
- * The database and schema of the relations that unqualified statements of a connection create or drop
1669
+ * A column of the grid of a result
1308
1670
  */
1309
- export interface ConnectionNameDefaults {
1310
- databaseName: string;
1311
- schemaName: string;
1312
- }
1671
+ export type ComputationColumnGroup = { type: "ROWNUMBER"; value: { rowNumberFieldName: string } } | { type: "SKIPPED"; value: { inputFieldName: string; inputFieldType: string; inputFieldNullable: boolean } } | { type: "ORDINAL"; value: ComputationValueColumn } | { type: "STRING"; value: ComputationValueColumn } | { type: "LIST"; value: ComputationValueColumn };
1313
1672
 
1314
1673
  /**
1315
- * Opaque JSON params: the params of a connection with one field named after the connector (`{ trino: {...} }`), or
1316
- * the params of a connector without that field
1674
+ * The fields of the table aggregation with the statistics of a column
1317
1675
  */
1318
- export type JsonParams = Record<string, unknown>;
1676
+ export interface ComputationStatsFields {
1677
+ countFieldName: string;
1678
+ distinctCountFieldName: string | null;
1679
+ minAggregateFieldName: string | null;
1680
+ maxAggregateFieldName: string | null;
1681
+ }
1319
1682
 
1320
1683
  /**
1321
- * The catalog updates of a connection
1684
+ * The table and the data frame of a summary
1322
1685
  */
1323
- export interface ConnectionCatalogUpdates {
1324
- /**
1325
- * The running updates in the order of their ids
1326
- */
1327
- tasksRunning: ConnectionCatalogUpdateTask[];
1328
- /**
1329
- * The finished updates in the order of their ids
1330
- */
1331
- tasksFinished: ConnectionCatalogUpdateTask[];
1332
- /**
1333
- * Does the catalog describe the connection?
1334
- */
1335
- described: boolean;
1336
- /**
1337
- * The running or most recently started full refresh
1338
- */
1339
- currentFullRefresh: number | null;
1340
- /**
1341
- * The relations that executed statements touched and that no update has answered yet
1342
- */
1343
- touchedRelations: ConnectionRelationName[];
1344
- /**
1345
- * The updates in a row that failed to answer them
1346
- */
1347
- touchedFailures: number;
1348
- /**
1349
- * Might the catalog miss what executed statements did, since asking the connection failed too often?
1350
- */
1351
- outOfDate: boolean;
1352
- /**
1353
- * Is the current full refresh running?
1354
- */
1355
- refreshRunning: boolean;
1686
+ export interface ComputationColumnSummary {
1687
+ table: number;
1688
+ dataFrame: number;
1689
+ analysis: ComputationSummaryAnalysis | null;
1356
1690
  }
1357
1691
 
1358
1692
  /**
1359
- * A catalog update
1693
+ * The rows that pass the filters, the table by its handle
1360
1694
  */
1361
- export interface ConnectionCatalogUpdateTask {
1362
- taskId: number;
1363
- variant: CatalogUpdateVariant;
1364
- status: CatalogUpdateTaskStatus;
1365
- queries: number[];
1366
- error: ConnectionError | null;
1367
- startedAt: number | null;
1368
- finishedAt: number | null;
1369
- touchedRelations: ConnectionRelationName[];
1370
- /**
1371
- * The handle of the record of the update at the host: its cancellation and its error
1372
- */
1373
- handle: number | null;
1695
+ export interface ComputationFilterTable {
1696
+ dataTable: number;
1697
+ rows: number;
1698
+ dataFrame: number;
1699
+ inputRowNumberColumnName: string;
1700
+ version: ComputationVersionValue;
1374
1701
  }
1375
1702
 
1376
1703
  /**
1377
- * The OAuth flow of a Trino connection, the steps that didn't happen yet are null. The PKCE verifier, the code and
1378
- * the token stay in the runtime.
1704
+ * The tasks that a computation tracks
1379
1705
  */
1380
- export interface ConnectionTrinoOAuthState {
1381
- /**
1382
- * Was the PKCE challenge generated?
1383
- */
1384
- pkceGenerated: boolean;
1385
- /**
1386
- * When the code arrived
1387
- */
1388
- authCodeReceivedAt: string | null;
1389
- accessToken: ConnectionTokenSummary | null;
1706
+ export interface ComputationTasks {
1707
+ tableAggregationTask: ComputationTrackedTask | null;
1708
+ systemColumnTask: ComputationTrackedTask | null;
1709
+ filteringTask: ComputationTrackedTask | null;
1710
+ orderingTask: ComputationTrackedTask | null;
1711
+ dataSearchTask: ComputationTrackedTask | null;
1712
+ columnAggregationTasks: (ComputationTrackedTask | null)[];
1713
+ filteredColumnAggregationTasks: (ComputationTrackedTask | null)[];
1390
1714
  }
1391
1715
 
1392
1716
  /**
1393
- * The details that only one connector keeps, Database.com has the ones of Salesforce
1717
+ * What is searched, the columns by their names or the data
1394
1718
  */
1395
- export type ConnectionConnectorDetails = { kind: "hyper" } | { kind: "trino"; schemaResolutionError: ConnectionError | null; oauthState: ConnectionTrinoOAuthState | null } | { kind: "salesforce"; setupError: ConnectionError | null; oauthState: ConnectionSalesforceOAuthState | null };
1719
+ export type ComputationSearchKind = "columns" | "data";
1396
1720
 
1397
1721
  /**
1398
- * The state of saving a connection: whether it saves and the outcome of the last save
1722
+ * The summary of a column over the rows that the filters and the data search select
1399
1723
  */
1400
- export interface ConnectionSaveView {
1401
- /**
1402
- * Is the connection being saved?
1403
- */
1404
- saving: boolean;
1405
- /**
1406
- * The outcome of the last save, null before one
1407
- */
1408
- outcome: ConnectionSaveOutcome | null;
1724
+ export interface ComputationFilteredAggregate {
1725
+ aggregate: ComputationColumnAggregate;
1726
+ filterVersion: ComputationVersionValue;
1727
+ dataSearchRequestId: number | null;
1409
1728
  }
1410
1729
 
1411
1730
  /**
1412
- * The parameters of the OAuth flow of a Salesforce connection
1731
+ * The summary of a column: the table of the binned or the frequent values by its handle, with its analysis
1413
1732
  */
1414
- export interface ConnectionSalesforceOAuthParams {
1415
- instanceUrl: string;
1416
- appConsumerKey: string;
1417
- requestedAt: number;
1418
- expiresAt: number;
1419
- }
1733
+ export type ComputationColumnAggregate = ({ kind: "ordinal" } & ComputationColumnSummary) | ({ kind: "string" } & ComputationColumnSummary) | ({ kind: "list" } & ComputationColumnSummary) | { kind: "skipped" };
1420
1734
 
1421
1735
  /**
1422
- * A connection, the slice `connection` of the runtime. The field names are the ones the app reads. The queries are
1423
- * listed by id, each one is a slice `query` of its own: the connection changes when a query starts or finishes, not
1424
- * with the progress of a query.
1736
+ * What the lower bounds of the bins of a histogram are
1425
1737
  */
1426
- export interface ConnectionView {
1427
- connectionId: string;
1428
- /**
1429
- * Does the connection belong to a committed workbook or was it online once?
1430
- */
1431
- active: boolean;
1432
- connectionStatus: ConnectionStatus;
1433
- connectionHealth: ConnectionHealth;
1434
- connectorType: ConnectorType;
1435
- /**
1436
- * The name the user gave the connection, the label falls back to the connector without it
1437
- */
1438
- name: string | null;
1439
- /**
1440
- * Does the connection cache query results? Null for the default of the connector.
1441
- */
1442
- cacheQueryResults: boolean | null;
1443
- /**
1444
- * Does the connection cache query results, the choice of the user or the default of the connector?
1445
- */
1446
- cachesQueryResults: boolean;
1447
- /**
1448
- * Is the connection connected or connecting? An open connection keeps its protocol and can't be merged.
1449
- */
1450
- open: boolean;
1451
- /**
1452
- * The health as the app prints it, e.g. `Not Started`
1453
- */
1454
- healthLabel: string;
1455
- /**
1456
- * Can the queries of the connection read the data files that are attached to a workbook? The embedded Hyper reads
1457
- * them.
1458
- */
1459
- readsAttachments: boolean;
1460
- details: ConnectionDetailsView;
1461
- /**
1462
- * The params of the last successful setup, the initial ones until then
1463
- */
1464
- params: JsonParams;
1465
- /**
1466
- * The local settings of the form
1467
- */
1468
- paramsDraft: JsonParams | null;
1469
- /**
1470
- * The params of the running setup, never saved
1471
- */
1472
- setupAttemptParams: JsonParams | null;
1473
- /**
1474
- * The draft when the running setup started
1475
- */
1476
- setupAttemptDraft: JsonParams | null;
1477
- catalogUpdates: ConnectionCatalogUpdates;
1478
- /**
1479
- * The catalog entry of the relations of the connection
1480
- */
1481
- catalogRelationEntryId: number;
1482
- /**
1483
- * The database and schema of the relations that unqualified statements create or drop
1484
- */
1485
- catalogNameDefaults: ConnectionNameDefaults;
1486
- /**
1487
- * The script with the functions of the connection, null once it is deleted
1488
- */
1489
- functionScriptEntryId: number | null;
1490
- /**
1491
- * The metrics of the finished queries
1492
- */
1493
- metrics: QueryHistoryMetrics;
1494
- /**
1495
- * The active queries in the order they started
1496
- */
1497
- queriesActiveOrdered: number[];
1498
- /**
1499
- * The active queries that run on the connection, not the queries of the computations that it only tracks
1500
- */
1501
- queriesRunning: number;
1502
- /**
1503
- * The finished queries in the order they finished
1504
- */
1505
- queriesFinishedOrdered: number[];
1506
- /**
1507
- * Changes whenever a query starts or finishes
1508
- */
1509
- snapshotQueriesActiveFinished: number;
1510
- /**
1511
- * The workbooks that use the connection
1512
- */
1513
- workbooks: string[];
1514
- /**
1515
- * Saving the connection
1516
- */
1517
- save: ConnectionSaveView;
1738
+ export type ComputationBinBounds = "numbers" | "epochMillis";
1739
+
1740
+ /**
1741
+ * The value column of a column group, ordinal, string or list
1742
+ */
1743
+ export interface ComputationValueColumn {
1744
+ inputFieldName: string;
1518
1745
  /**
1519
- * Can the user refresh the catalog: is the connection online without a running full refresh?
1746
+ * The type of the field as the runtime names it, the app reads the Arrow type from the schema of the table
1520
1747
  */
1521
- canRefresh: boolean;
1748
+ inputFieldType: string;
1749
+ inputFieldNullable: boolean;
1750
+ statsFields: ComputationStatsFields | null;
1522
1751
  /**
1523
- * Does a setup of the connection run?
1752
+ * The bins of an ordinal column, null without
1524
1753
  */
1525
- setupRunning: boolean;
1754
+ binFieldName: string | null;
1526
1755
  /**
1527
- * Counts the announcements of a new catalog: the scripts that use the connection are analyzed again with it
1756
+ * The number of bins of an ordinal column, 0 without
1528
1757
  */
1529
- catalogVersion: number;
1758
+ binCount: number;
1530
1759
  /**
1531
- * The identity of the catalog of the connection: a connection that is created again under the same id has another
1532
- * catalog, a handle of the catalog (`Runtime.catalog`) goes with its identity
1760
+ * The value ids of a string or a list column, null without
1533
1761
  */
1534
- catalogId: number;
1762
+ valueIdFieldName: string | null;
1535
1763
  }
1536
1764
 
1537
1765
  /**
1538
- * The connections of the runtime, the slice `connectionList`
1766
+ * The numbers of the analysis of a summary that the runtime computed. The app formats the values of the tables: the
1767
+ * minimum and the maximum of the statistics, the lower bounds of the bins and the frequent values.
1539
1768
  */
1540
- export interface ConnectionListView {
1769
+ export type ComputationSummaryAnalysis = { kind: "ordinal"; totalCount: number; countNotNull: number; countNull: number; binCount: number; binValueCounts: number[]; binPercentages: number[]; binLowerBounds: (number | null)[]; binBounds: ComputationBinBounds } | { kind: "string"; totalCount: number; countNotNull: number; countNull: number; countDistinct: number; isUnique: boolean; frequentValueIds: number[]; frequentValueCounts: number[]; frequentValuePercentages: number[] };
1770
+
1771
+ /**
1772
+ * The view of the computation of a result table. The tables are handles of the platform, the data frames ids of
1773
+ * the compute database.
1774
+ */
1775
+ export interface ComputationView {
1776
+ tableId: number;
1777
+ revision: number;
1778
+ connectionId: string | null;
1541
1779
  /**
1542
- * The connections in the order they were registered
1780
+ * The client context of the queries of a computation without a connection, opaque JSON
1543
1781
  */
1544
- connections: ConnectionListEntry[];
1782
+ clientContext: string | null;
1783
+ tasks: ComputationTasks;
1784
+ version: ComputationVersionValue;
1545
1785
  /**
1546
- * The ids of the connections by connector, in the order they were registered
1786
+ * The table, with the system columns once they are computed
1547
1787
  */
1548
- connectionsByType: string[][];
1549
- }
1550
-
1551
- /**
1552
- * The details of the setup of a connection
1553
- */
1554
- export interface ConnectionDetailsView {
1788
+ dataTable: number;
1789
+ dataTableRows: number;
1555
1790
  /**
1556
- * When the steps of the setup happened, by the name of the step, e.g. `channelReadyAt`
1791
+ * The fields of the table that the computation was created with, in order
1557
1792
  */
1558
- setupTimings: Record<string, number>;
1793
+ dataTableFields: string[];
1794
+ dataFrame: number | null;
1559
1795
  /**
1560
- * The params of the connector that the setup uses, without the field of the connector
1796
+ * The column groups of the grid
1561
1797
  */
1562
- setupParams: Record<string, unknown> | null;
1563
- channelError: ConnectionError | null;
1564
- healthCheckError: ConnectionError | null;
1798
+ columnGroups: ComputationColumnGroup[];
1799
+ dataTableOrdering: ComputationOrderBy[];
1565
1800
  /**
1566
- * The handle of a channel of the host, once it is ready: the embedded Hyper or Hyper over gRPC. The channels that
1567
- * the runtime speaks itself have none.
1801
+ * The selections in the summaries of the column groups, in the order of the column groups
1568
1802
  */
1569
- channel: number | null;
1570
- connector: ConnectionConnectorDetails;
1803
+ crossFilters: ComputationCrossFilter[];
1804
+ filterTable: ComputationFilterTable | null;
1805
+ orderingTable: ComputationOrderingTable | null;
1806
+ columnSearch: ComputationSearch;
1807
+ dataSearch: ComputationSearch;
1808
+ dataSearchTable: ComputationDataSearchTable | null;
1809
+ rowNumberColumnGroup: number | null;
1810
+ rowNumberColumnName: string | null;
1811
+ tableAggregation: ComputationTableAggregation | null;
1812
+ columnAggregates: (ComputationColumnAggregate | null)[];
1813
+ filteredColumnAggregates: (ComputationFilteredAggregate | null)[];
1814
+ filteredColumnAggregatesOutdated: boolean[];
1571
1815
  }
1572
1816
 
1573
1817
  /**
1574
- * A table name of the analyzer, null for a name that a statement left out
1818
+ * The comparison of a scalar filter
1575
1819
  */
1576
- export interface ConnectionTableName {
1577
- databaseName: string | null;
1578
- schemaName: string | null;
1579
- tableName: string | null;
1580
- }
1820
+ export type ComputationFilterOp = "=" | "<" | "<=" | ">" | ">=";
1581
1821
 
1582
1822
  /**
1583
- * The tokens of a connection as their JSON, null for a token that the connection doesn't hold. Only
1584
- * `Runtime.revealConnectionSecrets` hands them out, the views summarize them.
1823
+ * A task that a computation tracks, the latest of its kind
1585
1824
  */
1586
- export interface ConnectionSecrets {
1587
- /**
1588
- * The OAuth token of a Trino connection
1589
- */
1590
- accessToken: string | null;
1825
+ export interface ComputationTrackedTask {
1591
1826
  /**
1592
- * The core token of a Salesforce connection
1827
+ * The task of the scheduler
1593
1828
  */
1594
- coreAccessToken: string | null;
1829
+ taskId: number;
1595
1830
  /**
1596
- * The Data Cloud token of a Salesforce connection
1831
+ * The version that the task computes for
1597
1832
  */
1598
- dataCloudAccessToken: string | null;
1599
- }
1600
-
1601
- /**
1602
- * A connection of the list of connections
1603
- */
1604
- export interface ConnectionListEntry {
1605
- connectionId: string;
1606
- connectorType: ConnectorType;
1607
- active: boolean;
1833
+ tableVersion: ComputationVersionValue;
1608
1834
  /**
1609
- * Is the connection listed next to the workbooks? Connections that workbooks use are, as are active ones.
1835
+ * The filters of a filtering
1610
1836
  */
1611
- listed: boolean;
1837
+ filters?: ComputationScalarFilter[];
1612
1838
  /**
1613
- * The number of the connection among the listed connections of its connector from 1, null if it is the only one
1839
+ * The ordering of an ordering, cleared with the ordering of the table
1614
1840
  */
1615
- ordinal: number | null;
1841
+ orderingConstraints?: ComputationOrderBy[];
1842
+ progress: ComputationTaskProgress;
1616
1843
  }
1617
1844
 
1618
1845
  /**
1619
- * A token of a connection without its secret: the facts around it that the views show, e.g. the instance or the
1620
- * expiry. The token itself stays in the runtime, `Runtime.revealConnectionSecrets` hands it out on request.
1846
+ * A filter that compares a field with a number
1621
1847
  */
1622
- export interface ConnectionTokenSummary {
1623
- tokenType: string | null;
1624
- scope: string | null;
1625
- /**
1626
- * The instance that the token is for, e.g. the org of Salesforce or the tenant of Data Cloud
1627
- */
1628
- instanceUrl: string | null;
1629
- /**
1630
- * The tenant or org that the token names, e.g. the audience of the Data Cloud JWT
1631
- */
1632
- tenantId: string | null;
1633
- issuedAt: string | null;
1634
- expiresAt: string | null;
1848
+ export interface ComputationScalarFilter {
1849
+ fieldName: string;
1850
+ op: ComputationFilterOp;
1851
+ value: number;
1635
1852
  }
1636
1853
 
1637
1854
  /**
1638
- * A relation that a statement touched or that a catalog update answers, empty names for none
1855
+ * The statistics of all columns of a table, the table by its handle
1639
1856
  */
1640
- export interface ConnectionRelationName {
1641
- databaseName: string;
1642
- schemaName: string;
1643
- tableName: string;
1857
+ export interface ComputationTableAggregation {
1858
+ table: number;
1859
+ dataFrame: number;
1860
+ countStarFieldName: string;
1644
1861
  }
1645
1862
 
1646
1863
  /**
1647
- * The OAuth flow of a Salesforce connection, the steps that didn't happen yet are null. The PKCE verifier, the code
1648
- * and the tokens stay in the runtime.
1864
+ * The options of the analysis of a result
1649
1865
  */
1650
- export interface ConnectionSalesforceOAuthState {
1651
- oauthParams: ConnectionSalesforceOAuthParams | null;
1866
+ export interface AnalyzeTableOptions {
1652
1867
  /**
1653
- * Was the PKCE challenge generated?
1868
+ * The connection that ran the query of the result, its query history lists the queries of the computation
1654
1869
  */
1655
- pkceGenerated: boolean;
1870
+ connectionId?: string;
1656
1871
  /**
1657
- * When the code of the core login arrived
1872
+ * The client context of the queries of a computation without a connection, opaque JSON
1658
1873
  */
1659
- coreAuthCodeReceivedAt: string | null;
1660
- coreAccessToken: ConnectionTokenSummary | null;
1661
- dataCloudAccessToken: ConnectionTokenSummary | null;
1874
+ clientContext?: string;
1875
+ /**
1876
+ * Compute the summaries of the columns, true without
1877
+ */
1878
+ columnAggregates?: boolean;
1879
+ /**
1880
+ * Order the rows before the analysis settles, e.g. like a result that the result replaces. An ordering of fields
1881
+ * that the result doesn't have is skipped.
1882
+ */
1883
+ ordering?: ComputationOrderBy[];
1662
1884
  }
1663
1885
 
1664
1886
  /**
1665
- * An error with a message and optional details
1887
+ * The progress of a task, times in milliseconds since epoch
1666
1888
  */
1667
- export interface ConnectionError {
1668
- message: string;
1669
- data?: Record<string, string>;
1889
+ export interface ComputationTaskProgress {
1890
+ status: TaskStatus;
1891
+ startedAt: number;
1892
+ completedAt: number | null;
1893
+ failedAt: number | null;
1894
+ failedWithError: string | null;
1670
1895
  }
1671
1896
 
1672
1897
  /**
1673
- * A question about a connection of an imported workbook: connections of the app may describe the same database
1898
+ * The search of a result, of its columns or of its data
1674
1899
  */
1675
- export interface ImportQuestion {
1676
- /**
1677
- * The id of the connection in the workbook
1678
- */
1679
- connectionId: string;
1680
- /**
1681
- * The params in the workbook, shared workbooks carry them without secrets
1682
- */
1683
- params: JsonValue;
1684
- /**
1685
- * The name the connection had in the exporting app
1686
- */
1687
- name: string | null;
1900
+ export interface ComputationSearch {
1901
+ requestedPattern: string;
1902
+ appliedPattern: string;
1903
+ requestId: number;
1904
+ appliedRequestId: number;
1905
+ matchingColumnGroups: number[] | null;
1688
1906
  /**
1689
- * The connections of the app that describe the same database, the first is the default
1907
+ * Does the search hold matching rows? They are the rows of the table of the data search.
1690
1908
  */
1691
- candidates: ImportCandidate[];
1909
+ hasMatchingRows: boolean;
1910
+ pending: boolean;
1911
+ error: string | null;
1692
1912
  }
1693
1913
 
1694
1914
  /**
1695
- * What an import does with a registered workbook of the same id
1696
- */
1697
- export type ImportConflictChoice = "replace" | "create-new";
1698
-
1699
- /**
1700
- * The cached query results that an imported workbook carries
1915
+ * The row numbers in the order of the grid, the table by its handle
1701
1916
  */
1702
- export interface ImportResultFiles {
1703
- count: number;
1704
- bytes: number;
1917
+ export interface ComputationOrderingTable {
1918
+ dataTable: number;
1919
+ rows: number;
1920
+ dataFrame: number;
1921
+ inputRowNumberColumnName: string;
1922
+ orderingConstraints: ComputationOrderBy[];
1923
+ version: ComputationVersionValue;
1924
+ dataSearchRequestId: number | null;
1705
1925
  }
1706
1926
 
1707
1927
  /**
1708
- * A connection of the app that an imported connection may use
1928
+ * The database and schema of the relations that unqualified statements of a connection create or drop
1709
1929
  */
1710
- export interface ImportCandidate {
1711
- id: string;
1712
- params: JsonValue;
1713
- name: string | null;
1930
+ export interface ConnectionNameDefaults {
1931
+ databaseName: string;
1932
+ schemaName: string;
1714
1933
  }
1715
1934
 
1716
1935
  /**
1717
- * What the user chose for a connection that may use an existing one
1936
+ * Opaque JSON params: the params of a connection with one field named after the connector (`{ trino: {...} }`), or
1937
+ * the params of a connector without that field
1718
1938
  */
1719
- export type ImportChoice = { kind: "link"; connectionId: string } | { kind: "separate" };
1939
+ export type JsonParams = Record<string, unknown>;
1720
1940
 
1721
1941
  /**
1722
- * The answers of an import
1942
+ * The catalog updates of a connection
1723
1943
  */
1724
- export interface ImportAnswers {
1944
+ export interface ConnectionCatalogUpdates {
1945
+ /**
1946
+ * The running updates in the order of their ids
1947
+ */
1948
+ tasksRunning: ConnectionCatalogUpdateTask[];
1949
+ /**
1950
+ * The finished updates in the order of their ids
1951
+ */
1952
+ tasksFinished: ConnectionCatalogUpdateTask[];
1725
1953
  /**
1726
- * The choices of the questions by the id of the imported connection, an unanswered question keeps its connection
1727
- * separate
1954
+ * Does the catalog describe the connection?
1728
1955
  */
1729
- connections?: Record<string, ImportChoice>;
1956
+ described: boolean;
1730
1957
  /**
1731
- * Answer every question with its first candidate, e.g. a preview of a published workbook
1958
+ * The running or most recently started full refresh
1732
1959
  */
1733
- preview?: boolean;
1960
+ currentFullRefresh: number | null;
1734
1961
  /**
1735
- * What to do with a registered workbook of the same id, an import fails on one without
1962
+ * The relations that executed statements touched and that no update has answered yet
1736
1963
  */
1737
- conflict?: ImportConflictChoice;
1964
+ touchedRelations: ConnectionRelationName[];
1738
1965
  /**
1739
- * The id of the written workbook, the id of the source if absent
1966
+ * The updates in a row that failed to answer them
1740
1967
  */
1741
- workbookId?: string;
1968
+ touchedFailures: number;
1742
1969
  /**
1743
- * The metadata of the written workbook, the metadata of the source if absent
1970
+ * Might the catalog miss what executed statements did, since asking the connection failed too often?
1744
1971
  */
1745
- metadata?: unknown;
1972
+ outOfDate: boolean;
1746
1973
  /**
1747
- * Add the cached query results to the cache, true if absent. A link never does.
1974
+ * Is the current full refresh running?
1748
1975
  */
1749
- results?: boolean;
1976
+ refreshRunning: boolean;
1977
+ }
1978
+
1979
+ /**
1980
+ * A catalog update
1981
+ */
1982
+ export interface ConnectionCatalogUpdateTask {
1983
+ taskId: number;
1984
+ variant: CatalogUpdateVariant;
1985
+ status: CatalogUpdateTaskStatus;
1986
+ queries: number[];
1987
+ error: ConnectionError | null;
1988
+ startedAt: number | null;
1989
+ finishedAt: number | null;
1990
+ touchedRelations: ConnectionRelationName[];
1750
1991
  /**
1751
- * Restore a written copy into the runtime, true if absent. Without, the caller reloads the app.
1992
+ * The handle of the record of the update at the host: its cancellation and its error
1752
1993
  */
1753
- restore?: boolean;
1994
+ handle: number | null;
1754
1995
  }
1755
1996
 
1756
1997
  /**
1757
- * The workbook with the same id that the storage registered
1998
+ * The OAuth flow of a Trino connection, the steps that didn't happen yet are null. The PKCE verifier, the code and
1999
+ * the token stay in the runtime.
1758
2000
  */
1759
- export interface ImportConflict {
2001
+ export interface ConnectionTrinoOAuthState {
1760
2002
  /**
1761
- * The id of the registered workbook, as the registry spells it
2003
+ * Was the PKCE challenge generated?
1762
2004
  */
1763
- workbookId: string;
2005
+ pkceGenerated: boolean;
1764
2006
  /**
1765
- * The entry of the workbook tree, `{ path, storageType, nativePath }`
2007
+ * When the code arrived
1766
2008
  */
1767
- entry: JsonValue;
2009
+ authCodeReceivedAt: string | null;
2010
+ accessToken: ConnectionTokenSummary | null;
1768
2011
  }
1769
2012
 
1770
2013
  /**
1771
- * What an import wrote
2014
+ * The details that only one connector keeps, Database.com has the ones of Salesforce
1772
2015
  */
1773
- export interface ImportOutcome {
2016
+ export type ConnectionConnectorDetails = { kind: "hyper" } | { kind: "trino"; schemaResolutionError: ConnectionError | null; oauthState: ConnectionTrinoOAuthState | null } | { kind: "salesforce"; setupError: ConnectionError | null; oauthState: ConnectionSalesforceOAuthState | null };
2017
+
2018
+ /**
2019
+ * The state of saving a connection: whether it saves and the outcome of the last save
2020
+ */
2021
+ export interface ConnectionSaveView {
1774
2022
  /**
1775
- * The id of the written workbook
2023
+ * Is the connection being saved?
1776
2024
  */
1777
- workbookId: string;
2025
+ saving: boolean;
1778
2026
  /**
1779
- * The outcome of the query results, null for a workbook without results
2027
+ * The outcome of the last save, null before one
1780
2028
  */
1781
- results: ImportedResults | null;
2029
+ outcome: ConnectionSaveOutcome | null;
2030
+ }
2031
+
2032
+ /**
2033
+ * The parameters of the OAuth flow of a Salesforce connection
2034
+ */
2035
+ export interface ConnectionSalesforceOAuthParams {
2036
+ instanceUrl: string;
2037
+ appConsumerKey: string;
2038
+ requestedAt: number;
2039
+ expiresAt: number;
2040
+ }
2041
+
2042
+ /**
2043
+ * A connection, the slice `connection` of the runtime. The field names are the ones the app reads. The queries are
2044
+ * listed by id, each one is a slice `query` of its own: the connection changes when a query starts or finishes, not
2045
+ * with the progress of a query.
2046
+ */
2047
+ export interface ConnectionView {
2048
+ connectionId: string;
1782
2049
  /**
1783
- * The connections that the import registered, the app didn't have them
2050
+ * Does the connection belong to a committed workbook or was it online once?
1784
2051
  */
1785
- registered: string[];
2052
+ active: boolean;
2053
+ connectionStatus: ConnectionStatus;
2054
+ connectionHealth: ConnectionHealth;
2055
+ connectorType: ConnectorType;
1786
2056
  /**
1787
- * Did a connection use an existing one that the user would have been asked about?
2057
+ * The name the user gave the connection, the label falls back to the connector without it
1788
2058
  */
1789
- unasked: boolean;
2059
+ name: string | null;
1790
2060
  /**
1791
- * Was the workbook restored into the runtime? A replacement or a native folder is not, the app reloads.
2061
+ * Does the connection cache query results? Null for the default of the connector.
1792
2062
  */
1793
- restored: boolean;
1794
- }
1795
-
1796
- /**
1797
- * The outcome of the import of the query results of a workbook
1798
- */
1799
- export interface ImportedResults {
2063
+ cacheQueryResults: boolean | null;
1800
2064
  /**
1801
- * The results of the workbook
2065
+ * Does the connection cache query results, the choice of the user or the default of the connector?
1802
2066
  */
1803
- total: number;
2067
+ cachesQueryResults: boolean;
1804
2068
  /**
1805
- * The results that became files of the cache
2069
+ * Is the connection connected or connecting? An open connection keeps its protocol and can't be merged.
1806
2070
  */
1807
- added: number;
2071
+ open: boolean;
1808
2072
  /**
1809
- * The results whose keys were cached already, the results of the app win
2073
+ * The health as the app prints it, e.g. `Not Started`
1810
2074
  */
1811
- kept: number;
2075
+ healthLabel: string;
1812
2076
  /**
1813
- * The results that couldn't be added
2077
+ * Can the queries of the connection read the data files that are attached to a workbook? The embedded Hyper reads
2078
+ * them.
1814
2079
  */
1815
- failed: number;
2080
+ readsAttachments: boolean;
2081
+ details: ConnectionDetailsView;
1816
2082
  /**
1817
- * The results left out because the workbook holds more than the cache keeps
2083
+ * The params of the last successful setup, the initial ones until then
1818
2084
  */
1819
- dropped: number;
2085
+ params: JsonParams;
1820
2086
  /**
1821
- * The bytes of the results that were added
2087
+ * The local settings of the form
1822
2088
  */
1823
- bytes: number;
2089
+ paramsDraft: JsonParams | null;
1824
2090
  /**
1825
- * Why the first result that failed couldn't be added, or why none was
2091
+ * The params of the running setup, never saved
1826
2092
  */
1827
- error: string | null;
1828
- }
1829
-
1830
- /**
1831
- * What an import read, before anything is written
1832
- */
1833
- export interface ImportPreview {
2093
+ setupAttemptParams: JsonParams | null;
1834
2094
  /**
1835
- * The pending import, `commitImport` and `dropImport` name it
2095
+ * The draft when the running setup started
1836
2096
  */
1837
- importId: number;
2097
+ setupAttemptDraft: JsonParams | null;
2098
+ catalogUpdates: ConnectionCatalogUpdates;
1838
2099
  /**
1839
- * The workbook file, migrated and with the file lists of its files
2100
+ * The catalog entry of the relations of the connection
1840
2101
  */
1841
- workbook: JsonValue;
2102
+ catalogRelationEntryId: number;
1842
2103
  /**
1843
- * The script files
2104
+ * The database and schema of the relations that unqualified statements create or drop
1844
2105
  */
1845
- scriptCount: number;
2106
+ catalogNameDefaults: ConnectionNameDefaults;
1846
2107
  /**
1847
- * The attachments
2108
+ * The script with the functions of the connection, null once it is deleted
1848
2109
  */
1849
- attachmentCount: number;
2110
+ functionScriptEntryId: number | null;
1850
2111
  /**
1851
- * The cached query results
2112
+ * The metrics of the finished queries
1852
2113
  */
1853
- results: ImportResultFiles;
2114
+ metrics: QueryHistoryMetrics;
1854
2115
  /**
1855
- * The registered workbook with the same id, null if there is none
2116
+ * The active queries in the order they started
1856
2117
  */
1857
- conflict: ImportConflict | null;
2118
+ queriesActiveOrdered: number[];
1858
2119
  /**
1859
- * The connections that the user decides on
2120
+ * The active queries that run on the connection, not the queries of the computations that it only tracks
1860
2121
  */
1861
- questions: ImportQuestion[];
2122
+ queriesRunning: number;
1862
2123
  /**
1863
- * The catalog files that didn't parse and were left out
2124
+ * The finished queries in the order they finished
1864
2125
  */
1865
- invalidCatalogs: string[];
2126
+ queriesFinishedOrdered: number[];
1866
2127
  /**
1867
- * False when unusable entries were removed from the file lists of the workbook file
2128
+ * Changes whenever a query starts or finishes
1868
2129
  */
1869
- filesValid: boolean;
2130
+ snapshotQueriesActiveFinished: number;
1870
2131
  /**
1871
- * The folder of a native workbook that is registered in place, null for a copy
2132
+ * The workbooks that use the connection
1872
2133
  */
1873
- nativePath: string | null;
1874
- }
1875
-
1876
-
1877
- /** What hears a run of a workbook */
1878
- export interface RunListener {
1879
- /** Something happened to a script of the run, a failure comes with what the platform failed with */
1880
- script?(file: string, event: WorkbookScriptRunEvent, error: unknown): void;
1881
- /** Set up a connection that statements run on before the first statement, e.g. with the credentials of the command line tool. The scripts of a connection whose setup rejects are skipped. A run with it takes every connection of the workbook. */
1882
- prepareConnection?(connectionId: string): Promise<void>;
1883
- }
1884
-
1885
-
1886
- /**
1887
- * The error of a failed or cancelled query
1888
- */
1889
- export interface QueryErrorView {
1890
- message: string;
1891
- details: string | null;
1892
- }
1893
-
1894
- /**
1895
- * A query, the slice `query` of the runtime: its text, what it is, its status and its latest progress. The field names
1896
- * are the ones the app reads. The result table is a table of the handle table of the platform.
1897
- */
1898
- export interface QueryView {
1899
- queryId: number;
2134
+ workbooks: string[];
1900
2135
  /**
1901
- * The connection of the query
2136
+ * Saving the connection
1902
2137
  */
1903
- connectionId: string;
2138
+ save: ConnectionSaveView;
1904
2139
  /**
1905
- * The trace of the log messages of the query
2140
+ * Can the user refresh the catalog: is the connection online without a running full refresh?
1906
2141
  */
1907
- traceId: number;
1908
- queryText: string;
1909
- queryMetadata: QueryMetadataView;
1910
- status: QueryExecutionStatus;
1911
- metrics: QueryMetricsView;
1912
- error: QueryErrorView | null;
1913
- resultTable: QueryResultTableView | null;
1914
- cacheKey: string | null;
1915
- servedFromCache: boolean;
1916
- cacheDeleted: boolean;
1917
- cachedAt: number | null;
1918
- latestProgressUpdate: QueryLatestProgressView | null;
1919
- revision: number;
2142
+ canRefresh: boolean;
1920
2143
  /**
1921
- * The handle of the record of the query at the host
2144
+ * Does a setup of the connection run?
1922
2145
  */
1923
- handle: number | null;
1924
- }
1925
-
1926
- /**
1927
- * A progress update of a channel of the host: the plain fields and the raw progress payload of the engine, e.g.
1928
- * `{ kind: 'hyper_query_status', status, receivedAt }`. The progress model of the query in the executor turns the
1929
- * payload into the structured progress.
1930
- */
1931
- export interface QueryProgressView {
1932
- isQueued: boolean | null;
1933
- progressPercent: number | null;
1934
- resultRows: number | null;
1935
- rowsProcessed: number | null;
1936
- executionTimeMs: number | null;
2146
+ setupRunning: boolean;
1937
2147
  /**
1938
- * The metrics of the response stream, none counts nothing
2148
+ * Counts the announcements of a new catalog: the scripts that use the connection are analyzed again with it
1939
2149
  */
1940
- metrics?: QueryStreamMetrics | null;
1941
- phase?: string | null;
2150
+ catalogVersion: number;
1942
2151
  /**
1943
- * The raw progress payload of the engine, a payload of an unknown kind is dropped
2152
+ * The identity of the catalog of the connection: a connection that is created again under the same id has another
2153
+ * catalog, a handle of the catalog (`Runtime.catalog`) goes with its identity
1944
2154
  */
1945
- engineProgress?: unknown;
1946
- }
1947
-
1948
- /**
1949
- * What a query is and who issued it. A planned statement of a run of a workbook is opaque JSON
1950
- * (`PlannedStatement` of the app).
1951
- */
1952
- export interface QueryMetadataView {
1953
- queryType: QueryType;
1954
- title: string | null;
1955
- description: string | null;
1956
- issuer: string | null;
1957
- userProvided: boolean;
1958
- workbookId?: string;
1959
- resultOwner?: string;
1960
- planned?: unknown;
1961
- }
1962
-
1963
- /**
1964
- * The metrics of the finished queries of a history, internal queries don't count
1965
- */
1966
- export interface QueryHistoryMetrics {
1967
- successfulQueries: QueryOutcomeMetrics;
1968
- canceledQueries: QueryOutcomeMetrics;
1969
- failedQueries: QueryOutcomeMetrics;
1970
- }
1971
-
1972
- /**
1973
- * The metrics of the finished queries of one outcome
1974
- */
1975
- export interface QueryOutcomeMetrics {
1976
- totalQueries: number;
1977
- totalBatchesReceived: number;
1978
- totalRowsReceived: number;
1979
- accumulatedTimeUntilFirstBatch: number;
1980
- accumulatedQueryDuration: number;
2155
+ catalogId: number;
1981
2156
  }
1982
2157
 
1983
2158
  /**
1984
- * The keys of the structured progress of a query that the host holds, their payloads don't cross again
2159
+ * The connections of the runtime, the slice `connectionList`
1985
2160
  */
1986
- export interface QueryProfileKeys {
2161
+ export interface ConnectionListView {
1987
2162
  /**
1988
- * The revision of the progress, the execution state crosses when it differs
2163
+ * The connections in the order they were registered
1989
2164
  */
1990
- revision: number | null;
2165
+ connections: ConnectionListEntry[];
1991
2166
  /**
1992
- * The version of the structure, the structure crosses when it differs
2167
+ * The ids of the connections by connector, in the order they were registered
1993
2168
  */
1994
- structureVersion: number | null;
2169
+ connectionsByType: string[][];
1995
2170
  }
1996
2171
 
1997
2172
  /**
1998
- * The structured progress of a query: the plan with its stages and their execution state. A payload is null when the
1999
- * host holds it already, its key names it.
2173
+ * The details of the setup of a connection
2000
2174
  */
2001
- export interface QueryProfileProgressView {
2002
- /**
2003
- * The revision of the progress, it changes with the structure or the execution state
2004
- */
2005
- revision: number;
2175
+ export interface ConnectionDetailsView {
2006
2176
  /**
2007
- * The version of the structure
2177
+ * When the steps of the setup happened, by the name of the step, e.g. `channelReadyAt`
2008
2178
  */
2009
- structureVersion: number;
2179
+ setupTimings: Record<string, number>;
2010
2180
  /**
2011
- * The packed `QueryProfile`, null while the host holds its version
2181
+ * The params of the connector that the setup uses, without the field of the connector
2012
2182
  */
2013
- structure: FlatBuffer<buffers_profile.QueryProfile> | null;
2183
+ setupParams: Record<string, unknown> | null;
2184
+ channelError: ConnectionError | null;
2185
+ healthCheckError: ConnectionError | null;
2014
2186
  /**
2015
- * The execution state as packed `QueryProfileEvents`, one event per entity with state, null while the host holds
2016
- * the revision
2187
+ * The handle of a channel of the host, once it is ready: the embedded Hyper or Hyper over gRPC. The channels that
2188
+ * the runtime speaks itself have none.
2017
2189
  */
2018
- execution: FlatBuffer<buffers_profile.QueryProfileEvents> | null;
2019
- }
2020
-
2021
- /**
2022
- * The result table of a query, the host keeps it under its handle
2023
- */
2024
- export interface QueryResultTableView {
2025
- id: number;
2026
- rows: number;
2027
- }
2028
-
2029
- /**
2030
- * The metrics of the response stream of a query, as the connector counts them
2031
- */
2032
- export interface QueryStreamMetrics {
2033
- totalDataBytesReceived: number;
2034
- totalBatchesReceived: number;
2035
- totalRowsReceived: number;
2036
- totalQueryRequestsStarted: number;
2037
- totalQueryRequestsSucceeded: number;
2038
- totalQueryRequestsFailed: number;
2039
- totalQueryRequestDurationMs: number;
2040
- durationUntilFirstBatchMs: number | null;
2190
+ channel: number | null;
2191
+ connector: ConnectionConnectorDetails;
2041
2192
  }
2042
2193
 
2043
2194
  /**
2044
- * The latest progress update of a query: the plain fields and the structured progress
2195
+ * A table name of the analyzer, null for a name that a statement left out
2045
2196
  */
2046
- export interface QueryLatestProgressView {
2047
- isQueued: boolean | null;
2048
- progressPercent: number | null;
2049
- resultRows: number | null;
2050
- rowsProcessed: number | null;
2051
- executionTimeMs: number | null;
2052
- metrics: QueryStreamMetrics;
2053
- phase: string | null;
2054
- profile: QueryProfileProgressView | null;
2197
+ export interface ConnectionTableName {
2198
+ databaseName: string | null;
2199
+ schemaName: string | null;
2200
+ tableName: string | null;
2055
2201
  }
2056
2202
 
2057
2203
  /**
2058
- * The layout of the plans of query profiles, the fields of `ProfileLayoutConfigT` of the generated FlatBuffer code
2204
+ * The tokens of a connection as their JSON, null for a token that the connection doesn't hold. Only
2205
+ * `Runtime.revealConnectionSecrets` hands them out, the views summarize them.
2059
2206
  */
2060
- export interface ProfileLayoutView {
2061
- levelHeight: number;
2062
- nodeHeight: number;
2063
- nodeMarginHorizontal: number;
2064
- nodePaddingLeft: number;
2065
- nodePaddingRight: number;
2066
- iconWidth: number;
2067
- iconMarginRight: number;
2068
- maxLabelChars: number;
2069
- widthPerLabelChar: number;
2070
- nodeMinWidth: number;
2071
- nodeMarginVertical: number;
2207
+ export interface ConnectionSecrets {
2072
2208
  /**
2073
- * A `ProfileLayoutOrientation`
2209
+ * The OAuth token of a Trino connection
2074
2210
  */
2075
- orientation: number;
2076
- symbolWidth: number;
2077
- }
2078
-
2079
- /**
2080
- * The points in time of a query in milliseconds since epoch and its counters
2081
- */
2082
- export interface QueryMetricsView {
2083
- queryRequestedAt: number | null;
2084
- querySendingStartedAt: number | null;
2085
- queryQueuedStartedAt: number | null;
2086
- queryRunningStartedAt: number | null;
2087
- receivedFirstBatchAt: number | null;
2088
- receivedLastBatchAt: number | null;
2089
- receivedAllBatchesAt: number | null;
2090
- processingResultsStartedAt: number | null;
2091
- processedResultsAt: number | null;
2092
- querySucceededAt: number | null;
2093
- queryFailedAt: number | null;
2094
- queryCancelledAt: number | null;
2095
- lastUpdatedAt: number | null;
2096
- progressUpdatesReceived: number;
2097
- queryDurationMs: number | null;
2098
- textLength: number | null;
2099
- streamMetrics: QueryStreamMetrics;
2100
- }
2101
-
2102
-
2103
- import type * as buffers_editor from '../gen/flatbuffers/dashql/buffers/editor.js';
2104
- import type * as buffers_diff from '../gen/flatbuffers/dashql/buffers/diff.js';
2105
- import type * as buffers_execution from '../gen/flatbuffers/dashql/buffers/execution.js';
2106
- import type * as buffers_profile from '../gen/flatbuffers/dashql/buffers/profile.js';
2107
- /** The bytes of a packed FlatBuffer whose root table is `T`, read with the generated accessors */
2108
- export type FlatBuffer<T> = Uint8Array & { readonly __flatbufferRoot?: T };
2109
-
2110
-
2111
- /**
2112
- * Opaque JSON in a view: a workbook file, a connection entry, the params of a connection. It crosses as a plain JS
2113
- * value and is read the way `JSON.stringify` reads it: members that are undefined or functions are left out, `toJSON`
2114
- * is called, numbers that are not finite are null.
2115
- */
2116
- export type JsonValue = unknown;
2117
-
2118
- /**
2119
- * The rows that a data search matched with their matching columns, the table by its handle
2120
- */
2121
- export interface ComputationDataSearchTable {
2122
- dataTable: number;
2123
- rows: number;
2124
- dataFrame: number;
2125
- inputRowNumberColumnName: string;
2126
- version: ComputationVersionValue;
2127
- requestId: number;
2128
- }
2129
-
2130
- /**
2131
- * A key of an ordering, ascending and nulls last without
2132
- */
2133
- export interface ComputationOrderBy {
2134
- field: string;
2135
- ascending?: boolean;
2136
- nullsFirst?: boolean;
2137
- }
2138
-
2139
- /**
2140
- * The version of a computation: the data changes with a new data frame, the filter with every scheduled filtering
2141
- */
2142
- export interface ComputationVersionValue {
2143
- data: number;
2144
- filter: number;
2211
+ accessToken: string | null;
2212
+ /**
2213
+ * The core token of a Salesforce connection
2214
+ */
2215
+ coreAccessToken: string | null;
2216
+ /**
2217
+ * The Data Cloud token of a Salesforce connection
2218
+ */
2219
+ dataCloudAccessToken: string | null;
2145
2220
  }
2146
2221
 
2147
2222
  /**
2148
- * The context of a call of the compute platform: the computation, the title of its task in the query history, the
2149
- * connection and the client context of the computation, and the run that `cancel` aborts
2223
+ * A connection of the list of connections
2150
2224
  */
2151
- export interface ComputeCallContext {
2152
- tableId: number;
2153
- title: string;
2154
- connectionId: string | null;
2225
+ export interface ConnectionListEntry {
2226
+ connectionId: string;
2227
+ connectorType: ConnectorType;
2228
+ active: boolean;
2155
2229
  /**
2156
- * The client context of the queries of a computation without a connection, opaque JSON
2230
+ * Is the connection listed next to the workbooks? Connections that workbooks use are, as are active ones.
2157
2231
  */
2158
- clientContext: string | null;
2159
- run: number;
2232
+ listed: boolean;
2233
+ /**
2234
+ * The number of the connection among the listed connections of its connector from 1, null if it is the only one
2235
+ */
2236
+ ordinal: number | null;
2160
2237
  }
2161
2238
 
2162
2239
  /**
2163
- * The selection in the summary of a column group
2164
- */
2165
- export type ComputationCrossFilter = { kind: "histogram"; column: number; selection: [number, number] } | { kind: "mostFrequent"; column: number; valueId: number };
2166
-
2167
- /**
2168
- * A column of the grid of a result
2240
+ * A token of a connection without its secret: the facts around it that the views show, e.g. the instance or the
2241
+ * expiry. The token itself stays in the runtime, `Runtime.revealConnectionSecrets` hands it out on request.
2169
2242
  */
2170
- export type ComputationColumnGroup = { type: "ROWNUMBER"; value: { rowNumberFieldName: string } } | { type: "SKIPPED"; value: { inputFieldName: string; inputFieldType: string; inputFieldNullable: boolean } } | { type: "ORDINAL"; value: ComputationValueColumn } | { type: "STRING"; value: ComputationValueColumn } | { type: "LIST"; value: ComputationValueColumn };
2243
+ export interface ConnectionTokenSummary {
2244
+ tokenType: string | null;
2245
+ scope: string | null;
2246
+ /**
2247
+ * The instance that the token is for, e.g. the org of Salesforce or the tenant of Data Cloud
2248
+ */
2249
+ instanceUrl: string | null;
2250
+ /**
2251
+ * The tenant or org that the token names, e.g. the audience of the Data Cloud JWT
2252
+ */
2253
+ tenantId: string | null;
2254
+ issuedAt: string | null;
2255
+ expiresAt: string | null;
2256
+ }
2171
2257
 
2172
2258
  /**
2173
- * The fields of the table aggregation with the statistics of a column
2259
+ * A relation that a statement touched or that a catalog update answers, empty names for none
2174
2260
  */
2175
- export interface ComputationStatsFields {
2176
- countFieldName: string;
2177
- distinctCountFieldName: string | null;
2178
- minAggregateFieldName: string | null;
2179
- maxAggregateFieldName: string | null;
2261
+ export interface ConnectionRelationName {
2262
+ databaseName: string;
2263
+ schemaName: string;
2264
+ tableName: string;
2180
2265
  }
2181
2266
 
2182
2267
  /**
2183
- * The table and the data frame of a summary
2268
+ * The OAuth flow of a Salesforce connection, the steps that didn't happen yet are null. The PKCE verifier, the code
2269
+ * and the tokens stay in the runtime.
2184
2270
  */
2185
- export interface ComputationColumnSummary {
2186
- table: number;
2187
- dataFrame: number;
2188
- analysis: ComputationSummaryAnalysis | null;
2271
+ export interface ConnectionSalesforceOAuthState {
2272
+ oauthParams: ConnectionSalesforceOAuthParams | null;
2273
+ /**
2274
+ * Was the PKCE challenge generated?
2275
+ */
2276
+ pkceGenerated: boolean;
2277
+ /**
2278
+ * When the code of the core login arrived
2279
+ */
2280
+ coreAuthCodeReceivedAt: string | null;
2281
+ coreAccessToken: ConnectionTokenSummary | null;
2282
+ dataCloudAccessToken: ConnectionTokenSummary | null;
2189
2283
  }
2190
2284
 
2191
2285
  /**
2192
- * The rows that pass the filters, the table by its handle
2286
+ * An error with a message and optional details
2193
2287
  */
2194
- export interface ComputationFilterTable {
2195
- dataTable: number;
2196
- rows: number;
2197
- dataFrame: number;
2198
- inputRowNumberColumnName: string;
2199
- version: ComputationVersionValue;
2288
+ export interface ConnectionError {
2289
+ message: string;
2290
+ data?: Record<string, string>;
2200
2291
  }
2201
2292
 
2202
2293
  /**
2203
- * The tasks that a computation tracks
2294
+ * A question about a connection of an imported workbook: connections of the app may describe the same database
2204
2295
  */
2205
- export interface ComputationTasks {
2206
- tableAggregationTask: ComputationTrackedTask | null;
2207
- systemColumnTask: ComputationTrackedTask | null;
2208
- filteringTask: ComputationTrackedTask | null;
2209
- orderingTask: ComputationTrackedTask | null;
2210
- dataSearchTask: ComputationTrackedTask | null;
2211
- columnAggregationTasks: (ComputationTrackedTask | null)[];
2212
- filteredColumnAggregationTasks: (ComputationTrackedTask | null)[];
2296
+ export interface ImportQuestion {
2297
+ /**
2298
+ * The id of the connection in the workbook
2299
+ */
2300
+ connectionId: string;
2301
+ /**
2302
+ * The params in the workbook, shared workbooks carry them without secrets
2303
+ */
2304
+ params: JsonValue;
2305
+ /**
2306
+ * The name the connection had in the exporting app
2307
+ */
2308
+ name: string | null;
2309
+ /**
2310
+ * The connections of the app that describe the same database, the first is the default
2311
+ */
2312
+ candidates: ImportCandidate[];
2213
2313
  }
2214
2314
 
2215
2315
  /**
2216
- * What is searched, the columns by their names or the data
2316
+ * What an import does with a registered workbook of the same id
2217
2317
  */
2218
- export type ComputationSearchKind = "columns" | "data";
2318
+ export type ImportConflictChoice = "replace" | "create-new";
2219
2319
 
2220
2320
  /**
2221
- * The summary of a column over the rows that the filters and the data search select
2321
+ * The cached query results that an imported workbook carries
2222
2322
  */
2223
- export interface ComputationFilteredAggregate {
2224
- aggregate: ComputationColumnAggregate;
2225
- filterVersion: ComputationVersionValue;
2226
- dataSearchRequestId: number | null;
2323
+ export interface ImportResultFiles {
2324
+ count: number;
2325
+ bytes: number;
2227
2326
  }
2228
2327
 
2229
2328
  /**
2230
- * The summary of a column: the table of the binned or the frequent values by its handle, with its analysis
2329
+ * A connection of the app that an imported connection may use
2231
2330
  */
2232
- export type ComputationColumnAggregate = ({ kind: "ordinal" } & ComputationColumnSummary) | ({ kind: "string" } & ComputationColumnSummary) | ({ kind: "list" } & ComputationColumnSummary) | { kind: "skipped" };
2331
+ export interface ImportCandidate {
2332
+ id: string;
2333
+ params: JsonValue;
2334
+ name: string | null;
2335
+ }
2233
2336
 
2234
2337
  /**
2235
- * What the lower bounds of the bins of a histogram are
2338
+ * What the user chose for a connection that may use an existing one
2236
2339
  */
2237
- export type ComputationBinBounds = "numbers" | "epochMillis";
2340
+ export type ImportChoice = { kind: "link"; connectionId: string } | { kind: "separate" };
2238
2341
 
2239
2342
  /**
2240
- * The value column of a column group, ordinal, string or list
2343
+ * The answers of an import
2241
2344
  */
2242
- export interface ComputationValueColumn {
2243
- inputFieldName: string;
2345
+ export interface ImportAnswers {
2244
2346
  /**
2245
- * The type of the field as the runtime names it, the app reads the Arrow type from the schema of the table
2347
+ * The choices of the questions by the id of the imported connection, an unanswered question keeps its connection
2348
+ * separate
2246
2349
  */
2247
- inputFieldType: string;
2248
- inputFieldNullable: boolean;
2249
- statsFields: ComputationStatsFields | null;
2350
+ connections?: Record<string, ImportChoice>;
2250
2351
  /**
2251
- * The bins of an ordinal column, null without
2352
+ * Answer every question with its first candidate, e.g. a preview of a published workbook
2252
2353
  */
2253
- binFieldName: string | null;
2354
+ preview?: boolean;
2254
2355
  /**
2255
- * The number of bins of an ordinal column, 0 without
2356
+ * What to do with a registered workbook of the same id, an import fails on one without
2256
2357
  */
2257
- binCount: number;
2358
+ conflict?: ImportConflictChoice;
2258
2359
  /**
2259
- * The value ids of a string or a list column, null without
2360
+ * The id of the written workbook, the id of the source if absent
2260
2361
  */
2261
- valueIdFieldName: string | null;
2362
+ workbookId?: string;
2363
+ /**
2364
+ * The metadata of the written workbook, the metadata of the source if absent
2365
+ */
2366
+ metadata?: unknown;
2367
+ /**
2368
+ * Add the cached query results to the cache, true if absent. A link never does.
2369
+ */
2370
+ results?: boolean;
2371
+ /**
2372
+ * Restore a written copy into the runtime, true if absent. Without, the caller reloads the app.
2373
+ */
2374
+ restore?: boolean;
2262
2375
  }
2263
2376
 
2264
2377
  /**
2265
- * The numbers of the analysis of a summary that the runtime computed. The app formats the values of the tables: the
2266
- * minimum and the maximum of the statistics, the lower bounds of the bins and the frequent values.
2378
+ * The workbook with the same id that the storage registered
2267
2379
  */
2268
- export type ComputationSummaryAnalysis = { kind: "ordinal"; totalCount: number; countNotNull: number; countNull: number; binCount: number; binValueCounts: number[]; binPercentages: number[]; binLowerBounds: (number | null)[]; binBounds: ComputationBinBounds } | { kind: "string"; totalCount: number; countNotNull: number; countNull: number; countDistinct: number; isUnique: boolean; frequentValueIds: number[]; frequentValueCounts: number[]; frequentValuePercentages: number[] };
2380
+ export interface ImportConflict {
2381
+ /**
2382
+ * The id of the registered workbook, as the registry spells it
2383
+ */
2384
+ workbookId: string;
2385
+ /**
2386
+ * The entry of the workbook tree, `{ path, storageType, nativePath }`
2387
+ */
2388
+ entry: JsonValue;
2389
+ }
2269
2390
 
2270
2391
  /**
2271
- * The view of the computation of a result table. The tables are handles of the platform, the data frames ids of
2272
- * the compute database.
2392
+ * What an import wrote
2273
2393
  */
2274
- export interface ComputationView {
2275
- tableId: number;
2276
- revision: number;
2277
- connectionId: string | null;
2394
+ export interface ImportOutcome {
2278
2395
  /**
2279
- * The client context of the queries of a computation without a connection, opaque JSON
2396
+ * The id of the written workbook
2280
2397
  */
2281
- clientContext: string | null;
2282
- tasks: ComputationTasks;
2283
- version: ComputationVersionValue;
2398
+ workbookId: string;
2284
2399
  /**
2285
- * The table, with the system columns once they are computed
2400
+ * The outcome of the query results, null for a workbook without results
2286
2401
  */
2287
- dataTable: number;
2288
- dataTableRows: number;
2402
+ results: ImportedResults | null;
2289
2403
  /**
2290
- * The fields of the table that the computation was created with, in order
2404
+ * The connections that the import registered, the app didn't have them
2291
2405
  */
2292
- dataTableFields: string[];
2293
- dataFrame: number | null;
2406
+ registered: string[];
2294
2407
  /**
2295
- * The column groups of the grid
2408
+ * Did a connection use an existing one that the user would have been asked about?
2296
2409
  */
2297
- columnGroups: ComputationColumnGroup[];
2298
- dataTableOrdering: ComputationOrderBy[];
2410
+ unasked: boolean;
2299
2411
  /**
2300
- * The selections in the summaries of the column groups, in the order of the column groups
2412
+ * Was the workbook restored into the runtime? A replacement or a native folder is not, the app reloads.
2301
2413
  */
2302
- crossFilters: ComputationCrossFilter[];
2303
- filterTable: ComputationFilterTable | null;
2304
- orderingTable: ComputationOrderingTable | null;
2305
- columnSearch: ComputationSearch;
2306
- dataSearch: ComputationSearch;
2307
- dataSearchTable: ComputationDataSearchTable | null;
2308
- rowNumberColumnGroup: number | null;
2309
- rowNumberColumnName: string | null;
2310
- tableAggregation: ComputationTableAggregation | null;
2311
- columnAggregates: (ComputationColumnAggregate | null)[];
2312
- filteredColumnAggregates: (ComputationFilteredAggregate | null)[];
2313
- filteredColumnAggregatesOutdated: boolean[];
2414
+ restored: boolean;
2314
2415
  }
2315
2416
 
2316
2417
  /**
2317
- * The comparison of a scalar filter
2318
- */
2319
- export type ComputationFilterOp = "=" | "<" | "<=" | ">" | ">=";
2320
-
2321
- /**
2322
- * A task that a computation tracks, the latest of its kind
2418
+ * The outcome of the import of the query results of a workbook
2323
2419
  */
2324
- export interface ComputationTrackedTask {
2420
+ export interface ImportedResults {
2325
2421
  /**
2326
- * The task of the scheduler
2422
+ * The results of the workbook
2327
2423
  */
2328
- taskId: number;
2424
+ total: number;
2329
2425
  /**
2330
- * The version that the task computes for
2426
+ * The results that became files of the cache
2331
2427
  */
2332
- tableVersion: ComputationVersionValue;
2428
+ added: number;
2333
2429
  /**
2334
- * The filters of a filtering
2430
+ * The results whose keys were cached already, the results of the app win
2335
2431
  */
2336
- filters?: ComputationScalarFilter[];
2432
+ kept: number;
2337
2433
  /**
2338
- * The ordering of an ordering, cleared with the ordering of the table
2434
+ * The results that couldn't be added
2339
2435
  */
2340
- orderingConstraints?: ComputationOrderBy[];
2341
- progress: ComputationTaskProgress;
2342
- }
2343
-
2344
- /**
2345
- * A filter that compares a field with a number
2346
- */
2347
- export interface ComputationScalarFilter {
2348
- fieldName: string;
2349
- op: ComputationFilterOp;
2350
- value: number;
2351
- }
2352
-
2353
- /**
2354
- * The statistics of all columns of a table, the table by its handle
2355
- */
2356
- export interface ComputationTableAggregation {
2357
- table: number;
2358
- dataFrame: number;
2359
- countStarFieldName: string;
2436
+ failed: number;
2437
+ /**
2438
+ * The results left out because the workbook holds more than the cache keeps
2439
+ */
2440
+ dropped: number;
2441
+ /**
2442
+ * The bytes of the results that were added
2443
+ */
2444
+ bytes: number;
2445
+ /**
2446
+ * Why the first result that failed couldn't be added, or why none was
2447
+ */
2448
+ error: string | null;
2360
2449
  }
2361
2450
 
2362
2451
  /**
2363
- * The options of the analysis of a result
2452
+ * What an import read, before anything is written
2364
2453
  */
2365
- export interface AnalyzeTableOptions {
2454
+ export interface ImportPreview {
2366
2455
  /**
2367
- * The connection that ran the query of the result, its query history lists the queries of the computation
2456
+ * The pending import, `commitImport` and `dropImport` name it
2457
+ */
2458
+ importId: number;
2459
+ /**
2460
+ * The workbook file, migrated and with the file lists of its files
2368
2461
  */
2369
- connectionId?: string;
2462
+ workbook: JsonValue;
2370
2463
  /**
2371
- * The client context of the queries of a computation without a connection, opaque JSON
2464
+ * The script files
2372
2465
  */
2373
- clientContext?: string;
2466
+ scriptCount: number;
2374
2467
  /**
2375
- * Compute the summaries of the columns, true without
2468
+ * The attachments
2376
2469
  */
2377
- columnAggregates?: boolean;
2470
+ attachmentCount: number;
2378
2471
  /**
2379
- * Order the rows before the analysis settles, e.g. like a result that the result replaces. An ordering of fields
2380
- * that the result doesn't have is skipped.
2472
+ * The cached query results
2381
2473
  */
2382
- ordering?: ComputationOrderBy[];
2383
- }
2384
-
2385
- /**
2386
- * The progress of a task, times in milliseconds since epoch
2387
- */
2388
- export interface ComputationTaskProgress {
2389
- status: TaskStatus;
2390
- startedAt: number;
2391
- completedAt: number | null;
2392
- failedAt: number | null;
2393
- failedWithError: string | null;
2394
- }
2395
-
2396
- /**
2397
- * The search of a result, of its columns or of its data
2398
- */
2399
- export interface ComputationSearch {
2400
- requestedPattern: string;
2401
- appliedPattern: string;
2402
- requestId: number;
2403
- appliedRequestId: number;
2404
- matchingColumnGroups: number[] | null;
2474
+ results: ImportResultFiles;
2405
2475
  /**
2406
- * Does the search hold matching rows? They are the rows of the table of the data search.
2476
+ * The registered workbook with the same id, null if there is none
2407
2477
  */
2408
- hasMatchingRows: boolean;
2409
- pending: boolean;
2410
- error: string | null;
2411
- }
2412
-
2413
- /**
2414
- * The row numbers in the order of the grid, the table by its handle
2415
- */
2416
- export interface ComputationOrderingTable {
2417
- dataTable: number;
2418
- rows: number;
2419
- dataFrame: number;
2420
- inputRowNumberColumnName: string;
2421
- orderingConstraints: ComputationOrderBy[];
2422
- version: ComputationVersionValue;
2423
- dataSearchRequestId: number | null;
2424
- }
2425
-
2426
- /**
2427
- * How a setup runs
2428
- */
2429
- export interface SetupOptions {
2478
+ conflict: ImportConflict | null;
2430
2479
  /**
2431
- * The params of the setup, the params of the connection by default
2480
+ * The connections that the user decides on
2432
2481
  */
2433
- params?: JsonParams;
2482
+ questions: ImportQuestion[];
2434
2483
  /**
2435
- * The params that the channel connects with when they differ from the ones that the connection keeps, e.g. the
2436
- * credentials of the environment that are never written
2484
+ * The catalog files that didn't parse and were left out
2437
2485
  */
2438
- channelParams?: JsonParams;
2486
+ invalidCatalogs: string[];
2439
2487
  /**
2440
- * Log in again instead of using a session of the browser
2488
+ * False when unusable entries were removed from the file lists of the workbook file
2441
2489
  */
2442
- forceRelogin?: boolean;
2490
+ filesValid: boolean;
2443
2491
  /**
2444
- * The redirect page of the app that an OAuth flow of Salesforce returns to
2492
+ * The folder of a native workbook that is registered in place, null for a copy
2445
2493
  */
2446
- oauthRedirect?: string;
2494
+ nativePath: string | null;
2447
2495
  }
2448
2496
 
2449
- /**
2450
- * The tokens and the user of a login
2451
- */
2452
- export interface SetupAuthentication {
2453
- tokens: { core: any; dataCloud: any };
2454
- userInfo: any | null;
2497
+
2498
+ /** What hears a run of a workbook */
2499
+ export interface RunListener {
2500
+ /** Something happened to a script of the run, a failure comes with what the platform failed with */
2501
+ script?(file: string, event: WorkbookScriptRunEvent, error: unknown): void;
2502
+ /** Set up a connection that statements run on before the first statement, e.g. with the credentials of the command line tool. The scripts of a connection whose setup rejects are skipped. A run with it takes every connection of the workbook. */
2503
+ prepareConnection?(connectionId: string): Promise<void>;
2455
2504
  }
2456
2505
 
2506
+
2457
2507
  /**
2458
- * How a setup or a login ended
2508
+ * The versions of the storage format of the module: of the storage root and of workbook files
2459
2509
  */
2460
- export interface SetupOutcome {
2461
- status: 'succeeded' | 'failed' | 'cancelled';
2462
- /**
2463
- * The error of a setup that didn't succeed
2464
- */
2465
- message: string | null;
2510
+ export interface StorageVersions {
2466
2511
  /**
2467
- * The details of the error, e.g. the status of a rejected request
2512
+ * The storage version of the app, `storageVersion` of the manifest
2468
2513
  */
2469
- data: Record<string, string>;
2514
+ storageVersion: number;
2470
2515
  /**
2471
- * The tokens of a login
2516
+ * The workbook format version of the app, `formatVersion` of a workbook file
2472
2517
  */
2473
- authentication: SetupAuthentication | null;
2518
+ formatVersion: number;
2474
2519
  }
2475
2520
 
2476
2521
  /**
2477
- * What the executor does around a query besides running its text
2522
+ * What a migration of the storage changed, with the versions it migrated to
2478
2523
  */
2479
- export interface QueryOptions {
2524
+ export interface StorageMigrationOutcome {
2480
2525
  /**
2481
- * Analyze the result on the compute database, false by default
2526
+ * The storage steps that ran
2482
2527
  */
2483
- analyzeResults?: boolean;
2528
+ steps: number;
2484
2529
  /**
2485
- * Collect the result, true by default. A statement whose output nothing reads drains it.
2530
+ * The workbook folders that were brought to the current workbook format
2486
2531
  */
2487
- publishResults?: boolean;
2532
+ workbooks: number;
2488
2533
  /**
2489
- * Reject with the error of a failed query instead of resolving
2534
+ * The storage version of the app
2490
2535
  */
2491
- throwOnError?: boolean;
2536
+ storageVersion: number;
2492
2537
  /**
2493
- * A call of a client function that runs instead of the text, as the core describes it
2538
+ * The workbook format version of the app
2494
2539
  */
2495
- clientFunctionCall?: JsonValue;
2540
+ formatVersion: number;
2541
+ }
2542
+
2543
+
2544
+ /** A file to attach to a workbook, with the name it was dropped with */
2545
+ export interface AttachedFile {
2546
+ name: string;
2547
+ file: Blob | Uint8Array;
2548
+ }
2549
+
2550
+
2551
+ /**
2552
+ * What an attach did
2553
+ */
2554
+ export interface AttachFilesOutcome {
2496
2555
  /**
2497
- * The time to wait for the next batch of a channel of the host, the default of the channel without
2556
+ * The attachments that were written or wait for a hold of the workbook, in the order of the files
2498
2557
  */
2499
- readTimeoutMs?: number;
2558
+ attached: AttachedFileName[];
2500
2559
  /**
2501
- * The query result cache, none for a query that never reads or writes it
2560
+ * The files that are no attachments (Parquet files only), by their names
2502
2561
  */
2503
- cache?: QueryCacheOptions;
2562
+ refused: string[];
2504
2563
  }
2505
2564
 
2506
2565
  /**
2507
- * How a query uses the query result cache
2566
+ * A file that was attached, with the name it got
2508
2567
  */
2509
- export interface QueryCacheOptions {
2510
- /**
2511
- * The semantic signature of the script that the key of the result derives from, with the params of the connection
2512
- */
2513
- signature: string;
2568
+ export interface AttachedFileName {
2514
2569
  /**
2515
- * Run the query instead of serving a cached result, the result becomes the newest file of its key
2570
+ * The name the file was dropped with
2516
2571
  */
2517
- refresh?: boolean;
2572
+ name: string;
2518
2573
  /**
2519
- * Serve the cached result or fail with a cache miss instead of running the query
2574
+ * The file name of the attachment, its table parameter takes no name of a script or another attachment
2520
2575
  */
2521
- only?: boolean;
2576
+ fileName: string;
2577
+ }
2578
+
2579
+
2580
+ /** The slices of the runtime by kind: the id of a slice, its view, and the keys of the payloads of its view that the host holds */
2581
+ export interface RuntimeViews {
2582
+ computation: { id: number; view: ComputationView; known: undefined };
2583
+ connectionList: { id: 'root'; view: ConnectionListView; known: undefined };
2584
+ connection: { id: string; view: ConnectionView; known: undefined };
2585
+ query: { id: number; view: QueryView; known: (QueryProfileKeys | null)[] };
2586
+ workbookList: { id: 'root'; view: WorkbookListView; known: undefined };
2587
+ workbook: { id: string; view: WorkbookView; known: undefined };
2588
+ script: { id: number; view: WorkbookScriptView; known: (WorkbookScriptKeys | null)[] };
2589
+ workbookDerived: { id: string; view: WorkbookDerivedView; known: undefined };
2590
+ storage: { id: 'root'; view: StorageView; known: undefined };
2591
+ run: { id: string; view: WorkbookRunView; known: undefined };
2592
+ }
2593
+ /** A kind of slices of the runtime */
2594
+ export type ViewKind = keyof RuntimeViews;
2595
+ /** The id of a slice of a kind */
2596
+ export type ViewId<K extends ViewKind> = RuntimeViews[K]['id'];
2597
+ /** The view of a slice of a kind */
2598
+ export type ViewOf<K extends ViewKind> = RuntimeViews[K]['view'];
2599
+ /** The keys of the payloads that the host holds, they don't cross again */
2600
+ export type KnownKeys<K extends ViewKind> = RuntimeViews[K]['known'];
2601
+ /** The read of a slice that a task of the runtime holds: it moves with the next changes, the host keeps its view */
2602
+ export type BusyView = 'busy';
2603
+ export interface Runtime {
2604
+ /** The views of the slices of a kind, null for a slice that is gone, `'busy'` for one that a task holds. One crossing per kind and flush. */
2605
+ views<K extends ViewKind>(kind: K, ids: ViewId<K>[], known?: KnownKeys<K>): (ViewOf<K> | BusyView | null)[];
2522
2606
  }
2523
2607
 
2608
+
2524
2609
  /**
2525
- * The failure of a query, `hostValue` tells whether `value` of the outcome is what the host failed with
2610
+ * The slice that an action changes
2526
2611
  */
2527
- export interface QueryRunFailure {
2528
- kind: QueryRunFailureKind;
2529
- message: string;
2530
- details: Record<string, string>;
2531
- target: string;
2532
- hostValue: boolean;
2612
+ export type Target = { computation: number } | { connection: string } | { workbook: string } | "app";
2613
+
2614
+ /**
2615
+ * The actions of the runtime. An action changes the state in the call and returns its outcome; a failed action leaves
2616
+ * the state as it was.
2617
+ */
2618
+ export type RuntimeAction = { kind: "deleteComputation" } | { kind: "orderBy"; value: { constraints: ComputationOrderBy[] } } | { kind: "histogramFilter"; value: { columnGroup: number; selection: [number, number] | null } } | { kind: "mostFrequentValueFilter"; value: { columnGroup: number; valueId: number | null } } | { kind: "clearCrossFilters" } | { kind: "setResultSearchPattern"; value: { search: ComputationSearchKind; pattern: string } } | { kind: "requestFilteredColumnAggregation"; value: { columnGroup: number } } | { kind: "createConnection"; value: { connectionId?: string; connectorType: ConnectorType; setupParams?: JsonParams; active?: boolean; params?: JsonParams; paramsDraft?: JsonParams; name?: string; cacheQueryResults?: boolean } } | { kind: "createWorkbook"; value: { workbookId?: string; connectionId: string; name?: string; ephemeral?: boolean; originalFileName?: string } } | { kind: "deleteWorkbook"; value: { workbookId: string } } | { kind: "createScript"; value: { index?: number; text?: string; base: string; connectionId?: string } } | { kind: "deleteScript"; value: { fileName: string } } | { kind: "renameScript"; value: { fileName: string; newName: string } } | { kind: "reorderScripts"; value: { order: string[] } } | { kind: "setScriptText"; value: { scriptKey: number; text: string; withDiff?: boolean } } | { kind: "acceptPendingDiff"; value: { scriptKey: number } } | { kind: "rejectPendingDiff"; value: { scriptKey: number } } | { kind: "setScriptVisSpec"; value: { scriptKey: number; spec: string } } | { kind: "setWorkbookInput"; value: { name: string; literal: string; scriptKeys: number[] } } | { kind: "analyzeOutdatedScript"; value: { scriptKey: number } } | { kind: "showScript"; value: { scriptKey: number; selected: boolean } } | { kind: "hideScript"; value: { scriptKey: number; selected: boolean } } | { kind: "renameWorkbook"; value: { name?: string } } | { kind: "setScriptConnection"; value: { fileName: string; connectionId: string } } | { kind: "setPendingConnection"; value: { connectionId: string } } | { kind: "replaceConnection"; value: { from: string; into: string } } | { kind: "detachConnection"; value: { from: string; into: string } } | { kind: "setWorkbookAttachments"; value: { files: WorkbookDataFile[] } } | { kind: "setCloudLink"; value: { link?: JsonValue } } | { kind: "setDraft"; value: { params: JsonParams } } | { kind: "discardDraft" } | { kind: "rename"; value: { name: string } } | { kind: "setQueryResultCaching"; value: { caching: boolean } } | { kind: "deleteConnection" } | { kind: "resetConnection" } | { kind: "relationsTouched"; value: { names: ConnectionTableName[] } } | { kind: "queryCacheDeleted"; value: { queryId: number } };
2619
+
2620
+ /**
2621
+ * The id of a slice or of what an action created: a number or a string
2622
+ */
2623
+ export type SliceId = number | string;
2624
+
2625
+ /**
2626
+ * A slice that changed since the host took the changes, its revision is null if it went
2627
+ */
2628
+ export interface SliceChange {
2629
+ kind: ViewKind;
2630
+ id: SliceId;
2631
+ revision: number | null;
2533
2632
  }
2534
2633
 
2535
2634
  /**
2536
- * A query that runs: its id and its outcome
2635
+ * The changes since the host took them last: the changed slices and the effects on handles, in order
2537
2636
  */
2538
- export interface QueryTicket {
2539
- queryId: number;
2540
- done: Promise<QueryRunOutcome>;
2637
+ export interface ChangeSet {
2638
+ changes: SliceChange[];
2639
+ effects: HandleEffect[];
2541
2640
  }
2542
2641
 
2543
2642
  /**
2544
- * A query that the runtime runs
2643
+ * What a dispatch did
2545
2644
  */
2546
- export interface QueryArgs {
2645
+ export interface DispatchOutcome {
2547
2646
  /**
2548
- * The text of the query as the history shows it
2647
+ * Was the action applied? A failed action leaves the state as it was.
2549
2648
  */
2550
- text: string;
2551
- metadata: QueryMetadataView;
2649
+ ok: boolean;
2552
2650
  /**
2553
- * The trace and the span of the log messages of the query
2651
+ * Did the action change the state?
2554
2652
  */
2555
- traceId: number;
2556
- spanId?: number;
2653
+ changed: boolean;
2557
2654
  /**
2558
- * What the executor does around the query
2655
+ * The error of a failed action
2559
2656
  */
2560
- options?: QueryOptions;
2657
+ error: string | null;
2658
+ /**
2659
+ * What the action created: the id of a connection or of a query
2660
+ */
2661
+ id: SliceId | null;
2561
2662
  }
2562
2663
 
2563
- /**
2564
- * The kind of the failure of a query
2565
- */
2566
- export type QueryRunFailureKind = "error" | "cancelled" | "cacheMiss" | "processing";
2567
-
2568
- /**
2569
- * What the caller of a query hears while it runs: the timings and the result before its analysis
2570
- */
2571
- export type QueryCallerEvent = { type: "timing"; label: string; elapsedMs: number } | { type: "resultsReady" };
2572
-
2573
- /**
2574
- * How a query ended for its caller: resolved with the result table, or rejected with the failure and what the host
2575
- * failed with
2576
- */
2577
- export type QueryRunOutcome = { status: "resolved"; hasResult: boolean; table: unknown } | { status: "rejected"; failure: QueryRunFailure; value: unknown };
2578
-
2579
2664
  /**
2580
2665
  * The type of a column of a workbook table
2581
2666
  */
@@ -2687,91 +2772,6 @@ export interface ExportOptions {
2687
2772
  linkBase?: string;
2688
2773
  }
2689
2774
 
2690
- /**
2691
- * What a restore restored: the connections and the workbooks that the runtime took, in order, the workbooks that were
2692
- * refused a load and the progress
2693
- */
2694
- export interface RestoreOutcome {
2695
- connectionIds: string[];
2696
- workbookIds: string[];
2697
- invalidWorkbooks: RestoredInvalidWorkbook[];
2698
- progress: RestoreProgress;
2699
- }
2700
-
2701
- /**
2702
- * A counter of the progress of a step of a restore
2703
- */
2704
- export interface RestoreProgressCounter {
2705
- started: number;
2706
- succeeded: number;
2707
- skipped: number;
2708
- failed: number;
2709
- /**
2710
- * Null until the total is known
2711
- */
2712
- total: number | null;
2713
- }
2714
-
2715
- /**
2716
- * A script file of a workbook
2717
- */
2718
- export interface RestoreScriptFile {
2719
- name: string;
2720
- sql: string;
2721
- }
2722
-
2723
- /**
2724
- * The progress of a restore
2725
- */
2726
- export interface RestoreProgress {
2727
- restoreConnections: RestoreProgressCounter;
2728
- restoreCatalogs: RestoreProgressCounter;
2729
- restoreWorkbookScripts: RestoreProgressCounter;
2730
- }
2731
-
2732
- /**
2733
- * A workbook that failed its validation or couldn't be restored
2734
- */
2735
- export interface RestoredInvalidWorkbook {
2736
- workbookId: string;
2737
- title: string;
2738
- connectorType: ConnectorType | null;
2739
- /**
2740
- * The code of the validation error, e.g. `unsupported_format_version`
2741
- */
2742
- error: string;
2743
- /**
2744
- * A short explanation of the error for the user
2745
- */
2746
- description: string;
2747
- }
2748
-
2749
- /**
2750
- * The outcome of saving a connection
2751
- */
2752
- export interface ConnectionSaveOutcome {
2753
- /**
2754
- * The saved params
2755
- */
2756
- params: JsonParams;
2757
- /**
2758
- * The outcome of writing the app manifest
2759
- */
2760
- manifest: StorageWriteOutcome;
2761
- /**
2762
- * The outcomes of writing the copies of the workbooks, none if the manifest wasn't written
2763
- */
2764
- workbooks: ConnectionCopyOutcome[];
2765
- }
2766
-
2767
- /**
2768
- * The outcome of writing the copy of a connection into a workbook
2769
- */
2770
- export interface ConnectionCopyOutcome {
2771
- workbookId: string;
2772
- result: StorageWriteOutcome;
2773
- }
2774
-
2775
2775
  /**
2776
2776
  * A catalog (`dashql_catalog_*`)
2777
2777
  */
@@ -3165,6 +3165,12 @@ export class Runtime {
3165
3165
  * answer to an older question is ignored.
3166
3166
  */
3167
3167
  answerExternalChange(workbook_id: string, prompt: number, reload?: boolean | null): void;
3168
+ /**
3169
+ * The relations file of the catalog of a connection, the text of its `dashql-catalog-relations.sql`: the tables that
3170
+ * the connection reported as `CREATE TABLE` statements. The tab writes it into the copies of an agent session. None
3171
+ * for an unknown connection, while a task holds it, and after a reset of the catalog.
3172
+ */
3173
+ catalogRelationsFile(connection_id: string): string | undefined;
3168
3174
  /**
3169
3175
  * Check the folders of workbooks that the platform keeps in folders of their own for changes outside the app, e.g.
3170
3176
  * when the window gets the focus. The checks run one at a time after the ones that are queued. A change of the
@@ -3835,80 +3841,6 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
3835
3841
 
3836
3842
  export interface InitOutput {
3837
3843
  readonly memory: WebAssembly.Memory;
3838
- readonly __wbg_runtime_free: (a: number, b: number) => void;
3839
- readonly runtime_allocateId: (a: number) => [number, number, number];
3840
- readonly runtime_analyzeTable: (a: number, b: number, c: number, d: any) => [number, number, number];
3841
- readonly runtime_answerExternalChange: (a: number, b: number, c: number, d: number, e: number) => void;
3842
- readonly runtime_applyEditorEvent: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number, number];
3843
- readonly runtime_attachFiles: (a: number, b: number, c: number, d: any) => [number, number, number];
3844
- readonly runtime_attachTableParameters: (a: number, b: number, c: number, d: number) => [number, number, number];
3845
- readonly runtime_authenticateSalesforce: (a: number, b: number, c: number, d: any, e: number, f: any) => [number, number, number];
3846
- readonly runtime_cancelQuery: (a: number, b: number) => [number, number, number];
3847
- readonly runtime_cancelSetup: (a: number, b: number, c: number) => void;
3848
- readonly runtime_catalog: (a: number, b: number, c: number) => number;
3849
- readonly runtime_catalogId: (a: number, b: number, c: number) => [number, number];
3850
- readonly runtime_checkWorkbookFolders: (a: number, b: number, c: number) => void;
3851
- readonly runtime_closeSession: (a: number, b: number, c: number, d: number) => void;
3852
- readonly runtime_commitImport: (a: number, b: number, c: any, d: any) => [number, number, number];
3853
- readonly runtime_connectionParamsLoginHint: (a: any) => [number, number, number, number];
3854
- readonly runtime_connectionParamsShareEqual: (a: any, b: any) => number;
3855
- readonly runtime_connectionParamsWithoutDraftRows: (a: any) => [number, number, number];
3856
- readonly runtime_create: (a: any) => number;
3857
- readonly runtime_defaultConnectionParams: (a: number) => [number, number, number];
3858
- readonly runtime_deleteInvalidWorkbook: (a: number, b: number, c: number) => any;
3859
- readonly runtime_dispatch: (a: number, b: any, c: any) => any;
3860
- readonly runtime_dropImport: (a: number, b: number) => void;
3861
- readonly runtime_executeQuery: (a: number, b: number, c: number, d: any, e: any, f: any) => [number, number, number];
3862
- readonly runtime_exportConnection: (a: number, b: number, c: number, d: any) => [number, number, number];
3863
- readonly runtime_exportWorkbook: (a: number, b: number, c: number, d: any, e: any) => [number, number, number];
3864
- readonly runtime_exportedResults: (a: number, b: number, c: number) => any;
3865
- readonly runtime_flushCacheWrites: (a: number) => any;
3866
- readonly runtime_followQueryProgress: (a: number, b: number, c: number, d: number) => [number, number, number];
3867
- readonly runtime_functionScriptText: (a: number, b: number, c: number) => [number, number, number, number];
3868
- readonly runtime_hyperCloudDefaultDatabaseName: () => [number, number];
3869
- readonly runtime_isAnalysisOutdated: (a: number, b: number) => number;
3870
- readonly runtime_isWorkbookHeld: (a: number, b: number, c: number) => number;
3871
- readonly runtime_matchesStoredScripts: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
3872
- readonly runtime_migrateStorage: (a: any, b: any) => any;
3873
- readonly runtime_migrateWorkbookFolder: (a: number, b: number, c: number) => any;
3874
- readonly runtime_openSession: (a: number, b: number, c: number) => number;
3875
- readonly runtime_previewResult: (a: number, b: number, c: number) => [number, number, number];
3876
- readonly runtime_queryProgressRecording: (a: number, b: number) => [number, number, number, number];
3877
- readonly runtime_readImport: (a: number, b: any) => any;
3878
- readonly runtime_refreshAttachments: (a: number, b: number, c: number) => any;
3879
- readonly runtime_refreshCatalog: (a: number, b: number, c: number, d: number) => void;
3880
- readonly runtime_renameAttachment: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
3881
- readonly runtime_restore: (a: number, b: any) => [number, number, number];
3882
- readonly runtime_restoreWorkbook: (a: number, b: number, c: number) => [number, number, number];
3883
- readonly runtime_resultKeys: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
3884
- readonly runtime_resync: (a: number, b: number, c: number, d: any) => [number, number];
3885
- readonly runtime_retrySave: (a: number, b: number, c: number, d: number, e: number) => any;
3886
- readonly runtime_revealConnectionSecrets: (a: number, b: number, c: number) => [number, number, number];
3887
- readonly runtime_runCatalogLoader: (a: number, b: number) => void;
3888
- readonly runtime_runScript: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
3889
- readonly runtime_runWorkbook: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
3890
- readonly runtime_salesforceCatalogDatabase: () => [number, number];
3891
- readonly runtime_sanitizeConnectionParams: (a: any, b: number) => [number, number, number];
3892
- readonly runtime_saveConnection: (a: number, b: number, c: number, d: number) => [number, number, number];
3893
- readonly runtime_scriptSession: (a: number, b: number) => number;
3894
- readonly runtime_setProgressLayout: (a: number, b: number) => [number, number];
3895
- readonly runtime_setUpOpenedWorkbook: (a: number, b: number, c: number) => void;
3896
- readonly runtime_settleCatalog: (a: number, b: number, c: number, d: number, e: number) => any;
3897
- readonly runtime_setupConnection: (a: number, b: number, c: number, d: number) => [number, number, number];
3898
- readonly runtime_shutdown: (a: number) => any;
3899
- readonly runtime_stopRun: (a: number, b: number, c: number) => void;
3900
- readonly runtime_storage: (a: number, b: any) => [number, number, number];
3901
- readonly runtime_storageDiscardWrites: (a: number, b: number, c: number) => void;
3902
- readonly runtime_storageHold: (a: number, b: any, c: number, d: number) => [number, number];
3903
- readonly runtime_storageRelease: (a: number, b: any, c: number, d: number) => [number, number];
3904
- readonly runtime_storageStatistics: (a: number, b: number, c: number) => [number, number, number];
3905
- readonly runtime_storageVersions: () => [number, number, number];
3906
- readonly runtime_takeChanges: (a: number) => [number, number, number];
3907
- readonly runtime_testCatalog: (a: number, b: number, c: number) => number;
3908
- readonly runtime_testHold: (a: number, b: number, c: number, d: any) => [number, number, number];
3909
- readonly runtime_views: (a: number, b: number, c: number, d: any, e: any) => [number, number, number];
3910
- readonly runtime_watchProfile: (a: number, b: number, c: number) => [number, number];
3911
- readonly runtime_workbookTables: () => [number, number, number];
3912
3844
  readonly __wbg_queryprogressfollower_free: (a: number, b: number) => void;
3913
3845
  readonly queryprogressfollower_new: (a: number) => [number, number, number];
3914
3846
  readonly replayQueryProgress: (a: number, b: number, c: number, d: number) => [number, number, number];
@@ -4106,10 +4038,85 @@ export interface InitOutput {
4106
4038
  readonly workbookscriptsession_textVersion: (a: number) => [bigint, number, number];
4107
4039
  readonly shellpromptresult_cursorByteOffset: (a: number) => number;
4108
4040
  readonly shellpromptresult_revision: (a: number) => bigint;
4109
- readonly wasm_bindgen__convert__closures_____invoke__ha7a2b373f2a9ce09: (a: number, b: number, c: any) => any;
4110
- readonly wasm_bindgen__closure__destroy__h74bdb7d22b702b82: (a: number, b: number) => void;
4041
+ readonly __wbg_runtime_free: (a: number, b: number) => void;
4042
+ readonly runtime_allocateId: (a: number) => [number, number, number];
4043
+ readonly runtime_analyzeTable: (a: number, b: number, c: number, d: any) => [number, number, number];
4044
+ readonly runtime_answerExternalChange: (a: number, b: number, c: number, d: number, e: number) => void;
4045
+ readonly runtime_applyEditorEvent: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number, number];
4046
+ readonly runtime_attachFiles: (a: number, b: number, c: number, d: any) => [number, number, number];
4047
+ readonly runtime_attachTableParameters: (a: number, b: number, c: number, d: number) => [number, number, number];
4048
+ readonly runtime_authenticateSalesforce: (a: number, b: number, c: number, d: any, e: number, f: any) => [number, number, number];
4049
+ readonly runtime_cancelQuery: (a: number, b: number) => [number, number, number];
4050
+ readonly runtime_cancelSetup: (a: number, b: number, c: number) => void;
4051
+ readonly runtime_catalog: (a: number, b: number, c: number) => number;
4052
+ readonly runtime_catalogId: (a: number, b: number, c: number) => [number, number];
4053
+ readonly runtime_catalogRelationsFile: (a: number, b: number, c: number) => [number, number];
4054
+ readonly runtime_checkWorkbookFolders: (a: number, b: number, c: number) => void;
4055
+ readonly runtime_closeSession: (a: number, b: number, c: number, d: number) => void;
4056
+ readonly runtime_commitImport: (a: number, b: number, c: any, d: any) => [number, number, number];
4057
+ readonly runtime_connectionParamsLoginHint: (a: any) => [number, number, number, number];
4058
+ readonly runtime_connectionParamsShareEqual: (a: any, b: any) => number;
4059
+ readonly runtime_connectionParamsWithoutDraftRows: (a: any) => [number, number, number];
4060
+ readonly runtime_create: (a: any) => number;
4061
+ readonly runtime_defaultConnectionParams: (a: number) => [number, number, number];
4062
+ readonly runtime_deleteInvalidWorkbook: (a: number, b: number, c: number) => any;
4063
+ readonly runtime_dispatch: (a: number, b: any, c: any) => any;
4064
+ readonly runtime_dropImport: (a: number, b: number) => void;
4065
+ readonly runtime_executeQuery: (a: number, b: number, c: number, d: any, e: any, f: any) => [number, number, number];
4066
+ readonly runtime_exportConnection: (a: number, b: number, c: number, d: any) => [number, number, number];
4067
+ readonly runtime_exportWorkbook: (a: number, b: number, c: number, d: any, e: any) => [number, number, number];
4068
+ readonly runtime_exportedResults: (a: number, b: number, c: number) => any;
4069
+ readonly runtime_flushCacheWrites: (a: number) => any;
4070
+ readonly runtime_followQueryProgress: (a: number, b: number, c: number, d: number) => [number, number, number];
4071
+ readonly runtime_functionScriptText: (a: number, b: number, c: number) => [number, number, number, number];
4072
+ readonly runtime_hyperCloudDefaultDatabaseName: () => [number, number];
4073
+ readonly runtime_isAnalysisOutdated: (a: number, b: number) => number;
4074
+ readonly runtime_isWorkbookHeld: (a: number, b: number, c: number) => number;
4075
+ readonly runtime_matchesStoredScripts: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
4076
+ readonly runtime_migrateStorage: (a: any, b: any) => any;
4077
+ readonly runtime_migrateWorkbookFolder: (a: number, b: number, c: number) => any;
4078
+ readonly runtime_openSession: (a: number, b: number, c: number) => number;
4079
+ readonly runtime_previewResult: (a: number, b: number, c: number) => [number, number, number];
4080
+ readonly runtime_queryProgressRecording: (a: number, b: number) => [number, number, number, number];
4081
+ readonly runtime_readImport: (a: number, b: any) => any;
4082
+ readonly runtime_refreshAttachments: (a: number, b: number, c: number) => any;
4083
+ readonly runtime_refreshCatalog: (a: number, b: number, c: number, d: number) => void;
4084
+ readonly runtime_renameAttachment: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number];
4085
+ readonly runtime_restore: (a: number, b: any) => [number, number, number];
4086
+ readonly runtime_restoreWorkbook: (a: number, b: number, c: number) => [number, number, number];
4087
+ readonly runtime_resultKeys: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
4088
+ readonly runtime_resync: (a: number, b: number, c: number, d: any) => [number, number];
4089
+ readonly runtime_retrySave: (a: number, b: number, c: number, d: number, e: number) => any;
4090
+ readonly runtime_revealConnectionSecrets: (a: number, b: number, c: number) => [number, number, number];
4091
+ readonly runtime_runCatalogLoader: (a: number, b: number) => void;
4092
+ readonly runtime_runScript: (a: number, b: number, c: number, d: number, e: number) => [number, number, number];
4093
+ readonly runtime_runWorkbook: (a: number, b: number, c: number, d: number, e: any) => [number, number, number];
4094
+ readonly runtime_salesforceCatalogDatabase: () => [number, number];
4095
+ readonly runtime_sanitizeConnectionParams: (a: any, b: number) => [number, number, number];
4096
+ readonly runtime_saveConnection: (a: number, b: number, c: number, d: number) => [number, number, number];
4097
+ readonly runtime_scriptSession: (a: number, b: number) => number;
4098
+ readonly runtime_setProgressLayout: (a: number, b: number) => [number, number];
4099
+ readonly runtime_setUpOpenedWorkbook: (a: number, b: number, c: number) => void;
4100
+ readonly runtime_settleCatalog: (a: number, b: number, c: number, d: number, e: number) => any;
4101
+ readonly runtime_setupConnection: (a: number, b: number, c: number, d: number) => [number, number, number];
4102
+ readonly runtime_shutdown: (a: number) => any;
4103
+ readonly runtime_stopRun: (a: number, b: number, c: number) => void;
4104
+ readonly runtime_storage: (a: number, b: any) => [number, number, number];
4105
+ readonly runtime_storageDiscardWrites: (a: number, b: number, c: number) => void;
4106
+ readonly runtime_storageHold: (a: number, b: any, c: number, d: number) => [number, number];
4107
+ readonly runtime_storageRelease: (a: number, b: any, c: number, d: number) => [number, number];
4108
+ readonly runtime_storageStatistics: (a: number, b: number, c: number) => [number, number, number];
4109
+ readonly runtime_storageVersions: () => [number, number, number];
4110
+ readonly runtime_takeChanges: (a: number) => [number, number, number];
4111
+ readonly runtime_testCatalog: (a: number, b: number, c: number) => number;
4112
+ readonly runtime_testHold: (a: number, b: number, c: number, d: any) => [number, number, number];
4113
+ readonly runtime_views: (a: number, b: number, c: number, d: any, e: any) => [number, number, number];
4114
+ readonly runtime_watchProfile: (a: number, b: number, c: number) => [number, number];
4115
+ readonly runtime_workbookTables: () => [number, number, number];
4111
4116
  readonly wasm_bindgen__convert__closures_____invoke__hc9cbe033348e018d: (a: number, b: number, c: any) => void;
4112
4117
  readonly wasm_bindgen__closure__destroy__he52a6c160ad8bcc6: (a: number, b: number) => void;
4118
+ readonly wasm_bindgen__convert__closures_____invoke__ha7a2b373f2a9ce09: (a: number, b: number, c: any) => any;
4119
+ readonly wasm_bindgen__closure__destroy__h74bdb7d22b702b82: (a: number, b: number) => void;
4113
4120
  readonly wasm_bindgen__convert__closures_____invoke__h3cb6850919769fd7: (a: number, b: number, c: any, d: any) => void;
4114
4121
  readonly __wbindgen_malloc: (a: number, b: number) => number;
4115
4122
  readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;