@finos/legend-cube-builder 0.0.4 → 0.0.6

package/src/stores/editors/CubePivotDraft.ts

@@ -0,0 +1,355 @@
+/**
+ * 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 {
+  AggregationFunction,
+  ColumnComparisonFilter,
+  Distinct,
+  Filter,
+  FilterOperator,
+  foldColumnName,
+  getLiteralText,
+  isValidColumnName,
+  type LiteralValue,
+  parseValue,
+  Pivot,
+  type PivotAggregation,
+  PIVOT_MAX_VALUES,
+  Restrict,
+  Schema,
+  Sort,
+  SortDirection,
+  TypeFamily,
+} from '@finos/legend-cube';
+import type { GeneratorFn } from '@finos/legend-shared';
+import { action, flow, makeObservable, observable } from 'mobx';
+import {
+  CubeEngineError,
+  type CubeResultValue,
+} from '../../graph-manager/CubeEngine.js';
+import type { CubeEditorState } from '../CubeEditorState.js';
+import { type CubeQueryRunResult, runCubeQuery } from '../CubeQueryRun.js';
+import {
+  CUBE_RUN_LABEL,
+  PIVOT_VALUE_DISABLED_REASON,
+} from '../../__lib__/LegendCubeLabels.js';
+import { isSameList, toggledColumns } from './CubeAggregationRows.js';
+import { CubeNodeDraft } from './CubeNodeDraft.js';
+
+/** The pivot column's values the engine gave, in its order, and whether it had more */
+export interface CubePivotLoadedValues {
+  readonly column: string;
+  readonly values: readonly LiteralValue[];
+  readonly more: boolean;
+}
+
+const sameValue = (a: LiteralValue, b: LiteralValue): boolean =>
+  a.kind === b.kind && a.value === b.value;
+
+/**
+ * A value of the column's type from what the engine gave for a cell: a
+ * Boolean as itself, else its text read as the type, a date-time's date part
+ * for a StrictDate; `undefined` for an empty value, which can't be listed,
+ * or text that isn't one
+ */
+export const toPivotValue = (
+  cell: CubeResultValue,
+  schema: Schema,
+  column: string,
+): LiteralValue | undefined => {
+  const type = schema.type(column);
+  if (cell === null || !type) {
+    return undefined;
+  }
+  if (typeof cell === 'boolean') {
+    return { kind: 'boolean', value: cell };
+  }
+  const text =
+    type.family === TypeFamily.STRICT_DATE
+      ? String(cell).slice(0, 10)
+      : String(cell);
+  const value = parseValue(text, type);
+  return value === undefined || value.kind === 'invalid' ? undefined : value;
+};
+
+/**
+ * The Pivot editor's draft (PLAN §11.12): its row columns, ticked, kept in
+ * the input's order; its pivot column; its values, loaded from the engine and
+ * ticked, kept in the order the engine lists them; its aggregation. Picking
+ * another pivot column drops the values, which were the other column's;
+ * Count rows takes no column, the other functions one.
+ */
+export class CubePivotDraft extends CubeNodeDraft<Pivot> {
+  readonly editorState: CubeEditorState;
+  rows: readonly string[];
+  column: string;
+  values: readonly LiteralValue[];
+  aggregation: PivotAggregation;
+  /** The values the engine gave for the pivot column, once loaded */
+  loaded: CubePivotLoadedValues | undefined;
+  loading = false;
+  /** Why the values couldn't be loaded */
+  loadError: string | undefined;
+  /** The load on its way, for this pivot column; picking another abandons it */
+  private load:
+    | { readonly column: string; readonly abortController: AbortController }
+    | undefined;
+  /** Anything was changed; until then, `build()` gives the original back */
+  private touched = false;
+
+  constructor(original: Pivot, editorState: CubeEditorState) {
+    super(original);
+    makeObservable<CubePivotDraft, 'touched'>(this, {
+      rows: observable.ref,
+      column: observable,
+      values: observable.ref,
+      aggregation: observable.ref,
+      loaded: observable.ref,
+      loading: observable,
+      loadError: observable,
+      touched: observable,
+      toggleRow: action,
+      clearRows: action,
+      setColumn: action,
+      toggleValue: action,
+      pickAllValues: action,
+      clearValues: action,
+      setFunction: action,
+      setAggregationColumn: action,
+      loadValues: flow,
+    });
+    this.editorState = editorState;
+    this.rows = original.rows;
+    this.column = original.column;
+    this.values = original.values;
+    this.aggregation = original.aggregation;
+  }
+
+  toggleRow(name: string, schema: Schema): void {
+    this.rows = toggledColumns(this.rows, name, schema);
+    this.touched = true;
+  }
+
+  clearRows(): void {
+    this.rows = [];
+    this.touched = true;
+  }
+
+  /**
+   * Picks the pivot column; another column's values, picked or loaded, are
+   * dropped, and a load on its way for it is abandoned, so its values never
+   * show under this one
+   */
+  setColumn(column: string): void {
+    if (column === this.column) {
+      return;
+    }
+    this.column = column;
+    this.values = [];
+    this.loaded = undefined;
+    this.loadError = undefined;
+    this.load?.abortController.abort();
+    this.load = undefined;
+    this.loading = false;
+    this.touched = true;
+  }
+
+  /** Values in the order the engine listed them, then those it didn't list, as they were */
+  private ordered(values: readonly LiteralValue[]): LiteralValue[] {
+    const listed = this.loaded?.values ?? [];
+    return [
+      ...listed.filter((value) => values.some((v) => sameValue(v, value))),
+      ...values.filter((value) => !listed.some((v) => sameValue(v, value))),
+    ];
+  }
+
+  /** Ticks or unticks a value */
+  toggleValue(value: LiteralValue): void {
+    this.values = this.ordered(
+      this.values.some((picked) => sameValue(picked, value))
+        ? this.values.filter((picked) => !sameValue(picked, value))
+        : [...this.values, value],
+    );
+    this.touched = true;
+  }
+
+  /**
+   * Why a value can't be ticked, given those ticked: its text can't name a
+   * column (`isValidColumnName`), another ticked value differs from it only in
+   * case, or `PIVOT_MAX_VALUES` are ticked already (the core refuses each,
+   * PLAN §11.12); `undefined` when it can, or is ticked
+   */
+  untickableReason(
+    value: LiteralValue,
+    ticked: readonly LiteralValue[] = this.values,
+  ): string | undefined {
+    const text = getLiteralText(value);
+    return !isValidColumnName(text)
+      ? PIVOT_VALUE_DISABLED_REASON.NOT_A_COLUMN_NAME
+      : ticked.some(
+            (other) =>
+              !sameValue(other, value) &&
+              foldColumnName(getLiteralText(other)) === foldColumnName(text),
+          )
+        ? PIVOT_VALUE_DISABLED_REASON.DIFFERS_ONLY_IN_CASE
+        : ticked.length >= PIVOT_MAX_VALUES &&
+            !ticked.some((other) => sameValue(other, value))
+          ? PIVOT_VALUE_DISABLED_REASON.TOO_MANY
+          : undefined;
+  }
+
+  /** Ticks every value loaded that can be, in the engine's order, keeping those picked */
+  pickAllValues(): void {
+    this.values = this.ordered(
+      (this.loaded?.values ?? []).reduce<readonly LiteralValue[]>(
+        (ticked, value) =>
+          ticked.some((picked) => sameValue(picked, value)) ||
+          this.untickableReason(value, ticked) !== undefined
+            ? ticked
+            : [...ticked, value],
+        this.values,
+      ),
+    );
+    this.touched = true;
+  }
+
+  clearValues(): void {
+    this.values = [];
+    this.touched = true;
+  }
+
+  /** Picks the function: Count rows takes no column; another function keeps one, or one to pick */
+  setFunction(fn: string): void {
+    const { column } = this.aggregation;
+    this.aggregation = {
+      function: fn,
+      column:
+        fn === AggregationFunction.COUNT_ROWS ? undefined : (column ?? ''),
+    };
+    this.touched = true;
+  }
+
+  setAggregationColumn(column: string): void {
+    this.aggregation = { ...this.aggregation, column };
+    this.touched = true;
+  }
+
+  /**
+   * Asks the engine for the pivot column's values (PLAN §11.12): the input's
+   * relation, the column alone, its non-empty values (an empty value can't be
+   * listed, and would take the row that tells whether there are more), each
+   * once, ascending, at most `PIVOT_MAX_VALUES`, run on the cube's runtime as a
+   * run is, written for its database. A load abandoned for another pivot
+   * column (`setColumn`) leaves the draft alone.
+   */
+  *loadValues(): GeneratorFn<void> {
+    const { editorState, column } = this;
+    const { context, query } = editorState.document;
+    const [inputId] = query.getInputIds(this.original.id);
+    const input =
+      inputId === undefined
+        ? undefined
+        : editorState.analysis.schemas.get(inputId);
+    const pivotColumn = column ? input?.lookup(column) : undefined;
+    if (
+      this.loading ||
+      context?.runtime === undefined ||
+      inputId === undefined ||
+      !input ||
+      !pivotColumn
+    ) {
+      return;
+    }
+    const load = { column, abortController: new AbortController() };
+    this.load = load;
+    this.loading = true;
+    this.loadError = undefined;
+    try {
+      const restrict = new Restrict(query.generateId(Restrict.TYPE), [column]);
+      const nonEmpty = new Filter(
+        query.generateId(Filter.TYPE),
+        new ColumnComparisonFilter(column, FilterOperator.IS_NOT_EMPTY),
+      );
+      const distinct = new Distinct(query.generateId(Distinct.TYPE));
+      const sort = new Sort(query.generateId(Sort.TYPE), [
+        { column, direction: SortDirection.ASC },
+      ]);
+      // each after the one before, off the pivot's input, the last selected
+      // (an add after the selected node selects it); the query isn't kept
+      const values = [restrict, nonEmpty, distinct, sort].reduce(
+        (built, node) => built.add(node, built.selected),
+        query.selected === inputId ? query : query.select(inputId),
+      );
+      const result = (yield runCubeQuery(editorState, {
+        query: values,
+        model: context.model,
+        runtime: context.runtime,
+        schema: new Schema([pivotColumn]),
+        rowLimit: PIVOT_MAX_VALUES,
+        abortController: load.abortController,
+        label: CUBE_RUN_LABEL.pivotValues(column),
+      })) as CubeQueryRunResult;
+      if (this.load !== load) {
+        return;
+      }
+      this.loaded = {
+        column,
+        values: result.rows
+          .map((row) => toPivotValue(row[0] ?? null, input, column))
+          .filter((value): value is LiteralValue => value !== undefined),
+        more: result.limited,
+      };
+    } catch (error) {
+      if (this.load === load) {
+        this.loadError =
+          error instanceof CubeEngineError
+            ? error.firstLine
+            : error instanceof Error
+              ? error.message
+              : String(error);
+      }
+    } finally {
+      if (this.load === load) {
+        this.load = undefined;
+        this.loading = false;
+      }
+    }
+  }
+
+  build(): Pivot {
+    const { original, rows, column, values, aggregation } = this;
+    const unchanged =
+      isSameList(rows, original.rows) &&
+      column === original.column &&
+      values.length === original.values.length &&
+      values.every((value, index) => {
+        const saved = original.values[index];
+        return saved !== undefined && sameValue(saved, value);
+      }) &&
+      aggregation.function === original.aggregation.function &&
+      aggregation.column === original.aggregation.column;
+    return !this.touched || unchanged
+      ? original
+      : new Pivot(
+          original.id,
+          rows,
+          column,
+          values,
+          aggregation,
+          original.rest,
+        );
+  }
+}

package/src/stores/fixtures/CubeSalesDuckDbModel.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 type { ModelContext } from '@finos/legend-cube';
+import {
+  CUBE_DIRECT_DATABASE_PATH,
+  CUBE_DIRECT_RUNTIME_PATH,
+  createCubeDirectModel,
+} from '../../graph-manager/CubeDirectConnection.js';
+
+// The Sales sample (the review of the demo, 2026-10-13): a small table on an
+// in-memory DuckDB, which the engine builds from setup SQL on each
+// connection, as the H2 samples are. The H2 samples can't run the engine's
+// pivot(); this one can, so Pivot works on a sample out of the box. Its orders
+// hold JSON documents as text, for Parse as JSON (PLAN §11.20). Its cubes are
+// direct-connection cubes: the connection is their model.
+
+/** The setup SQL that makes the table, one statement an entry */
+export const CUBE_SALES_SETUP_SQLS: readonly string[] = Object.freeze([
+  'drop schema if exists demo cascade',
+  'create schema demo',
+  'create table demo.sales (id INTEGER PRIMARY KEY, country VARCHAR(10), product VARCHAR(10), year INTEGER, amount INTEGER, price DOUBLE)',
+  "insert into demo.sales values (1, 'France', 'Tea', 2022, 120, 2.5), (2, 'France', 'Coffee', 2023, 80, 3.1), (3, 'France', 'Tea', 2024, 150, 2.7), (4, 'Germany', 'Tea', 2022, 90, 2.4), (5, 'Germany', 'Coffee', 2022, 60, 3.0), (6, 'Germany', 'Coffee', 2024, 110, 3.3), (7, 'Japan', 'Tea', 2023, 200, 2.9), (8, 'Japan', 'Tea', 2024, 40, 2.9), (9, 'France', 'Coffee', 2024, 30, 3.2), (10, 'Spain', 'Coffee', 2022, 70, 3.0)",
+  // orders as JSON documents in a text column (PLAN §11.20): Parse as JSON
+  // reads them as a Variant column, which Explore JSON and Explode Array use
+  'create table demo.orders (id INTEGER PRIMARY KEY, document VARCHAR)',
+  `insert into demo.orders values (1, '{"customer":{"name":"Ann","tier":"gold","country":"France"},"items":[{"product":"Tea","qty":2,"price":2.5},{"product":"Coffee","qty":1,"price":3.1}],"paid":true,"placed":"2024-01-31","tags":["web","promo"]}'), (2, '{"customer":{"name":"Bob","tier":"silver","country":"Germany"},"items":[{"product":"Coffee","qty":3,"price":3.0}],"paid":false,"placed":"2024-02-02","tags":["store"]}'), (3, '{"customer":{"name":"Chloé","country":"France"},"items":[{"product":"Tea","qty":1,"price":2.7},{"product":"Tea","qty":4,"price":2.7},{"product":"Coffee","qty":1,"price":3.2}],"paid":true,"placed":"2024-02-14","tags":["web"]}'), (4, '{"customer":{"name":"Daichi","tier":"gold","country":"Japan"},"items":[{"product":"Tea","qty":5,"price":2.9}],"paid":true,"placed":"2024-03-01","tags":[]}'), (5, '{"customer":{"name":"Eva","tier":"bronze","country":"Spain"},"items":[],"paid":false,"placed":"2024-03-09","tags":["web","promo"]}'), (6, '{"customer":{"name":"Felix","tier":"silver","country":"Germany"},"items":[{"product":"Tea","qty":2,"price":2.4},{"product":"Coffee","qty":2,"price":3.3}],"paid":true,"placed":"2024-04-20","tags":["store","promo"]}'), (7, null), (8, '{"customer":{"name":"Gabi","tier":"gold","country":"Spain"},"items":[{"product":"Coffee","qty":1,"price":3.0}],"paid":true,"placed":"2024-05-05","tags":["web"]}')`,
+]);
+
+/** The model of a Sales cube: an in-memory DuckDB connection with its setup SQL */
+export const CUBE_SALES_MODEL: ModelContext = createCubeDirectModel({
+  _type: 'RelationalDatabaseConnection',
+  type: 'DuckDB',
+  databaseType: 'DuckDB',
+  datasourceSpecification: {
+    _type: 'duckDB',
+    path: '',
+    testDataSetupSqls: [...CUBE_SALES_SETUP_SQLS],
+  },
+  authenticationStrategy: { _type: 'test' },
+});
+export const CUBE_SALES_RUNTIME = CUBE_DIRECT_RUNTIME_PATH;
+export const CUBE_SALES_DATABASE = CUBE_DIRECT_DATABASE_PATH;
+/** As a direct connection's coordinates store a name: quoted */
+export const CUBE_SALES_SCHEMA = '"demo"';
+export const CUBE_SALES_TABLE = '"sales"';
+export const CUBE_SALES_ORDERS_TABLE = '"orders"';

package/src/stores/fixtures/CubeTradesModel.ts

@@ -166,7 +166,8 @@ export const CUBE_TRADES_SETUP_SQLS = [
   sampleInsert(`${CUBE_TRADES_SCHEMA}.TRADES`, createTrades()),
 ];
 
-export const CUBE_TRADES_MODEL_CODE = `###Relational
+/** The trades sample before its functions (PLAN §6.5), which cubes saved before may hold */
+const CUBE_TRADES_TABLES_CODE = `###Relational
 Database ${CUBE_TRADES_DATABASE}
 (
   Schema ${CUBE_TRADES_SCHEMA}
@@ -234,8 +235,42 @@ Runtime ${CUBE_TRADES_RUNTIME}
 }
 `;
 
+export const CUBE_TRADES_LARGE_TRADES_FUNCTION =
+  'cube::samples::trades::tradesAbove';
+export const CUBE_TRADES_DESK_BOOK_FUNCTION = 'cube::samples::trades::deskBook';
+
+// Two functions that return a relation (PLAN §6.5): one that leaves the
+// runtime to the cube, and one that reads through its own
+const CUBE_TRADES_FUNCTIONS_CODE = `###Pure
+function ${CUBE_TRADES_LARGE_TRADES_FUNCTION}(minNotionalUsd: Float[1]): Relation<(TRADE_ID:Integer, TRADE_DATE:StrictDate, DESK_ID:Integer, SIDE:String, NOTIONAL_USD:Decimal)>[1]
+{
+  #>{${CUBE_TRADES_DATABASE}.${CUBE_TRADES_SCHEMA}.TRADES}#
+    ->filter(t|$t.NOTIONAL_USD > $minNotionalUsd)
+    ->select(~[TRADE_ID, TRADE_DATE, DESK_ID, SIDE, NOTIONAL_USD])
+}
+
+function ${CUBE_TRADES_DESK_BOOK_FUNCTION}(desk: String[1], side: String[0..1]): Relation<(TRADE_ID:Integer, TRADE_DATE:StrictDate, DESK:String, REGION:String, SIDE:String, NOTIONAL_USD:Decimal)>[1]
+{
+  #>{${CUBE_TRADES_DATABASE}.${CUBE_TRADES_SCHEMA}.TRADES}#
+    ->join(#>{${CUBE_TRADES_DATABASE}.${CUBE_TRADES_SCHEMA}.DESKS}#, JoinKind.INNER, {t, d|$t.DESK_ID == $d.ID})
+    ->filter(r|($r.DESK == $desk) && ($side->isEmpty() || ($r.SIDE == $side->toOne())))
+    ->select(~[TRADE_ID, TRADE_DATE, DESK, REGION, SIDE, NOTIONAL_USD])
+    ->from(${CUBE_TRADES_RUNTIME})
+}
+`;
+
+export const CUBE_TRADES_MODEL_CODE = `${CUBE_TRADES_TABLES_CODE}
+
+${CUBE_TRADES_FUNCTIONS_CODE}`;
+
 /** The trades sample as a cube saves it (PLAN §6.2.2) */
 export const CUBE_TRADES_MODEL: ModelContext = Object.freeze({
   _type: 'text',
   code: CUBE_TRADES_MODEL_CODE,
 });
+
+/** The trades sample's text before its functions: cubes saved on it open on the same tables */
+export const CUBE_TRADES_MODEL_BEFORE_FUNCTIONS: ModelContext = Object.freeze({
+  _type: 'text',
+  code: CUBE_TRADES_TABLES_CODE,
+});