Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

fix(sql-editor): explain in the format the viewer draws, and translate its label (#21666)

Danny Xue77473a25aa1
diff --git a/frontend/src/locales/en-US.json b/frontend/src/locales/en-US.json
index fa3272b9f0..ca1b18050a 100644
--- a/frontend/src/locales/en-US.json
+++ b/frontend/src/locales/en-US.json
@@ -3419,6 +3419,7 @@
"data-explorer-sql-filter-placeholder": "Enter a query predicate, e.g. WHERE id = 1",
"ddl-dml-requires-data-change-plan": "To execute DDL/DML statements in <environment></environment>, please submit a Data Change Plan for approval.",
"download-as-file": "Download as {{file}}",
+ "dry-run": "Dry run",
"duration-day": "{{days}} day",
"duration-days": "{{days}} days",
"duration-hour": "{{hours}} hour",
@@ -3428,6 +3429,7 @@
"expire-at": "Expire at {{time}}",
"expire-in": "Expire in {{time}}",
"expired": "Expired",
+ "explain": "Explain",
"explore-data": "Explore data",
"export-available-via-issue": "Export available via issue \"{{title}}\"",
"export-available-via-n-grants": "Export available via {{count}} access grants:",
diff --git a/frontend/src/locales/es-ES.json b/frontend/src/locales/es-ES.json
index 9ebbdb5fdc..6d36d7b52f 100644
--- a/frontend/src/locales/es-ES.json
+++ b/frontend/src/locales/es-ES.json
@@ -3419,6 +3419,7 @@
"data-explorer-sql-filter-placeholder": "Introduce un predicado de consulta, p. ej. WHERE id = 1",
"ddl-dml-requires-data-change-plan": "Para ejecutar sentencias DDL/DML en <environment></environment>, envíe un Plan de Cambio de Datos para su aprobación.",
"download-as-file": "Descargar como {{file}}",
+ "dry-run": "Simulación",
"duration-day": "{{days}} día",
"duration-days": "{{days}} días",
"duration-hour": "{{hours}} hora",
@@ -3428,6 +3429,7 @@
"expire-at": "Expira el {{time}}",
"expire-in": "Expira en {{time}}",
"expired": "Expirado",
+ "explain": "Explicar",
"explore-data": "Explorar datos",
"export-available-via-issue": "Exportación disponible vía issue \"{{title}}\"",
"export-available-via-n-grants": "Exportación disponible vía {{count}} concesiones de acceso:",
diff --git a/frontend/src/locales/ja-JP.json b/frontend/src/locales/ja-JP.json
index 44239613b9..45bdd07ffb 100644
--- a/frontend/src/locales/ja-JP.json
+++ b/frontend/src/locales/ja-JP.json
@@ -3419,6 +3419,7 @@
"data-explorer-sql-filter-placeholder": "クエリ条件を入力(例: WHERE id = 1)",
"ddl-dml-requires-data-change-plan": "<environment></environment> で DDL/DML ステートメントを実行するには、承認のためデータ変更プランを送信してください。",
"download-as-file": "{{file}} 形式でダウンロード",
+ "dry-run": "ドライラン",
"duration-day": "{{days}} 日",
"duration-days": "{{days}} 日",
"duration-hour": "{{hours}} 時間",
@@ -3428,6 +3429,7 @@
"expire-at": "{{time}} に期限切れ",
"expire-in": "{{time}} 後に期限切れ",
"expired": "期限切れ",
+ "explain": "実行計画を表示",
"explore-data": "データを探索",
"export-available-via-issue": "Issue「{{title}}」によりエクスポート可能",
"export-available-via-n-grants": "{{count}} 件のアクセス付与によりエクスポート可能:",
diff --git a/frontend/src/locales/vi-VN.json b/frontend/src/locales/vi-VN.json
index 19edc7dfd6..481db9d20b 100644
--- a/frontend/src/locales/vi-VN.json
+++ b/frontend/src/locales/vi-VN.json
@@ -3419,6 +3419,7 @@
"data-explorer-sql-filter-placeholder": "Nhập điều kiện truy vấn, ví dụ WHERE id = 1",
"ddl-dml-requires-data-change-plan": "Để thực thi câu lệnh DDL/DML trong <environment></environment>, vui lòng gửi Kế hoạch Thay đổi Dữ liệu để được phê duyệt.",
"download-as-file": "Tải xuống dưới dạng {{file}}",
+ "dry-run": "Chạy thử",
"duration-day": "{{days}} ngày",
"duration-days": "{{days}} ngày",
"duration-hour": "{{hours}} giờ",
@@ -3428,6 +3429,7 @@
"expire-at": "Hết hạn lúc {{time}}",
"expire-in": "Hết hạn sau {{time}}",
"expired": "Đã hết hạn",
+ "explain": "Giải thích",
"explore-data": "Khám phá dữ liệu",
"export-available-via-issue": "Xuất khả dụng qua issue \"{{title}}\"",
"export-available-via-n-grants": "Xuất khả dụng qua {{count}} cấp quyền truy cập:",
diff --git a/frontend/src/locales/zh-CN.json b/frontend/src/locales/zh-CN.json
index 73abd29fbd..c1d069b257 100644
--- a/frontend/src/locales/zh-CN.json
+++ b/frontend/src/locales/zh-CN.json
@@ -3419,6 +3419,7 @@
"data-explorer-sql-filter-placeholder": "输入查询条件,例如 WHERE id = 1",
"ddl-dml-requires-data-change-plan": "如需在 <environment></environment> 中执行 DDL/DML 语句,请创建变更计划以获得审批。",
"download-as-file": "下载为 {{file}} 格式",
+ "dry-run": "试运行",
"duration-day": "{{days}} 天",
"duration-days": "{{days}} 天",
"duration-hour": "{{hours}} 小时",
@@ -3428,6 +3429,7 @@
"expire-at": "{{time}} 过期",
"expire-in": "{{time}} 后过期",
"expired": "已过期",
+ "explain": "查看执行计划",
"explore-data": "浏览数据",
"export-available-via-issue": "通过工单 \"{{title}}\" 可导出",
"export-available-via-n-grants": "通过 {{count}} 个访问授权可导出:",
diff --git a/frontend/src/modules/sql-editor/components/ResultView/SingleResultView.tsx b/frontend/src/modules/sql-editor/components/ResultView/SingleResultView.tsx
index 6a8b92e82a..a77e2611e8 100644
--- a/frontend/src/modules/sql-editor/components/ResultView/SingleResultView.tsx
+++ b/frontend/src/modules/sql-editor/components/ResultView/SingleResultView.tsx
@@ -1,4 +1,3 @@
-import { create } from "@bufbuild/protobuf";
import { isEmpty } from "lodash-es";
import {
ArrowDownIcon,
@@ -51,11 +50,11 @@ import { Engine, ExportFormat } from "@/types/proto-es/v1/common_pb";
import type { Database } from "@/types/proto-es/v1/database_service_pb";
import {
QueryOption_ExplainFormat,
- QueryOptionSchema,
type QueryResult,
} from "@/types/proto-es/v1/sql_service_pb";
import { hasProjectPermissionV2 } from "@/utils/iam/permission";
import {
+ explainQueryOption,
isVisualizerEngine,
VISUALIZER_EXPLAIN_FORMATS,
} from "@/utils/queryPlanEngines";
@@ -1012,16 +1011,13 @@ async function explainStatement(
signal?: AbortSignal
): Promise<InlineQueryPlan | undefined> {
if (!statement) return undefined;
- const explainFormat = isVisualizerEngine(engine)
- ? QueryOption_ExplainFormat[VISUALIZER_EXPLAIN_FORMATS[engine]]
- : QueryOption_ExplainFormat.EXPLAIN_FORMAT_UNSPECIFIED;
const context: SQLEditorDatabaseQueryContext = {
id: uuidv4(),
params: {
...params,
statement,
explain: true,
- queryOption: create(QueryOptionSchema, { explainFormat }),
+ queryOption: explainQueryOption(engine),
},
status: "PENDING",
};
diff --git a/frontend/src/modules/sql-editor/components/StandardPanel/SQLEditor.tsx b/frontend/src/modules/sql-editor/components/StandardPanel/SQLEditor.tsx
index d50eaa0242..13d7658286 100644
--- a/frontend/src/modules/sql-editor/components/StandardPanel/SQLEditor.tsx
+++ b/frontend/src/modules/sql-editor/components/StandardPanel/SQLEditor.tsx
@@ -1,6 +1,7 @@
import type { IRange } from "monaco-editor";
import * as monaco from "monaco-editor";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
import { v1 as uuidv1 } from "uuid";
import { MonacoEditor } from "@/components/monaco/MonacoEditor";
import type {
@@ -31,6 +32,7 @@ import {
import { Engine } from "@/types/proto-es/v1/common_pb";
import { languageOfEngineV1 } from "@/types/sqlEditor/editor";
import { instanceV1AllowsExplain, nextAnimationFrame } from "@/utils";
+import { explainQueryOption } from "@/utils/queryPlanEngines";
import { useAIActions } from "../Panels/common/useAIActions";
import { monacoThemeName } from "../theme/derive";
import { useActiveSQLEditorTheme } from "../theme/useActiveSQLEditorTheme";
@@ -63,6 +65,7 @@ interface SQLEditorProps {
* imperatively focus the editor.
*/
export function SQLEditor({ onExecute }: SQLEditorProps) {
+ const { t } = useTranslation();
const { isReadOnly: readonly } = useSavedQueryAndTab();
const setShowAIPanel = useSQLEditorStore((s) => s.setShowAIPanel);
const setPendingInsertAtCaret = useSQLEditorStore(
@@ -196,11 +199,13 @@ export function SQLEditor({ onExecute }: SQLEditorProps) {
const tab = tabsState.tabsById.get(tabsState.currentTabId);
if (!tab) return;
const statement = getActiveStatement();
+ const engine = engineRef.current ?? Engine.MYSQL;
const params: SQLEditorQueryParams = {
connection: { ...tab.connection },
statement,
- engine: engineRef.current ?? Engine.MYSQL,
+ engine,
explain,
+ ...(explain ? { queryOption: explainQueryOption(engine) } : {}),
selection: newTab ? null : tab.editorState.selection,
};
onExecuteRef.current(params, newTab);
@@ -291,7 +296,7 @@ export function SQLEditor({ onExecute }: SQLEditorProps) {
const isBigQuery = engine === Engine.BIGQUERY;
const action = editorState.addAction({
id: "ExplainQuery",
- label: isBigQuery ? "Dry Run Query" : "Explain Query",
+ label: isBigQuery ? t("sql-editor.dry-run") : t("sql-editor.explain"),
keybindings: [monacoState.KeyMod.CtrlCmd | monacoState.KeyCode.KeyE],
contextMenuGroupId: "operation",
contextMenuOrder: 0,
@@ -300,7 +305,7 @@ export function SQLEditor({ onExecute }: SQLEditorProps) {
return () => {
action.dispose();
};
- }, [engine, runQueryAction, editorState, monacoState]);
+ }, [engine, runQueryAction, editorState, monacoState, t]);
// ----- pendingInsertAtCaret -----
const pendingInsertAtCaret = useSQLEditorStore((s) => s.pendingInsertAtCaret);
diff --git a/frontend/src/modules/sql-editor/components/TerminalPanel/CompactSQLEditor.tsx b/frontend/src/modules/sql-editor/components/TerminalPanel/CompactSQLEditor.tsx
index bbee196954..18438532e4 100644
--- a/frontend/src/modules/sql-editor/components/TerminalPanel/CompactSQLEditor.tsx
+++ b/frontend/src/modules/sql-editor/components/TerminalPanel/CompactSQLEditor.tsx
@@ -2,6 +2,7 @@ import { debounce } from "lodash-es";
import type { IDisposable } from "monaco-editor";
import * as monaco from "monaco-editor";
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useTranslation } from "react-i18next";
import { MonacoEditor } from "@/components/monaco/MonacoEditor";
import type {
IStandaloneCodeEditor,
@@ -16,6 +17,7 @@ import { dialectOfEngineV1 } from "@/types";
import { Engine } from "@/types/proto-es/v1/common_pb";
import { languageOfEngineV1 } from "@/types/sqlEditor/editor";
import { instanceV1AllowsExplain } from "@/utils";
+import { explainQueryOption } from "@/utils/queryPlanEngines";
import { monacoThemeName } from "../theme/derive";
import { useActiveSQLEditorTheme } from "../theme/useActiveSQLEditorTheme";
import {
@@ -54,6 +56,7 @@ export function CompactSQLEditor({
onHistory,
onClearScreen,
}: CompactSQLEditorProps) {
+ const { t } = useTranslation();
const { connection, instance, database } =
useConnectionOfCurrentSQLEditorTab();
@@ -266,7 +269,9 @@ export function CompactSQLEditor({
if (!allows) return;
const isBigQuery = engine === Engine.BIGQUERY;
- const label = isBigQuery ? "Dry Run Query" : "Explain Query";
+ const label = isBigQuery
+ ? t("sql-editor.dry-run")
+ : t("sql-editor.explain");
const action = editor.addAction({
id: "ExplainQuery",
@@ -282,6 +287,7 @@ export function CompactSQLEditor({
statement: propsRef.current.content,
engine,
explain: true,
+ queryOption: explainQueryOption(engine),
selection: null,
});
},
@@ -289,7 +295,7 @@ export function CompactSQLEditor({
return () => {
action.dispose();
};
- }, [engine, editorState]);
+ }, [engine, editorState, t]);
// Format-content event from `sqlEditorEvents`.
useEffect(() => {
diff --git a/frontend/src/utils/queryPlanEngines.test.ts b/frontend/src/utils/queryPlanEngines.test.ts
new file mode 100644
index 0000000000..b2eb5d08ef
--- /dev/null
+++ b/frontend/src/utils/queryPlanEngines.test.ts
@@ -0,0 +1,43 @@
+import { describe, expect, test } from "vitest";
+import { Engine } from "@/types/proto-es/v1/common_pb";
+import { QueryOption_ExplainFormat } from "@/types/proto-es/v1/sql_service_pb";
+import {
+ explainQueryOption,
+ isVisualizerEngine,
+ VISUALIZER_EXPLAIN_FORMATS,
+} from "./queryPlanEngines";
+
+describe("isVisualizerEngine", () => {
+ test("covers the engines the viewer has a parser for", () => {
+ expect(Object.keys(VISUALIZER_EXPLAIN_FORMATS).map(Number).sort()).toEqual(
+ [Engine.POSTGRES, Engine.MSSQL, Engine.SPANNER].sort()
+ );
+ expect(isVisualizerEngine(Engine.POSTGRES)).toBe(true);
+ expect(isVisualizerEngine(Engine.MYSQL)).toBe(false);
+ });
+});
+
+describe("explainQueryOption", () => {
+ test("asks for the format the viewer draws, so a plan takes one call", () => {
+ // Without this the engine answers in its own default — text, on
+ // PostgreSQL — and drawing it would mean explaining a second time.
+ expect(explainQueryOption(Engine.POSTGRES).explainFormat).toBe(
+ QueryOption_ExplainFormat.JSON
+ );
+ expect(explainQueryOption(Engine.MSSQL).explainFormat).toBe(
+ QueryOption_ExplainFormat.XML
+ );
+ expect(explainQueryOption(Engine.SPANNER).explainFormat).toBe(
+ QueryOption_ExplainFormat.JSON
+ );
+ });
+
+ test("leaves an engine the viewer cannot draw on its own default", () => {
+ expect(explainQueryOption(Engine.MYSQL).explainFormat).toBe(
+ QueryOption_ExplainFormat.EXPLAIN_FORMAT_UNSPECIFIED
+ );
+ expect(explainQueryOption(Engine.ORACLE).explainFormat).toBe(
+ QueryOption_ExplainFormat.EXPLAIN_FORMAT_UNSPECIFIED
+ );
+ });
+});
diff --git a/frontend/src/utils/queryPlanEngines.ts b/frontend/src/utils/queryPlanEngines.ts
index b4bbe6ff4e..91ff08c2de 100644
--- a/frontend/src/utils/queryPlanEngines.ts
+++ b/frontend/src/utils/queryPlanEngines.ts
@@ -1,4 +1,9 @@
+import { create } from "@bufbuild/protobuf";
import { Engine } from "@/types/proto-es/v1/common_pb";
+import {
+ QueryOption_ExplainFormat,
+ QueryOptionSchema,
+} from "@/types/proto-es/v1/sql_service_pb";
/**
* The engines the query-plan visualizer draws, each with the explain output it
@@ -17,3 +22,14 @@ export type VisualizerEngine = keyof typeof VISUALIZER_EXPLAIN_FORMATS;
export const isVisualizerEngine = (
engine: Engine
): engine is VisualizerEngine => engine in VISUALIZER_EXPLAIN_FORMATS;
+
+/**
+ * The options of an explain request: the format the visualizer draws where the
+ * engine has one, and the engine's default otherwise.
+ */
+export const explainQueryOption = (engine: Engine) =>
+ create(QueryOptionSchema, {
+ explainFormat: isVisualizerEngine(engine)
+ ? QueryOption_ExplainFormat[VISUALIZER_EXPLAIN_FORMATS[engine]]
+ : QueryOption_ExplainFormat.EXPLAIN_FORMAT_UNSPECIFIED,
+ });