@finos/legend-cube-builder 0.0.3 → 0.0.5

package/src/stores/CubeExecutionState.ts

@@ -15,27 +15,21 @@
  */
 
 import {
+  type CubeContext,
   isSchemasError,
-  needsDatabaseType,
   type Query,
   type Schema,
 } from '@finos/legend-cube';
 import { assertErrorThrown, type GeneratorFn } from '@finos/legend-shared';
-import {
-  action,
-  computed,
-  flow,
-  flowResult,
-  makeObservable,
-  observable,
-} from 'mobx';
+import { action, computed, flow, makeObservable, observable } from 'mobx';
 import {
   CubeEngineError,
   CubeEngineErrorKind,
-  type CubeResult,
   type CubeResultValue,
 } from '../graph-manager/CubeEngine.js';
+import { CUBE_RUN_LABEL } from '../__lib__/LegendCubeLabels.js';
 import type { CubeEditorState } from './CubeEditorState.js';
+import { type CubeQueryRunResult, runCubeQuery } from './CubeQueryRun.js';
 
 /** What the grid shows of a run: the rows within the limit, under the schema the run was made with */
 export interface CubeExecutionResult {
@@ -43,6 +37,10 @@ export interface CubeExecutionResult {
   readonly id: number;
   /** The query that ran: results are stale once the document holds another */
   readonly query: Query;
+  /** The context it ran in: results are stale once the document holds another, e.g. another warehouse */
+  readonly context: CubeContext | undefined;
+  /** The warehouse a data product cube ran on, its own or the viewer's: results are stale once another is used */
+  readonly warehouse: string | undefined;
   /** The capture node's schema when the run started; the grid's columns, by position */
   readonly schema: Schema;
   /** At most `rowLimit` rows */
@@ -120,12 +118,15 @@ export class CubeExecutionState {
     return this.runController !== undefined;
   }
 
-  /** The shown result no longer matches the query or the row limit; it is kept until the next run */
+  /** The shown result no longer matches the query, the context or the row limit; it is kept until the next run */
   get isStale(): boolean {
     return (
       this.result !== undefined &&
       !this.isRunning &&
       (this.result.query !== this.editorState.document.query ||
+        this.result.context !== this.editorState.document.context ||
+        this.result.warehouse !==
+          this.editorState.dataProductRuntime.effectiveWarehouse ||
         this.result.rowLimit !== this.editorState.rowLimit)
     );
   }
@@ -149,8 +150,14 @@ export class CubeExecutionState {
     }
     const captureId = query.selected;
     if (captureId === undefined) {
-      reasons.push('Select the node to run.');
-    } else if (!emitter.canEmit(captureId)) {
+      reasons.push(
+        'Pick the step to run: Run this step, from its menu or editor.',
+      );
+    } else if (
+      !emitter.canEmit(captureId) ||
+      // as the editor sees it: an Extend typed for another input waits
+      (analysis.validity.get(captureId) ?? []).length > 0
+    ) {
       reasons.push(findUpstreamError(query, analysis.validity, captureId));
     }
     return reasons;
@@ -164,8 +171,9 @@ export class CubeExecutionState {
     if (this.isRunning || !this.canExecute) {
       return;
     }
-    const { document, emitter, analysis, rowLimit, host } = this.editorState;
+    const { document, analysis, rowLimit } = this.editorState;
     const { query, context } = document;
+    const warehouse = this.editorState.dataProductRuntime.effectiveWarehouse;
     // checked by canExecute
     const captureId = query.selected as string;
     const model = context?.model;
@@ -179,62 +187,33 @@ export class CubeExecutionState {
     this.runController = controller;
     this.error = undefined;
     this.editorState.clearHostIssues();
+    // an export's failure is of the run it exported
+    this.editorState.export.clearError();
     try {
-      // a Drop, Slice, Limit or Distinct is written for the database it runs on
-      // (PLAN §11.4), which the model's outline gives: loaded once, waited
-      // for only then; the query, model and runtime are the ones captured
-      let databaseType: string | undefined;
-      if (needsDatabaseType(query, captureId)) {
-        yield flowResult(this.editorState.loadModelOutline(model));
-        if (this.runController !== controller || controller.signal.aborted) {
-          return;
-        }
-        databaseType = this.editorState.getRunDatabaseType(
-          query,
-          captureId,
-          model,
-          runtime,
-        );
-      }
-      const lambda = emitter.emitExecutionLambda({
-        rowLimit,
+      // the query, model and runtime are the ones captured
+      const run = (yield runCubeQuery(this.editorState, {
+        query,
+        model,
         runtime,
-        databaseType,
-      });
-      const response = (yield host.engine.execute(model, lambda, {
+        schema,
+        rowLimit,
         abortController: controller,
-      })) as CubeResult;
+        label: CUBE_RUN_LABEL.EXECUTE,
+      })) as CubeQueryRunResult;
       if (this.runController !== controller) {
         return;
       }
-      // rows are read by position, so the engine's columns must be the query's
-      if (response.columns.length !== schema.columns.length) {
-        throw new CubeEngineError(
-          CubeEngineErrorKind.EXECUTION,
-          `The engine returned ${response.columns.length} columns, but the query has ${schema.columns.length}`,
-          captureId,
-        );
-      }
-      const misplaced = schema.columns.findIndex(
-        (column, position) => response.columns[position] !== column.name,
-      );
-      if (misplaced !== -1) {
-        throw new CubeEngineError(
-          CubeEngineErrorKind.EXECUTION,
-          `The engine returned the column "${response.columns[misplaced]}" at position ${misplaced + 1}, but the query has "${schema.columns[misplaced]?.name}" there`,
-          captureId,
-        );
-      }
-      const limited = response.rows.length > rowLimit;
       this.result = {
         id: ++this.runCount,
         query,
+        context,
+        warehouse,
         schema,
-        rows: limited ? response.rows.slice(0, rowLimit) : response.rows,
+        rows: run.rows,
         rowLimit,
-        limited,
-        sql: response.sql,
-        durationMs: response.durationMs,
+        limited: run.limited,
+        sql: run.sql,
+        durationMs: run.durationMs,
       };
     } catch (error) {
       // a stopped or replaced run shows nothing
@@ -252,9 +231,13 @@ export class CubeExecutionState {
             );
       // the rows of an earlier run are never shown as this run's
       this.result = undefined;
-      // an error belongs to the query it came from: one that changed while
-      // the run was in flight drops it, as an edit after the run would
-      if (this.editorState.document.query === query) {
+      // an error belongs to the query and the context it came from: one
+      // that changed while the run was in flight drops it, as an edit after
+      // the run would
+      if (
+        this.editorState.document.query === query &&
+        this.editorState.document.context === context
+      ) {
         this.error = engineError;
         this.editorState.setHostIssue(
           engineError.nodeId ?? captureId,
@@ -282,6 +265,11 @@ export class CubeExecutionState {
   /** Stops any run and forgets the last one's rows and error, e.g. when another cube is opened */
   reset(): void {
     this.stop();
+    this.editorState.gridFetcher.purge();
+    this.editorState.export.stop();
+    // an export's failure is of the run it exported (review of M7)
+    this.editorState.export.clearError();
+    this.editorState.grid.closeSettings();
     this.result = undefined;
     this.error = undefined;
   }

package/src/stores/CubeExportState.ts

@@ -0,0 +1,196 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  checkDrilldown,
+  type ColumnDirection,
+  deriveDrilldownLevel,
+  type IR,
+  needsDatabaseType,
+  QueryEmitter,
+} from '@finos/legend-cube';
+import {
+  assertErrorThrown,
+  ContentType,
+  downloadFileUsingDataURI,
+  type GeneratorFn,
+} from '@finos/legend-shared';
+import {
+  action,
+  computed,
+  flow,
+  flowResult,
+  makeObservable,
+  observable,
+} from 'mobx';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+} from '../graph-manager/CubeEngine.js';
+import { CUBE_RUN_LABEL } from '../__lib__/LegendCubeLabels.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+import type { CubeExecutionResult } from './CubeExecutionState.js';
+
+export const CUBE_EXPORT_CONTEXT_CHANGED =
+  "The cube's model, runtime or warehouse changed since this run: execute again to export it.";
+
+/** A file name for a cube's export, from its name, e.g. `Largest_buys.csv` */
+export const getCubeExportFileName = (
+  name: string | undefined,
+  extension: 'csv' | 'xlsx',
+): string => {
+  const base = name?.trim().replace(/[^\w.-]+/gu, '_') ?? '';
+  return `${base.length ? base : 'cube'}.${extension}`;
+};
+
+/**
+ * The results' export (spec §12.5, PLAN §11.10): CSV of the whole query,
+ * run on the engine with no row limit, sorted as the grid is, saved by the
+ * browser. Only the run on screen is exported, in the context it ran in. A
+ * failure is kept for the grid region; Stop aborts the export.
+ */
+export class CubeExportState {
+  readonly editorState: CubeEditorState;
+  error: CubeEngineError | undefined;
+  private controller: AbortController | undefined;
+
+  constructor(editorState: CubeEditorState) {
+    makeObservable<CubeExportState, 'controller'>(this, {
+      error: observable.ref,
+      controller: observable.ref,
+      isExporting: computed,
+      exportCsv: flow,
+      stop: action,
+      clearError: action,
+    });
+    this.editorState = editorState;
+  }
+
+  get isExporting(): boolean {
+    return this.controller !== undefined;
+  }
+
+  /** The run's whole query as CSV, sorted as the grid is (by the run's column names) */
+  *exportCsv(
+    result: CubeExecutionResult,
+    sorts: readonly ColumnDirection[] = [],
+  ): GeneratorFn<void> {
+    const { editorState } = this;
+    const model = result.context?.model;
+    const runtime = result.context?.runtime;
+    const captureId = result.query.selected;
+    if (this.isExporting || !model || !runtime || captureId === undefined) {
+      return;
+    }
+    this.error = undefined;
+    // the warehouse is read from the page when the query runs
+    if (
+      result.context !== editorState.document.context ||
+      result.warehouse !== editorState.dataProductRuntime.effectiveWarehouse
+    ) {
+      this.error = new CubeEngineError(
+        CubeEngineErrorKind.EXECUTION,
+        CUBE_EXPORT_CONTEXT_CHANGED,
+        captureId,
+      );
+      return;
+    }
+    const controller = new AbortController();
+    this.controller = controller;
+    const startedAt = Date.now();
+    // kept for the Runs panel, once written (PLAN §11.16)
+    let lambda: IR | undefined;
+    try {
+      // the run's rows, sorted as the grid is: no drill-down level
+      const { query } = deriveDrilldownLevel({
+        query: result.query,
+        captureId,
+        schema: result.schema,
+        drilldown: checkDrilldown(
+          { columns: [], aggregations: [] },
+          result.schema,
+        ),
+        keys: [],
+        sorts,
+      });
+      const runId = query.selected as string;
+      let databaseType: string | undefined;
+      if (needsDatabaseType(query, runId)) {
+        yield flowResult(editorState.loadModelOutline(model));
+        databaseType = editorState.getRunDatabaseType(
+          query,
+          runId,
+          model,
+          runtime,
+        );
+      }
+      if (controller.signal.aborted) {
+        return;
+      }
+      lambda = new QueryEmitter(
+        query,
+        editorState.registry,
+      ).emitExecutionLambda({ runtime, databaseType });
+      const csv = (yield editorState.host.engine.exportCsv(model, lambda, {
+        abortController: controller,
+      })) as string;
+      // stopped while it ran: `stop()` lets go of it
+      if (this.controller !== controller) {
+        return;
+      }
+      downloadFileUsingDataURI(
+        getCubeExportFileName(editorState.document.name, 'csv'),
+        csv,
+        ContentType.TEXT_CSV,
+      );
+      editorState.runStats.record(CUBE_RUN_LABEL.EXPORT_CSV, {
+        durationMs: Date.now() - startedAt,
+        lambda,
+      });
+    } catch (error) {
+      if (controller.signal.aborted) {
+        return;
+      }
+      assertErrorThrown(error);
+      this.error =
+        error instanceof CubeEngineError
+          ? error
+          : new CubeEngineError(
+              CubeEngineErrorKind.EXECUTION,
+              error.message,
+              captureId,
+            );
+      editorState.runStats.record(CUBE_RUN_LABEL.EXPORT_CSV, {
+        durationMs: Date.now() - startedAt,
+        lambda,
+        error: this.error.firstLine,
+      });
+    } finally {
+      if (this.controller === controller) {
+        this.controller = undefined;
+      }
+    }
+  }
+
+  stop(): void {
+    this.controller?.abort();
+    this.controller = undefined;
+  }
+
+  clearError(): void {
+    this.error = undefined;
+  }
+}

package/src/stores/CubeExpressionFilterCheck.ts

@@ -0,0 +1,218 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {
+  colSpec,
+  colSpecArray,
+  EmitRole,
+  type ExpressionCheck,
+  type ExpressionFilter,
+  foldColumnName,
+  func,
+  getExpressionFilterSignature,
+  type IR,
+  type JsonObject,
+  lambda,
+  lambdaJson,
+  type NodeRegistry,
+  originOf,
+  type Query,
+  QueryEmitter,
+  Schema,
+  type SchemaColumn,
+  TypeFamily,
+} from '@finos/legend-cube';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+  type NodeId,
+} from '../graph-manager/CubeEngine.js';
+import { withoutEngineContext } from './CubeExtendTyping.js';
+
+// Checking a Filter by Expression's condition with the engine (PLAN §11.11):
+// its input's relation, as Cube types any node, then `filter` with the
+// condition. A condition that isn't one Boolean fails there with no location
+// and the whole relation type, so the same call types the condition alone,
+// as an extend column, which gives its type for Cube's own message.
+
+/** The key of the lambda that filters the input with the condition */
+const filterKeyOf = (filterId: string): NodeId => `${filterId}#filter`;
+
+/** The key of the lambda that types the condition alone, as an extend column */
+const conditionKeyOf = (filterId: string): NodeId => `${filterId}#condition`;
+
+/** A name for the condition typed alone that no input column has, as databases that ignore case compare names */
+export const getConditionColumnName = (input: Schema): string => {
+  const taken = new Set(input.names().map(foldColumnName));
+  let name = 'cube_condition';
+  for (let suffix = 2; taken.has(foldColumnName(name)); suffix += 1) {
+    name = `cube_condition_${suffix}`;
+  }
+  return name;
+};
+
+/**
+ * The lambdas that check a condition, by key: the input's relation filtered
+ * with it, and the input's relation extended with it under a name no input
+ * column has. A located lambda keeps its locations, so an error points into
+ * its text; a stored one is marked with the filter, so an error lands on it.
+ * The input must be valid.
+ */
+export const buildCubeConditionCheckLambdas = (
+  query: Query,
+  filter: ExpressionFilter,
+  condition: JsonObject,
+  input: Schema,
+  registry: NodeRegistry,
+  located: boolean,
+): Map<NodeId, IR> => {
+  const [inputId] = query.getInputIds(filter.id);
+  if (inputId === undefined) {
+    throw new Error(
+      `Filter by expression "${filter.id}" has no input to check it on`,
+    );
+  }
+  const relation = new QueryEmitter(query, registry).emitRelation(inputId);
+  const origin = located ? undefined : originOf(filter.id, EmitRole.EXPRESSION);
+  return new Map<NodeId, IR>([
+    [
+      filterKeyOf(filter.id),
+      lambda([], [func('filter', [relation, lambdaJson(condition, origin)])]),
+    ],
+    [
+      conditionKeyOf(filter.id),
+      lambda(
+        [],
+        [
+          func('extend', [
+            relation,
+            colSpecArray([
+              colSpec(
+                getConditionColumnName(input),
+                lambdaJson(condition, origin),
+              ),
+            ]),
+          ]),
+        ],
+      ),
+    ],
+  ]);
+};
+
+/** A condition's type as the message names it: `Integer`, `Boolean[0..1]` */
+const describeConditionType = (column: SchemaColumn): string =>
+  `${column.type.displayName}${column.nullable ? '[0..1]' : ''}`;
+
+/** What checking a condition gave: the check to store, and the error the engine gave, if it failed */
+export interface CubeConditionCheckResult {
+  readonly check: ExpressionCheck;
+  readonly error?: CubeEngineError | undefined;
+}
+
+/**
+ * The check the engine's answers give, for this input and this condition:
+ * checked when the filter types; else failed, with the condition's type when
+ * it types alone but isn't one Boolean, and the engine's error: the
+ * condition's own when it fails alone, as it names no `filter`, else the
+ * filter's (a network failure when there is neither)
+ */
+export const readCubeConditionCheck = (
+  answers: ReadonlyMap<NodeId, Schema | CubeEngineError>,
+  filter: ExpressionFilter,
+  input: Schema,
+  upstream: string | undefined,
+): CubeConditionCheckResult => {
+  const signature = getExpressionFilterSignature(input, filter.lambda);
+  const filtered = answers.get(filterKeyOf(filter.id));
+  if (filtered instanceof Schema) {
+    return { check: { kind: 'checked', signature, upstream } };
+  }
+  const alone = answers.get(conditionKeyOf(filter.id));
+  const conditionColumn =
+    alone instanceof Schema ? alone.columns.at(-1) : undefined;
+  const resultType =
+    conditionColumn &&
+    !(
+      conditionColumn.type.family === TypeFamily.BOOLEAN &&
+      !conditionColumn.nullable
+    )
+      ? describeConditionType(conditionColumn)
+      : undefined;
+  const error =
+    (alone instanceof CubeEngineError ? alone : undefined) ??
+    filtered ??
+    new CubeEngineError(
+      CubeEngineErrorKind.NETWORK,
+      'The engine gave no answer for this condition',
+      filter.id,
+    );
+  return {
+    check: {
+      kind: 'failed',
+      signature,
+      message: withoutEngineContext(error.detail),
+      resultType,
+      upstream,
+    },
+    error,
+  };
+};
+
+/** The digest of what the engine was given for the input, which the check recorded */
+export const getCubeConditionCheckUpstream = (
+  check: ExpressionCheck,
+): string | undefined =>
+  check.kind === 'unresolved' ? undefined : check.upstream;
+
+/**
+ * Whether the filter's check says its condition is one Boolean for this
+ * input: checked, for this schema and this condition, and for this input as
+ * the engine is given it, or recorded without it, as when loaded
+ */
+export const isCubeConditionCheckCurrent = (
+  filter: ExpressionFilter,
+  input: Schema,
+  upstream: string | undefined,
+): boolean => {
+  const { check } = filter;
+  const recorded = getCubeConditionCheckUpstream(check);
+  return (
+    check.kind === 'checked' &&
+    filter.currentCheck(input) === check &&
+    (recorded === undefined || recorded === upstream)
+  );
+};
+
+/** Whether two checks say the same: the same kind, signature and input as the engine was given it, and the same failure */
+export const isSameCubeConditionCheck = (
+  a: ExpressionCheck,
+  b: ExpressionCheck,
+): boolean => {
+  if (getCubeConditionCheckUpstream(a) !== getCubeConditionCheckUpstream(b)) {
+    return false;
+  }
+  if (a.kind === 'checked' && b.kind === 'checked') {
+    return a.signature === b.signature;
+  }
+  if (a.kind === 'failed' && b.kind === 'failed') {
+    return (
+      a.signature === b.signature &&
+      a.message === b.message &&
+      a.resultType === b.resultType
+    );
+  }
+  return a.kind === 'unresolved' && b.kind === 'unresolved';
+};