@finos/legend-cube-builder 0.0.5 → 0.0.6

package/src/stores/editors/CubeExplodeDraft.ts

@@ -0,0 +1,272 @@
+/**
+ * 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 Explode,
+  getVariantDatabaseProblem,
+  type Schema,
+} from '@finos/legend-cube';
+import { assertErrorThrown, type GeneratorFn } from '@finos/legend-shared';
+import { action, computed, flow, makeObservable, observable } from 'mobx';
+import { CubeEngineError } from '../../graph-manager/CubeEngine.js';
+import type { CubeEditorState } from '../CubeEditorState.js';
+import { CubeQueryRunAborted } from '../CubeQueryRun.js';
+import {
+  type CubeJsonField,
+  getCubeJsonElementName,
+  getCubeJsonFields,
+  getFreeCubeColumnName,
+} from '../variant/CubeJsonOffers.js';
+import { readCubeJsonSample } from '../variant/CubeJsonSampling.js';
+import type { CubeJsonSample } from '../variant/CubeJsonShape.js';
+import { isSameList } from './CubeAggregationRows.js';
+import { CubeNodeDraft } from './CubeNodeDraft.js';
+
+/** An array a sample of the column holds, to explode */
+export interface CubeExplodeArray {
+  /** The keys from the column to it, empty for the column itself */
+  readonly path: readonly string[];
+  /** What it held, e.g. `list of object` */
+  readonly description: string;
+  /** Its share, 0 to 1, of the places it could be */
+  readonly presence: number;
+}
+
+/** The arrays of a column's fields, in tree order */
+const arraysOf = (field: CubeJsonField): CubeExplodeArray[] => [
+  ...(field.offers.some((offer) => offer.explode !== undefined)
+    ? [
+        {
+          path: field.path,
+          description: field.description,
+          presence: field.presence,
+        },
+      ]
+    : []),
+  ...field.children.flatMap(arraysOf),
+];
+
+/**
+ * The Explode Array editor's draft (PLAN §11.20): the Variant column, the
+ * keys to its array and the new column's name. The arrays to pick from come
+ * from a sample of the column's documents, read after the node's input as
+ * Explore JSON reads them. Until a name is typed, the name follows the
+ * column and keys (`<last key>_element`, free in the input); picking another
+ * column drops the keys and the sample, which were the other column's.
+ */
+export class CubeExplodeDraft extends CubeNodeDraft<Explode> {
+  readonly editorState: CubeEditorState;
+  column: string;
+  path: readonly string[];
+  name: string;
+  /** What a sample of the column held, once read */
+  sample:
+    | { readonly column: string; readonly sample: CubeJsonSample }
+    | undefined;
+  isSampling = false;
+  /** Why the sample couldn't be read */
+  sampleError: string | undefined;
+  /** The name follows the column and keys until one is typed */
+  private namedByDefault: boolean;
+  private controller: AbortController | undefined;
+  /** Anything was changed; until then, `build()` gives the original back */
+  private touched = false;
+
+  constructor(original: Explode, editorState: CubeEditorState) {
+    super(original);
+    makeObservable<CubeExplodeDraft, 'touched' | 'namedByDefault'>(this, {
+      column: observable,
+      path: observable.ref,
+      name: observable,
+      sample: observable.ref,
+      isSampling: observable,
+      sampleError: observable,
+      namedByDefault: observable,
+      touched: observable,
+      arrays: computed,
+      sampleProblem: computed,
+      setColumn: action,
+      setKey: action,
+      addKey: action,
+      removeKey: action,
+      pickArray: action,
+      setName: action,
+      stopSample: action,
+      readSample: flow,
+    });
+    this.editorState = editorState;
+    this.column = original.column;
+    this.path = original.path;
+    this.name = original.name;
+    // a new node's, or one still named as Explore JSON names it
+    this.namedByDefault =
+      original.name === '' ||
+      original.name === this.defaultName(original.column, original.path);
+  }
+
+  /** The element's default name for a column and keys: `<last key>_element`, free in the input */
+  private defaultName(column: string, path: readonly string[]): string {
+    return column
+      ? getFreeCubeColumnName(
+          getCubeJsonElementName(column, path),
+          this.input?.schema.names() ?? [],
+        )
+      : '';
+  }
+
+  /**
+   * Why Find arrays can't read the column: the database the node's input
+   * runs on has no JSON functions; `undefined` when it can, or isn't known
+   */
+  get sampleProblem(): string | undefined {
+    const { editorState, input } = this;
+    const { context, query } = editorState.document;
+    return input === undefined || context?.runtime === undefined
+      ? undefined
+      : getVariantDatabaseProblem(
+          editorState.getRunDatabaseType(
+            query,
+            input.id,
+            context.model,
+            context.runtime,
+          ),
+        );
+  }
+
+  /** The node's input: its id and schema, once known */
+  private get input(): { id: string; schema: Schema } | undefined {
+    const [id] = this.editorState.document.query.getInputIds(this.original.id);
+    const schema =
+      id === undefined ? undefined : this.editorState.analysis.schemas.get(id);
+    return id === undefined || !schema ? undefined : { id, schema };
+  }
+
+  /** The arrays the sample found, if it was of the picked column */
+  get arrays(): CubeExplodeArray[] | undefined {
+    const { sample, column } = this;
+    return sample && sample.column === column
+      ? arraysOf(getCubeJsonFields(column, sample.sample))
+      : undefined;
+  }
+
+  private edited(): void {
+    this.touched = true;
+    if (this.namedByDefault) {
+      this.name = this.defaultName(this.column, this.path);
+    }
+  }
+
+  /** Picks the column; another column's keys and sample are dropped */
+  setColumn(column: string): void {
+    if (column === this.column) {
+      return;
+    }
+    this.stopSample();
+    this.column = column;
+    this.path = [];
+    this.sample = undefined;
+    this.sampleError = undefined;
+    this.edited();
+  }
+
+  setKey(index: number, key: string): void {
+    this.path = this.path.map((each, at) => (at === index ? key : each));
+    this.edited();
+  }
+
+  addKey(): void {
+    this.path = [...this.path, ''];
+    this.edited();
+  }
+
+  removeKey(index: number): void {
+    this.path = this.path.filter((_, at) => at !== index);
+    this.edited();
+  }
+
+  /** Takes the keys of an array the sample found */
+  pickArray(path: readonly string[]): void {
+    this.path = path;
+    this.edited();
+  }
+
+  /** Types the name: it no longer follows the column and keys */
+  setName(name: string): void {
+    this.name = name;
+    this.namedByDefault = false;
+    this.touched = true;
+  }
+
+  stopSample(): void {
+    this.controller?.abort();
+    this.controller = undefined;
+    this.isSampling = false;
+  }
+
+  /**
+   * Reads the picked column's first values after the node's input, as
+   * Explore JSON does (listed in Runs, can be stopped), for the arrays they
+   * hold; picking another column abandons it
+   */
+  *readSample(): GeneratorFn<void> {
+    const { editorState, column, input } = this;
+    const picked = column ? input?.schema.lookup(column) : undefined;
+    if (this.isSampling || !input || !picked || this.sampleProblem) {
+      return;
+    }
+    const controller = new AbortController();
+    this.controller = controller;
+    this.isSampling = true;
+    this.sampleError = undefined;
+    try {
+      const sample = (yield readCubeJsonSample(editorState, {
+        document: editorState.document,
+        afterId: input.id,
+        column: picked,
+        everyRow: false,
+        abortController: controller,
+      })) as CubeJsonSample | undefined;
+      if (this.controller === controller && sample) {
+        this.sample = { column, sample };
+      }
+    } catch (error) {
+      if (
+        this.controller !== controller ||
+        error instanceof CubeQueryRunAborted
+      ) {
+        return;
+      }
+      assertErrorThrown(error);
+      this.sampleError =
+        error instanceof CubeEngineError ? error.firstLine : error.message;
+    } finally {
+      if (this.controller === controller) {
+        this.controller = undefined;
+        this.isSampling = false;
+      }
+    }
+  }
+
+  build(): Explode {
+    const { original, column, path, name } = this;
+    return !this.touched ||
+      (column === original.column &&
+        isSameList(path, original.path) &&
+        name === original.name)
+      ? original
+      : original.with({ column, path, name });
+  }
+}

package/src/stores/editors/CubeExpressionFilterDraft.ts

@@ -50,6 +50,7 @@ import {
   type NodeId,
 } from '../../graph-manager/CubeEngine.js';
 import type { CubeEditorState } from '../CubeEditorState.js';
+import { CubeJsonFieldsState } from '../variant/CubeJsonFieldsState.js';
 import {
   buildCubeConditionCheckLambdas,
   readCubeConditionCheck,
@@ -118,6 +119,8 @@ const asEngineError = (error: unknown): CubeEngineError =>
  */
 export class CubeExpressionFilterDraft extends CubeNodeDraft<ExpressionFilter> {
   readonly editorState: CubeEditorState;
+  /** A Variant input column's fields, opened from its chip (PLAN §11.20, V.9) */
+  readonly jsonFields: CubeJsonFieldsState;
   code: string;
   /** What the engine made of the code the last time it parsed it */
   checked: CubeConditionCheckedCode | undefined;
@@ -149,6 +152,7 @@ export class CubeExpressionFilterDraft extends CubeNodeDraft<ExpressionFilter> {
       follow: action,
     });
     this.editorState = editorState;
+    this.jsonFields = new CubeJsonFieldsState(editorState, original.id);
     const { code, lambda } = original;
     this.code = code || NEW_CONDITION_CODE;
     this.checked = lambda ? { code, lambda, located: lambda } : undefined;

package/src/stores/editors/CubeExtendDraft.ts

@@ -51,6 +51,8 @@ import {
   type NodeId,
 } from '../../graph-manager/CubeEngine.js';
 import type { CubeEditorState } from '../CubeEditorState.js';
+import { CubeJsonFieldsState } from '../variant/CubeJsonFieldsState.js';
+import { getFreeCubeColumnName } from '../variant/CubeJsonOffers.js';
 import {
   buildCubeExtendTypingLambdas,
   getCubeExtendUpstream,
@@ -110,6 +112,8 @@ const problemOf = (error: CubeEngineError): CubeExtendRowProblem => ({
  */
 export class CubeExtendDraft extends CubeNodeDraft<Extend> {
   readonly editorState: CubeEditorState;
+  /** A Variant input column's fields, opened from its chip (PLAN §11.20, V.9) */
+  readonly jsonFields: CubeJsonFieldsState;
   rows: readonly CubeExtendRow[];
   /** The typing the last Validate gave, for the rows as they were then */
   typing: ExtendTyping | undefined;
@@ -131,6 +135,7 @@ export class CubeExtendDraft extends CubeNodeDraft<Extend> {
       isValidated: computed,
       applyDisabledReason: computed,
       addRow: action,
+      addColumn: action,
       removeRow: action,
       moveRow: action,
       setName: action,
@@ -139,6 +144,7 @@ export class CubeExtendDraft extends CubeNodeDraft<Extend> {
       follow: action,
     });
     this.editorState = editorState;
+    this.jsonFields = new CubeJsonFieldsState(editorState, original.id);
     const types = original.typing.kind === 'typed' ? original.typing.types : [];
     this.rows = original.columns.map(({ name, code, lambda }, index) => ({
       key: nextRowKey++,
@@ -214,6 +220,29 @@ export class CubeExtendDraft extends CubeNodeDraft<Extend> {
     this.change([...this.rows, this.newRow()]);
   }
 
+  /**
+   * Adds a row of this code, named as given or the next free name, compared
+   * as the input's and the other rows' names fold (a JSON field's "+ column",
+   * V.9); it replaces a new row still empty
+   */
+  addColumn(name: string, code: string): void {
+    const blank = this.rows.find(
+      (row) => row.code.trim() === NEW_EXPRESSION_CODE.trim() && !row.checked,
+    );
+    const others = this.rows.filter((row) => row !== blank);
+    this.change([
+      ...others,
+      {
+        key: nextRowKey++,
+        name: getFreeCubeColumnName(name, [
+          ...(this.inputSchema?.names() ?? []),
+          ...others.map((row) => row.name),
+        ]),
+        code,
+      },
+    ]);
+  }
+
   removeRow(key: number): void {
     this.change(this.rows.filter((row) => row.key !== key));
   }

package/src/stores/editors/CubeNodeDraftRegistry.ts

@@ -19,6 +19,7 @@ import {
   Difference,
   Distinct,
   Drop,
+  Explode,
   ExpressionFilter,
   Pivot,
   Extend,
@@ -38,6 +39,7 @@ import { guaranteeType } from '@finos/legend-shared';
 import type { CubeEditorState } from '../CubeEditorState.js';
 import { CubeConcatDraft } from './CubeConcatDraft.js';
 import { CubeDifferenceDraft } from './CubeDifferenceDraft.js';
+import { CubeExplodeDraft } from './CubeExplodeDraft.js';
 import { CubeExpressionFilterDraft } from './CubeExpressionFilterDraft.js';
 import { CubePivotDraft } from './CubePivotDraft.js';
 import { CubeExtendDraft } from './CubeExtendDraft.js';
@@ -113,6 +115,11 @@ export const CUBE_NODE_DRAFT_FACTORIES: ReadonlyMap<
     (node, editorState) =>
       new CubePivotDraft(guaranteeType(node, Pivot), editorState),
   ],
+  [
+    Explode.TYPE,
+    (node, editorState) =>
+      new CubeExplodeDraft(guaranteeType(node, Explode), editorState),
+  ],
 ]);
 
 /**

package/src/stores/fixtures/CubeSalesDuckDbModel.ts

@@ -24,8 +24,9 @@ import {
 // 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 cubes
-// are direct-connection cubes: the connection is their model.
+// 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([
@@ -33,6 +34,10 @@ export const CUBE_SALES_SETUP_SQLS: readonly string[] = Object.freeze([
   '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 */
@@ -52,3 +57,4 @@ 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"';