@finos/legend-application-query 13.8.52 → 13.8.54

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finos/legend-application-query",
-  "version": "13.8.52",
+  "version": "13.8.54",
   "description": "Legend Query application core",
   "keywords": [
     "legend",
@@ -44,18 +44,18 @@
     "test:watch": "jest --watch"
   },
   "dependencies": {
-    "@finos/legend-application": "16.0.123",
-    "@finos/legend-art": "7.1.163",
-    "@finos/legend-code-editor": "2.0.203",
-    "@finos/legend-data-cube": "0.3.121",
-    "@finos/legend-extension-dsl-data-space": "10.4.255",
-    "@finos/legend-graph": "32.6.34",
-    "@finos/legend-lego": "2.0.223",
-    "@finos/legend-query-builder": "4.19.12",
-    "@finos/legend-server-depot": "6.1.20",
-    "@finos/legend-server-lakehouse": "0.3.83",
-    "@finos/legend-shared": "11.0.28",
-    "@finos/legend-storage": "3.0.150",
+    "@finos/legend-application": "16.0.125",
+    "@finos/legend-art": "7.1.165",
+    "@finos/legend-code-editor": "2.0.205",
+    "@finos/legend-data-cube": "0.3.123",
+    "@finos/legend-extension-dsl-data-space": "10.4.257",
+    "@finos/legend-graph": "32.7.1",
+    "@finos/legend-lego": "2.0.225",
+    "@finos/legend-query-builder": "4.19.14",
+    "@finos/legend-server-depot": "6.1.22",
+    "@finos/legend-server-lakehouse": "0.3.85",
+    "@finos/legend-shared": "11.0.30",
+    "@finos/legend-storage": "3.0.152",
     "@testing-library/dom": "10.4.0",
     "@testing-library/react": "16.2.0",
     "@types/react": "19.0.10",

package/src/__lib__/LegendQueryAgentChatTelemetryHelper.ts

@@ -16,6 +16,36 @@
 
 import type { TelemetryService } from '@finos/legend-application';
 import { LEGEND_QUERY_APP_EVENT } from './LegendQueryEvent.js';
+import type { LegendQuerySourceInfo } from './LegendQuerySourceInfo.js';
+
+/**
+ * The entry point the suggestion was triggered from ({@link LegendQuerySourceInfo})
+ * is spread FLAT into the payload, matching how `sourceInfo` is reported on
+ * every other query telemetry event.
+ */
+export type QueryAISuggest_TelemetryData = {
+  sourceInfo?: LegendQuerySourceInfo | undefined;
+};
+
+export type QueryAISuggestSuccess_TelemetryData =
+  QueryAISuggest_TelemetryData & {
+    /** Wall-clock duration of the suggester call, in milliseconds. */
+    durationMs: number;
+  };
+
+export type QueryAISuggestFailure_TelemetryData =
+  QueryAISuggest_TelemetryData & {
+    /** Wall-clock duration until the suggester call failed, in milliseconds. */
+    durationMs: number;
+    errorMessage: string;
+  };
+
+const flattenSourceInfo = (
+  data: QueryAISuggest_TelemetryData,
+): Record<string, unknown> => {
+  const { sourceInfo, ...rest } = data;
+  return { ...rest, ...(sourceInfo ?? {}) };
+};
 
 /**
  * Telemetry surface for Legend AI agent-chat and AI-suggest flows. These
@@ -41,27 +71,53 @@ export class LegendQueryAgentChatTelemetryHelper {
     );
   }
 
-  static logEvent_QueryAISuggestLaunched(service: TelemetryService): void {
-    service.logEvent(LEGEND_QUERY_APP_EVENT.LEGENDAI_QUERY_SUGGEST__LAUNCH, {});
+  static logEvent_QueryAISuggestLaunched(
+    service: TelemetryService,
+    data: QueryAISuggest_TelemetryData = {},
+  ): void {
+    service.logEvent(
+      LEGEND_QUERY_APP_EVENT.LEGENDAI_QUERY_SUGGEST__LAUNCH,
+      flattenSourceInfo(data),
+    );
   }
 
-  static logEvent_QueryAISuggestApplied(service: TelemetryService): void {
-    service.logEvent(LEGEND_QUERY_APP_EVENT.LEGENDAI_QUERY_SUGGEST__APPLY, {});
+  static logEvent_QueryAISuggestSucceeded(
+    service: TelemetryService,
+    data: QueryAISuggestSuccess_TelemetryData,
+  ): void {
+    service.logEvent(
+      LEGEND_QUERY_APP_EVENT.LEGENDAI_QUERY_SUGGEST__SUCCESS,
+      flattenSourceInfo(data),
+    );
+  }
+
+  static logEvent_QueryAISuggestApplied(
+    service: TelemetryService,
+    data: QueryAISuggest_TelemetryData = {},
+  ): void {
+    service.logEvent(
+      LEGEND_QUERY_APP_EVENT.LEGENDAI_QUERY_SUGGEST__APPLY,
+      flattenSourceInfo(data),
+    );
   }
 
-  static logEvent_QueryAISuggestDiscarded(service: TelemetryService): void {
+  static logEvent_QueryAISuggestDiscarded(
+    service: TelemetryService,
+    data: QueryAISuggest_TelemetryData = {},
+  ): void {
     service.logEvent(
       LEGEND_QUERY_APP_EVENT.LEGENDAI_QUERY_SUGGEST__DISCARD,
-      {},
+      flattenSourceInfo(data),
     );
   }
 
   static logEvent_QueryAISuggestFailure(
     service: TelemetryService,
-    errorMessage: string,
+    data: QueryAISuggestFailure_TelemetryData,
   ): void {
-    service.logEvent(LEGEND_QUERY_APP_EVENT.LEGENDAI_QUERY_SUGGEST__FAILURE, {
-      errorMessage,
-    });
+    service.logEvent(
+      LEGEND_QUERY_APP_EVENT.LEGENDAI_QUERY_SUGGEST__FAILURE,
+      flattenSourceInfo(data),
+    );
   }
 }

package/src/__lib__/LegendQueryEvent.ts

@@ -22,17 +22,42 @@ export enum LEGEND_QUERY_APP_EVENT {
   CREATE_QUERY__SUCCESS = 'query-editor.create-query.success',
   UPDATE_QUERY__SUCCESS = 'query-editor.update-query.success',
   RENAME_QUERY__SUCCESS = 'query-editor.rename.query.success',
+  DELETE_QUERY__SUCCESS = 'query-editor.delete-query.success',
+
+  CREATE_QUERY__FAILURE = 'query-editor.create-query.failure',
+  UPDATE_QUERY__FAILURE = 'query-editor.update-query.failure',
+  RENAME_QUERY__FAILURE = 'query-editor.rename-query.failure',
+  DELETE_QUERY__FAILURE = 'query-editor.delete-query.failure',
+  VIEW_QUERY__FAILURE = 'query-editor.view-query.failure',
+  INITIALIZE_QUERY_STATE__FAILURE = 'query-editor.initialize-query-state.failure',
+  GRAPH_INITIALIZATION__FAILURE = 'query-editor.graph-initialization.failure',
+  PRODUCTIONIZE_QUERY__LAUNCH = 'query-editor.productionize-query.launch',
   INITIALIZE_QUERY_STATE__SUCCESS = 'query-editor.initialize-query-state.success',
+  INITIALIZE_QUERY_CREATOR__FAILURE = 'query-editor.initialize-query-creator.failure',
   LEGENDAI_QUERY_AGENT_CHAT__OPENED = 'query-editor.legendai-query-agent-chat.opened',
   LEGENDAI_QUERY_AGENT_CHAT__QUERY_LOADED = 'query-editor.legendai-query-agent-chat.query-loaded',
   LEGENDAI_QUERY_SUGGEST__LAUNCH = 'query-editor.legendai-query-suggest.launch',
+  LEGENDAI_QUERY_SUGGEST__SUCCESS = 'query-editor.legendai-query-suggest.success',
   LEGENDAI_QUERY_SUGGEST__APPLY = 'query-editor.legendai-query-suggest.apply',
   LEGENDAI_QUERY_SUGGEST__DISCARD = 'query-editor.legendai-query-suggest.discard',
   LEGENDAI_QUERY_SUGGEST__FAILURE = 'query-editor.legendai-query-suggest.failure',
 
+  CHANGE_DATA_SPACE = 'query-editor.change-data-space',
+  CHANGE_DATA_PRODUCT = 'query-editor.change-data-product',
+
   VIEW_PROJECT__LAUNCH = 'query-editor.view-project.launch',
   VIEW_SDLC_PROJECT__LAUNCH = 'query-editor.view-sdlc-project.launch',
 
+  // Help-menu items injected by Legend Query into the query builder header.
+  // Each carries the shared query builder telemetry envelope (source info flat
+  // + `state` nested), matching every other query telemetry event.
+  ABOUT_QUERY_INFO__LAUNCH = 'query-editor.about-query-info.launch',
+  QUERY_VERSION_HISTORY__LAUNCH = 'query-editor.query-version-history.launch',
+  ABOUT_LEGEND_QUERY__LAUNCH = 'query-editor.about-legend-query.launch',
+  ABOUT_DATA_SPACE__LAUNCH = 'query-editor.about-data-space.launch',
+  ABOUT_DATA_PRODUCT__LAUNCH = 'query-editor.about-data-product.launch',
+  ABOUT_INGEST__LAUNCH = 'query-editor.about-ingest.launch',
+
   LOCAL_STORAGE_PERSIST_ERROR = 'LOCAL_STORAGE_PERSIST_ERROR',
   HOSTED_DATA_CUBE__LAUNCH = 'query-editor.hosted-data-cube.launch',
 }

package/src/__lib__/LegendQueryLifecycleTelemetry.ts

@@ -0,0 +1,132 @@
+/**
+ * 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 { LightQuery } from '@finos/legend-graph';
+import { buildTelemetryErrorFields } from '@finos/legend-shared';
+import type { GenericLegendApplicationStore } from '@finos/legend-application';
+import type { CompleteQueryLoaderLifecycleHandlers } from '@finos/legend-query-builder';
+import {
+  type PartialQuery_TelemetryData,
+  type QueryCreateFailure_TelemetryData,
+  type QueryLifecycleFailure_TelemetryData,
+  type Query_TelemetryData,
+  LegendQueryTelemetryHelper,
+} from './LegendQueryTelemetryHelper.js';
+
+/**
+ * Builds the error half of a saved-query lifecycle failure payload, applying the
+ * same message cap and `errorMessageTruncated` flag as every other failure event.
+ */
+export const buildQueryLifecycleFailureData = (
+  queryId: string,
+  error: Error,
+): QueryLifecycleFailure_TelemetryData => ({
+  // NOTE: only the id is available on these paths — the loader reports a
+  // failure by id, and the query it refers to was never resolved
+  query: { id: queryId },
+  ...buildTelemetryErrorFields(error),
+});
+
+/**
+ * Maps a query to the identity block every lifecycle event carries.
+ */
+export const buildQueryIdentity = (query: LightQuery): Query_TelemetryData => ({
+  query: {
+    id: query.id,
+    name: query.name,
+    groupId: query.groupId,
+    artifactId: query.artifactId,
+    versionId: query.versionId,
+  },
+});
+
+/**
+ * Builds the payload for a failed *create*.
+ *
+ * Separate from {@link buildQueryLifecycleFailureData} because a failed create
+ * has no query to identify — the server assigns the id and the request never got
+ * that far. Reporting the chosen name instead of a placeholder id keeps "never
+ * persisted" distinguishable from a real value.
+ */
+export const buildQueryCreateFailureData = (
+  queryName: string,
+  error: Error,
+): QueryCreateFailure_TelemetryData => ({
+  queryName,
+  ...buildTelemetryErrorFields(error),
+});
+
+/**
+ * The saved-query lifecycle handlers every `QueryLoaderState` host wires in.
+ *
+ * Rename and delete happen inside the shared query loader, which reports them
+ * back through callbacks — so without this the same emit would be duplicated at
+ * each of the three hosts that build a loader (and before this existed, the
+ * rename emit was in fact triplicated while delete was reported nowhere).
+ *
+ * NOTE: these events deliberately carry no source info. They fire from the query
+ * *picker*, where the user may rename or delete one query while editing another
+ * — attaching the loaded query builder's source info would silently mislabel the
+ * row as belonging to the wrong query.
+ */
+export const buildQueryLoaderLifecycleTelemetryHandlers = (
+  applicationStore: GenericLegendApplicationStore,
+  sideEffects?:
+    | {
+        /**
+         * Runs alongside the delete telemetry — hosts use this to prune their
+         * recently-viewed list.
+         */
+        onQueryDeleted?: ((queryId: string) => void) | undefined;
+      }
+    | undefined,
+): CompleteQueryLoaderLifecycleHandlers => {
+  const { telemetryService } = applicationStore;
+  return {
+    onQueryRenamed: (query): void => {
+      LegendQueryTelemetryHelper.logEvent_RenameQuerySucceeded(
+        telemetryService,
+        buildQueryIdentity(query),
+      );
+    },
+    onQueryDeleted: (queryId, deletedQuery): void => {
+      sideEffects?.onQueryDeleted?.(queryId);
+      // the entry may not have been in the loaded list, in which case only the
+      // id is known
+      const identity: PartialQuery_TelemetryData = deletedQuery
+        ? buildQueryIdentity(deletedQuery)
+        : { query: { id: queryId } };
+      LegendQueryTelemetryHelper.logEvent_DeleteQuerySucceeded(
+        telemetryService,
+        identity,
+      );
+    },
+    onQueryRenameFailed: (queryId, error): void => {
+      // the rename failed, so the loader never resolved the renamed query —
+      // only its id and the error are known
+      LegendQueryTelemetryHelper.logEvent_RenameQueryFailed(
+        telemetryService,
+        buildQueryLifecycleFailureData(queryId, error),
+      );
+    },
+    onQueryDeleteFailed: (queryId, error): void => {
+      LegendQueryTelemetryHelper.logEvent_DeleteQueryFailed(
+        telemetryService,
+        buildQueryLifecycleFailureData(queryId, error),
+      );
+    },
+  };
+};

package/src/__lib__/LegendQueryNavigation.ts

@@ -407,17 +407,17 @@ export const EXTERNAL_APPLICATION_NAVIGATION__generateStudioProductionizeQueryUr
     `${studioApplicationUrl}/extensions/productionize-query/${queryId}`;
 
 /**
- * @external_application_navigation This depends on Legend Taxonomy routing and is hardcoded so it's potentially brittle
+ * @external_application_navigation This depends on Legend Marketplace routing and is hardcoded so it's potentially brittle
  */
-export const EXTERNAL_APPLICATION_NAVIGATION__generateTaxonomyDataspaceViewUrl =
+export const EXTERNAL_APPLICATION_NAVIGATION__generateMarketplaceDataspaceViewUrl =
   (
-    taxonomyApplicationUrl: string,
+    marketplaceApplicationUrl: string,
     groupId: string,
     artifactId: string,
     versionId: string,
     dataspacePath: string,
   ): string =>
-    `${taxonomyApplicationUrl}/dataspace/${generateGAVCoordinates(
+    `${marketplaceApplicationUrl}/dataProduct/legacy/${generateGAVCoordinates(
       groupId,
       artifactId,
       versionId,
@@ -442,6 +442,20 @@ export const EXTERNAL_APPLICATION_NAVIGATION__generateNewDataCubeUrl = (
   )}`;
 };
 
+/**
+ * Mirrors `generateAnchorForSection` from `@finos/legend-extension-dsl-data-product`,
+ * which this package does not depend on. The data product viewer registers one anchor
+ * per access point group, and reads the zone from the URL hash on load.
+ *
+ * @external_application_navigation This depends on Legend Marketplace routing and is hardcoded so it's potentially brittle
+ */
+const EXTERNAL_APPLICATION_NAVIGATION__generateAccessPointGroupAnchor = (
+  accessPointGroupId: string,
+): string =>
+  encodeURIComponent(
+    `apg-${accessPointGroupId}`.trim().toLowerCase().replace(/\s+/gu, '-'),
+  );
+
 /**
  * @external_application_navigation This depends on Legend Marketplace routing and is hardcoded so it's potentially brittle
  */
@@ -450,5 +464,10 @@ export const EXTERNAL_APPLICATION_NAVIGATION__generateMarketplaceDataProductUrl
     marketplaceApplicationUrl: string,
     dataProductId: string,
     deploymentId: string,
+    accessPointGroupId?: string | undefined,
   ): string =>
-    `${marketplaceApplicationUrl}/dataProduct/deployed/${dataProductId}/${deploymentId}`;
+    `${marketplaceApplicationUrl}/dataProduct/deployed/${dataProductId}/${deploymentId}${
+      accessPointGroupId
+        ? `#${EXTERNAL_APPLICATION_NAVIGATION__generateAccessPointGroupAnchor(accessPointGroupId)}`
+        : ''
+    }`;

package/src/__lib__/LegendQuerySourceInfo.ts

@@ -0,0 +1,162 @@
+/**
+ * Copyright (c) 2020-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 { LegendSourceInfo } from '@finos/legend-storage';
+
+/**
+ * The entry point a query creator was started from.
+ */
+export enum LegendQuerySourceType {
+  MAPPING = 'mapping',
+  SERVICE = 'service',
+  DATA_SPACE = 'data-space',
+  DATA_SPACE_TEMPLATE = 'data-space.template',
+  DATA_PRODUCT = 'data-product',
+  DATA_PRODUCT_SAMPLE = 'data-product.sample',
+  INGEST = 'ingest',
+  /**
+   * The default route, when no data product or data space has been selected yet
+   */
+  UNSELECTED = 'unselected',
+}
+
+/**
+ * Coordinates of the project the query is started from
+ */
+interface LegendQueryProjectSourceInfo extends LegendSourceInfo {
+  groupId: string;
+  artifactId: string;
+  versionId: string;
+  /**
+   * Set when a *saved* query was opened (the `/existing/:queryId` route) rather
+   * than a new one created from a creator route. The `sourceType` still
+   * describes what the query targets — a saved data space query reports
+   * `data-space`, same as a freshly created one — so a dashboard can slice by
+   * target without caring how the query was opened, and use the presence of
+   * this field to separate saved from new when it does care.
+   */
+  queryId?: string | undefined;
+}
+
+/**
+ * Query created on a mapping and runtime
+ * `/create/manual/:gav/:mappingPath/:runtimePath`
+ */
+export interface LegendQueryMappingSourceInfo
+  extends LegendQueryProjectSourceInfo {
+  sourceType: LegendQuerySourceType.MAPPING;
+  mapping: string;
+  runtime: string;
+}
+
+/**
+ * Query created from a service
+ * `/create-from-service/:gav/:servicePath`
+ */
+export interface LegendQueryServiceSourceInfo
+  extends LegendQueryProjectSourceInfo {
+  sourceType: LegendQuerySourceType.SERVICE;
+  service: string;
+}
+
+/**
+ * Query created on a data space
+ * `/dataspace/:gav/:dataSpacePath/:executionContext?`
+ */
+export interface LegendQueryDataSpaceSourceInfo
+  extends LegendQueryProjectSourceInfo {
+  sourceType: LegendQuerySourceType.DATA_SPACE;
+  dataSpace: string;
+  /**
+   * The key of the execution context the query was started with, when known
+   */
+  executionContext?: string | undefined;
+}
+
+/**
+ * Query created from a data space template query
+ * `/dataspace/:gav/:dataSpacePath/template/:templateQueryId`
+ */
+export interface LegendQueryDataSpaceTemplateSourceInfo
+  extends LegendQueryProjectSourceInfo {
+  sourceType: LegendQuerySourceType.DATA_SPACE_TEMPLATE;
+  dataSpace: string;
+  templateQueryId: string;
+}
+
+/**
+ * Query created on a data product
+ * `/data-product/:accessType/:gav/:dataProductPath/:accessId`
+ */
+export interface LegendQueryDataProductSourceInfo
+  extends LegendQueryProjectSourceInfo {
+  sourceType: LegendQuerySourceType.DATA_PRODUCT;
+  dataProduct: string;
+  /**
+   * The access type (e.g. native, model, lakehouse) the query was started
+   * with, when known
+   */
+  accessType?: string | undefined;
+  /**
+   * The ID of the access point (group) or execution context the query was
+   * started with, when known
+   */
+  accessId?: string | undefined;
+}
+
+/**
+ * Query created from a data product sample query
+ * `/data-product/native/sample-query/:gav/:dataProductPath/:sampleQueryId`
+ */
+export interface LegendQueryDataProductSampleSourceInfo
+  extends LegendQueryProjectSourceInfo {
+  sourceType: LegendQuerySourceType.DATA_PRODUCT_SAMPLE;
+  dataProduct: string;
+  sampleQueryId: string;
+}
+
+/**
+ * Query created on an ingest data set
+ * `/ingest/:gav/:ingestDefinitionPath/:dataSet`
+ */
+export interface LegendQueryIngestSourceInfo
+  extends LegendQueryProjectSourceInfo {
+  sourceType: LegendQuerySourceType.INGEST;
+  ingestDefinitionPath: string;
+  dataSet: string;
+}
+
+/**
+ * The default route `/`, when no data product or data space has been
+ * selected yet
+ */
+export interface LegendQueryUnselectedSourceInfo extends LegendSourceInfo {
+  sourceType: LegendQuerySourceType.UNSELECTED;
+}
+
+/**
+ * Where a query creator was started from, used as the query builder state
+ * source info (see `QueryBuilderState.sourceInfo`) and reported in telemetry
+ */
+export type LegendQuerySourceInfo =
+  | LegendQueryMappingSourceInfo
+  | LegendQueryServiceSourceInfo
+  | LegendQueryDataSpaceSourceInfo
+  | LegendQueryDataSpaceTemplateSourceInfo
+  | LegendQueryDataProductSourceInfo
+  | LegendQueryDataProductSampleSourceInfo
+  | LegendQueryIngestSourceInfo
+  | LegendQueryUnselectedSourceInfo;