Skip to content

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

feat: visualization for spanner explain (#18487)

ecmadao47ad5d3f3e47
diff --git a/backend/plugin/db/spanner/spanner.go b/backend/plugin/db/spanner/spanner.go
index 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, queryCont
row, 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.vue
index 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.vue
new file mode 100644
index 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.vue
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.vue
index 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();