Database governance built for humans and agents — controlling changes and access across every major database.
Go cicddata-governancedata-maskingdata-securitydatabase-accessdatabase-governancedevopsdevsecopsflywaygitopsliquibasemongodbmysqloraclepostgresqlschema-migrationssecuritysql-clientsqlservertidb
feat: visualization for spanner explain (#18487)
ecmadao47ad5d3f3e47
diff --git a/backend/plugin/db/spanner/spanner.go b/backend/plugin/db/spanner/spanner.goindex 555802fccb..f0591293bf 100644--- a/backend/plugin/db/spanner/spanner.go+++ b/backend/plugin/db/spanner/spanner.go@@ -320,7 +320,7 @@ func getDatabaseFromDSN(dsn string) (string, error) {// QueryConn queries a SQL statement in a given connection.func (d *Driver) QueryConn(ctx context.Context, _ *sql.Conn, statement string, queryContext db.QueryContext) ([]*v1pb.QueryResult, error) {if queryContext.Explain {- return nil, errors.New("Spanner does not support EXPLAIN")+ return d.explainStatement(ctx, statement)}stmts, err := util.SanitizeSQL(statement)@@ -391,7 +391,15 @@ func (d *Driver) queryStatement(ctx context.Context, statement string, queryControw, err := iter.Next()if err == iterator.Done {- return nil, nil+ // Empty result set - return empty QueryResult with column info+ columnTypeNames, typeErr := getColumnTypeNames(iter)+ if typeErr != nil {+ return nil, typeErr+ }+ return &v1pb.QueryResult{+ ColumnNames: getColumnNames(iter),+ ColumnTypeNames: columnTypeNames,+ }, nil}if err != nil {return nil, err@@ -549,3 +557,142 @@ func readRow(row *spanner.Row) (*v1pb.QueryRow, error) {return result, nil}++// explainStatement returns the query plan for the given statement as JSON.+func (d *Driver) explainStatement(ctx context.Context, statement string) ([]*v1pb.QueryResult, error) {+ if d.client == nil {+ return nil, errors.New("spanner client is not initialized, database name may be missing")+ }++ stmts, err := util.SanitizeSQL(statement)+ if err != nil {+ return nil, err+ }++ var results []*v1pb.QueryResult+ for _, stmt := range stmts {+ startTime := time.Now()+ queryResult, err := func() (*v1pb.QueryResult, error) {+ plan, err := d.client.Single().AnalyzeQuery(ctx, spanner.NewStatement(stmt))+ if err != nil {+ return nil, err+ }++ // Convert the query plan to JSON+ planJSON, err := convertQueryPlanToJSON(plan)+ if err != nil {+ return nil, errors.Wrap(err, "failed to convert query plan to JSON")+ }++ return &v1pb.QueryResult{+ ColumnNames: []string{"QUERY PLAN"},+ ColumnTypeNames: []string{"JSON"},+ Rows: []*v1pb.QueryRow{+ {+ Values: []*v1pb.RowValue{+ {Kind: &v1pb.RowValue_StringValue{StringValue: planJSON}},+ },+ },+ },+ }, nil+ }()+ if err != nil {+ queryResult = &v1pb.QueryResult{+ Error: err.Error(),+ }+ }+ queryResult.Statement = stmt+ queryResult.Latency = durationpb.New(time.Since(startTime))+ queryResult.RowsCount = int64(len(queryResult.Rows))+ results = append(results, queryResult)+ }++ return results, nil+}++// PlanNode represents a node in the Spanner query plan for JSON serialization.+type PlanNode struct {+ Index int32 `json:"index"`+ Kind string `json:"kind"`+ DisplayName string `json:"displayName"`+ ChildLinks []ChildLink `json:"childLinks,omitempty"`+ ShortRepresentation *ShortRepresentation `json:"shortRepresentation,omitempty"`+ Metadata map[string]any `json:"metadata,omitempty"`+ ExecutionStats map[string]any `json:"executionStats,omitempty"`+}++// ChildLink represents a child link in the query plan.+type ChildLink struct {+ ChildIndex int32 `json:"childIndex"`+ Type string `json:"type,omitempty"`+ Variable string `json:"variable,omitempty"`+}++// ShortRepresentation represents the short representation of a scalar node.+type ShortRepresentation struct {+ Description string `json:"description"`+ Subqueries map[string]int32 `json:"subqueries,omitempty"`+}++// QueryPlan represents the full query plan for JSON serialization.+type QueryPlan struct {+ PlanNodes []PlanNode `json:"planNodes"`+}++// convertQueryPlanToJSON converts a Spanner QueryPlan to JSON string.+func convertQueryPlanToJSON(plan *sppb.QueryPlan) (string, error) {+ if plan == nil {+ return "{}", nil+ }++ queryPlan := QueryPlan{+ PlanNodes: make([]PlanNode, 0, len(plan.PlanNodes)),+ }++ for _, node := range plan.PlanNodes {+ planNode := PlanNode{+ Index: node.Index,+ Kind: node.Kind.String(),+ DisplayName: node.DisplayName,+ }++ // Convert child links+ if len(node.ChildLinks) > 0 {+ planNode.ChildLinks = make([]ChildLink, 0, len(node.ChildLinks))+ for _, link := range node.ChildLinks {+ planNode.ChildLinks = append(planNode.ChildLinks, ChildLink{+ ChildIndex: link.ChildIndex,+ Type: link.Type,+ Variable: link.Variable,+ })+ }+ }++ // Convert short representation+ if node.ShortRepresentation != nil {+ planNode.ShortRepresentation = &ShortRepresentation{+ Description: node.ShortRepresentation.Description,+ Subqueries: node.ShortRepresentation.Subqueries,+ }+ }++ // Convert metadata+ if node.Metadata != nil {+ planNode.Metadata = node.Metadata.AsMap()+ }++ // Convert execution stats+ if node.ExecutionStats != nil {+ planNode.ExecutionStats = node.ExecutionStats.AsMap()+ }++ queryPlan.PlanNodes = append(queryPlan.PlanNodes, planNode)+ }++ jsonBytes, err := json.Marshal(queryPlan)+ if err != nil {+ return "", err+ }++ return string(jsonBytes), nil+}diff --git a/frontend/src/ExplainVisualizerApp.vue b/frontend/src/ExplainVisualizerApp.vueindex 27dae64825..0007eb7cce 100644--- a/frontend/src/ExplainVisualizerApp.vue+++ b/frontend/src/ExplainVisualizerApp.vue@@ -13,6 +13,12 @@ref="mssqlContainer"class="mssql-query-plan-container"/>+ <!-- Spanner visualization -->+ <SpannerQueryPlan+ v-else-if="isSpanner"+ :plan-source="storedQuery.explain"+ :plan-query="storedQuery.statement"+ /><!-- Fallback for unsupported engines --><div v-else class="unsupported-engine"><h2>Unsupported Database Engine</h2>@@ -31,6 +37,7 @@ import "pev2/dist/pev2.css";import "html-query-plan/css/qp.css";import { parse } from "qs";import { computed, onMounted, ref } from "vue";+import { SpannerQueryPlan } from "@/components/SpannerQueryPlan";import { Engine } from "@/types/proto-es/v1/common_pb";import { readExplainFromToken } from "@/utils/pev2";@@ -54,6 +61,7 @@ const isPostgreSQL = computed(() => storedQuery.value?.engine === Engine.POSTGRES);const isMSSQL = computed(() => storedQuery.value?.engine === Engine.MSSQL);+const isSpanner = computed(() => storedQuery.value?.engine === Engine.SPANNER);const mssqlContainer = ref<HTMLDivElement>();const qpLoaded = ref(false);diff --git a/frontend/src/components/SpannerQueryPlan/SpannerPlanNode.vue b/frontend/src/components/SpannerQueryPlan/SpannerPlanNode.vuenew file mode 100644index 0000000000..0717737a34--- /dev/null+++ b/frontend/src/components/SpannerQueryPlan/SpannerPlanNode.vue@@ -0,0 +1,256 @@+<template>+ <div class="plan-node" :class="{ 'is-scalar': isScalar }">+ <div class="node-content" @click="toggleExpanded">+ <span class="expand-icon" v-if="hasChildren">+ <ChevronDownIcon v-if="expanded" class="w-4" />+ <ChevronUpIcon v-else class="w-4" />+ </span>+ <span v-else class="expand-icon-placeholder"></span>++ <span class="node-kind" :class="kindClass">{{ node.kind }}</span>+ <span class="node-name">{{ node.displayName }}</span>++ <span v-if="shortDescription" class="node-description">+ {{ shortDescription }}+ </span>+ </div>++ <div v-if="hasMetadata" class="node-metadata">+ <div+ v-for="(value, key) in displayMetadata"+ :key="key"+ class="metadata-item"+ >+ <span class="metadata-key">{{ key }}:</span>+ <span class="metadata-value">{{ formatValue(value) }}</span>+ </div>+ </div>++ <div v-if="expanded && hasChildren" class="node-children">+ <div+ v-for="childLink in relationalChildLinks"+ :key="childLink.childIndex"+ class="child-wrapper"+ >+ <div v-if="childLink.type" class="child-link-type">+ {{ childLink.type }}+ </div>+ <SpannerPlanNode+ :node="getChildNode(childLink.childIndex)"+ :all-nodes="allNodes"+ :depth="depth + 1"+ />+ </div>+ </div>+ </div>+</template>++<script setup lang="ts">+import { ChevronDownIcon, ChevronUpIcon } from "lucide-vue-next";+import { computed, ref } from "vue";+import type { SpannerChildLink, SpannerPlanNodeData } from "./types";++const props = defineProps<{+ node: SpannerPlanNodeData;+ allNodes: SpannerPlanNodeData[];+ depth: number;+}>();++const expanded = ref(true);++const isScalar = computed(() => props.node.kind === "SCALAR");++const kindClass = computed(() => {+ switch (props.node.kind) {+ case "RELATIONAL":+ return "kind-relational";+ case "SCALAR":+ return "kind-scalar";+ default:+ return "kind-unknown";+ }+});++const hasChildren = computed(() => {+ return relationalChildLinks.value.length > 0;+});++// Only show relational children in the tree+const relationalChildLinks = computed((): SpannerChildLink[] => {+ if (!props.node.childLinks) return [];+ return props.node.childLinks.filter((link) => {+ const childNode = props.allNodes.find((n) => n.index === link.childIndex);+ return childNode && childNode.kind === "RELATIONAL";+ });+});++const shortDescription = computed(() => {+ return props.node.shortRepresentation?.description;+});++const hasMetadata = computed(() => {+ return props.node.metadata && Object.keys(props.node.metadata).length > 0;+});++const displayMetadata = computed(() => {+ if (!props.node.metadata) return {};+ // Filter out some internal metadata keys+ const filtered: Record<string, unknown> = {};+ for (const [key, value] of Object.entries(props.node.metadata)) {+ if (!key.startsWith("_")) {+ filtered[key] = value;+ }+ }+ return filtered;+});++const toggleExpanded = () => {+ if (hasChildren.value) {+ expanded.value = !expanded.value;+ }+};++const getChildNode = (index: number): SpannerPlanNodeData => {+ const child = props.allNodes.find((n) => n.index === index);+ if (!child) {+ return {+ index,+ kind: "UNKNOWN",+ displayName: `Unknown Node (${index})`,+ };+ }+ return child;+};++const formatValue = (value: unknown): string => {+ if (value === null || value === undefined) return "null";+ if (typeof value === "object") {+ return JSON.stringify(value);+ }+ return String(value);+};+</script>++<style scoped>+.plan-node {+ margin-left: 0;+ font-size: 14px;+}++.plan-node.is-scalar {+ display: inline;+}++.node-content {+ display: flex;+ align-items: center;+ gap: 8px;+ padding: 6px 8px;+ border-radius: 4px;+ cursor: pointer;+ transition: background-color 0.15s ease;+}++.node-content:hover {+ background-color: #f0f4f8;+}++.expand-icon {+ width: 16px;+ font-size: 10px;+ color: #666;+ user-select: none;+}++.expand-icon-placeholder {+ width: 16px;+}++.node-kind {+ font-size: 11px;+ font-weight: 600;+ padding: 2px 6px;+ border-radius: 3px;+ text-transform: uppercase;+}++.kind-relational {+ background-color: #e3f2fd;+ color: #1565c0;+}++.kind-scalar {+ background-color: #f3e5f5;+ color: #7b1fa2;+}++.kind-unknown {+ background-color: #f5f5f5;+ color: #666;+}++.node-name {+ font-weight: 500;+ color: #333;+}++.node-description {+ font-family: "SF Mono", Monaco, Consolas, "Liberation Mono", "Courier New",+ monospace;+ font-size: 12px;+ color: #666;+ background-color: #f5f5f5;+ padding: 2px 6px;+ border-radius: 3px;+ max-width: 400px;+ overflow: hidden;+ text-overflow: ellipsis;+ white-space: nowrap;+}++.node-metadata {+ margin-left: 40px;+ margin-top: 4px;+ padding: 8px 12px;+ background-color: #fafafa;+ border-radius: 4px;+ border-left: 3px solid #e0e0e0;+}++.metadata-item {+ display: flex;+ gap: 8px;+ font-size: 12px;+ line-height: 1.6;+}++.metadata-key {+ font-weight: 500;+ color: #666;+}++.metadata-value {+ font-family: "SF Mono", Monaco, Consolas, "Liberation Mono", "Courier New",+ monospace;+ color: #333;+ word-break: break-all;+}++.node-children {+ margin-left: 24px;+ padding-left: 16px;+ border-left: 2px solid #e0e0e0;+}++.child-wrapper {+ margin-top: 4px;+}++.child-link-type {+ font-size: 11px;+ color: #999;+ margin-left: 8px;+ margin-bottom: 2px;+ font-style: italic;+}+</style>diff --git a/frontend/src/components/SpannerQueryPlan/SpannerQueryPlan.vue b/frontend/src/components/SpannerQueryPlan/SpannerQueryPlan.vuenew file mode 100644index 0000000000..8ad713100a--- /dev/null+++ b/frontend/src/components/SpannerQueryPlan/SpannerQueryPlan.vue@@ -0,0 +1,92 @@+<template>+ <div class="spanner-query-plan">+ <div class="plan-header">+ <h3>Query Plan</h3>+ <div v-if="query" class="query-text">{{ query }}</div>+ </div>+ <div class="plan-tree">+ <SpannerPlanNode+ v-if="rootNode"+ :node="rootNode"+ :all-nodes="planNodes"+ :depth="0"+ />+ <div v-else class="no-plan">No query plan available</div>+ </div>+ </div>+</template>++<script setup lang="ts">+import { computed } from "vue";+import SpannerPlanNode from "./SpannerPlanNode.vue";+import type { SpannerPlanNodeData } from "./types";++const props = defineProps<{+ planSource: string;+ planQuery?: string;+}>();++const query = computed(() => props.planQuery);++const planNodes = computed((): SpannerPlanNodeData[] => {+ try {+ const parsed = JSON.parse(props.planSource);+ return parsed.planNodes || [];+ } catch {+ return [];+ }+});++const rootNode = computed((): SpannerPlanNodeData | undefined => {+ if (planNodes.value.length === 0) return undefined;+ // The first node (index 0) is the root node in Spanner query plans+ return planNodes.value.find((node) => node.index === 0);+});+</script>++<style scoped>+.spanner-query-plan {+ width: 100%;+ height: 100%;+ overflow: auto;+ padding: 16px;+ font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen,+ Ubuntu, Cantarell, "Open Sans", "Helvetica Neue", sans-serif;+}++.plan-header {+ margin-bottom: 16px;+ padding-bottom: 12px;+ border-bottom: 1px solid #e0e0e0;+}++.plan-header h3 {+ margin: 0 0 8px 0;+ font-size: 18px;+ font-weight: 600;+ color: #333;+}++.query-text {+ font-family: "SF Mono", Monaco, Consolas, "Liberation Mono", "Courier New",+ monospace;+ font-size: 13px;+ color: #666;+ background-color: #f5f5f5;+ padding: 8px 12px;+ border-radius: 4px;+ white-space: pre-wrap;+ word-break: break-word;+}++.plan-tree {+ padding: 8px 0;+}++.no-plan {+ color: #999;+ font-style: italic;+ padding: 16px;+ text-align: center;+}+</style>diff --git a/frontend/src/components/SpannerQueryPlan/index.ts b/frontend/src/components/SpannerQueryPlan/index.tsnew file mode 100644index 0000000000..b90040f2e0--- /dev/null+++ b/frontend/src/components/SpannerQueryPlan/index.ts@@ -0,0 +1,2 @@+export { default as SpannerQueryPlan } from "./SpannerQueryPlan.vue";+export * from "./types";diff --git a/frontend/src/components/SpannerQueryPlan/types.ts b/frontend/src/components/SpannerQueryPlan/types.tsnew file mode 100644index 0000000000..fc9d587212--- /dev/null+++ b/frontend/src/components/SpannerQueryPlan/types.ts@@ -0,0 +1,24 @@+export interface SpannerChildLink {+ childIndex: number;+ type?: string;+ variable?: string;+}++export interface SpannerShortRepresentation {+ description: string;+ subqueries?: Record<string, number>;+}++export interface SpannerPlanNodeData {+ index: number;+ kind: string;+ displayName: string;+ childLinks?: SpannerChildLink[];+ shortRepresentation?: SpannerShortRepresentation;+ metadata?: Record<string, unknown>;+ executionStats?: Record<string, unknown>;+}++export interface SpannerQueryPlanData {+ planNodes: SpannerPlanNodeData[];+}diff --git a/frontend/src/utils/v1/instance.ts b/frontend/src/utils/v1/instance.tsindex 000a13645d..8e00d4aee1 100644--- a/frontend/src/utils/v1/instance.ts+++ b/frontend/src/utils/v1/instance.ts@@ -244,6 +244,7 @@ export const instanceV1AllowsExplain = (Engine.REDSHIFT,Engine.SNOWFLAKE,Engine.STARROCKS,+ Engine.SPANNER,].includes(engine);};diff --git a/frontend/src/views/sql-editor/EditorCommon/ResultView/SingleResultViewV1.vue b/frontend/src/views/sql-editor/EditorCommon/ResultView/SingleResultViewV1.vueindex f53ee0e358..59620b3e5a 100644--- a/frontend/src/views/sql-editor/EditorCommon/ResultView/SingleResultViewV1.vue+++ b/frontend/src/views/sql-editor/EditorCommon/ResultView/SingleResultViewV1.vue@@ -604,7 +604,9 @@ const engine = computed(() => props.database.instanceResource.engine);const showVisualizeButton = computed((): boolean => {return (- (engine.value === Engine.POSTGRES || engine.value === Engine.MSSQL) &&+ (engine.value === Engine.POSTGRES ||+ engine.value === Engine.MSSQL ||+ engine.value === Engine.SPANNER) &&props.params.explain);});@@ -612,7 +614,7 @@ const showVisualizeButton = computed((): boolean => {const visualizeExplain = async () => {let token: string | undefined;try {- if (engine.value === Engine.POSTGRES) {+ if (engine.value === Engine.POSTGRES || engine.value === Engine.SPANNER) {token = getExplainToken(props.result);} else if (engine.value === Engine.MSSQL) {token = await getExplainTokenForMSSQL();