[Lens] [ES|QL] Improved ES|QL conversion failure tooltip messages

x-pack/platform/plugins/shared/lens/public/app_plugin/shared/edit_on_the_fly/use_esql_conversion.tsx

@@ -15,7 +15,11 @@ import type {
 import { partition } from 'lodash';
 import type { CoreStart } from '@kbn/core/public';
 import { i18n } from '@kbn/i18n';
-import { getESQLForLayer } from '../../../datasources/form_based/to_esql';
+import {
+  getESQLForLayer,
+  isEsqlQuerySuccess,
+  type EsqlConversionFailureReason,
+} from '../../../datasources/form_based/to_esql';
 import type { ConvertibleLayer } from './convert_to_esql_modal';
 import { operationDefinitionMap } from '../../../datasources/form_based/operations';
 import type { LensPluginStartDependencies } from '../../../plugin';
@@ -25,6 +29,52 @@ const cannotConvertToEsqlTooltip = i18n.translate('xpack.lens.config.cannotConve
   defaultMessage: 'This visualization cannot be converted to ES|QL',
 });
 
+const failureReasonMessages: Record<EsqlConversionFailureReason, string> = {
+  non_utc_timezone: i18n.translate('xpack.lens.config.cannotConvertToEsqlNonUtcTimezone', {
+    defaultMessage: 'Cannot convert to ES|QL: UTC timezone is required.',
+  }),
+  formula_not_supported: i18n.translate('xpack.lens.config.cannotConvertToEsqlFormula', {
+    defaultMessage: 'Cannot convert to ES|QL: Formula operations are not yet supported.',
+  }),
+  time_shift_not_supported: i18n.translate('xpack.lens.config.cannotConvertToEsqlTimeShift', {
+    defaultMessage: 'Cannot convert to ES|QL: Time shift is not yet supported.',
+  }),
+  runtime_field_not_supported: i18n.translate('xpack.lens.config.cannotConvertToEsqlRuntimeField', {
+    defaultMessage: 'Cannot convert to ES|QL: Runtime fields are not yet supported.',
+  }),
+  reduced_time_range_not_supported: i18n.translate(
+    'xpack.lens.config.cannotConvertToEsqlReducedTimeRange',
+    {
+      defaultMessage: 'Cannot convert to ES|QL: Reduced time range is not yet supported.',
+    }
+  ),
+  function_not_supported: i18n.translate('xpack.lens.config.cannotConvertToEsqlOperation', {
+    defaultMessage: 'Cannot convert to ES|QL: One or more functions are not yet supported.',
+  }),
+  drop_partials_not_supported: i18n.translate('xpack.lens.config.cannotConvertToEsqlDropPartials', {
+    defaultMessage: 'Cannot convert to ES|QL: "Drop partial buckets" option is not yet supported.',
+  }),
+  include_empty_rows_not_supported: i18n.translate(
+    'xpack.lens.config.cannotConvertToEsqlIncludeEmptyRows',
+    {
+      defaultMessage: 'Cannot convert to ES|QL: "Include empty rows" option is not yet supported.',
+    }
+  ),
+  terms_not_supported: i18n.translate('xpack.lens.config.cannotConvertToEsqlTerms', {
+    defaultMessage: 'Cannot convert to ES|QL: Top values (terms) aggregation is not yet supported.',
+  }),
+  unknown: i18n.translate('xpack.lens.config.cannotConvertToEsqlUnknown', {
+    defaultMessage: 'Cannot convert to ES|QL: This visualization has unsupported settings.',
+  }),
+};
+
+const getFailureTooltip = (reason: EsqlConversionFailureReason | undefined): string => {
+  if (!reason) {
+    return cannotConvertToEsqlTooltip;
+  }
+  return failureReasonMessages[reason] ?? failureReasonMessages.unknown;
+};
+
 const getEsqlConversionDisabledSettings = (tooltip: string = cannotConvertToEsqlTooltip) => ({
   isConvertToEsqlButtonDisabled: true,
   convertToEsqlButtonTooltip: tooltip,
@@ -134,7 +184,7 @@ export const useEsqlConversion = (
       // This prevents conversion errors from breaking the visualization
     }
 
-    return esqlLayer
+    return isEsqlQuerySuccess(esqlLayer)
       ? {
           isConvertToEsqlButtonDisabled: false,
           convertToEsqlButtonTooltip: i18n.translate('xpack.lens.config.convertToEsqlTooltip', {
@@ -151,11 +201,7 @@ export const useEsqlConversion = (
             },
           ],
         }
-      : getEsqlConversionDisabledSettings(
-          i18n.translate('xpack.lens.config.cannotConvertToEsqlUnsupportedSettingsTooltip', {
-            defaultMessage: 'The visualization has unsupported settings for query mode',
-          })
-        );
+      : getEsqlConversionDisabledSettings(getFailureTooltip(esqlLayer?.reason));
   }, [
     activeVisualization,
     coreStart.uiSettings,

x-pack/platform/plugins/shared/lens/public/datasources/form_based/to_esql.test.ts

@@ -81,15 +81,18 @@ describe('to_esql', () => {
       new Date()
     );
 
-    expect(esql?.esql).toEqual(
-      `FROM myIndexPattern
+    expect(esql).toEqual(
+      expect.objectContaining({
+        success: true,
+        esql: `FROM myIndexPattern
   | WHERE order_date >= ?_tstart AND order_date <= ?_tend
   | STATS bucket_0_0 = COUNT(*) BY order_date = BUCKET(order_date, 30 minutes)
-  | SORT order_date ASC`
+  | SORT order_date ASC`,
+      })
     );
   });
 
-  it('should return undefined if missing row option is set', () => {
+  it('should return failure with include_empty_rows_not_supported reason if missing row option is set', () => {
     const esql = getESQLForLayer(
       [
         [
@@ -124,10 +127,13 @@ describe('to_esql', () => {
       new Date()
     );
 
-    expect(esql?.esql).toEqual(undefined);
+    expect(esql).toEqual({
+      success: false,
+      reason: 'include_empty_rows_not_supported',
+    });
   });
 
-  it('should return undefined if lens formula is used', () => {
+  it('should return failure with formula_not_supported reason if lens formula is used', () => {
     const esql = getESQLForLayer(
       [
         [
@@ -151,7 +157,10 @@ describe('to_esql', () => {
       new Date()
     );
 
-    expect(esql).toEqual(undefined);
+    expect(esql).toEqual({
+      success: false,
+      reason: 'formula_not_supported',
+    });
   });
 
   test('it should add a where condition to esql if timeField is set', () => {
@@ -189,11 +198,14 @@ describe('to_esql', () => {
       new Date()
     );
 
-    expect(esql?.esql).toEqual(
-      `FROM myIndexPattern
+    expect(esql).toEqual(
+      expect.objectContaining({
+        success: true,
+        esql: `FROM myIndexPattern
   | WHERE order_date >= ?_tstart AND order_date <= ?_tend
   | STATS bucket_0_0 = COUNT(*) BY order_date = BUCKET(order_date, 30 minutes)
-  | SORT order_date ASC`
+  | SORT order_date ASC`,
+      })
     );
   });
 
@@ -239,14 +251,17 @@ describe('to_esql', () => {
       new Date()
     );
 
-    expect(esql?.esql).toEqual(
-      `FROM myIndexPattern
+    expect(esql).toEqual(
+      expect.objectContaining({
+        success: true,
+        esql: `FROM myIndexPattern
   | STATS bucket_0_0 = COUNT(*) BY order_date = BUCKET(order_date, 30 minutes)
-  | SORT order_date ASC`
+  | SORT order_date ASC`,
+      })
     );
   });
 
-  it('should return undefined if timezone is not UTC', () => {
+  it('should return failure with non_utc_timezone reason if timezone is not UTC', () => {
     uiSettings.get.mockImplementation((key: string) => {
       if (key === 'dateFormat:tz') return 'America/Chicago';
       return defaultUiSettingsGet(key);
@@ -286,7 +301,10 @@ describe('to_esql', () => {
       new Date()
     );
 
-    expect(esql).toEqual(undefined);
+    expect(esql).toEqual({
+      success: false,
+      reason: 'non_utc_timezone',
+    });
   });
 
   it('should work with iana timezones that fall under UTC+0', () => {
@@ -330,11 +348,14 @@ describe('to_esql', () => {
       new Date()
     );
 
-    expect(esql?.esql).toEqual(
-      `FROM myIndexPattern
+    expect(esql).toEqual(
+      expect.objectContaining({
+        success: true,
+        esql: `FROM myIndexPattern
   | WHERE order_date >= ?_tstart AND order_date <= ?_tend
   | STATS bucket_0_0 = COUNT(*) BY order_date = BUCKET(order_date, 30 minutes)
-  | SORT order_date ASC`
+  | SORT order_date ASC`,
+      })
     );
   });
 
@@ -377,11 +398,14 @@ describe('to_esql', () => {
       new Date()
     );
 
-    expect(esql?.esql).toEqual(
-      `FROM myIndexPattern
+    expect(esql).toEqual(
+      expect.objectContaining({
+        success: true,
+        esql: `FROM myIndexPattern
   | WHERE order_date >= ?_tstart AND order_date <= ?_tend
   | STATS bucket_0_0 = COUNT(*) WHERE KQL("geo.src:\\"US\\"") BY order_date = BUCKET(order_date, 30 minutes)
-  | SORT order_date ASC`
+  | SORT order_date ASC`,
+      })
     );
   });
 });

x-pack/platform/plugins/shared/lens/public/datasources/form_based/to_esql.top_n.test.ts

@@ -106,6 +106,9 @@ describe('to_esql top N', () => {
       mockNowInstant
     );
 
-    expect(result?.esql).toEqual(undefined);
+    expect(result).toEqual({
+      success: false,
+      reason: 'terms_not_supported',
+    });
   });
 });