@finos/legend-cube-builder 0.0.4 → 0.0.5

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]));
+  }
+};

package/src/stores/CubeGridFetcher.ts

@@ -0,0 +1,302 @@
+/**
+ * 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 {
+  buildSchemasAndValidity,
+  checkDrilldown,
+  type ColumnDirection,
+  deriveDrilldownLevel,
+  type DrilldownCell,
+  type DrilldownLevel,
+  printIR,
+  QueryEmitter,
+  SortDirection,
+} from '@finos/legend-cube';
+import { NULL_CELL_TEXT } from '../__lib__/LegendCubeLabels.js';
+import {
+  CubeEngineError,
+  CubeEngineErrorKind,
+  type CubeResultValue,
+} from '../graph-manager/CubeEngine.js';
+import type { CubeEditorState } from './CubeEditorState.js';
+import type { CubeExecutionResult } from './CubeExecutionState.js';
+import { type CubeQueryRunResult, runCubeQuery } from './CubeQueryRun.js';
+
+/** A row of a level, by the run's column positions */
+export interface CubeGridRow {
+  /** Each run column's value, `undefined` where the level shows none (a group row's column with no aggregation) */
+  readonly cells: readonly (CubeResultValue | undefined)[];
+  /** On a group row, how many of the run's rows the group holds */
+  readonly count?: number | undefined;
+}
+
+/** The rows of one level of the grid: the run's rows, or groups of them */
+export interface CubeGridLevelRows {
+  readonly level: DrilldownLevel;
+  readonly rows: readonly CubeGridRow[];
+  /** The engine returned more than the run's row limit */
+  readonly limited: boolean;
+}
+
+/** An answer for rows the grid no longer shows: a newer run, or the grid purged its rows; it is dropped */
+export class CubeGridFetchDropped extends Error {
+  constructor() {
+    super('The rows were asked for by a grid that no longer shows them');
+    this.name = 'CubeGridFetchDropped';
+  }
+}
+
+/** The most rows the cache holds across its levels; the oldest levels go first (PLAN §11.10) */
+export const MAX_CUBE_GRID_CACHED_ROWS = 200_000;
+
+export const CUBE_GRID_CONTEXT_CHANGED =
+  "The cube's model, runtime or warehouse changed since this run: execute again to see more of its rows.";
+
+interface CachedLevel {
+  readonly promise: Promise<CubeGridLevelRows>;
+  /** Its rows, once answered; 0 until then */
+  rows: number;
+}
+
+/** How a fetch is shown in the run stats, e.g. `Rows of SHIP_COUNTRY "France"` */
+const describeFetch = (
+  level: DrilldownLevel,
+  keys: readonly DrilldownCell[],
+  levels: readonly string[],
+  sorts: readonly ColumnDirection[],
+): string => {
+  const of = keys
+    .map(
+      (key, index) =>
+        `${levels[index]} ${key === null ? NULL_CELL_TEXT : JSON.stringify(String(key))}`,
+    )
+    .join(', ');
+  const sorted = sorts
+    .map(
+      ({ column, direction }) =>
+        `${column} ${direction === SortDirection.DESC ? 'descending' : 'ascending'}`,
+    )
+    .join(', ');
+  return [
+    level.isLeaf ? 'Rows' : `Groups by ${level.groupColumns.at(-1)}`,
+    of ? ` of ${of}` : '',
+    sorted ? `, sorted by ${sorted}` : '',
+  ].join('');
+};
+
+/**
+ * Fetches the levels of the grid's server-side mode (PLAN §11.10): each a
+ * query derived from the run on screen, never the live cube, with the
+ * drill-down the cube has now and the grid's sort, run as Execute runs
+ * (`runCubeQuery`), with the run's model, runtime and row limit. Answers are
+ * cached by the derived query, the oldest dropped past
+ * `MAX_CUBE_GRID_CACHED_ROWS` rows. `purge()` drops them all, aborts the
+ * fetches in flight and drops their answers, as a new run does.
+ */
+export class CubeGridFetcher {
+  readonly editorState: CubeEditorState;
+  /** The most rows the cache holds */
+  readonly maxCachedRows: number;
+  /** Bumped by each purge: an answer of an older generation is dropped */
+  private generation = 0;
+  private resultId: number | undefined;
+  /** In the order last used, the oldest first */
+  private readonly cache = new Map<string, CachedLevel>();
+  private readonly controllers = new Set<AbortController>();
+
+  constructor(
+    editorState: CubeEditorState,
+    maxCachedRows = MAX_CUBE_GRID_CACHED_ROWS,
+  ) {
+    this.editorState = editorState;
+    this.maxCachedRows = maxCachedRows;
+  }
+
+  /** How many rows the cache holds */
+  get cachedRows(): number {
+    return Array.from(this.cache.values()).reduce(
+      (total, cached) => total + cached.rows,
+      0,
+    );
+  }
+
+  /** Drops every cached level, and aborts the fetches in flight, whose answers are then dropped */
+  purge(): void {
+    this.generation += 1;
+    this.cache.clear();
+    this.controllers.forEach((controller) => controller.abort());
+    this.controllers.clear();
+  }
+
+  /**
+   * The rows of the level under the expanded groups' keys (outermost first;
+   * none for the top level), sorted by the grid. Rejects with a
+   * `CubeEngineError`, or a `CubeGridFetchDropped` when the answer is for rows
+   * the grid no longer shows.
+   */
+  fetchLevel(
+    result: CubeExecutionResult,
+    keys: readonly DrilldownCell[],
+    sorts: readonly ColumnDirection[],
+  ): Promise<CubeGridLevelRows> {
+    if (result.id !== this.resultId) {
+      this.purge();
+      this.resultId = result.id;
+    }
+    const { editorState } = this;
+    const model = result.context?.model;
+    const runtime = result.context?.runtime;
+    const captureId = result.query.selected;
+    if (!model || !runtime || captureId === undefined) {
+      return Promise.reject(
+        new Error('A run has a model, a runtime and a node'),
+      );
+    }
+    // the warehouse is read from the page when the query runs, so a fetch
+    // under another one would run the run's query elsewhere
+    if (
+      result.context !== editorState.document.context ||
+      result.warehouse !== editorState.dataProductRuntime.effectiveWarehouse
+    ) {
+      return Promise.reject(
+        new CubeEngineError(
+          CubeEngineErrorKind.EXECUTION,
+          CUBE_GRID_CONTEXT_CHANGED,
+          captureId,
+        ),
+      );
+    }
+    let level: DrilldownLevel;
+    const drilldown = checkDrilldown(
+      editorState.document.meta.drilldown ?? { columns: [], aggregations: [] },
+      result.schema,
+    );
+    try {
+      level = deriveDrilldownLevel({
+        query: result.query,
+        captureId,
+        schema: result.schema,
+        drilldown,
+        keys,
+        sorts,
+      });
+    } catch (error) {
+      return Promise.reject(
+        new CubeEngineError(
+          CubeEngineErrorKind.EXECUTION,
+          error instanceof Error ? error.message : String(error),
+          captureId,
+        ),
+      );
+    }
+    const runId = level.query.selected as string;
+    // Cube's own checks first, so the engine never gets a query Cube knows is wrong
+    const { schemas, validity } = buildSchemasAndValidity(
+      level.query,
+      editorState.registry.queryRules,
+    );
+    const problem = (validity.get(runId) ?? [])[0];
+    const schema = schemas.get(runId);
+    if (problem !== undefined || !schema) {
+      return Promise.reject(
+        new CubeEngineError(
+          CubeEngineErrorKind.EXECUTION,
+          `These rows can't be fetched: ${problem ?? 'the query has no columns'}`,
+          captureId,
+        ),
+      );
+    }
+    // the whole run, so a sort the row order keeps is in it
+    const key = printIR(
+      new QueryEmitter(level.query, editorState.registry).emitExecutionLambda({
+        rowLimit: result.rowLimit,
+        runtime,
+      }),
+    );
+    const cached = this.cache.get(key);
+    if (cached) {
+      // last used now
+      this.cache.delete(key);
+      this.cache.set(key, cached);
+      return cached.promise;
+    }
+    const generation = this.generation;
+    const controller = new AbortController();
+    this.controllers.add(controller);
+    const entry: CachedLevel = {
+      rows: 0,
+      promise: runCubeQuery(editorState, {
+        query: level.query,
+        model,
+        runtime,
+        schema,
+        rowLimit: result.rowLimit,
+        abortController: controller,
+        label: describeFetch(level, keys, drilldown.columns, sorts),
+      })
+        .then((run: CubeQueryRunResult): CubeGridLevelRows => {
+          if (generation !== this.generation) {
+            throw new CubeGridFetchDropped();
+          }
+          const positions = result.schema.columns.map(({ name }) => {
+            const output = level.columns.get(name);
+            return output === undefined
+              ? -1
+              : schema.columns.findIndex((column) => column.name === output);
+          });
+          const countAt = level.countColumn
+            ? schema.columns.findIndex(
+                (column) => column.name === level.countColumn,
+              )
+            : -1;
+          const rows = run.rows.map(
+            (row): CubeGridRow => ({
+              cells: positions.map((position) =>
+                position === -1 ? undefined : (row[position] ?? null),
+              ),
+              ...(countAt === -1 ? {} : { count: Number(row[countAt]) }),
+            }),
+          );
+          entry.rows = rows.length;
+          this.evict(key);
+          return { level, rows, limited: run.limited };
+        })
+        .catch((error: unknown) => {
+          if (this.cache.get(key) === entry) {
+            this.cache.delete(key);
+          }
+          throw generation !== this.generation
+            ? new CubeGridFetchDropped()
+            : error;
+        })
+        .finally(() => this.controllers.delete(controller)),
+    };
+    this.cache.set(key, entry);
+    return entry.promise;
+  }
+
+  /** Drops the least recently used levels until the cache holds at most its rows, never the one just answered */
+  private evict(keep: string): void {
+    for (const [key] of this.cache) {
+      if (this.cachedRows <= this.maxCachedRows) {
+        return;
+      }
+      if (key !== keep) {
+        this.cache.delete(key);
+      }
+    }
+  }
+}