@finos/legend-cube-builder 0.0.2 → 0.0.4

package/src/graph-manager/protocol/pure/v1/V1_CubeDataProductArtifact.ts

@@ -0,0 +1,251 @@
+/**
+ * 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 { Schema } from '@finos/legend-cube';
+import type { PlainObject } from '@finos/legend-shared';
+import {
+  CubeAccessPoint,
+  CubeAccessPointGroup,
+  type CubeAccessPointLocation,
+  type CubeDataProductCandidate,
+  CubeDataProductDescription,
+} from '../../../CubeDataProductCatalog.js';
+import type { CubeResultValue } from '../../../CubeEngine.js';
+import { V1_buildCubeSchema } from './V1_CubeRelationTypeAdapter.js';
+
+// A deployed data product's access points (PLAN §6.8), read from two
+// documents: the product's definition at its deployed version (titles, kinds
+// and parameters) and its deployed artifact (each access point's columns, as
+// the engine typed them when it deployed, and sample rows). Both are read
+// tolerantly: what Cube doesn't know is skipped, and a problem stays on its
+// access point, which is listed but can't be picked. No engine call
+
+/** How many sample rows the preview shows */
+export const V1_CUBE_SAMPLE_ROW_LIMIT = 5;
+
+const LAKEHOUSE_ACCESS_POINT_TYPE = 'lakehouseAccessPoint';
+const MODEL_ACCESS_POINT_GROUP_TYPE = 'modelAccessPointGroup';
+const RELATION_TYPE = 'relationType';
+
+/** Why an access point can't be picked */
+export const V1_CUBE_ACCESS_POINT_REASON = {
+  MODEL_GROUP: 'Model access point groups are not supported yet',
+  NOT_LAKEHOUSE: 'Only Lakehouse access points can be added for now',
+  PARAMETERS: 'It takes parameters, which Cube does not support yet',
+  NOT_DEPLOYED: 'It is not in the deployed artifact',
+  NO_DEFINITION: "Cube couldn't read the data product's definition",
+  NO_RELATION: 'Its result is not a relation',
+  NO_TYPE: 'Its columns are not in the deployed artifact',
+  BAD_MULTIPLICITY: (column: string): string =>
+    `Column "${column}" holds more than one value, which Cube can't show`,
+} as const;
+
+const asObject = (value: unknown): PlainObject =>
+  value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as PlainObject)
+    : {};
+
+const asList = (value: unknown): unknown[] =>
+  Array.isArray(value) ? value : [];
+
+const asString = (value: unknown): string | undefined =>
+  typeof value === 'string' && value.length ? value : undefined;
+
+/** A pair's key: an access point is known by its group and its own id */
+const keyOf = (groupId: string, accessPointId: string): string =>
+  JSON.stringify([groupId, accessPointId]);
+
+/** The artifact's access point implementations, by group and id */
+const readImplementations = (artifact: unknown): Map<string, PlainObject> => {
+  const implementations = new Map<string, PlainObject>();
+  asList(asObject(artifact).accessPointGroups).forEach((group) => {
+    const groupId = asString(asObject(group).id);
+    if (!groupId) {
+      return;
+    }
+    asList(asObject(group).accessPointImplementations).forEach((value) => {
+      const implementation = asObject(value);
+      const id = asString(implementation.id);
+      if (id) {
+        implementations.set(keyOf(groupId, id), implementation);
+      }
+    });
+  });
+  return implementations;
+};
+
+/**
+ * An access point's columns, from its implementation's lambdaGenericType:
+ * the first relation type among its type arguments, whatever the outer type
+ * (a relation, or an ingest relation accessor)
+ */
+const readSchema = (
+  implementation: PlainObject,
+): { schema: Schema } | { reason: string } => {
+  const genericType = asObject(implementation.lambdaGenericType);
+  if (!Object.keys(genericType).length) {
+    return { reason: V1_CUBE_ACCESS_POINT_REASON.NO_TYPE };
+  }
+  const relationType = asList(genericType.typeArguments)
+    .map((argument) => asObject(asObject(argument).rawType))
+    .find((rawType) => rawType._type === RELATION_TYPE);
+  if (!relationType) {
+    return { reason: V1_CUBE_ACCESS_POINT_REASON.NO_RELATION };
+  }
+  for (const column of asList(relationType.columns).map(asObject)) {
+    const multiplicity = asObject(column.multiplicity);
+    if (Object.keys(multiplicity).length && multiplicity.upperBound !== 1) {
+      return {
+        reason: V1_CUBE_ACCESS_POINT_REASON.BAD_MULTIPLICITY(
+          String(column.name),
+        ),
+      };
+    }
+  }
+  try {
+    return { schema: V1_buildCubeSchema(relationType) };
+  } catch (error) {
+    return { reason: error instanceof Error ? error.message : String(error) };
+  }
+};
+
+/** Up to the preview's limit of rows, by the schema's columns; the artifact holds them as text */
+const readSampleRows = (
+  implementation: PlainObject,
+  schema: Schema,
+): CubeResultValue[][] => {
+  const element = asObject(implementation.relationElement);
+  const columns = asList(element.columns).map(String);
+  const positions = schema.columns.map((column) =>
+    columns.indexOf(column.name),
+  );
+  return asList(element.rows)
+    .slice(0, V1_CUBE_SAMPLE_ROW_LIMIT)
+    .map((row) => {
+      const values = asList(asObject(row).values);
+      return positions.map((position) => {
+        const value = position < 0 ? undefined : values[position];
+        return value === undefined || value === null ? null : String(value);
+      });
+    });
+};
+
+/** The stereotype a host's marketplace marks groups open to everyone with */
+export interface V1_CubeEnterpriseStereotype {
+  readonly profile: string;
+  readonly value: string;
+}
+
+/** Whether a group's definition carries the host's enterprise stereotype */
+const isEnterpriseGroup = (
+  group: PlainObject,
+  stereotype: V1_CubeEnterpriseStereotype | undefined,
+): boolean =>
+  stereotype !== undefined &&
+  asList(group.stereotypes)
+    .map(asObject)
+    .some(
+      (each) =>
+        each.profile === stereotype.profile && each.value === stereotype.value,
+    );
+
+/**
+ * A product's access points by group, as its definition lists them. One is
+ * pickable when it is a Lakehouse access point without parameters, outside
+ * a model group, deployed with a relation of columns Cube can read
+ */
+export const V1_readCubeDataProductDescription = (
+  candidate: CubeDataProductCandidate,
+  artifact: unknown,
+  definition: unknown,
+  enterpriseStereotype?: V1_CubeEnterpriseStereotype | undefined,
+): CubeDataProductDescription => {
+  const implementations = readImplementations(artifact);
+  const hasDefinition = Boolean(asObject(definition).accessPointGroups);
+  // without a definition, the artifact's groups are listed, unpickable
+  const groupsJson = hasDefinition
+    ? asList(asObject(definition).accessPointGroups)
+    : asList(asObject(artifact).accessPointGroups).map((group) => ({
+        ...asObject(group),
+        accessPoints: asList(asObject(group).accessPointImplementations),
+      }));
+  const groups = groupsJson
+    .map(asObject)
+    .filter((group) => asString(group.id))
+    .map((group) => {
+      const groupId = group.id as string;
+      const isModelGroup = group._type === MODEL_ACCESS_POINT_GROUP_TYPE;
+      return new CubeAccessPointGroup({
+        id: groupId,
+        title: asString(group.title),
+        isEnterprise: isEnterpriseGroup(group, enterpriseStereotype),
+        accessPoints: asList(group.accessPoints)
+          .map(asObject)
+          .filter((point) => asString(point.id))
+          .map((point) => {
+            const id = point.id as string;
+            const implementation = implementations.get(keyOf(groupId, id));
+            const read = implementation
+              ? readSchema(implementation)
+              : undefined;
+            const schema = read && 'schema' in read ? read.schema : undefined;
+            const disabledReason = !hasDefinition
+              ? V1_CUBE_ACCESS_POINT_REASON.NO_DEFINITION
+              : isModelGroup
+                ? V1_CUBE_ACCESS_POINT_REASON.MODEL_GROUP
+                : point._type !== LAKEHOUSE_ACCESS_POINT_TYPE
+                  ? V1_CUBE_ACCESS_POINT_REASON.NOT_LAKEHOUSE
+                  : asList(asObject(point.func).parameters).length
+                    ? V1_CUBE_ACCESS_POINT_REASON.PARAMETERS
+                    : !implementation
+                      ? V1_CUBE_ACCESS_POINT_REASON.NOT_DEPLOYED
+                      : read && 'reason' in read
+                        ? read.reason
+                        : undefined;
+            return new CubeAccessPoint({
+              id,
+              title: asString(point.title),
+              description:
+                asString(point.description) ??
+                asString(implementation?.description),
+              schema,
+              disabledReason,
+              sampleRows:
+                implementation && schema
+                  ? readSampleRows(implementation, schema)
+                  : [],
+            });
+          }),
+      });
+    });
+  return new CubeDataProductDescription(candidate, groups);
+};
+
+/** A saved source's schema, from the product's description, or why it has none */
+export const V1_findCubeAccessPointSchema = (
+  description: CubeDataProductDescription,
+  location: CubeAccessPointLocation,
+): Schema | string => {
+  const accessPoint = description.groups
+    .find((group) => group.id === location.accessPointGroup)
+    ?.accessPoints.find((point) => point.id === location.accessPoint);
+  if (!accessPoint) {
+    return `The data product has no access point "${location.accessPoint}" in group "${location.accessPointGroup}"`;
+  }
+  return accessPoint.isPickable
+    ? (accessPoint.schema as Schema)
+    : (accessPoint.disabledReason ?? V1_CUBE_ACCESS_POINT_REASON.NO_TYPE);
+};

package/src/graph-manager/protocol/pure/v1/V1_CubeDataProductModel.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 { IR } from '@finos/legend-cube';
+import type { PlainObject } from '@finos/legend-shared';
+import {
+  CUBE_DATA_PRODUCT_RUNTIME_PATH,
+  type CubeDataProductProject,
+} from '../../../CubeDataProduct.js';
+
+// The models a data product cube's engine calls run on (PLAN §6.8), built for
+// each call and never saved: the project at its saved version, and for a run
+// a lakehouse runtime at Cube's fixed path, whose environment and warehouse
+// are resolved for the viewer
+
+const splitPath = (path: string): { package: string; name: string } => {
+  const index = path.lastIndexOf('::');
+  return { package: path.slice(0, index), name: path.slice(index + 2) };
+};
+
+/** The project at the version its data products were deployed from: never a moving alias */
+const pointerOf = (project: CubeDataProductProject): PlainObject => ({
+  _type: 'pointer',
+  sdlcInfo: {
+    _type: 'alloy',
+    baseVersion: 'latest',
+    version: project.versionId,
+    packageableElementPointers: [],
+    groupId: project.groupId,
+    artifactId: project.artifactId,
+  },
+});
+
+/** Whether a lambda reads a data product's access point, anywhere in it */
+export const V1_hasCubeDataProductAccessor = (ir: IR): boolean => {
+  const visit = (value: unknown): boolean => {
+    if (Array.isArray(value)) {
+      return value.some(visit);
+    }
+    if (!value || typeof value !== 'object') {
+      return false;
+    }
+    const node = value as PlainObject;
+    if (node.k === 'dataProductAccessor') {
+      return true;
+    }
+    return node.k !== 'raw' && Object.values(node).some(visit);
+  };
+  return visit(ir);
+};
+
+/** The model typing runs on: the project alone, with no runtime */
+export const V1_buildCubeDataProductTypingContext = (
+  project: CubeDataProductProject,
+): PlainObject => pointerOf(project);
+
+/**
+ * The model a run runs on: the project, then a model holding only the
+ * lakehouse runtime at Cube's fixed path, with the viewer's environment and
+ * the warehouse, always given
+ */
+export const V1_buildCubeDataProductExecutionContext = (
+  project: CubeDataProductProject,
+  environment: string,
+  warehouse: string,
+): PlainObject => ({
+  _type: 'combination',
+  contexts: [
+    pointerOf(project),
+    {
+      _type: 'data',
+      elements: [
+        {
+          _type: 'runtime',
+          ...splitPath(CUBE_DATA_PRODUCT_RUNTIME_PATH),
+          runtimeValue: {
+            _type: 'LakehouseRuntime',
+            connectionStores: [],
+            connections: [],
+            mappings: [],
+            environment,
+            warehouse,
+          },
+        },
+      ],
+    },
+  ],
+});

package/src/graph-manager/protocol/pure/v1/V1_CubeDirectConnection.ts

@@ -0,0 +1,339 @@
+/**
+ * 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 { PlainObject } from '@finos/legend-shared';
+import {
+  CubeConnectionDatasourceKind,
+  CubeDirectDatabaseType,
+  type CubeConnectionDraft,
+  type CubeConnectionSummary,
+} from '../../../CubeConnectionExplorer.js';
+
+// A direct connection's protocol JSON (PLAN §6.8), read and written as plain
+// JSON. legend-graph's connection serializers are not used: they drop a DuckDB
+// connection's setup SQL and an H2 one's identifier setting, and a saved
+// connection must reach the engine exactly as it was saved. A connection is
+// checked against what Cube supports, and anything else is refused, never
+// dropped, since an imported cube is saved again unchanged
+
+const CONNECTION_TYPE = 'RelationalDatabaseConnection';
+const H2_DATASOURCE_TYPE = 'h2Local';
+const DUCKDB_DATASOURCE_TYPE = 'duckDB';
+const H2_DEFAULT_AUTHENTICATION_TYPE = 'h2Default';
+const TEST_AUTHENTICATION_TYPE = 'test';
+
+/** Where the engine records source positions: kept, and ignored when comparing */
+const SOURCE_INFORMATION_KEYS = [
+  'sourceInformation',
+  'elementSourceInformation',
+];
+/** The store the connection is bound to: set only in the model built for each call */
+const ELEMENT_KEY = 'element';
+
+/** The authentication strategies, as the engine names them, each database allows */
+const AUTHENTICATION_TYPES: Record<CubeDirectDatabaseType, readonly string[]> =
+  {
+    [CubeDirectDatabaseType.H2]: [
+      H2_DEFAULT_AUTHENTICATION_TYPE,
+      TEST_AUTHENTICATION_TYPE,
+    ],
+    [CubeDirectDatabaseType.DUCKDB]: [TEST_AUTHENTICATION_TYPE],
+  };
+
+const isEmptyList = (value: unknown): boolean =>
+  value === undefined ||
+  value === null ||
+  (Array.isArray(value) && value.length === 0);
+
+/**
+ * Connection settings Cube doesn't support yet, accepted only at the engine's
+ * default value: each changes how a query runs, in ways Cube doesn't show
+ */
+const UNSUPPORTED_SETTINGS: Record<string, (value: unknown) => boolean> = {
+  localMode: (value) =>
+    value === undefined || value === null || value === false,
+  quoteIdentifiers: (value) =>
+    value === undefined || value === null || value === false,
+  timeZone: (value) => value === undefined || value === null,
+  queryTimeOutInSeconds: (value) => value === undefined || value === null,
+  queryGenerationConfigs: (value) => isEmptyList(value),
+  // a schema mapper ran a query on another schema with no error
+  postProcessors: (value) => isEmptyList(value),
+  postProcessorWithParameter: (value) => isEmptyList(value),
+};
+
+const isObject = (value: unknown): value is PlainObject =>
+  Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const isDatabaseType = (value: unknown): value is CubeDirectDatabaseType =>
+  Object.values(CubeDirectDatabaseType).includes(
+    value as CubeDirectDatabaseType,
+  );
+
+const isStatementList = (value: unknown): value is string[] =>
+  Array.isArray(value) &&
+  value.every((statement) => typeof statement === 'string');
+
+/** The keys of an object that are neither expected nor source information */
+const unexpectedKeys = (
+  object: PlainObject,
+  expected: readonly string[],
+): string[] =>
+  Object.keys(object).filter(
+    (key) => !expected.includes(key) && !SOURCE_INFORMATION_KEYS.includes(key),
+  );
+
+const checkDatasource = (
+  databaseType: CubeDirectDatabaseType,
+  datasource: PlainObject,
+): string[] => {
+  const problems: string[] = [];
+  // a CSV setup is the engine's own SQL generation, which lost rows in tests
+  if (
+    datasource.testDataSetupCsv !== undefined &&
+    datasource.testDataSetupCsv !== null &&
+    datasource.testDataSetupCsv !== ''
+  ) {
+    problems.push(
+      "The connection sets up its data from CSV, which Cube doesn't support: use setup SQL statements",
+    );
+  }
+  if (databaseType === CubeDirectDatabaseType.H2) {
+    if (datasource._type !== H2_DATASOURCE_TYPE) {
+      problems.push(
+        'An H2 connection must use a local H2 database, created by its setup SQL',
+      );
+      return problems;
+    }
+    if (
+      datasource.disableDatabaseToUpper !== undefined &&
+      datasource.disableDatabaseToUpper !== null &&
+      datasource.disableDatabaseToUpper !== false
+    ) {
+      problems.push(
+        "The connection keeps H2 from upper-casing names, which Cube doesn't support",
+      );
+    }
+    if (
+      !isStatementList(datasource.testDataSetupSqls) ||
+      datasource.testDataSetupSqls.length === 0
+    ) {
+      // without setup SQL the engine connects to an H2 server that isn't there
+      problems.push('An H2 connection needs at least one setup SQL statement');
+    }
+    unexpectedKeys(datasource, [
+      '_type',
+      'testDataSetupSqls',
+      'testDataSetupCsv',
+      'disableDatabaseToUpper',
+    ]).forEach((key) =>
+      problems.push(
+        `The connection's database has a property Cube doesn't know: "${key}"`,
+      ),
+    );
+  } else {
+    if (datasource._type !== DUCKDB_DATASOURCE_TYPE) {
+      problems.push(
+        'A DuckDB connection must name a DuckDB database file, or none for an in-memory database',
+      );
+      return problems;
+    }
+    if (typeof datasource.path !== 'string') {
+      problems.push(
+        'A DuckDB connection must name a database file, or none for an in-memory database',
+      );
+    }
+    if (
+      datasource.testDataSetupSqls !== undefined &&
+      !isStatementList(datasource.testDataSetupSqls)
+    ) {
+      problems.push("The connection's setup SQL must be a list of statements");
+    }
+    unexpectedKeys(datasource, [
+      '_type',
+      'path',
+      'testDataSetupSqls',
+      'testDataSetupCsv',
+    ]).forEach((key) =>
+      problems.push(
+        `The connection's database has a property Cube doesn't know: "${key}"`,
+      ),
+    );
+  }
+  return problems;
+};
+
+const checkAuthentication = (
+  databaseType: CubeDirectDatabaseType,
+  authentication: PlainObject,
+): string[] => {
+  const allowed = AUTHENTICATION_TYPES[databaseType];
+  if (!allowed.includes(authentication._type as string)) {
+    return [
+      `${databaseType === CubeDirectDatabaseType.H2 ? 'An' : 'A'} ${databaseType} connection's authentication must be ${allowed
+        .map((type) => `"${type}"`)
+        .join(' or ')}`,
+    ];
+  }
+  // these strategies take no settings, so no secret can be saved with them
+  return unexpectedKeys(authentication, ['_type']).map(
+    (key) =>
+      `The connection's authentication has a property Cube doesn't know: "${key}"`,
+  );
+};
+
+/**
+ * What keeps Cube from using a connection, in words a user can act on: none
+ * when the connection is one Cube supports. Values are never repeated, only
+ * the names of properties, since a property Cube doesn't know could hold a
+ * secret
+ */
+export const V1_checkCubeDirectConnection = (
+  connection: unknown,
+): readonly string[] => {
+  if (!isObject(connection) || connection._type !== CONNECTION_TYPE) {
+    return ['The connection is not a relational database connection'];
+  }
+  const { type, databaseType } = connection;
+  if (!isDatabaseType(databaseType)) {
+    return [
+      `Cube connects to H2 and DuckDB databases only, not to "${String(databaseType)}"`,
+    ];
+  }
+  const problems: string[] = [];
+  if (type !== databaseType) {
+    problems.push(
+      "The connection's type and database type must be the same database",
+    );
+  }
+  Object.entries(UNSUPPORTED_SETTINGS).forEach(([key, isDefault]) => {
+    if (!isDefault(connection[key])) {
+      problems.push(`The connection sets "${key}", which Cube doesn't support`);
+    }
+  });
+  unexpectedKeys(connection, [
+    '_type',
+    'type',
+    'databaseType',
+    'datasourceSpecification',
+    'authenticationStrategy',
+    ELEMENT_KEY,
+    ...Object.keys(UNSUPPORTED_SETTINGS),
+  ]).forEach((key) =>
+    problems.push(`The connection has a property Cube doesn't know: "${key}"`),
+  );
+  if (isObject(connection.datasourceSpecification)) {
+    problems.push(
+      ...checkDatasource(databaseType, connection.datasourceSpecification),
+    );
+  } else {
+    problems.push("The connection doesn't say how to reach its database");
+  }
+  if (isObject(connection.authenticationStrategy)) {
+    problems.push(
+      ...checkAuthentication(databaseType, connection.authenticationStrategy),
+    );
+  } else {
+    problems.push("The connection doesn't say how to authenticate");
+  }
+  return problems;
+};
+
+/**
+ * The connection the form describes, as the engine reads it. It names no
+ * store: each call binds it to the Database built for that call
+ */
+export const V1_buildCubeDirectConnection = (
+  draft: CubeConnectionDraft,
+): PlainObject => {
+  const setupSqls = [...draft.setupSqls];
+  return draft.databaseType === CubeDirectDatabaseType.H2
+    ? {
+        _type: CONNECTION_TYPE,
+        type: CubeDirectDatabaseType.H2,
+        databaseType: CubeDirectDatabaseType.H2,
+        datasourceSpecification: {
+          _type: H2_DATASOURCE_TYPE,
+          testDataSetupSqls: setupSqls,
+        },
+        authenticationStrategy: { _type: H2_DEFAULT_AUTHENTICATION_TYPE },
+      }
+    : {
+        _type: CONNECTION_TYPE,
+        type: CubeDirectDatabaseType.DUCKDB,
+        databaseType: CubeDirectDatabaseType.DUCKDB,
+        datasourceSpecification: {
+          _type: DUCKDB_DATASOURCE_TYPE,
+          path: draft.path ?? '',
+          ...(setupSqls.length ? { testDataSetupSqls: setupSqls } : {}),
+        },
+        authenticationStrategy: { _type: TEST_AUTHENTICATION_TYPE },
+      };
+};
+
+/**
+ * What the page shows of a connection Cube supports (see
+ * `V1_checkCubeDirectConnection`): never its setup SQL
+ */
+export const V1_summarizeCubeDirectConnection = (
+  connection: PlainObject,
+): CubeConnectionSummary => {
+  const databaseType = connection.databaseType as CubeDirectDatabaseType;
+  const datasource = connection.datasourceSpecification as PlainObject;
+  const authentication = connection.authenticationStrategy as PlainObject;
+  const path = typeof datasource.path === 'string' ? datasource.path : '';
+  const setupSqls = datasource.testDataSetupSqls;
+  return {
+    databaseType,
+    datasourceKind:
+      databaseType === CubeDirectDatabaseType.H2
+        ? CubeConnectionDatasourceKind.LOCAL_H2
+        : path
+          ? CubeConnectionDatasourceKind.DUCKDB_FILE
+          : CubeConnectionDatasourceKind.DUCKDB_IN_MEMORY,
+    path:
+      databaseType === CubeDirectDatabaseType.DUCKDB && path ? path : undefined,
+    setupSqlCount: Array.isArray(setupSqls) ? setupSqls.length : 0,
+    authenticationKind: String(authentication._type),
+  };
+};
+
+const canonicalValue = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map(canonicalValue);
+  }
+  if (isObject(value)) {
+    return Object.fromEntries(
+      Object.keys(value)
+        .filter(
+          (key) =>
+            key !== ELEMENT_KEY && !SOURCE_INFORMATION_KEYS.includes(key),
+        )
+        .sort()
+        .map((key) => [key, canonicalValue(value[key])]),
+    );
+  }
+  return value;
+};
+
+/**
+ * A connection as text that two connections share exactly when they reach the
+ * same database the same way: key order, the bound store and source
+ * positions don't count. Used to compare connections and to key caches
+ */
+export const V1_canonicalCubeDirectConnection = (
+  connection: PlainObject,
+): string => JSON.stringify(canonicalValue(connection));