@finos/legend-cube-builder 0.0.4 → 0.0.6

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';
+};

package/src/stores/CubeExtendTyping.ts

@@ -15,18 +15,15 @@
  */
 
 import {
-  buildSchemasAndValidity,
   colSpec,
   colSpecArray,
   EmitRole,
-  ERR_TYPING,
-  Extend,
+  type Extend,
   type ExtendTyping,
   func,
   getExtendSignature,
   hashText,
   type IR,
-  isTypingError,
   type JsonObject,
   lambda,
   lambdaJson,
@@ -36,7 +33,6 @@ import {
   printIR,
   type Query,
   QueryEmitter,
-  type QueryRule,
   type Schema,
   stableJsonText,
 } from '@finos/legend-cube';
@@ -116,10 +112,11 @@ const digestModel = (model: ModelContext): string => {
 };
 
 /**
- * What the engine is given for an Extend's input when it types it, digested
- * (PLAN §11.7): the input's relation as emitted, and the model. A typing
- * records it (`upstream`), since the engine sees more than Cube's schema
- * does; `undefined` when the input can't be emitted, e.g. it is invalid.
+ * What the engine is given for a node's input when it types an Extend or
+ * checks a Filter by Expression, digested (PLAN §11.7, §11.11): the input's
+ * relation as emitted, and the model. A typing or a check records it
+ * (`upstream`), since the engine sees more than Cube's schema does;
+ * `undefined` when the input can't be emitted, e.g. it is invalid.
  */
 export const getCubeExtendUpstream = (
   emitter: QueryEmitter,
@@ -162,43 +159,6 @@ export const isCubeExtendTypingCurrent = (
   );
 };
 
-/**
- * A query rule for the editor (PLAN §11.7): an Extend whose typing recorded
- * another input than the engine would be given now waits to be typed again
- * (`ERR_TYPING`), e.g. after an Extend above it gains `->toOne()`, which
- * Cube's schema doesn't show. A typing that recorded nothing, as one loaded,
- * is used as it is; an Extend that already waits, or whose input is invalid,
- * is left to its own checks.
- */
-export const createStaleCubeExtendTypingRule =
-  (
-    registry: NodeRegistry,
-    modelOf: () => ModelContext | undefined,
-  ): QueryRule =>
-  (query) => {
-    const stale = new Map<string, readonly string[]>();
-    const model = modelOf();
-    const recorded = query.nodes.filter(
-      (node): node is Extend =>
-        node instanceof Extend && upstreamOf(node.typing) !== undefined,
-    );
-    if (!model || !recorded.length) {
-      return stale;
-    }
-    const { validity } = buildSchemasAndValidity(query, registry.queryRules);
-    const emitter = new QueryEmitter(query, registry);
-    recorded.forEach((node) => {
-      if ((validity.get(node.id) ?? []).some(isTypingError)) {
-        return;
-      }
-      const upstream = getCubeExtendUpstream(emitter, node.id, model);
-      if (upstream !== undefined && upstream !== upstreamOf(node.typing)) {
-        stale.set(node.id, [ERR_TYPING]);
-      }
-    });
-    return stale;
-  };
-
 /** What typing an Extend gave: the typing to store, and the error the engine gave, if it failed */
 export interface CubeExtendTypingResult {
   readonly typing: ExtendTyping;

package/src/stores/CubeFunctionRecheck.ts

@@ -0,0 +1,97 @@
+/**
+ * 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 {
+  emitFunctionSource,
+  type EnteredValue,
+  type FunctionSource,
+  getLiteralKinds,
+  type IR,
+  lambda,
+  type LiteralValue,
+  type ModelContext,
+  type Schema,
+} from '@finos/legend-cube';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+  type CubeEngine,
+  type NodeId,
+} from '../graph-manager/CubeEngine.js';
+
+/** A value of each kind, which only types the call: a function's columns don't depend on its values */
+const PLACEHOLDERS: Readonly<Record<LiteralValue['kind'], LiteralValue>> = {
+  string: { kind: 'string', value: '' },
+  boolean: { kind: 'boolean', value: false },
+  integer: { kind: 'integer', value: '0' },
+  float: { kind: 'float', value: '0' },
+  decimal: { kind: 'decimal', value: '0' },
+  strictDate: { kind: 'strictDate', value: '2000-01-01' },
+  dateTime: { kind: 'dateTime', value: '2000-01-01T00:00:00' },
+  enum: { kind: 'enum', value: '' },
+};
+
+/**
+ * The lambda that types a function source, `{| sales::ordersAbove(…)}`: its
+ * values where they are valid, else a placeholder of the parameter's type, or
+ * `[]` for an empty optional one
+ */
+export const buildCubeFunctionTypingLambda = (source: FunctionSource): IR => {
+  const values: EnteredValue[] = source.parameters.map((parameter, index) => {
+    const value = source.values[index];
+    if (value !== undefined && value.kind !== 'invalid') {
+      return value;
+    }
+    if (value === undefined && parameter.optional) {
+      return undefined;
+    }
+    const [kind] = getLiteralKinds(parameter.type);
+    return kind ? PLACEHOLDERS[kind] : undefined;
+  });
+  return lambda([], [emitFunctionSource(source.withValues(values))]);
+};
+
+/**
+ * Types a cube's functions again with the engine (PLAN §6.5), in one call:
+ * their columns as the engine types the call. One answer per source,
+ * failures included; never rejects.
+ */
+export const recheckCubeFunctionSources = async (
+  engine: CubeEngine,
+  model: ModelContext,
+  sources: readonly FunctionSource[],
+): Promise<Map<NodeId, Schema | CubeEngineError>> => {
+  try {
+    return await engine.typeLambdas(
+      model,
+      new Map(
+        sources.map((source) => [
+          source.id,
+          buildCubeFunctionTypingLambda(source),
+        ]),
+      ),
+    );
+  } catch (error) {
+    const failure =
+      error instanceof CubeEngineError
+        ? error
+        : new CubeEngineError(
+            CubeEngineErrorKind.NETWORK,
+            error instanceof Error ? error.message : String(error),
+          );
+    return new Map(sources.map((source) => [source.id, failure]));
+  }
+};