Skip to content

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

feat(sql-editor): draw query plans for twelve more engines (#21670)

Danny Xu79c7a756ef53
diff --git a/backend/api/v1/sql_service_test.go b/backend/api/v1/sql_service_test.go
index 5155742461..730cb8224a 100644
--- a/backend/api/v1/sql_service_test.go
+++ b/backend/api/v1/sql_service_test.go
@@ -362,10 +362,25 @@ func TestValidateExplainFormat(t *testing.T) {
{name: "spanner json", engine: storepb.Engine_SPANNER, format: v1pb.QueryOption_JSON},
{name: "spanner has no text plan", engine: storepb.Engine_SPANNER, format: v1pb.QueryOption_TEXT, wantErr: true},
{name: "mysql text", engine: storepb.Engine_MYSQL, format: v1pb.QueryOption_TEXT},
- {name: "mysql json is not implemented yet", engine: storepb.Engine_MYSQL, format: v1pb.QueryOption_JSON, wantErr: true},
+ {name: "mysql json", engine: storepb.Engine_MYSQL, format: v1pb.QueryOption_JSON},
+ {name: "mysql has no xml plan", engine: storepb.Engine_MYSQL, format: v1pb.QueryOption_XML, wantErr: true},
+ {name: "mariadb json", engine: storepb.Engine_MARIADB, format: v1pb.QueryOption_JSON},
+ {name: "tidb json", engine: storepb.Engine_TIDB, format: v1pb.QueryOption_JSON},
+ {name: "oceanbase json", engine: storepb.Engine_OCEANBASE, format: v1pb.QueryOption_JSON},
+ {name: "oracle json", engine: storepb.Engine_ORACLE, format: v1pb.QueryOption_JSON},
{name: "oracle xml is not implemented yet", engine: storepb.Engine_ORACLE, format: v1pb.QueryOption_XML, wantErr: true},
+ {name: "clickhouse json", engine: storepb.Engine_CLICKHOUSE, format: v1pb.QueryOption_JSON},
+ {name: "trino json", engine: storepb.Engine_TRINO, format: v1pb.QueryOption_JSON},
+ // CockroachDB's own EXPLAIN takes no JSON — the plan the driver reads is
+ // the one encoded in the diagram EXPLAIN (DISTSQL) links to.
+ {name: "cockroachdb json", engine: storepb.Engine_COCKROACHDB, format: v1pb.QueryOption_JSON},
+ {name: "starrocks json is a syntax error on the engine", engine: storepb.Engine_STARROCKS, format: v1pb.QueryOption_JSON, wantErr: true},
+ {name: "doris text", engine: storepb.Engine_DORIS, format: v1pb.QueryOption_TEXT},
+ {name: "doris json is a syntax error on the engine too", engine: storepb.Engine_DORIS, format: v1pb.QueryOption_JSON, wantErr: true},
+ {name: "hive json is not implemented yet", engine: storepb.Engine_HIVE, format: v1pb.QueryOption_JSON, wantErr: true},
{name: "redis explains nothing at all", engine: storepb.Engine_REDIS, format: v1pb.QueryOption_TEXT, wantErr: true},
- {name: "mongodb explains nothing at all", engine: storepb.Engine_MONGODB, format: v1pb.QueryOption_JSON, wantErr: true},
+ {name: "mongodb json", engine: storepb.Engine_MONGODB, format: v1pb.QueryOption_JSON},
+ {name: "mongodb has no text plan", engine: storepb.Engine_MONGODB, format: v1pb.QueryOption_TEXT, wantErr: true},
// A driver that ignores the explain flag runs the statement instead, and
// the explain path skips the read-only validation, so an unspecified
// format must be refused here too rather than reaching the driver.
diff --git a/backend/plugin/db/cockroachdb/cockroachdb.go b/backend/plugin/db/cockroachdb/cockroachdb.go
index 00d9a751aa..1fe1ad1638 100644
--- a/backend/plugin/db/cockroachdb/cockroachdb.go
+++ b/backend/plugin/db/cockroachdb/cockroachdb.go
@@ -2,9 +2,13 @@
package cockroachdb
import (
+ "bytes"
+ "compress/zlib"
"context"
"database/sql"
+ "encoding/base64"
"fmt"
+ "io"
"log/slog"
"net"
"regexp"
@@ -618,11 +622,13 @@ func (*Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string,
var results []*v1pb.QueryResult
for _, singleSQL := range singleSQLs {
statement := singleSQL
+ planAsJSON := false
if queryContext.Explain {
explained, err := base.ExplainStatement(storepb.Engine_COCKROACHDB, statement, db.ExplainFormat(queryContext.Option.GetExplainFormat()))
if err != nil {
return nil, err
}
+ planAsJSON = db.ExplainFormat(queryContext.Option.GetExplainFormat()) == base.ExplainFormatJSON
statement = explained
} else if queryContext.Limit > 0 {
statement = base.StatementWithResultLimit(storepb.Engine_COCKROACHDB, statement, queryContext.Limit, "")
@@ -665,6 +671,9 @@ func (*Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string,
}); err != nil {
return nil, err
}
+ if planAsJSON {
+ return planDiagram(r)
+ }
return r, nil
}
@@ -700,3 +709,61 @@ func (*Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string,
return results, nil
}
+
+// diagramLink is the line EXPLAIN (DISTSQL) prints after the text plan. What
+// follows the fragment marker is the plan itself, deflated and base64'd.
+var diagramLink = regexp.MustCompile(`https?://\S*#([A-Za-z0-9+/_=-]+)`)
+
+// planDiagram returns the physical plan EXPLAIN (DISTSQL) encodes in the link
+// it prints, as the JSON document the query-plan viewer parses.
+//
+// CockroachDB publishes no plan as a document: every EXPLAIN option of its own
+// returns text, and the one machine-readable form it has is the payload behind
+// this link, which its own diagram page decodes in the browser. Decoding it
+// here is what lets the viewer draw the plan without the browser fetching
+// anything, and it is the same move the Oracle driver makes in rendering the
+// plan table.
+func planDiagram(result *v1pb.QueryResult) (*v1pb.QueryResult, error) {
+ var payload string
+ for _, row := range result.GetRows() {
+ for _, value := range row.GetValues() {
+ if match := diagramLink.FindStringSubmatch(value.GetStringValue()); match != nil {
+ payload = match[1]
+ }
+ }
+ }
+ if payload == "" {
+ return nil, errors.New("the plan carried no diagram to read")
+ }
+ // CockroachDB encodes with the standard alphabet, but the payload rides in
+ // a URL fragment, so accept either spelling of the two bytes that differ.
+ normalized := strings.NewReplacer("-", "+", "_", "/").Replace(strings.TrimRight(payload, "="))
+ deflated, err := base64.RawStdEncoding.DecodeString(normalized)
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to decode the query plan")
+ }
+ reader, err := zlib.NewReader(bytes.NewReader(deflated))
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to read the query plan")
+ }
+ defer reader.Close()
+ // A plan is small; the bound keeps a corrupt payload from inflating
+ // without end.
+ plan, err := io.ReadAll(io.LimitReader(reader, maxPlanBytes))
+ if err != nil {
+ return nil, errors.Wrap(err, "failed to read the query plan")
+ }
+
+ return &v1pb.QueryResult{
+ ColumnNames: []string{"plan"},
+ ColumnTypeNames: []string{"TEXT"},
+ Rows: []*v1pb.QueryRow{{Values: []*v1pb.RowValue{
+ {Kind: &v1pb.RowValue_StringValue{StringValue: string(plan)}},
+ }}},
+ }, nil
+}
+
+// maxPlanBytes bounds the inflated plan. CockroachDB's diagrams run to a few
+// tens of kilobytes; this is far above that and far below anything that would
+// trouble the editor.
+const maxPlanBytes = 8 << 20
diff --git a/backend/plugin/db/cockroachdb/cockroachdb_test.go b/backend/plugin/db/cockroachdb/cockroachdb_test.go
index be4bbc24f8..3469599d6b 100644
--- a/backend/plugin/db/cockroachdb/cockroachdb_test.go
+++ b/backend/plugin/db/cockroachdb/cockroachdb_test.go
@@ -1,18 +1,23 @@
package cockroachdb
import (
+ "bytes"
+ "compress/zlib"
"crypto/rand"
"crypto/rsa"
"crypto/x509"
"crypto/x509/pkix"
+ "encoding/base64"
"encoding/pem"
"math/big"
+ "strings"
"testing"
"time"
"github.com/stretchr/testify/require"
storepb "github.com/bytebase/bytebase/backend/generated-go/store"
+ v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"
"github.com/bytebase/bytebase/backend/plugin/db"
)
@@ -218,3 +223,68 @@ func generateCAAndServerCertificates(t *testing.T, hosts []string) (string, map[
caPEM := pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: caDER})
return string(caPEM), serverCertDERByHost
}
+
+// encodeDiagram is how CockroachDB encodes the plan behind the link it prints:
+// deflated, then base64 in the standard alphabet.
+func encodeDiagram(t *testing.T, plan string) string {
+ t.Helper()
+ var deflated bytes.Buffer
+ writer := zlib.NewWriter(&deflated)
+ _, err := writer.Write([]byte(plan))
+ require.NoError(t, err)
+ require.NoError(t, writer.Close())
+ return base64.RawStdEncoding.EncodeToString(deflated.Bytes())
+}
+
+func diagramResult(lines ...string) *v1pb.QueryResult {
+ result := &v1pb.QueryResult{ColumnNames: []string{"info"}}
+ for _, line := range lines {
+ result.Rows = append(result.Rows, &v1pb.QueryRow{Values: []*v1pb.RowValue{
+ {Kind: &v1pb.RowValue_StringValue{StringValue: line}},
+ }})
+ }
+ return result
+}
+
+// TestPlanDiagram covers the one machine-readable plan CockroachDB publishes.
+// Every EXPLAIN option of its own returns text; this is the payload behind the
+// link EXPLAIN (DISTSQL) prints beside that text.
+func TestPlanDiagram(t *testing.T) {
+ t.Parallel()
+ const plan = `{"processors":[{"core":{"title":"TableReader/0"}}],"edges":[]}`
+
+ t.Run("reads the plan out of the link", func(t *testing.T) {
+ t.Parallel()
+ result, err := planDiagram(diagramResult(
+ "distribution: local",
+ "• scan",
+ "Diagram: https://cockroachdb.github.io/distsqlplan/decode.html#"+encodeDiagram(t, plan),
+ ))
+ require.NoError(t, err)
+ require.Equal(t, []string{"plan"}, result.GetColumnNames())
+ require.Len(t, result.GetRows(), 1)
+ require.JSONEq(t, plan, result.GetRows()[0].GetValues()[0].GetStringValue())
+ })
+
+ t.Run("reads a link written in the URL alphabet", func(t *testing.T) {
+ t.Parallel()
+ // The payload rides in a URL fragment, so either spelling of the two
+ // bytes that differ between the alphabets has to decode.
+ encoded := strings.NewReplacer("+", "-", "/", "_").Replace(encodeDiagram(t, plan))
+ result, err := planDiagram(diagramResult("Diagram: https://example.test/#" + encoded))
+ require.NoError(t, err)
+ require.JSONEq(t, plan, result.GetRows()[0].GetValues()[0].GetStringValue())
+ })
+
+ t.Run("refuses a plan with no link in it", func(t *testing.T) {
+ t.Parallel()
+ _, err := planDiagram(diagramResult("distribution: local", "• scan"))
+ require.ErrorContains(t, err, "no diagram")
+ })
+
+ t.Run("refuses a link it cannot read", func(t *testing.T) {
+ t.Parallel()
+ _, err := planDiagram(diagramResult("Diagram: https://example.test/#bm90emxpYg"))
+ require.Error(t, err)
+ })
+}
diff --git a/backend/plugin/db/explain_format.go b/backend/plugin/db/explain_format.go
index 77cc4b3127..1d2b92fc37 100644
--- a/backend/plugin/db/explain_format.go
+++ b/backend/plugin/db/explain_format.go
@@ -1,6 +1,8 @@
package db
import (
+ "strings"
+
storepb "github.com/bytebase/bytebase/backend/generated-go/store"
v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"
"github.com/bytebase/bytebase/backend/plugin/parser/base"
@@ -32,9 +34,13 @@ func SupportedExplainFormats(engine storepb.Engine) []v1pb.QueryOption_ExplainFo
return []v1pb.QueryOption_ExplainFormat{v1pb.QueryOption_TEXT, v1pb.QueryOption_JSON, v1pb.QueryOption_XML, v1pb.QueryOption_YAML}
case storepb.Engine_MSSQL:
return []v1pb.QueryOption_ExplainFormat{v1pb.QueryOption_TEXT, v1pb.QueryOption_XML}
- case storepb.Engine_SPANNER:
+ case storepb.Engine_SPANNER, storepb.Engine_MONGODB:
return []v1pb.QueryOption_ExplainFormat{v1pb.QueryOption_JSON}
- case storepb.Engine_MONGODB, storepb.Engine_REDIS, storepb.Engine_DYNAMODB,
+ case storepb.Engine_MYSQL, storepb.Engine_MARIADB, storepb.Engine_TIDB,
+ storepb.Engine_ORACLE, storepb.Engine_CLICKHOUSE, storepb.Engine_TRINO,
+ storepb.Engine_OCEANBASE, storepb.Engine_COCKROACHDB:
+ return []v1pb.QueryOption_ExplainFormat{v1pb.QueryOption_TEXT, v1pb.QueryOption_JSON}
+ case storepb.Engine_REDIS, storepb.Engine_DYNAMODB,
storepb.Engine_CASSANDRA, storepb.Engine_COSMOSDB, storepb.Engine_DATABRICKS,
storepb.Engine_ELASTICSEARCH:
return nil
@@ -49,14 +55,35 @@ func ExplainResultFormat(engine storepb.Engine, format v1pb.QueryOption_ExplainF
if engine == storepb.Engine_BIGQUERY {
return v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED, false
}
- if engine == storepb.Engine_MYSQL {
+ // MySQL has no text format to name: the plain EXPLAIN that every other
+ // format builds follows the session's explain_format from 8.0.32, so the
+ // JSON we ask for outright is the only answer the request settles.
+ if engine == storepb.Engine_MYSQL && format != v1pb.QueryOption_JSON {
return v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED, true
}
if format != v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED {
return format, true
}
- if engine == storepb.Engine_SPANNER {
+ if engine == storepb.Engine_SPANNER || engine == storepb.Engine_MONGODB {
return v1pb.QueryOption_JSON, true
}
return v1pb.QueryOption_TEXT, true
}
+
+// TypedExplainPlan describes the plan a result carries because the caller's own
+// statement asked for one, from the engine parser's DescribeExplain:
+//
+// r.QueryPlan = db.TypedExplainPlan(mysqlparser.DescribeExplain(statement))
+//
+// A format the enum does not name is left unspecified, which is the answer for
+// MySQL's omitted FORMAT: it follows the session's explain_format, so the
+// statement does not settle it, and the viewer reads unknown as text.
+func TypedExplainPlan(format string, executed, isExplain bool) *v1pb.QueryResult_QueryPlan {
+ if !isExplain {
+ return nil
+ }
+ return &v1pb.QueryResult_QueryPlan{
+ Format: v1pb.QueryOption_ExplainFormat(v1pb.QueryOption_ExplainFormat_value[strings.ToUpper(format)]),
+ Executed: executed,
+ }
+}
diff --git a/backend/plugin/db/explain_format_test.go b/backend/plugin/db/explain_format_test.go
index 94a653a50c..3cba1dda76 100644
--- a/backend/plugin/db/explain_format_test.go
+++ b/backend/plugin/db/explain_format_test.go
@@ -41,6 +41,20 @@ func TestExplainResultFormat(t *testing.T) {
{name: "mssql xml", engine: storepb.Engine_MSSQL, format: v1pb.QueryOption_XML, want: v1pb.QueryOption_XML, isPlan: true},
{name: "spanner default", engine: storepb.Engine_SPANNER, want: v1pb.QueryOption_JSON, isPlan: true},
{name: "mysql unknown", engine: storepb.Engine_MYSQL, format: v1pb.QueryOption_TEXT, want: v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED, isPlan: true},
+ // The one format MySQL asks for outright, and so the one it can report.
+ {name: "mysql json", engine: storepb.Engine_MYSQL, format: v1pb.QueryOption_JSON, want: v1pb.QueryOption_JSON, isPlan: true},
+ {name: "mariadb json", engine: storepb.Engine_MARIADB, format: v1pb.QueryOption_JSON, want: v1pb.QueryOption_JSON, isPlan: true},
+ {name: "mariadb default", engine: storepb.Engine_MARIADB, want: v1pb.QueryOption_TEXT, isPlan: true},
+ {name: "tidb json", engine: storepb.Engine_TIDB, format: v1pb.QueryOption_JSON, want: v1pb.QueryOption_JSON, isPlan: true},
+ {name: "oracle json", engine: storepb.Engine_ORACLE, format: v1pb.QueryOption_JSON, want: v1pb.QueryOption_JSON, isPlan: true},
+ {name: "oracle default", engine: storepb.Engine_ORACLE, want: v1pb.QueryOption_TEXT, isPlan: true},
+ {name: "clickhouse json", engine: storepb.Engine_CLICKHOUSE, format: v1pb.QueryOption_JSON, want: v1pb.QueryOption_JSON, isPlan: true},
+ {name: "trino json", engine: storepb.Engine_TRINO, format: v1pb.QueryOption_JSON, want: v1pb.QueryOption_JSON, isPlan: true},
+ // MongoDB has one plan format, so it is the default as well.
+ {name: "mongodb default", engine: storepb.Engine_MONGODB, want: v1pb.QueryOption_JSON, isPlan: true},
+ {name: "mongodb json", engine: storepb.Engine_MONGODB, format: v1pb.QueryOption_JSON, want: v1pb.QueryOption_JSON, isPlan: true},
+ {name: "cockroachdb json", engine: storepb.Engine_COCKROACHDB, format: v1pb.QueryOption_JSON, want: v1pb.QueryOption_JSON, isPlan: true},
+ {name: "cockroachdb default", engine: storepb.Engine_COCKROACHDB, want: v1pb.QueryOption_TEXT, isPlan: true},
{name: "bigquery dry run", engine: storepb.Engine_BIGQUERY},
} {
t.Run(tc.name, func(t *testing.T) {
@@ -50,3 +64,28 @@ func TestExplainResultFormat(t *testing.T) {
})
}
}
+
+// TestTypedExplainPlan pins how an engine parser's answer about the caller's own
+// EXPLAIN reaches the result. A format the parser cannot name is the answer for
+// MySQL's omitted FORMAT, and it has to stay unspecified rather than becoming
+// text, which the viewer would take as a promise about what came back.
+func TestTypedExplainPlan(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ format string
+ executed bool
+ isExplain bool
+ want *v1pb.QueryResult_QueryPlan
+ }{
+ {name: "not an explain at all"},
+ {name: "json", format: "json", isExplain: true, want: &v1pb.QueryResult_QueryPlan{Format: v1pb.QueryOption_JSON}},
+ {name: "text", format: "text", isExplain: true, want: &v1pb.QueryResult_QueryPlan{Format: v1pb.QueryOption_TEXT}},
+ {name: "an executed plan", format: "xml", executed: true, isExplain: true, want: &v1pb.QueryResult_QueryPlan{Format: v1pb.QueryOption_XML, Executed: true}},
+ {name: "a format the parser could not name", isExplain: true, want: &v1pb.QueryResult_QueryPlan{Format: v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED}},
+ {name: "a format the enum does not have", format: "tree", isExplain: true, want: &v1pb.QueryResult_QueryPlan{Format: v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED}},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ require.Equal(t, tc.want, TypedExplainPlan(tc.format, tc.executed, tc.isExplain))
+ })
+ }
+}
diff --git a/backend/plugin/db/mongodb/mongodb.go b/backend/plugin/db/mongodb/mongodb.go
index bbc0cdf4a8..f225a03c0f 100644
--- a/backend/plugin/db/mongodb/mongodb.go
+++ b/backend/plugin/db/mongodb/mongodb.go
@@ -183,11 +183,10 @@ func getBasicMongoDBConnectionURI(connConfig db.ConnectionConfig) string {
// 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) {
+ statement = strings.Trim(statement, " \t\n\r\f;")
if queryContext.Explain {
- return nil, errors.New("MongoDB does not support EXPLAIN")
+ return d.explainConn(ctx, statement, queryContext)
}
-
- statement = strings.Trim(statement, " \t\n\r\f;")
startTime := time.Now()
gmClient := gomongo.NewClient(d.client)
@@ -199,7 +198,41 @@ func (d *Driver) QueryConn(ctx context.Context, _ *sql.Conn, statement string, q
if err != nil {
return nil, err
}
- return d.convertGomongoResult(result, statement, startTime), nil
+ results := d.convertGomongoResult(result, statement, startTime)
+ for _, r := range results {
+ r.QueryPlan = db.TypedExplainPlan(mongodbparser.DescribeExplain(statement))
+ }
+ return results, nil
+}
+
+// explainConn plans each statement of the request on its own. The client runs a
+// whole script in one call, but a plan covers one statement: a request holding
+// two would be refused outright and the reader would get no plan at all. No row
+// limit is set, since limiting the query a plan covers would change the plan
+// rather than the reading of it.
+func (d *Driver) explainConn(ctx context.Context, statement string, queryContext db.QueryContext) ([]*v1pb.QueryResult, error) {
+ statements, err := base.SplitMultiSQL(storepb.Engine_MONGODB, statement)
+ if err != nil {
+ return nil, err
+ }
+ gmClient := gomongo.NewClient(d.client)
+ var results []*v1pb.QueryResult
+ for _, each := range statements {
+ if each.Empty {
+ continue
+ }
+ explained, err := base.ExplainStatement(storepb.Engine_MONGODB, each.Text, db.ExplainFormat(queryContext.Option.GetExplainFormat()))
+ if err != nil {
+ return nil, err
+ }
+ startTime := time.Now()
+ result, err := gmClient.Execute(ctx, d.databaseName, explained)
+ if err != nil {
+ return nil, err
+ }
+ results = append(results, d.convertGomongoResult(result, explained, startTime)...)
+ }
+ return results, nil
}
func (*Driver) convertGomongoResult(res *gomongo.Result, statement string, startTime time.Time) []*v1pb.QueryResult {
diff --git a/backend/plugin/db/mongodb/mongodb_test.go b/backend/plugin/db/mongodb/mongodb_test.go
index 32520503bd..801c61e4c2 100644
--- a/backend/plugin/db/mongodb/mongodb_test.go
+++ b/backend/plugin/db/mongodb/mongodb_test.go
@@ -2,6 +2,7 @@ package mongodb
import (
"context"
+ "encoding/json"
"strings"
"testing"
"time"
@@ -460,3 +461,99 @@ func TestQueryDoubleNotation(t *testing.T) {
`{"_id":1129063441,"name":"repro user 1","created_at":1779696815227,"updated_at":1779803079861,"current_workspace_id":585723378473606}`,
jsonStr)
}
+
+// TestQueryConnExplain pins the plan the query-plan viewer draws. MongoDB asks
+// for a plan with a cursor method rather than a keyword, and only the
+// queryPlanner verbosity describes the query without running it.
+func TestQueryConnExplain(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ container, database := testcontainer.NewMongoDatabase(t)
+
+ driver := &Driver{}
+ opened, err := driver.Open(ctx, storepb.Engine_MONGODB, db.ConnectionConfig{
+ DataSource: &storepb.DataSource{
+ Host: container.GetHost(),
+ Port: container.GetPort(),
+ Username: container.GetUsername(),
+ },
+ ConnectionContext: db.ConnectionContext{DatabaseName: database},
+ Password: container.GetPassword(),
+ })
+ require.NoError(t, err)
+ t.Cleanup(func() { opened.Close(ctx) })
+ require.NoError(t, opened.Ping(ctx))
+
+ _, err = opened.Execute(ctx, `db.orders.insertMany([
+ {"customer_id": 1, "total": 100}, {"customer_id": 2, "total": 900}
+ ]);`, db.ExecuteOptions{})
+ require.NoError(t, err)
+
+ explain := func(statement string, asExplain bool) *v1pb.QueryResult {
+ t.Helper()
+ results, err := opened.QueryConn(ctx, nil, statement, db.QueryContext{
+ Explain: asExplain,
+ Limit: 5000,
+ MaximumSQLResultSize: 1 << 30,
+ Option: &v1pb.QueryOption{ExplainFormat: v1pb.QueryOption_JSON},
+ })
+ require.NoError(t, err)
+ require.Len(t, results, 1)
+ require.Empty(t, results[0].GetError())
+ return results[0]
+ }
+ planner := func(result *v1pb.QueryResult) map[string]any {
+ t.Helper()
+ require.Len(t, result.GetRows(), 1)
+ var plan map[string]any
+ require.NoError(t, json.Unmarshal([]byte(result.GetRows()[0].GetValues()[0].GetStringValue()), &plan))
+ queryPlanner, ok := plan["queryPlanner"].(map[string]any)
+ require.True(t, ok, "no queryPlanner in %v", plan)
+ return queryPlanner
+ }
+
+ const statement = `db.orders.find({total: {$gt: 500}})`
+ plan := explain(statement, true)
+ require.Equal(t, statement+`.explain("queryPlanner")`, plan.GetStatement())
+ require.Contains(t, planner(plan), "winningPlan")
+
+ // A statement that already asks for a plan keeps its query and loses its
+ // verbosity, so an explain request never runs what it plans.
+ replanned := explain(statement+`.explain("executionStats")`, true)
+ require.Equal(t, statement+`.explain("queryPlanner")`, replanned.GetStatement())
+ require.NotContains(t, planner(replanned), "executionStats")
+
+ // The client runs a whole script in one call, but a plan covers one
+ // statement, so a script is planned a statement at a time rather than
+ // refused for holding two.
+ const second = `db.orders.find({total: {$lt: 500}})`
+ scripted, err := opened.QueryConn(ctx, nil, statement+"; "+second, db.QueryContext{
+ Explain: true, MaximumSQLResultSize: 1 << 30,
+ Option: &v1pb.QueryOption{ExplainFormat: v1pb.QueryOption_JSON},
+ })
+ require.NoError(t, err)
+ require.Len(t, scripted, 2)
+ require.Equal(t, statement+`.explain("queryPlanner")`, scripted[0].GetStatement())
+ require.Equal(t, second+`.explain("queryPlanner")`, scripted[1].GetStatement())
+ require.Contains(t, planner(scripted[1]), "winningPlan")
+
+ // Run on a statement that explains itself reports the plan it returned.
+ ran := explain(statement+`.explain()`, false)
+ require.Equal(t, v1pb.QueryOption_JSON, ran.GetQueryPlan().GetFormat())
+ require.False(t, ran.GetQueryPlan().GetExecuted())
+
+ // A measured plan runs the query, which the result has to say.
+ measured := explain(statement+`.explain("executionStats")`, false)
+ require.Equal(t, v1pb.QueryOption_JSON, measured.GetQueryPlan().GetFormat())
+ require.True(t, measured.GetQueryPlan().GetExecuted())
+
+ // An ordinary query is no plan at all.
+ require.Nil(t, explain(statement, false).GetQueryPlan())
+
+ // A write has no plan, and planning it would mean running it.
+ _, err = opened.QueryConn(ctx, nil, `db.orders.insertOne({a: 1})`, db.QueryContext{
+ Explain: true, MaximumSQLResultSize: 1 << 30,
+ Option: &v1pb.QueryOption{ExplainFormat: v1pb.QueryOption_JSON},
+ })
+ require.ErrorContains(t, err, "insertOne")
+}
diff --git a/backend/plugin/db/mysql/mysql.go b/backend/plugin/db/mysql/mysql.go
index 7bcd0f82d9..0d029352b7 100644
--- a/backend/plugin/db/mysql/mysql.go
+++ b/backend/plugin/db/mysql/mysql.go
@@ -638,6 +638,9 @@ func (d *Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string
if err := rows.Err(); err != nil {
return nil, err
}
+ if !queryContext.Explain {
+ r.QueryPlan = db.TypedExplainPlan(mysqlparser.DescribeExplain(statement))
+ }
return r, nil
}
diff --git a/backend/plugin/db/mysql/mysql_test.go b/backend/plugin/db/mysql/mysql_test.go
index 4c525b8cbd..7294c78ac6 100644
--- a/backend/plugin/db/mysql/mysql_test.go
+++ b/backend/plugin/db/mysql/mysql_test.go
@@ -8,6 +8,7 @@ import (
"crypto/rand"
"crypto/x509"
"crypto/x509/pkix"
+ "encoding/json"
"encoding/pem"
"math/big"
"net/http"
@@ -21,7 +22,10 @@ import (
"github.com/stretchr/testify/require"
"github.com/bytebase/bytebase/backend/common"
+ "github.com/bytebase/bytebase/backend/common/testcontainer"
storepb "github.com/bytebase/bytebase/backend/generated-go/store"
+ v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"
+ "github.com/bytebase/bytebase/backend/plugin/db"
"github.com/bytebase/bytebase/backend/plugin/db/util"
)
@@ -495,3 +499,89 @@ func TestRDSCertPoolLeaderCancellationDoesNotFailWaiter(t *testing.T) {
require.Fail(t, "waiter never completed after leader cancellation")
}
}
+
+// TestQueryConnExplainJSON pins the structured plan the query-plan viewer draws,
+// on the oldest MariaDB release Bytebase supports as well as the newest, since
+// FORMAT=JSON is the one plan format they share and a plan the viewer cannot
+// read loses the picture silently rather than failing.
+func TestQueryConnExplainJSON(t *testing.T) {
+ t.Parallel()
+ for _, tc := range []struct {
+ version string
+ newDatabase func(testing.TB) (*testcontainer.Container, string)
+ }{
+ {version: "11.8", newDatabase: testcontainer.NewMariaDBDatabase},
+ {version: "10.7", newDatabase: testcontainer.NewMariaDB107Database},
+ } {
+ t.Run(tc.version, func(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ container, database := tc.newDatabase(t)
+ driver := openTestDriver(ctx, t, storepb.Engine_MARIADB, container, container.GetUsername(), container.GetPassword(), database)
+ _, err := driver.db.ExecContext(ctx, "CREATE TABLE plan_target (id INT PRIMARY KEY, note VARCHAR(64))")
+ require.NoError(t, err)
+
+ conn, err := driver.GetDB().Conn(ctx)
+ require.NoError(t, err)
+ defer conn.Close()
+
+ const statement = "SELECT note FROM plan_target WHERE id > 100"
+ explain := func(s string, option *v1pb.QueryOption, asExplain bool) *v1pb.QueryResult {
+ results, err := driver.QueryConn(ctx, conn, s, db.QueryContext{
+ Explain: asExplain,
+ Limit: 5000,
+ MaximumSQLResultSize: 1 << 30,
+ Option: option,
+ })
+ require.NoError(t, err)
+ require.Len(t, results, 1)
+ require.Empty(t, results[0].GetError())
+ return results[0]
+ }
+
+ jsonOption := &v1pb.QueryOption{ExplainFormat: v1pb.QueryOption_JSON}
+ plan := explain(statement, jsonOption, true)
+ require.Equal(t, "EXPLAIN FORMAT=JSON "+statement, plan.GetStatement())
+ require.Equal(t, "query_block", planRoot(t, plan))
+
+ // The default plan stays the table MariaDB has always returned.
+ text := explain(statement, nil, true)
+ require.Equal(t, "EXPLAIN "+statement, text.GetStatement())
+ require.Greater(t, len(text.GetColumnNames()), 1)
+
+ // A caller's own EXPLAIN is replanned in the format asked for rather
+ // than wrapped in a second one, which would not parse.
+ typed := explain("EXPLAIN FORMAT=JSON "+statement, jsonOption, true)
+ require.Equal(t, "EXPLAIN FORMAT=JSON "+statement, typed.GetStatement())
+ require.Equal(t, "query_block", planRoot(t, typed))
+
+ // Run on that same statement reports the plan it returned, so the
+ // viewer draws it without explaining a second time.
+ ran := explain("EXPLAIN FORMAT=JSON "+statement, nil, false)
+ require.Equal(t, v1pb.QueryOption_JSON, ran.GetQueryPlan().GetFormat())
+ require.False(t, ran.GetQueryPlan().GetExecuted())
+ require.Equal(t, "query_block", planRoot(t, ran))
+
+ // A plain EXPLAIN says nothing about its format: from MySQL 8.0.32 an
+ // omitted FORMAT follows the session's explain_format.
+ ranText := explain("EXPLAIN "+statement, nil, false)
+ require.Equal(t, v1pb.QueryOption_EXPLAIN_FORMAT_UNSPECIFIED, ranText.GetQueryPlan().GetFormat())
+ require.NotNil(t, ranText.GetQueryPlan())
+ })
+ }
+}
+
+// planRoot returns the one key at the top of a one-column JSON plan.
+func planRoot(t *testing.T, result *v1pb.QueryResult) string {
+ t.Helper()
+ require.Len(t, result.GetColumnNames(), 1)
+ require.Len(t, result.GetRows(), 1)
+ require.Len(t, result.GetRows()[0].GetValues(), 1)
+ var plan map[string]json.RawMessage
+ require.NoError(t, json.Unmarshal([]byte(result.GetRows()[0].GetValues()[0].GetStringValue()), &plan))
+ require.Len(t, plan, 1)
+ for key := range plan {
+ return key
+ }
+ return ""
+}
diff --git a/backend/plugin/db/oracle/oracle.go b/backend/plugin/db/oracle/oracle.go
index b0197050db..c45107135b 100644
--- a/backend/plugin/db/oracle/oracle.go
+++ b/backend/plugin/db/oracle/oracle.go
@@ -7,6 +7,7 @@ import (
"crypto/tls"
"database/sql"
"database/sql/driver"
+ "encoding/json"
"fmt"
"log/slog"
"math/big"
@@ -321,6 +322,7 @@ func (d *Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string
var results []*v1pb.QueryResult
for _, singleSQL := range singleSQLs {
statement := singleSQL.Text
+ planAsJSON := false
if queryContext.Explain {
startTime := time.Now()
randNum, err := rand.Int(rand.Reader, big.NewInt(999))
@@ -332,7 +334,12 @@ func (d *Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string
if _, err := conn.ExecContext(ctx, fmt.Sprintf("EXPLAIN PLAN SET STATEMENT_ID = '%s' FOR %s", randomID, statement)); err != nil {
return nil, err
}
- statement = fmt.Sprintf(`SELECT LPAD(' ', LEVEL-1) || OPERATION || ' (' || OPTIONS || ')' "Operation", OBJECT_NAME "Object", OPTIMIZER "Optimizer", COST "Cost", CARDINALITY "Cardinality", BYTES "Bytes", PARTITION_START "Partition Start", PARTITION_ID "Partition ID", ACCESS_PREDICATES "Access Predicates" FROM PLAN_TABLE START WITH ID = 0 AND statement_id = '%s' CONNECT BY PRIOR ID=PARENT_ID AND statement_id = '%s' ORDER BY id`, randomID, randomID)
+ planAsJSON = db.ExplainFormat(queryContext.Option.GetExplainFormat()) == base.ExplainFormatJSON
+ if planAsJSON {
+ statement = fmt.Sprintf(planStepsQuery, randomID)
+ } else {
+ statement = fmt.Sprintf(`SELECT LPAD(' ', LEVEL-1) || OPERATION || ' (' || OPTIONS || ')' "Operation", OBJECT_NAME "Object", OPTIMIZER "Optimizer", COST "Cost", CARDINALITY "Cardinality", BYTES "Bytes", PARTITION_START "Partition Start", PARTITION_ID "Partition ID", ACCESS_PREDICATES "Access Predicates" FROM PLAN_TABLE START WITH ID = 0 AND statement_id = '%s' CONNECT BY PRIOR ID=PARENT_ID AND statement_id = '%s' ORDER BY id`, randomID, randomID)
+ }
}
if !queryContext.Explain && queryContext.Limit > 0 {
@@ -345,6 +352,9 @@ func (d *Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string
}
startTime := time.Now()
queryResult, err := func() (*v1pb.QueryResult, error) {
+ if planAsJSON {
+ return queryPlanSteps(ctx, conn, statement)
+ }
if allQuery {
rows, err := conn.QueryContext(ctx, statement)
if err != nil {
@@ -389,3 +399,98 @@ func (d *Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string
return results, nil
}
+
+// planStepsQuery reads the plan Oracle recorded for one EXPLAIN PLAN: a row per
+// operator, each naming its parent, which is how Oracle states a plan. The
+// columns are what the query-plan viewer reads — the tree's shape, what each
+// step does, the object it reads, and what the optimizer expects it to cost.
+const planStepsQuery = `SELECT id, parent_id, position, operation, options, object_owner, object_name, object_type, optimizer, cost, cardinality, bytes, partition_start, partition_stop, access_predicates, filter_predicates FROM plan_table WHERE statement_id = '%s' ORDER BY id`
+
+// queryPlanSteps returns those rows as one JSON array, which is the form the
+// query-plan viewer parses; the viewer rebuilds the tree from the parent links.
+//
+// Oracle renders a plan as rows rather than as a document, and no EXPLAIN option
+// renders it as one, so this is where the rendering happens. It is built here
+// rather than with Oracle's own JSON_ARRAYAGG so that it works on releases older
+// than 12.2, which do not have those functions. A tab-separated grid would not
+// do: a predicate can hold a tab or a newline, and nothing downstream could tell
+// that apart from the next column or the next row.
+func queryPlanSteps(ctx context.Context, conn *sql.Conn, query string) (*v1pb.QueryResult, error) {
+ rows, err := conn.QueryContext(ctx, query)
+ if err != nil {
+ return nil, err
+ }
+ defer rows.Close()
+
+ columns, err := rows.Columns()
+ if err != nil {
+ return nil, err
+ }
+ var steps [][]any
+ for rows.Next() {
+ values := make([]any, len(columns))
+ scan := make([]any, len(columns))
+ for i := range values {
+ scan[i] = &values[i]
+ }
+ if err := rows.Scan(scan...); err != nil {
+ return nil, err
+ }
+ steps = append(steps, values)
+ }
+ if err := rows.Err(); err != nil {
+ return nil, err
+ }
+
+ payload, err := renderPlanSteps(columns, steps)
+ if err != nil {
+ return nil, err
+ }
+ return &v1pb.QueryResult{
+ ColumnNames: []string{"PLAN"},
+ ColumnTypeNames: []string{"CLOB"},
+ Rows: []*v1pb.QueryRow{{Values: []*v1pb.RowValue{
+ {Kind: &v1pb.RowValue_StringValue{StringValue: payload}},
+ }}},
+ }, nil
+}
+
+// renderPlanSteps writes the scanned plan rows as a JSON array, one object per
+// operator keyed by the lower-cased column names.
+//
+// A column the optimizer had nothing to say about is left out rather than
+// carried as a null, so a reader of the plan sees only what Oracle stated.
+func renderPlanSteps(columns []string, rows [][]any) (string, error) {
+ steps := make([]map[string]any, 0, len(rows))
+ for _, row := range rows {
+ step := make(map[string]any, len(columns))
+ for i, column := range columns {
+ if i >= len(row) {
+ break
+ }
+ if value := jsonValue(row[i]); value != nil {
+ step[strings.ToLower(column)] = value
+ }
+ }
+ steps = append(steps, step)
+ }
+ payload, err := json.Marshal(steps)
+ if err != nil {
+ return "", errors.Wrap(err, "failed to render the query plan")
+ }
+ return string(payload), nil
+}
+
+// jsonValue renders one scanned column, or nil where the row has no value for
+// it. The driver hands back text as bytes, which JSON would otherwise encode as
+// base64.
+func jsonValue(value any) any {
+ switch typed := value.(type) {
+ case nil:
+ return nil
+ case []byte:
+ return string(typed)
+ default:
+ return typed
+ }
+}
diff --git a/backend/plugin/db/oracle/oracle_test.go b/backend/plugin/db/oracle/oracle_test.go
index 1615a0af03..091d96ff94 100644
--- a/backend/plugin/db/oracle/oracle_test.go
+++ b/backend/plugin/db/oracle/oracle_test.go
@@ -8,6 +8,9 @@ import (
"crypto/tls"
"crypto/x509"
"crypto/x509/pkix"
+ "database/sql"
+ "database/sql/driver"
+ "encoding/json"
"encoding/pem"
"fmt"
"maps"
@@ -596,3 +599,56 @@ func ping(t *testing.T, dataSource *storepb.DataSource) string {
require.Error(t, err)
return err.Error()
}
+
+// TestQueryPlanSteps covers the one form of plan the query-plan viewer draws:
+// Oracle states a plan as rows of PLAN_TABLE, and the driver is where those
+// become the JSON document the viewer parses.
+func TestQueryPlanSteps(t *testing.T) {
+ t.Parallel()
+ connector := &fakePlanConnector{
+ columns: []string{"ID", "PARENT_ID", "OPERATION", "OPTIONS", "OBJECT_NAME", "COST", "ACCESS_PREDICATES"},
+ plan: [][]driver.Value{
+ {"0", nil, "SELECT STATEMENT", nil, nil, "48", nil},
+ // The driver hands text back as bytes, which JSON would otherwise
+ // encode as base64.
+ {"1", "0", "TABLE ACCESS", []byte("FULL"), []byte("ORDERS"), "48", []byte(`"TOTAL">880`)},
+ },
+ }
+ database := sql.OpenDB(connector)
+ defer database.Close()
+ conn, err := database.Conn(context.Background())
+ require.NoError(t, err)
+ defer conn.Close()
+
+ result, err := queryPlanSteps(context.Background(), conn, "SELECT ...")
+ require.NoError(t, err)
+ require.Equal(t, []string{"PLAN"}, result.GetColumnNames())
+ require.Len(t, result.GetRows(), 1)
+
+ var steps []map[string]any
+ require.NoError(t, json.Unmarshal([]byte(result.GetRows()[0].GetValues()[0].GetStringValue()), &steps))
+ require.Equal(t, []map[string]any{
+ // A column the optimizer said nothing about is left out, not carried
+ // as a null the viewer would have to skip.
+ {"id": "0", "operation": "SELECT STATEMENT", "cost": "48"},
+ {
+ "id": "1", "parent_id": "0", "operation": "TABLE ACCESS",
+ "options": "FULL", "object_name": "ORDERS", "cost": "48",
+ "access_predicates": `"TOTAL">880`,
+ },
+ }, steps)
+}
+
+// TestRenderPlanStepsHandlesARaggedRow keeps the rendering off the end of a row
+// shorter than the column list, which no Oracle returns but a fake might.
+func TestRenderPlanStepsHandlesARaggedRow(t *testing.T) {
+ t.Parallel()
+ payload, err := renderPlanSteps([]string{"ID", "COST"}, [][]any{{"0"}})
+ require.NoError(t, err)
+ require.JSONEq(t, `[{"id":"0"}]`, payload)
+
+ // A plan with no steps is an empty list rather than a JSON null.
+ payload, err = renderPlanSteps([]string{"ID"}, nil)
+ require.NoError(t, err)
+ require.JSONEq(t, `[]`, payload)
+}
diff --git a/backend/plugin/db/oracle/stats_test.go b/backend/plugin/db/oracle/stats_test.go
index 70b066350d..f50b9e9666 100644
--- a/backend/plugin/db/oracle/stats_test.go
+++ b/backend/plugin/db/oracle/stats_test.go
@@ -179,7 +179,9 @@ func TestWithDynamicSamplingHint(t *testing.T) {
// fakePlanConnector returns the plan rows for every query and records each statement with the
// number of the connection that ran it.
type fakePlanConnector struct {
- plan [][]driver.Value
+ plan [][]driver.Value
+ // columns names the plan columns; empty means the four CountAffectedRows reads.
+ columns []string
opened int
queries []fakePlanQuery
}
@@ -222,14 +224,18 @@ func (c *fakePlanConn) ExecContext(_ context.Context, query string, _ []driver.N
func (c *fakePlanConn) QueryContext(_ context.Context, query string, _ []driver.NamedValue) (driver.Rows, error) {
c.connector.queries = append(c.connector.queries, fakePlanQuery{conn: c.id, text: query})
- return &fakePlanRows{rows: c.connector.plan}, nil
+ return &fakePlanRows{rows: c.connector.plan, columns: c.connector.columns}, nil
}
type fakePlanRows struct {
- rows [][]driver.Value
+ rows [][]driver.Value
+ columns []string
}
-func (*fakePlanRows) Columns() []string {
+func (r *fakePlanRows) Columns() []string {
+ if len(r.columns) > 0 {
+ return r.columns
+ }
return []string{"ID", "PARENT_ID", "OPERATION", "CARDINALITY"}
}
diff --git a/backend/plugin/db/pg/pg.go b/backend/plugin/db/pg/pg.go
index 90d024c6f4..6da77df8d4 100644
--- a/backend/plugin/db/pg/pg.go
+++ b/backend/plugin/db/pg/pg.go
@@ -839,7 +839,7 @@ func (d *Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string
return nil, err
}
if !queryContext.Explain {
- r.QueryPlan = typedExplainPlan(statement)
+ r.QueryPlan = db.TypedExplainPlan(pgparser.DescribeExplain(statement))
}
return r, nil
}
@@ -874,17 +874,6 @@ func (d *Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string
return results, nil
}
-func typedExplainPlan(statement string) *v1pb.QueryResult_QueryPlan {
- format, executed, ok := pgparser.DescribeExplain(statement)
- if !ok {
- return nil
- }
- return &v1pb.QueryResult_QueryPlan{
- Format: v1pb.QueryOption_ExplainFormat(v1pb.QueryOption_ExplainFormat_value[strings.ToUpper(format)]),
- Executed: executed,
- }
-}
-
func getPgError(e error) *v1pb.QueryResult_PostgresError_ {
if e == nil {
return nil
diff --git a/backend/plugin/db/pg/pg_test.go b/backend/plugin/db/pg/pg_test.go
index 2ee168c29f..7a6c85d138 100644
--- a/backend/plugin/db/pg/pg_test.go
+++ b/backend/plugin/db/pg/pg_test.go
@@ -20,6 +20,7 @@ import (
storepb "github.com/bytebase/bytebase/backend/generated-go/store"
v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"
"github.com/bytebase/bytebase/backend/plugin/db"
+ pgparser "github.com/bytebase/bytebase/backend/plugin/parser/pg"
)
func TestGetDatabaseInCreateDatabaseStatement(t *testing.T) {
@@ -440,7 +441,7 @@ func TestTypedExplainPlan(t *testing.T) {
{statement: "EXPLAIN (ANALYZE, FORMAT XML) SELECT 1", want: &v1pb.QueryResult_QueryPlan{Format: v1pb.QueryOption_XML, Executed: true}},
{statement: "EXPLAIN (FORMAT YAML) SELECT 1", want: &v1pb.QueryResult_QueryPlan{Format: v1pb.QueryOption_YAML}},
} {
- require.Equal(t, tc.want, typedExplainPlan(tc.statement), tc.statement)
+ require.Equal(t, tc.want, db.TypedExplainPlan(pgparser.DescribeExplain(tc.statement)), tc.statement)
}
}
diff --git a/backend/plugin/db/tidb/tidb.go b/backend/plugin/db/tidb/tidb.go
index 74b2182609..316371b9f4 100644
--- a/backend/plugin/db/tidb/tidb.go
+++ b/backend/plugin/db/tidb/tidb.go
@@ -403,6 +403,9 @@ func (d *Driver) QueryConn(ctx context.Context, conn *sql.Conn, statement string
if err := rows.Err(); err != nil {
return nil, err
}
+ if !queryContext.Explain {
+ r.QueryPlan = db.TypedExplainPlan(tidbparser.DescribeExplain(statement))
+ }
return r, nil
}
diff --git a/backend/plugin/db/tidb/tidb_test.go b/backend/plugin/db/tidb/tidb_test.go
index 20c53ad3f7..c98df82bff 100644
--- a/backend/plugin/db/tidb/tidb_test.go
+++ b/backend/plugin/db/tidb/tidb_test.go
@@ -2,6 +2,7 @@ package tidb
import (
"context"
+ "encoding/json"
"fmt"
"strings"
"testing"
@@ -11,6 +12,7 @@ import (
"github.com/bytebase/bytebase/backend/common"
"github.com/bytebase/bytebase/backend/common/testcontainer"
storepb "github.com/bytebase/bytebase/backend/generated-go/store"
+ v1pb "github.com/bytebase/bytebase/backend/generated-go/v1"
"github.com/bytebase/bytebase/backend/plugin/db"
)
@@ -157,3 +159,75 @@ func TestExecutePreparedStatementFlowWithCreateIndexString(t *testing.T) {
require.NoError(t, err)
require.Equal(t, 1, count)
}
+
+// TestQueryConnExplainJSON pins the structured plan the query-plan viewer draws.
+// TiDB spells it FORMAT=tidb_json and rejects a quoted format in the statement
+// Bytebase validates, so what the driver builds has to parse here as well.
+func TestQueryConnExplainJSON(t *testing.T) {
+ t.Parallel()
+ ctx := context.Background()
+ container, database := testcontainer.NewTiDBDatabase(t)
+ driver := openTestDriver(ctx, t, container)
+ defer func() { require.NoError(t, driver.Close(ctx)) }()
+
+ _, err := driver.db.ExecContext(ctx, fmt.Sprintf("CREATE TABLE %s.plan_target (id INT PRIMARY KEY, note VARCHAR(64))", database))
+ require.NoError(t, err)
+
+ conn, err := driver.GetDB().Conn(ctx)
+ require.NoError(t, err)
+ defer conn.Close()
+
+ statement := fmt.Sprintf("SELECT note FROM %s.plan_target WHERE id > 100", database)
+ explain := func(s string, option *v1pb.QueryOption, asExplain bool) *v1pb.QueryResult {
+ results, err := driver.QueryConn(ctx, conn, s, db.QueryContext{
+ Explain: asExplain,
+ Limit: 5000,
+ MaximumSQLResultSize: 1 << 30,
+ Option: option,
+ })
+ require.NoError(t, err)
+ require.Len(t, results, 1)
+ require.Empty(t, results[0].GetError())
+ return results[0]
+ }
+ // The root operator's id, which every node of a tidb_json plan carries.
+ rootOperator := func(result *v1pb.QueryResult) string {
+ t.Helper()
+ require.Len(t, result.GetColumnNames(), 1)
+ require.Len(t, result.GetRows(), 1)
+ var plan []struct {
+ ID string `json:"id"`
+ }
+ require.NoError(t, json.Unmarshal([]byte(result.GetRows()[0].GetValues()[0].GetStringValue()), &plan))
+ require.NotEmpty(t, plan)
+ return plan[0].ID
+ }
+
+ jsonOption := &v1pb.QueryOption{ExplainFormat: v1pb.QueryOption_JSON}
+ plan := explain(statement, jsonOption, true)
+ require.Equal(t, "EXPLAIN FORMAT=tidb_json "+statement, plan.GetStatement())
+ require.NotEmpty(t, rootOperator(plan))
+
+ // The default plan stays the table TiDB has always returned.
+ text := explain(statement, nil, true)
+ require.Equal(t, "EXPLAIN "+statement, text.GetStatement())
+ require.Greater(t, len(text.GetColumnNames()), 1)
+
+ // A caller's own EXPLAIN is replanned in the format asked for rather than
+ // wrapped in a second one.
+ typed := explain("EXPLAIN FORMAT=brief "+statement, jsonOption, true)
+ require.Equal(t, "EXPLAIN FORMAT=tidb_json "+statement, typed.GetStatement())
+ require.NotEmpty(t, rootOperator(typed))
+
+ // Run on that statement reports the plan it returned, so the viewer draws it
+ // without explaining a second time.
+ ran := explain("EXPLAIN FORMAT=tidb_json "+statement, nil, false)
+ require.Equal(t, v1pb.QueryOption_JSON, ran.GetQueryPlan().GetFormat())
+ require.False(t, ran.GetQueryPlan().GetExecuted())
+ require.NotEmpty(t, rootOperator(ran))
+
+ // TiDB has no session setting that changes what a plain EXPLAIN returns, so
+ // its format is known to be text.
+ ranText := explain("EXPLAIN "+statement, nil, false)
+ require.Equal(t, v1pb.QueryOption_TEXT, ranText.GetQueryPlan().GetFormat())
+}
diff --git a/backend/plugin/parser/mongodb/explain.go b/backend/plugin/parser/mongodb/explain.go
new file mode 100644
index 0000000000..4aa9d5d929
--- /dev/null
+++ b/backend/plugin/parser/mongodb/explain.go
@@ -0,0 +1,127 @@
+package mongodb
+
+import (
+ "strings"
+
+ "github.com/bytebase/omni/mongo/ast"
+ "github.com/pkg/errors"
+
+ storepb "github.com/bytebase/bytebase/backend/generated-go/store"
+ "github.com/bytebase/bytebase/backend/plugin/parser/base"
+)
+
+func init() {
+ base.RegisterExplainStatementFunc(storepb.Engine_MONGODB, explainStatement)
+}
+
+// explainCursorMethod is how a mongosh statement asks for its own plan: a
+// cursor method on the end of the query, not a keyword in front of it.
+const explainCursorMethod = "explain"
+
+// planVerbosity is the one verbosity that does not run the statement it plans,
+// and is also MongoDB's default. The other two, executionStats and
+// allPlansExecution, execute the query to measure it.
+const planVerbosity = "queryPlanner"
+
+// explainableMethods are the operations MongoDB will plan. A write, a findOne
+// or a metadata read is not among them: either there is no plan to make, or
+// making it would mean running the statement.
+var explainableMethods = map[string]bool{
+ "aggregate": true,
+ "count": true,
+ "countDocuments": true,
+ "distinct": true,
+ "estimatedDocumentCount": true,
+ "find": true,
+}
+
+// explainStatement implements base.ExplainStatement. MongoDB states a plan as
+// one document and has no second format, so the format a caller asks for has
+// nowhere to go; the driver capability table offers this engine JSON alone.
+//
+// A statement that already asks for its own plan has its verbosity replaced
+// rather than kept, which is what keeps an explain request from running the
+// query it is meant to describe.
+func explainStatement(statement string, _ base.ExplainFormat) (string, error) {
+ collection, err := singleCollectionStatement(statement)
+ if err != nil {
+ return "", err
+ }
+ if !explainableMethods[collection.Method] {
+ return "", errors.Errorf("MongoDB plans aggregate, count, countDocuments, distinct, estimatedDocumentCount and find; %q is none of those", collection.Method)
+ }
+
+ for _, cursor := range collection.CursorMethods {
+ if cursor.Method != explainCursorMethod {
+ continue
+ }
+ return statement[collection.Loc.Start:cursor.Loc.Start] +
+ explainCall() +
+ statement[cursor.Loc.End:collection.Loc.End], nil
+ }
+ return statement[collection.Loc.Start:collection.Loc.End] + "." + explainCall(), nil
+}
+
+func explainCall() string {
+ return explainCursorMethod + `("` + planVerbosity + `")`
+}
+
+// DescribeExplain returns the output format of a statement that asks for its
+// own plan, and whether producing that plan runs the statement.
+//
+// MongoDB has one plan format, so the format is JSON or the statement is not an
+// explain at all. A verbosity other than queryPlanner measures the query by
+// running it, which the caller needs to know: such a plan is an executed one.
+func DescribeExplain(statement string) (format string, executed bool, ok bool) {
+ collection, err := singleCollectionStatement(statement)
+ if err != nil {
+ return "", false, false
+ }
+ for _, cursor := range collection.CursorMethods {
+ if cursor.Method != explainCursorMethod {
+ continue
+ }
+ return "json", explainExecutes(statement, cursor), true
+ }
+ return "", false, false
+}
+
+// explainExecutes reports whether the verbosity the caller named runs the
+// statement. An omitted verbosity is queryPlanner, which does not.
+func explainExecutes(statement string, cursor ast.CursorMethod) bool {
+ if len(cursor.Args) == 0 {
+ return false
+ }
+ loc := cursor.Args[0].GetLoc()
+ if loc.Start < 0 || loc.End > len(statement) || loc.Start >= loc.End {
+ // A verbosity this parser cannot read is assumed to measure, since
+ // calling an executed plan an estimate is the costlier mistake.
+ return true
+ }
+ return strings.Trim(statement[loc.Start:loc.End], `"'`) != planVerbosity
+}
+
+// singleCollectionStatement returns the one query over a collection in text. An
+// explain request plans one statement at a time: both the driver and the API
+// gate split a multi-statement request first.
+func singleCollectionStatement(statement string) (*ast.CollectionStatement, error) {
+ statements, err := ParseMongoShell(statement)
+ if err != nil {
+ return nil, err
+ }
+ if len(statements) == 0 {
+ return nil, errors.New("a plan needs a statement to plan")
+ }
+ if len(statements) > 1 {
+ return nil, errors.New("a plan covers a single statement")
+ }
+ node, ok := GetOmniNode(statements[0].AST)
+ if !ok || node == nil {
+ return nil, errors.New("the statement cannot be planned")
+ }
+ collection, ok := node.(*ast.CollectionStatement)
+ if !ok {
+ return nil, errors.New("MongoDB plans a query over a collection, and this statement queries none")
+ }
+ return collection, nil
+}
diff --git a/backend/plugin/parser/mongodb/explain_test.go b/backend/plugin/parser/mongodb/explain_test.go
new file mode 100644
index 0000000000..81ff339789
--- /dev/null
+++ b/backend/plugin/parser/mongodb/explain_test.go
@@ -0,0 +1,92 @@
+package mongodb
+
+import (
+ "testing"
+
+ "github.com/stretchr/testify/require"
+
+ "github.com/bytebase/bytebase/backend/plugin/parser/base"
+)
+
+// TestExplainStatement pins the statement that asks MongoDB for a plan. It is a
+// cursor method on the end of the query, and its verbosity is the one that does
+// not run what it plans.
+func TestExplainStatement(t *testing.T) {
+ tests := []struct {
+ statement string
+ want string
+ }{
+ {`db.orders.find({a: 1})`, `db.orders.find({a: 1}).explain("queryPlanner")`},
+ {`db.orders.find({}).sort({a: -1}).limit(10)`, `db.orders.find({}).sort({a: -1}).limit(10).explain("queryPlanner")`},
+ {`db.orders.aggregate([{$match: {a: 1}}])`, `db.orders.aggregate([{$match: {a: 1}}]).explain("queryPlanner")`},
+ {`db.orders.countDocuments({})`, `db.orders.countDocuments({}).explain("queryPlanner")`},
+ {`db.orders.distinct("a")`, `db.orders.distinct("a").explain("queryPlanner")`},
+ // Leading comments and a trailing semicolon are outside the statement.
+ {"// plan it\ndb.orders.find({}) ;", `db.orders.find({}).explain("queryPlanner")`},
+ // A statement that asks for its own plan keeps its query and loses its
+ // verbosity, so a request to plan never runs what it plans.
+ {`db.orders.find({}).explain()`, `db.orders.find({}).explain("queryPlanner")`},
+ {`db.orders.find({}).explain("executionStats")`, `db.orders.find({}).explain("queryPlanner")`},
+ {`db.orders.find({}).explain( "allPlansExecution" )`, `db.orders.find({}).explain("queryPlanner")`},
+ {`db.orders.find({}).sort({a: 1}).explain("executionStats")`, `db.orders.find({}).sort({a: 1}).explain("queryPlanner")`},
+ }
+ for _, tc := range tests {
+ got, err := explainStatement(tc.statement, base.ExplainFormatJSON)
+ require.NoErrorf(t, err, "%q", tc.statement)
+ require.Equalf(t, tc.want, got, "%q", tc.statement)
+ }
+ // What this builds has to plan again to the same thing: the Visualize path
+ // explains a statement that already explains.
+ for _, tc := range tests {
+ got, err := explainStatement(tc.want, base.ExplainFormatJSON)
+ require.NoErrorf(t, err, "%q", tc.want)
+ require.Equalf(t, tc.want, got, "%q", tc.want)
+ }
+}
+
+// TestExplainStatementRejects locks what MongoDB will not plan. Unlike an
+// engine that prefixes EXPLAIN, returning the statement unchanged here would
+// run it, so anything unplannable is refused instead.
+func TestExplainStatementRejects(t *testing.T) {
+ for _, statement := range []string{
+ `db.orders.insertOne({a: 1})`,
+ `db.orders.updateOne({a: 1}, {$set: {b: 2}})`,
+ `db.orders.deleteMany({})`,
+ `db.orders.drop()`,
+ // findOne has no plan of its own in the client that runs it.
+ `db.orders.findOne({a: 1})`,
+ // Not a query over a collection at all.
+ `db.getCollectionNames()`,
+ `db.orders.find({}); db.orders.find({})`,
+ ``,
+ } {
+ _, err := explainStatement(statement, base.ExplainFormatJSON)
+ require.Errorf(t, err, "%q", statement)
+ }
+}
+
+// TestDescribeExplain pins what a result says about a plan the caller asked for
+// itself, and in particular whether producing it ran the query.
+func TestDescribeExplain(t *testing.T) {
+ tests := []struct {
+ statement string
+ format string
+ executed bool
+ isExplain bool
+ }{
+ {statement: `db.orders.find({}).explain()`, format: "json", isExplain: true},
+ {statement: `db.orders.find({}).explain("queryPlanner")`, format: "json", isExplain: true},
+ {statement: `db.orders.find({}).explain("executionStats")`, format: "json", executed: true, isExplain: true},
+ {statement: `db.orders.find({}).explain("allPlansExecution")`, format: "json", executed: true, isExplain: true},
+ {statement: `db.orders.aggregate([]).explain()`, format: "json", isExplain: true},
+ {statement: `db.orders.find({})`},
+ {statement: `db.orders.insertOne({a: 1})`},
+ {statement: `not a statement`},
+ }
+ for _, tc := range tests {
+ format, executed, isExplain := DescribeExplain(tc.statement)
+ require.Equalf(t, tc.isExplain, isExplain, "%q", tc.statement)
+ require.Equalf(t, tc.format, format, "%q", tc.statement)
+ require.Equalf(t, tc.executed, executed, "%q", tc.statement)
+ }
+}
diff --git a/backend/plugin/parser/mysql/explain.go b/backend/plugin/parser/mysql/explain.go
index de98c1c09a..1aaa0dd996 100644
--- a/backend/plugin/parser/mysql/explain.go
+++ b/backend/plugin/parser/mysql/explain.go
@@ -16,11 +16,11 @@ func init() {
base.RegisterExplainStatementFunc(storepb.Engine_OCEANBASE, explainStatement)
}
-// explainStatement implements base.ExplainStatement. MySQL returns one plan
-// format here whatever the caller asked for: FORMAT=JSON and FORMAT=TREE are
-// plans of their own shape that nothing downstream reads (the driver capability
-// table offers this engine the default plan only).
-func explainStatement(statement string, _ base.ExplainFormat) (string, error) {
+// explainStatement implements base.ExplainStatement. MySQL and MariaDB both
+// spell their structured plan FORMAT=JSON; any other format the caller names
+// gets the engine's default plan, since FORMAT=TREE is a shape of its own that
+// nothing downstream reads (the driver capability table refuses the rest).
+func explainStatement(statement string, format base.ExplainFormat) (string, error) {
node, err := singleStatement(statement)
if err != nil {
return "", err
@@ -39,9 +39,43 @@ func explainStatement(statement string, _ base.ExplainFormat) (string, error) {
return statement, nil
}
}
+ if format == base.ExplainFormatJSON {
+ return "EXPLAIN FORMAT=JSON " + planned, nil
+ }
return "EXPLAIN " + planned, nil
}
+// DescribeExplain returns the output format of an EXPLAIN statement and whether
+// it executes the statement it plans. It is not an explain at all unless it
+// plans a statement: EXPLAIN tbl_name and DESCRIBE tbl_name parse here too and
+// describe a table's columns, which is a result like any other.
+//
+// An omitted FORMAT is not text: from MySQL 8.0.32 it follows the session's
+// explain_format, which the statement alone does not reveal. It is reported as
+// no format at all, which the caller reads as unknown.
+func DescribeExplain(statement string) (format string, executed bool, ok bool) {
+ node, err := singleStatement(statement)
+ if err != nil {
+ return "", false, false
+ }
+ explain, ok := node.(*ast.ExplainStmt)
+ if !ok {
+ return "", false, false
+ }
+ if _, plans := explainedStart(explain.Stmt); !plans {
+ return "", false, false
+ }
+ switch {
+ case strings.EqualFold(explain.Format, "json"):
+ return "json", explain.Analyze, true
+ case explain.Format == "":
+ return "", explain.Analyze, true
+ default:
+ // TRADITIONAL is a table and TREE a tree of lines; both are text.
+ return "text", explain.Analyze, true
+ }
+}
+
// singleStatement returns the one statement in text. An explain request plans one
// statement at a time: both the drivers and the API gate split a multi-statement
// request first.
diff --git a/backend/plugin/parser/mysql/explain_test.go b/backend/plugin/parser/mysql/explain_test.go
index af2721a054..d4c395f553 100644
--- a/backend/plugin/parser/mysql/explain_test.go
+++ b/backend/plugin/parser/mysql/explain_test.go
@@ -36,6 +36,68 @@ func TestExplainStatement(t *testing.T) {
}
}
+// TestExplainStatementJSON pins the statement that asks for the structured plan
+// the visualizer draws. A caller's own FORMAT is replaced rather than kept, so
+// the request decides the format whatever the statement named.
+func TestExplainStatementJSON(t *testing.T) {
+ tests := []struct {
+ statement string
+ want string
+ }{
+ {"SELECT 1", "EXPLAIN FORMAT=JSON SELECT 1"},
+ {"EXPLAIN SELECT 1", "EXPLAIN FORMAT=JSON SELECT 1"},
+ {"EXPLAIN FORMAT=TREE SELECT 1", "EXPLAIN FORMAT=JSON SELECT 1"},
+ {"EXPLAIN FORMAT=JSON SELECT 1", "EXPLAIN FORMAT=JSON SELECT 1"},
+ // Nothing to plan, so the statement runs as written and the format the
+ // request named has nowhere to go.
+ {"EXPLAIN t", "EXPLAIN t"},
+ }
+ for _, tc := range tests {
+ got, err := explainStatement(tc.statement, base.ExplainFormatJSON)
+ require.NoErrorf(t, err, "%q", tc.statement)
+ require.Equalf(t, tc.want, got, "%q", tc.statement)
+ }
+ // Only JSON has a reader; the rest fall back to the engine's own plan.
+ for _, format := range []base.ExplainFormat{base.ExplainFormatText, base.ExplainFormatXML, base.ExplainFormatYAML} {
+ got, err := explainStatement("SELECT 1", format)
+ require.NoError(t, err)
+ require.Equal(t, "EXPLAIN SELECT 1", got)
+ }
+}
+
+// TestDescribeExplain pins what a result says about a plan the caller asked for
+// itself. An omitted FORMAT is unknown rather than text, because from MySQL
+// 8.0.32 it follows the session's explain_format.
+func TestDescribeExplain(t *testing.T) {
+ tests := []struct {
+ statement string
+ format string
+ executed bool
+ isExplain bool
+ }{
+ {statement: "EXPLAIN FORMAT=JSON SELECT 1", format: "json", isExplain: true},
+ {statement: "explain format = json select 1", format: "json", isExplain: true},
+ {statement: "EXPLAIN FORMAT=TREE SELECT 1", format: "text", isExplain: true},
+ {statement: "EXPLAIN FORMAT=TRADITIONAL SELECT 1", format: "text", isExplain: true},
+ {statement: "EXPLAIN SELECT 1", isExplain: true},
+ {statement: "EXPLAIN ANALYZE SELECT 1", executed: true, isExplain: true},
+ {statement: "SELECT 1"},
+ {statement: "SELECT 1; SELECT 2"},
+ // EXPLAIN over a table name describes its columns. The result is a
+ // table like any other, and calling it a query plan would put it in
+ // the viewer instead of the grid.
+ {statement: "EXPLAIN t"},
+ {statement: "DESCRIBE t"},
+ {statement: "EXPLAIN FOR CONNECTION 5"},
+ }
+ for _, tc := range tests {
+ format, executed, isExplain := DescribeExplain(tc.statement)
+ require.Equalf(t, tc.isExplain, isExplain, "%q", tc.statement)
+ require.Equalf(t, tc.format, format, "%q", tc.statement)
+ require.Equalf(t, tc.executed, executed, "%q", tc.statement)
+ }
+}
+
// TestExplainStatementRejects locks what never becomes an EXPLAIN: a write with
// EXPLAIN options smuggled in front of it, which anything that simply prefixed
// EXPLAIN would turn into an EXPLAIN ANALYZE DELETE that runs the DELETE, and an
diff --git a/backend/plugin/parser/pg/explain.go b/backend/plugin/parser/pg/explain.go
index a9b9374f02..762c4e3b03 100644
--- a/backend/plugin/parser/pg/explain.go
+++ b/backend/plugin/parser/pg/explain.go
@@ -14,27 +14,40 @@ func init() {
base.RegisterExplainStatementFunc(storepb.Engine_POSTGRES, explainStatement)
// CockroachDB parses through the PostgreSQL grammar here as it does for the
// read-only gate (see query.go).
- base.RegisterExplainStatementFunc(storepb.Engine_COCKROACHDB, explainStatementDefaultFormat)
+ base.RegisterExplainStatementFunc(storepb.Engine_COCKROACHDB, cockroachExplainStatement)
+}
+
+// plannedStatement returns the statement an EXPLAIN should be built around, and
+// whether one can be: a statement that already asks for a plan is rebuilt around
+// the statement it plans, and one whose planned statement cannot be located runs
+// as the caller wrote it rather than becoming the plan of a plan.
+func plannedStatement(statement string) (planned string, rebuild bool, err error) {
+ node, err := singleStatement(statement)
+ if err != nil {
+ return "", false, err
+ }
+ explain, ok := node.(*ast.ExplainStmt)
+ if !ok {
+ return statement, true, nil
+ }
+ if isExplainAnalyzeOmni(explain) {
+ return "", false, base.ErrExplainAnalyzeExecutes
+ }
+ inner, ok := explainedText(explain, statement)
+ if !ok {
+ return statement, false, nil
+ }
+ return inner, true, nil
}
// explainStatement implements base.ExplainStatement for PostgreSQL.
func explainStatement(statement string, format base.ExplainFormat) (string, error) {
- node, err := singleStatement(statement)
+ planned, rebuild, err := plannedStatement(statement)
if err != nil {
return "", err
}
- planned := statement
- if explain, ok := node.(*ast.ExplainStmt); ok {
- if isExplainAnalyzeOmni(explain) {
- return "", base.ErrExplainAnalyzeExecutes
- }
- inner, ok := explainedText(explain, statement)
- if !ok {
- // Nothing to rebuild around: run what the caller wrote rather than
- // plan a plan.
- return statement, nil
- }
- planned = inner
+ if !rebuild {
+ return planned, nil
}
switch format {
case base.ExplainFormatJSON:
@@ -80,12 +93,26 @@ func explainFormat(explain *ast.ExplainStmt) string {
return format
}
-// explainStatementDefaultFormat plans in the engine's default format whatever the
-// request asked for. CockroachDB's EXPLAIN takes its own option list rather than
-// PostgreSQL's FORMAT, so it offers only the default plan (the driver capability
-// table refuses any other format before a request gets here).
-func explainStatementDefaultFormat(statement string, _ base.ExplainFormat) (string, error) {
- return explainStatement(statement, base.ExplainFormatDefault)
+// cockroachExplainStatement implements base.ExplainStatement for CockroachDB,
+// whose EXPLAIN takes its own option list rather than PostgreSQL's FORMAT and
+// has no option that returns a plan as a document.
+//
+// What it does have is DISTSQL, which returns the text plan as always and a
+// link to a diagram of the physical flow beside it; the payload in that link is
+// the one machine-readable plan CockroachDB publishes, and the driver decodes
+// it. The statement does not execute, as EXPLAIN ANALYZE (DISTSQL) would.
+func cockroachExplainStatement(statement string, format base.ExplainFormat) (string, error) {
+ planned, rebuild, err := plannedStatement(statement)
+ if err != nil {
+ return "", err
+ }
+ if !rebuild {
+ return planned, nil
+ }
+ if format == base.ExplainFormatJSON {
+ return "EXPLAIN (DISTSQL) " + planned, nil
+ }
+ return "EXPLAIN " + planned, nil
}
// singleStatement returns the one statement in text. An explain request plans one
diff --git a/backend/plugin/parser/pg/explain_test.go b/backend/plugin/parser/pg/explain_test.go
index b992852a3e..a13bc5f3d9 100644
--- a/backend/plugin/parser/pg/explain_test.go
+++ b/backend/plugin/parser/pg/explain_test.go
@@ -103,8 +103,32 @@ func TestExplainStatementNeverPlansAPlan(t *testing.T) {
}
}
-func TestExplainStatementCockroachDBIgnoresFormat(t *testing.T) {
- got, err := explainStatementDefaultFormat("SELECT 1", base.ExplainFormatJSON)
- require.NoError(t, err)
- require.Equal(t, "EXPLAIN SELECT 1", got)
+// TestCockroachExplainStatement pins CockroachDB's own option list. Its EXPLAIN
+// has no FORMAT, and DISTSQL is the one option whose output carries a plan a
+// parser can read — beside the text plan, not instead of it.
+func TestCockroachExplainStatement(t *testing.T) {
+ tests := []struct {
+ statement string
+ format base.ExplainFormat
+ want string
+ }{
+ {"SELECT 1", base.ExplainFormatJSON, "EXPLAIN (DISTSQL) SELECT 1"},
+ {"SELECT 1", base.ExplainFormatDefault, "EXPLAIN SELECT 1"},
+ // PostgreSQL's formats mean nothing here, so they get the default plan.
+ {"SELECT 1", base.ExplainFormatText, "EXPLAIN SELECT 1"},
+ {"SELECT 1", base.ExplainFormatXML, "EXPLAIN SELECT 1"},
+ // A statement that already asks for a plan is rebuilt around the
+ // statement it plans, whichever option it named.
+ {"EXPLAIN SELECT 1", base.ExplainFormatJSON, "EXPLAIN (DISTSQL) SELECT 1"},
+ {"EXPLAIN (VERBOSE) SELECT 1", base.ExplainFormatJSON, "EXPLAIN (DISTSQL) SELECT 1"},
+ {"EXPLAIN (DISTSQL) SELECT 1", base.ExplainFormatJSON, "EXPLAIN (DISTSQL) SELECT 1"},
+ }
+ for _, tc := range tests {
+ got, err := cockroachExplainStatement(tc.statement, tc.format)
+ require.NoErrorf(t, err, "%q", tc.statement)
+ require.Equalf(t, tc.want, got, "%q/%v", tc.statement, tc.format)
+ }
+ // Planning by executing is refused here as it is for PostgreSQL.
+ _, err := cockroachExplainStatement("EXPLAIN ANALYZE SELECT 1", base.ExplainFormatJSON)
+ require.ErrorIs(t, err, base.ErrExplainAnalyzeExecutes)
}
diff --git a/backend/plugin/parser/standard/explain.go b/backend/plugin/parser/standard/explain.go
index 633bc6f215..e279cbcdf6 100644
--- a/backend/plugin/parser/standard/explain.go
+++ b/backend/plugin/parser/standard/explain.go
@@ -6,7 +6,7 @@ import (
)
func init() {
- base.RegisterExplainStatementFunc(storepb.Engine_CLICKHOUSE, explainStatement)
+ base.RegisterExplainStatementFunc(storepb.Engine_CLICKHOUSE, clickhouseExplainStatement)
base.RegisterExplainStatementFunc(storepb.Engine_HIVE, explainStatement)
}
@@ -14,11 +14,29 @@ func init() {
// as text here. With no AST to ask which statement an EXPLAIN plans, a statement
// that already asks for a plan runs as the user wrote it; that keeps a request
// from planning a plan, which is what the rest of this package can promise.
-// Both engines return one plan format whatever the caller asked for; the driver
-// capability table offers them the default plan only.
+// Hive returns one plan format whatever the caller asked for; the driver
+// capability table offers it the default plan only.
func explainStatement(statement string, _ base.ExplainFormat) (string, error) {
if base.StartsWithExplain(statement) {
return statement, nil
}
return "EXPLAIN " + statement, nil
}
+
+// clickhouseExplainStatement asks ClickHouse for the structured plan the
+// query-plan viewer draws. `indexes = 1` is what makes each read report how
+// many parts and granules its indexes let it skip, which is what a ClickHouse
+// plan is read for; without it the plan is shape alone.
+//
+// A statement that already asks for a plan still runs as the user wrote it, so
+// a typed EXPLAIN keeps whichever of ClickHouse's plan kinds it named rather
+// than being rewritten by a parser that cannot read it.
+func clickhouseExplainStatement(statement string, format base.ExplainFormat) (string, error) {
+ if base.StartsWithExplain(statement) {
+ return statement, nil
+ }
+ if format == base.ExplainFormatJSON {
+ return "EXPLAIN json = 1, indexes = 1 " + statement, nil
+ }
+ return "EXPLAIN " + statement, nil
+}
diff --git a/backend/plugin/parser/standard/explain_test.go b/backend/plugin/parser/standard/explain_test.go
index 2d55e7d878..6a5a814285 100644
--- a/backend/plugin/parser/standard/explain_test.go
+++ b/backend/plugin/parser/standard/explain_test.go
@@ -29,3 +29,38 @@ func TestExplainStatement(t *testing.T) {
require.Equalf(t, tc.want, got, "%q", tc.statement)
}
}
+
+// TestClickhouseExplainStatement pins the statement that asks ClickHouse for
+// the structured plan the viewer draws, and for the index accounting that is
+// what a reader opens a ClickHouse plan for.
+func TestClickhouseExplainStatement(t *testing.T) {
+ tests := []struct {
+ statement string
+ format base.ExplainFormat
+ want string
+ }{
+ {"SELECT 1", base.ExplainFormatJSON, "EXPLAIN json = 1, indexes = 1 SELECT 1"},
+ {"SELECT 1", base.ExplainFormatDefault, "EXPLAIN SELECT 1"},
+ // Only JSON has a reader; the rest get the engine's own plan.
+ {"SELECT 1", base.ExplainFormatText, "EXPLAIN SELECT 1"},
+ {"SELECT 1", base.ExplainFormatXML, "EXPLAIN SELECT 1"},
+ // Without an AST, a statement that already asks for a plan runs as the
+ // user wrote it, so a typed EXPLAIN keeps the plan kind it named.
+ {"EXPLAIN PIPELINE SELECT 1", base.ExplainFormatJSON, "EXPLAIN PIPELINE SELECT 1"},
+ }
+ for _, tc := range tests {
+ got, err := clickhouseExplainStatement(tc.statement, tc.format)
+ require.NoErrorf(t, err, "%q", tc.statement)
+ require.Equalf(t, tc.want, got, "%q/%v", tc.statement, tc.format)
+ }
+}
+
+// TestHiveKeepsItsOneFormat locks Hive to the plan it has always returned: it
+// shares this file with ClickHouse but has no structured plan of its own.
+func TestHiveKeepsItsOneFormat(t *testing.T) {
+ for _, format := range []base.ExplainFormat{base.ExplainFormatDefault, base.ExplainFormatJSON} {
+ got, err := explainStatement("SELECT 1", format)
+ require.NoError(t, err)
+ require.Equal(t, "EXPLAIN SELECT 1", got)
+ }
+}
diff --git a/backend/plugin/parser/tidb/explain.go b/backend/plugin/parser/tidb/explain.go
index 9c8af8442e..2575c32548 100644
--- a/backend/plugin/parser/tidb/explain.go
+++ b/backend/plugin/parser/tidb/explain.go
@@ -14,11 +14,16 @@ func init() {
base.RegisterExplainStatementFunc(storepb.Engine_TIDB, explainStatement)
}
-// explainStatement implements base.ExplainStatement. TiDB returns one plan format
-// here whatever the caller asked for: its other FORMAT values are plans of their
-// own shape that nothing downstream reads (the driver capability table offers
-// this engine the default plan only).
-func explainStatement(statement string, _ base.ExplainFormat) (string, error) {
+// tidbJSONFormat is TiDB's name for the plan as a tree of JSON objects. Its
+// other JSON-ish format, plain `json`, TiDB rejects outright.
+const tidbJSONFormat = "tidb_json"
+
+// explainStatement implements base.ExplainStatement. TiDB spells its structured
+// plan FORMAT=tidb_json, unquoted so that what this builds parses again; any
+// other format the caller names gets the engine's default plan, since the rest
+// of TiDB's FORMAT values are shapes nothing downstream reads (the driver
+// capability table refuses them).
+func explainStatement(statement string, format base.ExplainFormat) (string, error) {
node, err := singleStatement(statement)
if err != nil {
return "", err
@@ -37,9 +42,35 @@ func explainStatement(statement string, _ base.ExplainFormat) (string, error) {
return statement, nil
}
}
+ if format == base.ExplainFormatJSON {
+ return "EXPLAIN FORMAT=" + tidbJSONFormat + " " + planned, nil
+ }
return "EXPLAIN " + planned, nil
}
+// DescribeExplain returns the output format of an EXPLAIN statement and whether
+// it executes the statement it plans. It is not an explain at all unless it
+// plans a statement: EXPLAIN tbl_name and DESCRIBE tbl_name parse here too and
+// describe a table's columns, which is a result like any other.
+func DescribeExplain(statement string) (format string, executed bool, ok bool) {
+ node, err := singleStatement(statement)
+ if err != nil {
+ return "", false, false
+ }
+ explain, ok := node.(*omniast.ExplainStmt)
+ if !ok {
+ return "", false, false
+ }
+ if _, plans := explainedStart(explain.Stmt); !plans {
+ return "", false, false
+ }
+ if strings.EqualFold(explain.Format, tidbJSONFormat) {
+ return "json", explain.Analyze, true
+ }
+ // Every other format TiDB prints is a table or a tree of lines.
+ return "text", explain.Analyze, true
+}
+
// singleStatement returns the one statement in text. An explain request plans one
// statement at a time: both the drivers and the API gate split a multi-statement
// request first.
diff --git a/backend/plugin/parser/tidb/explain_test.go b/backend/plugin/parser/tidb/explain_test.go
index da9107e15c..80c24db09d 100644
--- a/backend/plugin/parser/tidb/explain_test.go
+++ b/backend/plugin/parser/tidb/explain_test.go
@@ -36,6 +36,67 @@ func TestExplainStatement(t *testing.T) {
}
}
+// TestExplainStatementJSON pins the statement that asks for the structured plan
+// the visualizer draws. The format is spelled unquoted because TiDB's grammar
+// here takes an identifier, so a quoted one would not parse again.
+func TestExplainStatementJSON(t *testing.T) {
+ tests := []struct {
+ statement string
+ want string
+ }{
+ {"SELECT 1", "EXPLAIN FORMAT=tidb_json SELECT 1"},
+ {"EXPLAIN SELECT 1", "EXPLAIN FORMAT=tidb_json SELECT 1"},
+ {"EXPLAIN FORMAT=brief SELECT 1", "EXPLAIN FORMAT=tidb_json SELECT 1"},
+ {"EXPLAIN FORMAT=tidb_json SELECT 1", "EXPLAIN FORMAT=tidb_json SELECT 1"},
+ {"EXPLAIN t", "EXPLAIN t"},
+ }
+ for _, tc := range tests {
+ got, err := explainStatement(tc.statement, base.ExplainFormatJSON)
+ require.NoErrorf(t, err, "%q", tc.statement)
+ require.Equalf(t, tc.want, got, "%q", tc.statement)
+ }
+ // What this builds has to parse again: the driver validates it before running it.
+ for _, tc := range tests {
+ _, err := explainStatement(tc.want, base.ExplainFormatJSON)
+ require.NoErrorf(t, err, "%q", tc.want)
+ }
+ // Only JSON has a reader; the rest fall back to the engine's own plan.
+ for _, format := range []base.ExplainFormat{base.ExplainFormatText, base.ExplainFormatXML, base.ExplainFormatYAML} {
+ got, err := explainStatement("SELECT 1", format)
+ require.NoError(t, err)
+ require.Equal(t, "EXPLAIN SELECT 1", got)
+ }
+}
+
+// TestDescribeExplain pins what a result says about a plan the caller asked for
+// itself.
+func TestDescribeExplain(t *testing.T) {
+ tests := []struct {
+ statement string
+ format string
+ executed bool
+ isExplain bool
+ }{
+ {statement: "EXPLAIN FORMAT=tidb_json SELECT 1", format: "json", isExplain: true},
+ {statement: "explain format = TiDB_JSON select 1", format: "json", isExplain: true},
+ {statement: "EXPLAIN FORMAT=brief SELECT 1", format: "text", isExplain: true},
+ {statement: "EXPLAIN SELECT 1", format: "text", isExplain: true},
+ {statement: "EXPLAIN ANALYZE SELECT 1", format: "text", executed: true, isExplain: true},
+ {statement: "SELECT 1"},
+ // EXPLAIN over a table name describes its columns. The result is a
+ // table like any other, and calling it a query plan would put it in
+ // the viewer instead of the grid.
+ {statement: "EXPLAIN t"},
+ {statement: "DESCRIBE t"},
+ }
+ for _, tc := range tests {
+ format, executed, isExplain := DescribeExplain(tc.statement)
+ require.Equalf(t, tc.isExplain, isExplain, "%q", tc.statement)
+ require.Equalf(t, tc.format, format, "%q", tc.statement)
+ require.Equalf(t, tc.executed, executed, "%q", tc.statement)
+ }
+}
+
// TestExplainStatementRejects locks what never becomes an EXPLAIN: a write with
// EXPLAIN options smuggled in front of it, which anything that simply prefixed
// EXPLAIN would turn into an EXPLAIN ANALYZE DELETE that runs the DELETE, and an
diff --git a/backend/plugin/parser/trino/explain.go b/backend/plugin/parser/trino/explain.go
index 922dd0e50d..b1b4ab3583 100644
--- a/backend/plugin/parser/trino/explain.go
+++ b/backend/plugin/parser/trino/explain.go
@@ -13,11 +13,10 @@ func init() {
base.RegisterExplainStatementFunc(storepb.Engine_TRINO, explainStatement)
}
-// explainStatement implements base.ExplainStatement. Trino returns one plan
-// format here whatever the caller asked for: its EXPLAIN (FORMAT JSON) is a plan
-// of its own shape that nothing downstream reads (the driver capability table
-// offers this engine the default plan only).
-func explainStatement(statement string, _ base.ExplainFormat) (string, error) {
+// explainStatement implements base.ExplainStatement. Trino spells its structured
+// plan (FORMAT JSON); any other format the caller names gets the engine's own
+// text plan (the driver capability table refuses the rest).
+func explainStatement(statement string, format base.ExplainFormat) (string, error) {
node, err := singleStatement(statement)
if err != nil {
return "", err
@@ -35,6 +34,9 @@ func explainStatement(statement string, _ base.ExplainFormat) (string, error) {
return statement, nil
}
}
+ if format == base.ExplainFormatJSON {
+ return "EXPLAIN (FORMAT JSON) " + planned, nil
+ }
return "EXPLAIN " + planned, nil
}
diff --git a/backend/plugin/parser/trino/explain_test.go b/backend/plugin/parser/trino/explain_test.go
index b314110ecc..27031325fe 100644
--- a/backend/plugin/parser/trino/explain_test.go
+++ b/backend/plugin/parser/trino/explain_test.go
@@ -49,3 +49,29 @@ func TestExplainStatementRejects(t *testing.T) {
require.Errorf(t, err, "%q", statement)
}
}
+
+// TestExplainStatementJSON pins the statement that asks for the structured plan
+// the visualizer draws. The caller's own FORMAT is replaced, so the request
+// decides the format whatever the statement named.
+func TestExplainStatementJSON(t *testing.T) {
+ tests := []struct {
+ statement string
+ want string
+ }{
+ {"SELECT 1", "EXPLAIN (FORMAT JSON) SELECT 1"},
+ {"EXPLAIN SELECT 1", "EXPLAIN (FORMAT JSON) SELECT 1"},
+ {"EXPLAIN (FORMAT TEXT) SELECT 1", "EXPLAIN (FORMAT JSON) SELECT 1"},
+ {"EXPLAIN (FORMAT JSON) SELECT 1", "EXPLAIN (FORMAT JSON) SELECT 1"},
+ }
+ for _, tc := range tests {
+ got, err := explainStatement(tc.statement, base.ExplainFormatJSON)
+ require.NoErrorf(t, err, "%q", tc.statement)
+ require.Equalf(t, tc.want, got, "%q", tc.statement)
+ }
+ // Only JSON has a reader; the rest fall back to the engine's own plan.
+ for _, format := range []base.ExplainFormat{base.ExplainFormatText, base.ExplainFormatXML, base.ExplainFormatYAML} {
+ got, err := explainStatement("SELECT 1", format)
+ require.NoError(t, err)
+ require.Equal(t, "EXPLAIN SELECT 1", got)
+ }
+}
diff --git a/docs/design/query-plan-visualizer.md b/docs/design/query-plan-visualizer.md
index 95338bd99f..ea1361a4e9 100644
--- a/docs/design/query-plan-visualizer.md
+++ b/docs/design/query-plan-visualizer.md
@@ -27,10 +27,11 @@ This ordering is a judgment call, not a measurement.
## 2. Background / problem
-The editor explains on 12 engines and draws a picture for 3 (PostgreSQL, SQL
-Server, Spanner). Reaching the picture takes five steps: Ctrl/Cmd+E → plan rows
-in the grid → click a small "Visualize Explain" link → Bytebase runs `EXPLAIN` a
-second time for JSON → a separate browser tab opens.
+The editor explained on 12 engines and drew a picture for 3 (PostgreSQL, SQL
+Server, Spanner); it now explains on 17 and draws for 15 (§3.4). Reaching the
+picture takes five steps: Ctrl/Cmd+E → plan rows in the grid → click a small
+"Visualize Explain" link → Bytebase runs `EXPLAIN` a second time for JSON → a
+separate browser tab opens.
Four problems, ordered by how many users each blocks:
@@ -216,7 +217,7 @@ Text is not optional. The explain action is that one icon: where the engine
cannot explain, the option is absent; where the user lacks the permission, it
is disabled with the reason (§3.5).
-**Text appears only when Plan has a picture.** On the nine engines we cannot draw
+**Text appears only when Plan has a picture.** On the engines we cannot draw
(§3.4), the plan *is* text, so a second text view would say the same thing
twice. There, Plan shows the plan as text, and nothing else.
@@ -341,8 +342,18 @@ regression.
| **PostgreSQL** | one `Query()`, on demand, cached | graph | `EXPLAIN (ANALYZE, FORMAT JSON)`, drawn |
| **SQL Server** | one `Query()`, on demand, cached | graph | `SET STATISTICS XML ON`, with the rows |
| **Spanner** | one `Query()`, on demand, cached | graph | none in the editor — profile mode is an API, not SQL |
-| **MySQL** | one `Query()`, on demand, cached | text | `EXPLAIN ANALYZE` from 8.0.18, TREE text only |
-| **Oracle, 7 others** | one `Query()`, on demand, cached | text | per engine, text at most |
+| **MySQL, MariaDB** | one `Query()`, on demand, cached | graph | `EXPLAIN ANALYZE` from MySQL 8.0.18, TREE text only; MariaDB's `ANALYZE FORMAT=JSON` is not an `EXPLAIN` the parser reads |
+| **TiDB** | one `Query()`, on demand, cached | graph, with no costs | `EXPLAIN ANALYZE FORMAT=tidb_json`, drawn for its rows |
+| **Oracle** | one `Query()`, on demand, cached | graph | none: `EXPLAIN PLAN` never executes, and a measured plan needs `DBMS_XPLAN` over a cursor Bytebase did not run |
+| **ClickHouse** | one `Query()`, on demand, cached | graph, with no costs | none in the editor — `EXPLAIN PIPELINE` describes the pipeline, not a run |
+| **Trino** | one `Query()`, on demand, cached | graph, with no costs | none in the editor — `EXPLAIN ANALYZE` executes |
+| **OceanBase** | one `Query()`, on demand, cached | graph, costed in estimated microseconds | none in the editor |
+| **MongoDB** | one `Query()`, on demand, cached | graph, with no estimates at all | `explain("executionStats")`, drawn for its rows |
+| **CockroachDB** | one `Query()`, on demand, cached | graph of the physical flow, with no estimates | none in the editor — `EXPLAIN ANALYZE` executes |
+| **Redshift** | one `Query()`, on demand, cached | graph, drawn from the text plan | none — `EXPLAIN` never analyzes |
+| **StarRocks** | one `Query()`, on demand, cached | graph, drawn from the text plan | none — `EXPLAIN ANALYZE` executes |
+| **Doris** | one `Query()`, on demand, cached | graph, drawn from the text plan by the StarRocks parser | none — Doris has no `EXPLAIN ANALYZE` |
+| **Hive, Snowflake** | one `Query()`, on demand, cached | text | per engine, text at most |
A plan opened from a result is always an estimate, on every engine. Measured
plans come from a typed `EXPLAIN ANALYZE` or its engine's equivalent, which is a
@@ -385,11 +396,68 @@ statistics, and if the slow run was caused by stale statistics that have since
refreshed, the plan shown is the *good* one, and the reader concludes the query
was never the problem. That is the inverted failure this wording exists to stop.
-**Nine of twelve engines have no parser**, so for those the plan is text. Showing
-it as formatted text instead of grid rows is a small change with wide reach.
-MySQL and Oracle are the
-cheapest graphs to add later: MySQL already emits structured JSON, and Oracle's
-plan table already holds the parent-child links the driver discards.
+**Two of the seventeen engines the editor explains have no parser**, so for
+those the plan is text. Showing a text plan as formatted text instead of grid
+rows is a small change with wide reach.
+
+**Hive's
+`EXPLAIN FORMATTED` does**, and is the next graph to add: it returns the stages
+of a Tez DAG, each holding its vertices' operator trees, so it is a third shape
+again rather than another tree to walk, and pinning it needs a warehouse with
+statistics behind it — a plan whose every operator reports "Column stats: NONE"
+is not a fixture worth keeping. **Snowflake's `EXPLAIN USING JSON` also does**,
+but it runs nowhere but Snowflake, and a parser written against documentation
+rather than output is how a viewer learns to draw a plan no server emits.
+
+**What each new engine's plans do and do not carry.** Oracle states a plan as
+rows of `PLAN_TABLE` rather than as a document, and no EXPLAIN option of its
+own renders one, so the driver renders those rows as JSON and the viewer
+rebuilds the tree from their parent links. It is the one engine here that
+qualifies every object it reads with its owning schema, so its nodes answer a
+table lookup exactly. ClickHouse publishes no cost or row estimate in any
+EXPLAIN it offers, so its plans rank nothing and shade by rows, but with
+`indexes = 1` each read reports the parts and granules its indexes let it skip,
+which is what a ClickHouse plan is read for.
+
+Neither MySQL nor MariaDB names
+the stored table a `table` entry reads — it prints the alias where the statement
+gave one, unqualified, and nothing in the plan says which it is. TiDB and
+OceanBase print that name too. So on those four the name is carried as the
+statement's: it names the read on the node, and a node's table facts (§3.3) are
+not looked up by it, since a stored table that happens to share an alias would
+answer with the wrong table's indexes — the failure §3.3 exists to avoid. Nor does either name an operator for the work
+between the query block and its tables: MariaDB charges a sort to the query
+block, which therefore ranks first in such a plan, since attributing that cost
+to the `filesort` or the `temporary_table` under it would be a guess about
+which of them spends it. What a `table` states costs that table alone, and an
+ordering's `sort_cost` costs the sort alone: a subquery materialized for a
+table is costed apart, and only the block's `query_cost` covers the lot. So
+each is its own operator's self cost rather than a total to subtract a subtree
+from. TiDB reports no cost in any format the editor can
+ask for, so its plans rank nothing and shade by rows; its measured plan is read
+for rows alone, because `time:` covers an operator and its subtree and the
+operators pushed down to a coprocessor report none — the same reason this
+section gives for SQL Server's actual plan.
+
+**MongoDB has no estimates at all.** Its planner publishes neither a cost nor a
+row count, so a plan that did not run is shape and index usage: which is the
+question a reader opens one to answer, since `COLLSCAN` against `IXSCAN` is
+what there is to see. A measured plan adds the rows each stage returned, and
+not its timings: MongoDB labels the per-stage time an estimate itself, and on a
+query that finishes quickly every stage reports zero, so a ranking built on it
+would be arbitrary. An aggregation explains to a pipeline rather than a tree,
+read backwards so the stage producing the result is the root and the `$cursor`
+feeding it becomes the read's own plan below. Which engine ran the query is not
+the reader's question, but it changes where the plan sits: the slot-based
+engine reports the operator tree under `winningPlan.queryPlan`, beside the plan
+it compiled for its own machine, where the classic engine puts the tree itself,
+and it spells a join's two sides `outerStage` and `innerStage` where the
+classic engine nests one `inputStage`. A sharded collection is planned a shard
+at a time, and the merge stage holds each shard's whole plan under `shards`
+rather than as an input stage, so the shards are drawn as what they are — the
+branches the merge reads — and each node says which shard it ran on. A sharded
+aggregation goes further and states no pipeline of its own: the merger's part
+is the plan, with each shard's part under the `$mergeCursors` that reads it.
**Attaching a measured plan to an ordinary run is deferred.** Two engines could:
Spanner has a run mode returning rows and plan and real timings in one execution,
@@ -484,7 +552,11 @@ the statement type, so this is the only case left to that single check.
**Slow and large plans.** The on-demand call can take as long as any query: show
a skeleton, allow cancel, time out rather than hang. Past a node cap the Plan view
falls back to Text instead of drawing something unreadable — SSMS degrades the
-same way, at 2 MB.
+same way, at 2 MB. Where a parser splices a graph into a tree — CockroachDB's
+processors, and the fragments of StarRocks, Doris and Trino — the cap is
+counted as the nodes are drawn rather than once the tree is built: a node that
+several paths reach is drawn under each of them, so the copies multiply with
+the paths and a flow of 35 processors expands into 262,143 of them.
**When the plan cannot be drawn or fetched.** A plan we fail to parse falls back
to Text rather than erroring; engines change their output between versions, and
@@ -506,6 +578,9 @@ rejects shows that error in the tab, like any failed query.
the four does. Permanent space for the rarest journey.
- **Parse the text plan.** PostgreSQL's text output has no escaping, so a string
containing a newline can fake a plan node. Supabase reverted it; pgcli declined.
+ Redshift, StarRocks and Doris are the engines where this is done anyway,
+ because none of them publishes any other plan at all; §6 says what holds the
+ hazard off there.
- **Profile every run everywhere.** Possible only on Spanner and SQL Server, and
not free even there (§3.4); on PostgreSQL it would run every statement twice.
@@ -535,7 +610,7 @@ live servers, September 2026.
## 6. Status
-Checked against `main` on 2026-10-26, at [#21668](https://github.com/bytebase/bytebase/pull/21668), plus [#21669](https://github.com/bytebase/bytebase/pull/21669) below.
+Checked against `main` on 2026-10-27, at [#21669](https://github.com/bytebase/bytebase/pull/21669), plus [#21670](https://github.com/bytebase/bytebase/pull/21670) below.
**Landed**
@@ -606,6 +681,94 @@ Checked against `main` on 2026-10-26, at [#21668](https://github.com/bytebase/by
which it could not find in the editor before
([#21669](https://github.com/bytebase/bytebase/pull/21669)).
+- §4 — Redshift, StarRocks and Doris draw, from their text plans, which is the
+ one thing §4 says not to parse. None of them publishes anything else:
+ StarRocks and Doris reject every JSON spelling outright, and Redshift's
+ EXPLAIN takes no format at all, its one structured copy living in
+ `STL_EXPLAIN`, which can be read from nowhere but a running cluster. The
+ hazard §4 names is a literal holding a newline putting a line that looks like
+ an operator into the output, and two things hold it off for all three: the
+ plan arrives one row per line, so a newline inside a value stays inside its
+ row, and an operator is recognized only by its own heading — a whole cost
+ tuple on Redshift, a number and a name on the other two.
+
+ Redshift's grammar is PostgreSQL's with an `XN` prefix, so a plan captured
+ from a real PostgreSQL server pins it — which matters, because Redshift
+ itself cannot be run from this repository and the rest of its fixtures are
+ AWS's documented output. What its plan is read for is the distribution
+ strategy on a join: `DS_BCAST_INNER` and its kin say rows moved between
+ slices, which is what a distribution key is chosen to avoid.
+
+ StarRocks' plan is two nested structures: fragments joined where one sends to
+ another's exchange, and within each a tree whose second input is drawn in a
+ `|----` branch behind a bar, so which operator a line belongs to is the
+ column its number starts at. It states no cost, but a scan states its table,
+ the predicates pushed into it and the rows it expects.
+
+ Doris is read by that same parser, and the editor offers it Explain for the
+ first time: the server could always explain it, which made it a gap of its
+ own rather than a missing parser. StarRocks forked from Doris and the plan is
+ what did not diverge; what differs is how an operator spells itself. Doris
+ prefixes the vectorized operators with `V`, prints its own plan node id after
+ the name, packs an operator's numbers onto one line, qualifies a scanned
+ table with its database, and prints the statistics it planned from under a
+ rule of equals signs. Until a table has been analyzed it says
+ `avgRowSize=0.0`, which is no width rather than a zero one
+ ([#21670](https://github.com/bytebase/bytebase/pull/21670)).
+
+- §3.4 — CockroachDB draws as well. Its EXPLAIN takes no format that returns a
+ document — every option is text — but `EXPLAIN (DISTSQL)` prints a link to a
+ diagram beside the text plan, and the payload in that link is a plan a parser
+ can read. The driver decodes it, as the Oracle driver renders the plan table,
+ so the browser fetches nothing. What that plan carries is the physical flow
+ rather than the logical one: processors and the streams between them, the
+ table and index each read covers and the keys it spans, and no estimate — the
+ row counts a reader wants stay in the text plan the same statement returns
+ ([#21670](https://github.com/bytebase/bytebase/pull/21670)).
+
+- §3.1/§3.4 — MongoDB draws as well, and the editor offers it Explain for the
+ first time. It is the first engine here that did not explain at all: the
+ driver refused outright, and asking for a plan means appending the
+ `.explain()` cursor method rather than prefixing a keyword, which the parser
+ does from the statement's own syntax tree. Only the `queryPlanner` verbosity
+ describes a query without running it, so that is the one an explain request
+ uses, and a statement that names another has its verbosity replaced rather
+ than kept. A typed `explain("executionStats")` runs the query, so its result
+ is marked as an executed plan and gated as one
+ ([#21670](https://github.com/bytebase/bytebase/pull/21670)).
+
+- §3.4 — OceanBase draws as well, and the editor offers it Explain for the
+ first time. It spells its plan `FORMAT=JSON` as MySQL does but returns an
+ operator tree, each operator naming its children under `CHILD_1`, `CHILD_2`;
+ its `EST.TIME(us)` covers an operator and everything below it, so what the
+ viewer ranks there is microseconds the optimizer expects
+ ([#21670](https://github.com/bytebase/bytebase/pull/21670)).
+
+- §3.4 — Trino draws as well, and the editor offers it Explain for the first
+ time. Its `EXPLAIN (FORMAT JSON)` returns the fragments it would distribute,
+ keyed by number and linked by `RemoteSource`, which the parser splices back
+ into the one tree Trino's own text plan shows. Its rows are read and its
+ costs are not: `cpuCost` is each operation's own rather than its subtree's,
+ an operator Trino fused reports one per fused step, and most report `NaN`
+ outright, so ranking by it would point at whichever happened to be known
+ ([#21670](https://github.com/bytebase/bytebase/pull/21670)).
+
+- §3.4 — Oracle and ClickHouse draw as well. Oracle's plan table is rendered
+ as JSON by the driver, built in Go rather than with Oracle's own
+ `JSON_ARRAYAGG` so that it works on releases older than 12.2; ClickHouse is
+ asked for `EXPLAIN json = 1, indexes = 1`
+ ([#21670](https://github.com/bytebase/bytebase/pull/21670)).
+
+- §3.4 — the MySQL family draws. MySQL and MariaDB are asked for
+ `EXPLAIN FORMAT=JSON` and TiDB for `EXPLAIN FORMAT=tidb_json`, one parser
+ reading both MySQL dialects and one reading TiDB's. MariaDB could always be
+ explained and was missing from the editor's own list. A typed
+ `EXPLAIN FORMAT=JSON` draws without a second call, and a typed plain
+ `EXPLAIN` offers Visualize, which it could not before: MySQL's omitted
+ FORMAT follows the session's `explain_format`, and the viewer now reads that
+ unknown answer as text
+ ([#21670](https://github.com/bytebase/bytebase/pull/21670)).
+
**Not yet**
Nothing: every section of this design is implemented. The one question §3.3
diff --git a/frontend/src/apps/explain-visualizer/QueryPlanDiagram.tsx b/frontend/src/apps/explain-visualizer/QueryPlanDiagram.tsx
index 64aedb728f..d6a5d150bb 100644
--- a/frontend/src/apps/explain-visualizer/QueryPlanDiagram.tsx
+++ b/frontend/src/apps/explain-visualizer/QueryPlanDiagram.tsx
@@ -19,7 +19,11 @@ import { Tooltip } from "@/components/ui/tooltip";
import { cn } from "@/lib/utils";
import { minmax } from "@/utils/math";
import { PLAN_MINI_MAP_BOX, PlanMiniMap } from "./PlanMiniMap";
-import { type QueryPlanTranslate, useQueryPlanTranslation } from "./plan-i18n";
+import {
+ planWarningText,
+ type QueryPlanTranslate,
+ useQueryPlanTranslation,
+} from "./plan-i18n";
import {
layoutPlan,
PLAN_IDENTITY_VIEWPORT,
@@ -449,7 +453,9 @@ export function QueryPlanDiagram({
const selected = node.id === selectedId;
const metrics = planCardMetrics(node, tree, translate);
const share = planSelfShare(node, tree);
- const warnings = node.warnings.map((warning) => warning.title);
+ const warnings = node.warnings.map(
+ (warning) => planWarningText(warning, translate).title
+ );
const collapsed = collapsedIds.has(node.id);
const subtreeCount = planDescendantCount(node);
const { relationship } = node;
diff --git a/frontend/src/apps/explain-visualizer/QueryPlanNodeDetails.test.tsx b/frontend/src/apps/explain-visualizer/QueryPlanNodeDetails.test.tsx
index 659c2ea6bf..d8ba06d2bb 100644
--- a/frontend/src/apps/explain-visualizer/QueryPlanNodeDetails.test.tsx
+++ b/frontend/src/apps/explain-visualizer/QueryPlanNodeDetails.test.tsx
@@ -1,5 +1,6 @@
import { render, screen } from "@testing-library/react";
import { describe, expect, test, vi } from "vitest";
+import { QueryPlanI18nProvider } from "./plan-i18n";
import { PLAN_FULL_TABLE_SCAN, type PlanNode } from "./plan-model";
import { QueryPlanNodeDetails } from "./QueryPlanNodeDetails";
@@ -101,6 +102,38 @@ describe("QueryPlanNodeDetails", () => {
expect(screen.getAllByRole("alert")).toEqual(warnings);
});
+ test("reads this viewer's own warning in the reader's language", () => {
+ const translate = vi.fn((key: string) => `localized:${key}`);
+ render(
+ <QueryPlanI18nProvider translate={translate}>
+ <QueryPlanNodeDetails
+ node={node({
+ warnings: [
+ PLAN_FULL_TABLE_SCAN,
+ {
+ title: "No join predicate",
+ detail: "Every row pairs up.",
+ source: "engine",
+ },
+ ],
+ })}
+ />
+ </QueryPlanI18nProvider>
+ );
+
+ const warnings = screen.getAllByTestId("plan-details-warning");
+ expect(warnings[0]).toHaveTextContent(
+ "localized:warning.full-table-scan.title"
+ );
+ expect(warnings[0]).toHaveTextContent(
+ "localized:warning.full-table-scan.detail"
+ );
+ // A warning the engine reported keeps the engine's words, as the plan's
+ // own operator names and values do.
+ expect(warnings[1]).toHaveTextContent("No join predicate");
+ expect(warnings[1]).toHaveTextContent("Every row pairs up.");
+ });
+
test("shows a warning the engine repeats as often as it reports it", () => {
const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
render(
diff --git a/frontend/src/apps/explain-visualizer/QueryPlanNodeDetails.tsx b/frontend/src/apps/explain-visualizer/QueryPlanNodeDetails.tsx
index 3e85519b15..12dc32c5ba 100644
--- a/frontend/src/apps/explain-visualizer/QueryPlanNodeDetails.tsx
+++ b/frontend/src/apps/explain-visualizer/QueryPlanNodeDetails.tsx
@@ -1,6 +1,10 @@
import { Alert } from "@/components/ui/alert";
import { Separator } from "@/components/ui/separator";
-import { type QueryPlanTranslate, useQueryPlanTranslation } from "./plan-i18n";
+import {
+ planWarningText,
+ type QueryPlanTranslate,
+ useQueryPlanTranslation,
+} from "./plan-i18n";
import {
formatPlanCost,
formatPlanCount,
@@ -189,17 +193,20 @@ export function QueryPlanNodeDetails({ node, table }: Props) {
{/* The diagram flags these with a hover-only icon, which a touch reader
never reaches. The pane is where the selected node is explained, so
it carries the warnings too. */}
- {node.warnings.map((warning, index) => (
- <Alert
- // An engine can report the same warning twice, so its text is not a
- // key; a node's warnings never reorder.
- key={index}
- variant="warning"
- data-testid="plan-details-warning"
- title={warning.title}
- description={warning.detail}
- />
- ))}
+ {node.warnings.map((warning, index) => {
+ const { title, detail } = planWarningText(warning, translate);
+ return (
+ <Alert
+ // An engine can report the same warning twice, so its text is not
+ // a key; a node's warnings never reorder.
+ key={index}
+ variant="warning"
+ data-testid="plan-details-warning"
+ title={title}
+ description={detail}
+ />
+ );
+ })}
{metrics.length > 0 ? (
<>
diff --git a/frontend/src/apps/explain-visualizer/QueryPlanSummary.tsx b/frontend/src/apps/explain-visualizer/QueryPlanSummary.tsx
index 9e31cbad8e..7b3f7bcbdd 100644
--- a/frontend/src/apps/explain-visualizer/QueryPlanSummary.tsx
+++ b/frontend/src/apps/explain-visualizer/QueryPlanSummary.tsx
@@ -2,7 +2,7 @@ import { TriangleAlert } from "lucide-react";
import { useMemo } from "react";
import { Button } from "@/components/ui/button";
import { cn } from "@/lib/utils";
-import { useQueryPlanTranslation } from "./plan-i18n";
+import { planWarningText, useQueryPlanTranslation } from "./plan-i18n";
import {
formatPlanCount,
formatPlanShare,
@@ -12,6 +12,7 @@ import {
planRankMetric,
planSelfShare,
planWarningGroups,
+ planWarningIdentity,
} from "./plan-model";
interface Props {
@@ -127,7 +128,7 @@ export function QueryPlanSummary({ tree, selectedId, onSelect }: Props) {
(node) => node.id === selectedId
);
return (
- <li key={group.warning.title}>
+ <li key={planWarningIdentity(group.warning)}>
<Button
appearance="secondary"
data-testid="plan-summary-warning"
@@ -143,7 +144,7 @@ export function QueryPlanSummary({ tree, selectedId, onSelect }: Props) {
/>
<span className="flex min-w-0 flex-1 flex-col">
<span className={titleClass(selected)}>
- {group.warning.title}
+ {planWarningText(group.warning, translate).title}
</span>
<span className="truncate text-xs leading-4 text-control-light">
{warningSubject(group, translate)}
diff --git a/frontend/src/apps/explain-visualizer/QueryPlanView.test.tsx b/frontend/src/apps/explain-visualizer/QueryPlanView.test.tsx
index a853611bb9..42c363ff6f 100644
--- a/frontend/src/apps/explain-visualizer/QueryPlanView.test.tsx
+++ b/frontend/src/apps/explain-visualizer/QueryPlanView.test.tsx
@@ -1,6 +1,10 @@
import { render, screen } from "@testing-library/react";
import { describe, expect, test, vi } from "vitest";
import { Engine } from "@/types/proto-es/v1/common_pb";
+import {
+ type VisualizerEngine,
+ VISUALIZER_EXPLAIN_FORMATS,
+} from "@/utils/queryPlanEngines";
import { QueryPlanView } from "./QueryPlanView";
describe("QueryPlanView", () => {
@@ -19,6 +23,72 @@ describe("QueryPlanView", () => {
expect(screen.getByText("localized:error.postgres-invalid")).toBeVisible();
});
+ /**
+ * The key family each engine's parser owns. MariaDB is read by the MySQL
+ * parser and Doris by the StarRocks one, so each reports the other's
+ * messages.
+ */
+ const ERROR_FAMILY: Record<VisualizerEngine, string> = {
+ [Engine.POSTGRES]: "postgres",
+ [Engine.MSSQL]: "mssql",
+ [Engine.SPANNER]: "spanner",
+ [Engine.MYSQL]: "mysql",
+ [Engine.MARIADB]: "mysql",
+ [Engine.TIDB]: "tidb",
+ [Engine.ORACLE]: "oracle",
+ [Engine.CLICKHOUSE]: "clickhouse",
+ [Engine.TRINO]: "trino",
+ [Engine.OCEANBASE]: "oceanbase",
+ [Engine.MONGODB]: "mongodb",
+ [Engine.COCKROACHDB]: "cockroachdb",
+ [Engine.REDSHIFT]: "redshift",
+ [Engine.STARROCKS]: "starrocks",
+ [Engine.DORIS]: "starrocks",
+ };
+
+ test("localizes what every parser says about a plan it cannot read", () => {
+ const translate = vi.fn((key: string) => `localized:${key}`);
+ const engines = Object.keys(VISUALIZER_EXPLAIN_FORMATS).map(
+ Number
+ ) as VisualizerEngine[];
+
+ for (const engine of engines) {
+ // Nothing at all, something that is not a plan, and a document of the
+ // right kind holding no plan: one message each, from every parser.
+ for (const planSource of ["", "not a plan", "{}"]) {
+ const { unmount } = render(
+ <QueryPlanView
+ engine={engine}
+ planSource={planSource}
+ translate={translate}
+ />
+ );
+ // A message the view has no key for would render as its own English
+ // text, leaving the title as the only localized line.
+ const localized = screen
+ .getAllByText(/^localized:error\./)
+ .map((element) => element.textContent);
+ expect(localized, `${engine} on ${JSON.stringify(planSource)}`).toEqual(
+ expect.arrayContaining(["localized:error.unreadable"])
+ );
+ expect(localized, `${engine} on ${JSON.stringify(planSource)}`).toHaveLength(2);
+ const described = localized.find(
+ (text) => text !== "localized:error.unreadable"
+ );
+ // The keys are looked up by message, so two parsers wording a
+ // message identically would quietly answer for each other. Which of
+ // its three messages a parser picks for a given input is its own
+ // business; whose message it is, is not.
+ expect(described, `${engine} on ${JSON.stringify(planSource)}`).toMatch(
+ new RegExp(
+ `^localized:error\\.${ERROR_FAMILY[engine]}-(empty|invalid|no-plan)$`
+ )
+ );
+ unmount();
+ }
+ }
+ });
+
test("shows the text plan when the structured plan cannot be parsed", () => {
render(
<QueryPlanView
diff --git a/frontend/src/apps/explain-visualizer/QueryPlanView.tsx b/frontend/src/apps/explain-visualizer/QueryPlanView.tsx
index e1a554765c..e564bc4609 100644
--- a/frontend/src/apps/explain-visualizer/QueryPlanView.tsx
+++ b/frontend/src/apps/explain-visualizer/QueryPlanView.tsx
@@ -2,11 +2,41 @@ import { type ReactNode, useMemo } from "react";
import { Alert } from "@/components/ui/alert";
import { cn } from "@/lib/utils";
import type { VisualizerEngine } from "@/utils/queryPlanEngines";
+import {
+ CLICKHOUSE_PLAN_EMPTY_MESSAGE,
+ CLICKHOUSE_PLAN_INVALID_JSON_MESSAGE,
+ CLICKHOUSE_PLAN_NO_PLAN_MESSAGE,
+} from "./clickhouse-plan";
+import {
+ COCKROACHDB_PLAN_EMPTY_MESSAGE,
+ COCKROACHDB_PLAN_INVALID_JSON_MESSAGE,
+ COCKROACHDB_PLAN_NO_PLAN_MESSAGE,
+} from "./cockroachdb-plan";
+import {
+ MONGODB_PLAN_EMPTY_MESSAGE,
+ MONGODB_PLAN_INVALID_JSON_MESSAGE,
+ MONGODB_PLAN_NO_PLAN_MESSAGE,
+} from "./mongodb-plan";
import {
MSSQL_PLAN_EMPTY_MESSAGE,
MSSQL_PLAN_INVALID_XML_MESSAGE,
MSSQL_PLAN_NO_PLAN_MESSAGE,
} from "./mssql-plan";
+import {
+ MYSQL_PLAN_EMPTY_MESSAGE,
+ MYSQL_PLAN_INVALID_JSON_MESSAGE,
+ MYSQL_PLAN_NO_PLAN_MESSAGE,
+} from "./mysql-plan";
+import {
+ OCEANBASE_PLAN_EMPTY_MESSAGE,
+ OCEANBASE_PLAN_INVALID_JSON_MESSAGE,
+ OCEANBASE_PLAN_NO_PLAN_MESSAGE,
+} from "./oceanbase-plan";
+import {
+ ORACLE_PLAN_EMPTY_MESSAGE,
+ ORACLE_PLAN_INVALID_JSON_MESSAGE,
+ ORACLE_PLAN_NO_PLAN_MESSAGE,
+} from "./oracle-plan";
import {
QueryPlanI18nProvider,
type QueryPlanTranslate,
@@ -25,12 +55,30 @@ import {
POSTGRES_PLAN_NO_PLAN_MESSAGE,
} from "./postgres-plan";
import { QueryPlanViewer } from "./QueryPlanViewer";
+import {
+ REDSHIFT_PLAN_EMPTY_MESSAGE,
+ REDSHIFT_PLAN_NO_PLAN_MESSAGE,
+} from "./redshift-plan";
import {
SPANNER_PLAN_EMPTY_MESSAGE,
SPANNER_PLAN_EMULATOR_MESSAGE,
SPANNER_PLAN_INVALID_JSON_MESSAGE,
SPANNER_PLAN_NO_PLAN_MESSAGE,
} from "./spanner-plan";
+import {
+ STARROCKS_PLAN_EMPTY_MESSAGE,
+ STARROCKS_PLAN_NO_PLAN_MESSAGE,
+} from "./starrocks-plan";
+import {
+ TIDB_PLAN_EMPTY_MESSAGE,
+ TIDB_PLAN_INVALID_JSON_MESSAGE,
+ TIDB_PLAN_NO_PLAN_MESSAGE,
+} from "./tidb-plan";
+import {
+ TRINO_PLAN_EMPTY_MESSAGE,
+ TRINO_PLAN_INVALID_JSON_MESSAGE,
+ TRINO_PLAN_NO_PLAN_MESSAGE,
+} from "./trino-plan";
const STATUS_CLASS =
"flex h-full min-h-0 w-full flex-col gap-4 overflow-auto bg-background p-4";
@@ -48,6 +96,34 @@ const PARSE_ERROR_KEYS = new Map<string, QueryPlanTranslationKey>([
[SPANNER_PLAN_INVALID_JSON_MESSAGE, "error.spanner-invalid"],
[SPANNER_PLAN_NO_PLAN_MESSAGE, "error.spanner-no-plan"],
[SPANNER_PLAN_EMULATOR_MESSAGE, "error.spanner-emulator"],
+ [MYSQL_PLAN_EMPTY_MESSAGE, "error.mysql-empty"],
+ [MYSQL_PLAN_INVALID_JSON_MESSAGE, "error.mysql-invalid"],
+ [MYSQL_PLAN_NO_PLAN_MESSAGE, "error.mysql-no-plan"],
+ [TIDB_PLAN_EMPTY_MESSAGE, "error.tidb-empty"],
+ [TIDB_PLAN_INVALID_JSON_MESSAGE, "error.tidb-invalid"],
+ [TIDB_PLAN_NO_PLAN_MESSAGE, "error.tidb-no-plan"],
+ [ORACLE_PLAN_EMPTY_MESSAGE, "error.oracle-empty"],
+ [ORACLE_PLAN_INVALID_JSON_MESSAGE, "error.oracle-invalid"],
+ [ORACLE_PLAN_NO_PLAN_MESSAGE, "error.oracle-no-plan"],
+ [CLICKHOUSE_PLAN_EMPTY_MESSAGE, "error.clickhouse-empty"],
+ [CLICKHOUSE_PLAN_INVALID_JSON_MESSAGE, "error.clickhouse-invalid"],
+ [CLICKHOUSE_PLAN_NO_PLAN_MESSAGE, "error.clickhouse-no-plan"],
+ [TRINO_PLAN_EMPTY_MESSAGE, "error.trino-empty"],
+ [TRINO_PLAN_INVALID_JSON_MESSAGE, "error.trino-invalid"],
+ [TRINO_PLAN_NO_PLAN_MESSAGE, "error.trino-no-plan"],
+ [OCEANBASE_PLAN_EMPTY_MESSAGE, "error.oceanbase-empty"],
+ [OCEANBASE_PLAN_INVALID_JSON_MESSAGE, "error.oceanbase-invalid"],
+ [OCEANBASE_PLAN_NO_PLAN_MESSAGE, "error.oceanbase-no-plan"],
+ [MONGODB_PLAN_EMPTY_MESSAGE, "error.mongodb-empty"],
+ [MONGODB_PLAN_INVALID_JSON_MESSAGE, "error.mongodb-invalid"],
+ [MONGODB_PLAN_NO_PLAN_MESSAGE, "error.mongodb-no-plan"],
+ [COCKROACHDB_PLAN_EMPTY_MESSAGE, "error.cockroachdb-empty"],
+ [COCKROACHDB_PLAN_INVALID_JSON_MESSAGE, "error.cockroachdb-invalid"],
+ [COCKROACHDB_PLAN_NO_PLAN_MESSAGE, "error.cockroachdb-no-plan"],
+ [REDSHIFT_PLAN_EMPTY_MESSAGE, "error.redshift-empty"],
+ [REDSHIFT_PLAN_NO_PLAN_MESSAGE, "error.redshift-no-plan"],
+ [STARROCKS_PLAN_EMPTY_MESSAGE, "error.starrocks-empty"],
+ [STARROCKS_PLAN_NO_PLAN_MESSAGE, "error.starrocks-no-plan"],
]);
interface Props {
diff --git a/frontend/src/apps/explain-visualizer/clickhouse-plan.test.ts b/frontend/src/apps/explain-visualizer/clickhouse-plan.test.ts
new file mode 100644
index 0000000000..73f297c782
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/clickhouse-plan.test.ts
@@ -0,0 +1,152 @@
+import { describe, expect, test } from "vitest";
+import {
+ CLICKHOUSE_PLAN_EMPTY_MESSAGE,
+ CLICKHOUSE_PLAN_INVALID_JSON_MESSAGE,
+ CLICKHOUSE_PLAN_NO_PLAN_MESSAGE,
+ parseClickhousePlan,
+} from "./clickhouse-plan";
+import {
+ PLAN_TOO_DEEP_MESSAGE,
+ type PlanNode,
+ type PlanTree,
+} from "./plan-model";
+import joinTwoTables from "./test-data/clickhouse/join-two-tables.json";
+import primaryKeyRange from "./test-data/clickhouse/primary-key-range.json";
+import readFilterAggregate from "./test-data/clickhouse/read-filter-aggregate.json";
+
+/** A chain of `depth` operators, which is what drives the depth limit. */
+const nestedPlan = (depth: number): string => {
+ let plan: Record<string, unknown> = { "Node Type": "ReadFromMergeTree" };
+ for (let level = 1; level < depth; level += 1) {
+ plan = { "Node Type": "Expression", Plans: [plan] };
+ }
+ return JSON.stringify([{ Plan: plan }]);
+};
+
+const parse = (source: string): PlanTree => {
+ const result = parseClickhousePlan(source);
+ if (!result.ok)
+ throw new Error(`expected a parsable plan: ${result.message}`);
+ return result.tree;
+};
+
+const parseFixture = (fixture: unknown): PlanTree =>
+ parse(JSON.stringify(fixture));
+
+const outline = (tree: PlanTree): string[] =>
+ tree.nodes.map((node) => `${node.id} ${node.nodeType}`);
+
+const propertyValue = (node: PlanNode, label: string): string | undefined =>
+ node.properties.find((property) => property.label === label)?.value;
+
+const byId = (tree: PlanTree, id: string): PlanNode => {
+ const node = tree.nodes.find((candidate) => candidate.id === id);
+ if (!node) throw new Error(`no node ${id} in ${outline(tree).join(", ")}`);
+ return node;
+};
+
+describe("parseClickhousePlan", () => {
+ test("reads the pipeline from the query's result down to the read", () => {
+ const tree = parseFixture(readFilterAggregate);
+
+ expect(outline(tree)).toEqual([
+ "0 Expression",
+ "0.0 Limit",
+ "0.0.0 Sorting",
+ "0.0.0.0 Expression",
+ "0.0.0.0.0 Aggregating",
+ "0.0.0.0.0.0 Expression",
+ "0.0.0.0.0.0.0 Expression",
+ "0.0.0.0.0.0.0.0 ReadFromMergeTree",
+ ]);
+ // ClickHouse says what each step is for, which is all it says: the one
+ // thing a node carries besides its name.
+ expect(tree.root.subject).toBe("Project names");
+ expect(byId(tree, "0.0.0").subject).toBe("Sorting for ORDER BY");
+ });
+
+ test("ranks nothing, because no ClickHouse EXPLAIN carries a cost", () => {
+ const tree = parseFixture(readFilterAggregate);
+
+ expect(tree.estimates).toEqual({
+ cost: false,
+ startupCost: false,
+ rows: false,
+ width: false,
+ });
+ expect(tree.measured).toEqual({ time: false, rows: false });
+ expect(tree.costBasis).toBe(0);
+ });
+
+ test("answers a read with the database ClickHouse qualified it by", () => {
+ const read = byId(parseFixture(primaryKeyRange), "0.0.0");
+
+ expect(read.nodeType).toBe("ReadFromMergeTree");
+ expect(read.relation).toEqual({ database: "default", table: "orders" });
+ });
+
+ test("reports how much each index let the read skip", () => {
+ const read = byId(parseFixture(primaryKeyRange), "0.0.0");
+
+ // Granules in against granules out is what a ClickHouse plan is read for.
+ const index = propertyValue(read, "PrimaryKey index");
+ expect(index).toContain("Initial granules:");
+ expect(index).toContain("Selected granules:");
+ expect(index).toContain("Condition:");
+ });
+
+ test("hangs both sides of a join off it, and names only the read it can", () => {
+ const tree = parseFixture(joinTwoTables);
+ const join = byId(tree, "0.0");
+
+ expect(join.nodeType).toBe("Join");
+ expect(join.children).toHaveLength(2);
+ expect(byId(tree, "0.0.0.0").relation).toEqual({
+ database: "default",
+ table: "orders",
+ });
+ // A read of a table function names no table to look up.
+ expect(byId(tree, "0.0.1.0").nodeType).toBe("ReadFromSystemNumbers");
+ expect(byId(tree, "0.0.1.0").relation).toBeUndefined();
+ });
+
+ test("leaves an unqualified description unresolved", () => {
+ const tree = parse(
+ JSON.stringify([
+ { Plan: { "Node Type": "ReadFromMergeTree", Description: "orders" } },
+ ])
+ );
+
+ // A bare name is the one the statement used, which is not enough to say
+ // which database's table it is.
+ expect(tree.root.relation).toBeUndefined();
+ expect(tree.root.subject).toBe("orders");
+ });
+
+ test("reports a plan it cannot read", () => {
+ expect(parseClickhousePlan(" ")).toEqual({
+ ok: false,
+ message: CLICKHOUSE_PLAN_EMPTY_MESSAGE,
+ });
+ expect(parseClickhousePlan("not json")).toEqual({
+ ok: false,
+ message: CLICKHOUSE_PLAN_INVALID_JSON_MESSAGE,
+ });
+ expect(parseClickhousePlan("[]")).toEqual({
+ ok: false,
+ message: CLICKHOUSE_PLAN_NO_PLAN_MESSAGE,
+ });
+ // The plan ClickHouse returns without `json = 1`, which is indented text.
+ expect(
+ parseClickhousePlan("Expression ((Project names + Projection))")
+ ).toEqual({ ok: false, message: CLICKHOUSE_PLAN_INVALID_JSON_MESSAGE });
+ });
+
+ test("gives up past the depth it can draw", () => {
+ expect(parseClickhousePlan(nestedPlan(400)).ok).toBe(true);
+ expect(parseClickhousePlan(nestedPlan(2000))).toEqual({
+ ok: false,
+ message: PLAN_TOO_DEEP_MESSAGE,
+ });
+ });
+});
diff --git a/frontend/src/apps/explain-visualizer/clickhouse-plan.ts b/frontend/src/apps/explain-visualizer/clickhouse-plan.ts
new file mode 100644
index 0000000000..70dc7c7b1a
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/clickhouse-plan.ts
@@ -0,0 +1,149 @@
+import {
+ addPlanProperty,
+ checkPlanDepth,
+ isJsonRecord,
+ type JsonRecord,
+ type PlanNode,
+ type PlanParseResult,
+ type PlanProperty,
+ type PlanRelation,
+ parseWithDepthLimit,
+ planLabel,
+} from "./plan-model";
+
+/**
+ * Maps `EXPLAIN json = 1` output onto the engine-neutral plan model.
+ *
+ * ClickHouse borrows PostgreSQL's spelling — a one-element array holding a
+ * `Plan`, children under `Plans`, the operator under `Node Type` — but not its
+ * numbers: it publishes no cost or row estimate in any EXPLAIN it offers, so a
+ * ClickHouse plan is a shape and a set of descriptions, and the viewer says it
+ * ranks nothing.
+ *
+ * What it does report, with `indexes = 1`, is how much each index let it skip,
+ * which is the question a reader of a ClickHouse plan actually has.
+ */
+
+const PLAN_KEY = "Plan";
+const CHILDREN_KEY = "Plans";
+const NODE_TYPE_KEY = "Node Type";
+const DESCRIPTION_KEY = "Description";
+const INDEXES_KEY = "Indexes";
+
+/** Keys the model promotes to typed fields, so the property list drops them. */
+const PROMOTED_KEYS = new Set([NODE_TYPE_KEY, DESCRIPTION_KEY, CHILDREN_KEY]);
+
+/** The operator that reads a table, and so names one in its description. */
+const TABLE_READERS = /^ReadFrom/;
+
+export const CLICKHOUSE_PLAN_EMPTY_MESSAGE =
+ "ClickHouse returned no query plan for this statement.";
+export const CLICKHOUSE_PLAN_INVALID_JSON_MESSAGE =
+ "The query plan is not valid JSON. EXPLAIN json = 1 output is expected.";
+export const CLICKHOUSE_PLAN_NO_PLAN_MESSAGE =
+ 'The ClickHouse query plan JSON does not contain a "Plan" object.';
+
+function stringValue(value: unknown): string | undefined {
+ return typeof value === "string" && value ? value : undefined;
+}
+
+function formatValue(value: unknown): string {
+ if (value === null || value === undefined) return "";
+ if (typeof value === "string") return value;
+ if (typeof value === "number" || typeof value === "boolean") {
+ return String(value);
+ }
+ return JSON.stringify(value);
+}
+
+/**
+ * The table a read names, where it names one.
+ *
+ * ClickHouse writes it qualified, as `default.orders`, so an unqualified
+ * description is left alone rather than guessed at — and a bare name would in
+ * any case be the one the statement used.
+ */
+function toRelation(
+ nodeType: string,
+ raw: JsonRecord
+): PlanRelation | undefined {
+ if (!TABLE_READERS.test(nodeType)) return undefined;
+ const description = stringValue(raw[DESCRIPTION_KEY]);
+ if (!description) return undefined;
+ const separator = description.lastIndexOf(".");
+ if (separator <= 0 || separator === description.length - 1) return undefined;
+ return {
+ database: description.slice(0, separator),
+ table: description.slice(separator + 1),
+ };
+}
+
+/**
+ * Each index the read consulted, as one property: what it is, the condition it
+ * was given, and how many of the table's parts and granules survived it. That
+ * last pair is the whole point of the entry — granules in against granules out
+ * is how much work the index saved.
+ */
+function indexProperties(raw: JsonRecord, properties: PlanProperty[]) {
+ const indexes = raw[INDEXES_KEY];
+ if (!Array.isArray(indexes)) return;
+ for (const index of indexes.filter(isJsonRecord)) {
+ const type = stringValue(index.Type) ?? "Index";
+ const described = Object.entries(index)
+ .filter(([key]) => key !== "Type")
+ .map(([key, value]) => `${planLabel(key)}: ${formatValue(value)}`)
+ .join(", ");
+ addPlanProperty(properties, `${type} index`, described);
+ }
+}
+
+function toProperties(raw: JsonRecord): PlanProperty[] {
+ const properties: PlanProperty[] = [];
+ for (const [key, value] of Object.entries(raw)) {
+ if (PROMOTED_KEYS.has(key) || key === INDEXES_KEY) continue;
+ addPlanProperty(properties, planLabel(key), formatValue(value));
+ }
+ indexProperties(raw, properties);
+ return properties;
+}
+
+function toPlanNode(raw: JsonRecord, id: string, depth: number): PlanNode {
+ checkPlanDepth(depth);
+ const rawChildren = raw[CHILDREN_KEY];
+ const children = (Array.isArray(rawChildren) ? rawChildren : [])
+ .filter(isJsonRecord)
+ .map((child, index) => toPlanNode(child, `${id}.${index}`, depth + 1));
+
+ const nodeType = stringValue(raw[NODE_TYPE_KEY]) ?? "Unknown";
+ return {
+ id,
+ nodeType,
+ subject: stringValue(raw[DESCRIPTION_KEY]),
+ relation: toRelation(nodeType, raw),
+ properties: toProperties(raw),
+ warnings: [],
+ children,
+ };
+}
+
+export function parseClickhousePlan(source: string): PlanParseResult {
+ const trimmed = source.trim();
+ if (!trimmed) {
+ return { ok: false, message: CLICKHOUSE_PLAN_EMPTY_MESSAGE };
+ }
+
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(trimmed);
+ } catch {
+ return { ok: false, message: CLICKHOUSE_PLAN_INVALID_JSON_MESSAGE };
+ }
+
+ const entry = Array.isArray(parsed) ? parsed[0] : parsed;
+ const plan = isJsonRecord(entry) ? entry[PLAN_KEY] : undefined;
+ if (!isJsonRecord(plan)) {
+ return { ok: false, message: CLICKHOUSE_PLAN_NO_PLAN_MESSAGE };
+ }
+
+ return parseWithDepthLimit(() => toPlanNode(plan, "0", 0));
+}
diff --git a/frontend/src/apps/explain-visualizer/cockroachdb-plan.test.ts b/frontend/src/apps/explain-visualizer/cockroachdb-plan.test.ts
new file mode 100644
index 0000000000..eb848dc621
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/cockroachdb-plan.test.ts
@@ -0,0 +1,214 @@
+import { describe, expect, test } from "vitest";
+import {
+ COCKROACHDB_PLAN_EMPTY_MESSAGE,
+ COCKROACHDB_PLAN_INVALID_JSON_MESSAGE,
+ COCKROACHDB_PLAN_NO_PLAN_MESSAGE,
+ parseCockroachdbPlan,
+} from "./cockroachdb-plan";
+import {
+ PLAN_FULL_TABLE_SCAN,
+ PLAN_TOO_DEEP_MESSAGE,
+ PLAN_TOO_MANY_NODES_MESSAGE,
+ type PlanNode,
+ type PlanTree,
+} from "./plan-model";
+import indexJoin from "./test-data/cockroachdb/index-join.json";
+import scanFilterGroup from "./test-data/cockroachdb/scan-filter-group.json";
+import sortLimit from "./test-data/cockroachdb/sort-limit.json";
+
+/** A chain of `depth` processors, which is what drives the depth limit. */
+const nestedPlan = (depth: number): string => {
+ const processors = Array.from({ length: depth }, (_, index) => ({
+ core: { title: `Processor/${index}`, details: [] },
+ }));
+ const edges = Array.from({ length: depth - 1 }, (_, index) => ({
+ sourceProc: index,
+ destProc: index + 1,
+ }));
+ return JSON.stringify({ processors, edges });
+};
+
+/**
+ * `stages` stages of two processors, each feeding both of the stage before it,
+ * which is the shape a repartitioning join takes. Every path through it draws
+ * the whole subgraph again, so the tree doubles per stage: 30 stages would be
+ * 2^31 nodes if the parser built them all before counting.
+ */
+const repartitionedPlan = (stages: number): string => {
+ const processors: unknown[] = [
+ { core: { title: "Response/-1", details: [] } },
+ ];
+ const edges: unknown[] = [];
+ let previous = [0];
+ for (let stage = 0; stage < stages; stage += 1) {
+ const current = [processors.length, processors.length + 1];
+ for (const index of current) {
+ processors.push({ core: { title: `Stage/${index}`, details: [] } });
+ }
+ for (const source of current) {
+ for (const destProc of previous)
+ edges.push({ sourceProc: source, destProc });
+ }
+ previous = current;
+ }
+ return JSON.stringify({ processors, edges });
+};
+
+const parse = (source: string): PlanTree => {
+ const result = parseCockroachdbPlan(source);
+ if (!result.ok)
+ throw new Error(`expected a parsable plan: ${result.message}`);
+ return result.tree;
+};
+
+const parseFixture = (fixture: unknown): PlanTree =>
+ parse(JSON.stringify(fixture));
+
+const outline = (tree: PlanTree): string[] =>
+ tree.nodes.map((node) => `${node.id} ${node.nodeType}`);
+
+const propertyValue = (node: PlanNode, label: string): string | undefined =>
+ node.properties.find((property) => property.label === label)?.value;
+
+const byId = (tree: PlanTree, id: string): PlanNode => {
+ const node = tree.nodes.find((candidate) => candidate.id === id);
+ if (!node) throw new Error(`no node ${id} in ${outline(tree).join(", ")}`);
+ return node;
+};
+
+describe("parseCockroachdbPlan", () => {
+ test("roots the flow at the processor nothing reads from", () => {
+ const tree = parseFixture(scanFilterGroup);
+
+ // The streams run from the read upwards; Response is where the query's
+ // rows come out, so it is the root and the read is the leaf.
+ expect(outline(tree)).toEqual([
+ "0 Response",
+ "0.0 Aggregator",
+ "0.0.0 Filterer",
+ "0.0.0.0 TableReader",
+ ]);
+ expect(propertyValue(byId(tree, "0.0.0"), "Filter")).toBe(
+ "@2 > 880:::INT8"
+ );
+ });
+
+ test("ranks nothing, because the diagram carries no estimate", () => {
+ const tree = parseFixture(scanFilterGroup);
+
+ expect(tree.estimates).toEqual({
+ cost: false,
+ startupCost: false,
+ rows: false,
+ width: false,
+ });
+ expect(tree.measured).toEqual({ time: false, rows: false });
+ });
+
+ test("names the stored table a read covers, not the statement's alias", () => {
+ const tree = parseFixture(indexJoin);
+
+ // The statement aliased both tables; CockroachDB names neither alias.
+ expect(byId(tree, "0.0.0").relation).toEqual({ table: "orders" });
+ expect(byId(tree, "0.0").relation).toEqual({ table: "customers" });
+ expect(byId(tree, "0.0.0").subject).toBe("orders@idx_customer");
+ });
+
+ test("flags a read whose spans cover everything, and leaves a range alone", () => {
+ expect(byId(parseFixture(sortLimit), "0.0.0").warnings).toEqual([
+ PLAN_FULL_TABLE_SCAN,
+ ]);
+ // `/!NULL-/10` is a bounded read of the index.
+ const bounded = byId(parseFixture(indexJoin), "0.0.0");
+ expect(propertyValue(bounded, "Spans")).toBe("/!NULL-/10");
+ expect(bounded.warnings).toEqual([]);
+ });
+
+ test("keeps a detail whose colon is part of an expression", () => {
+ const join = byId(parseFixture(indexJoin), "0.0");
+
+ // `ON @3 < 10:::INT8` carries a cast, not a label, so splitting it at the
+ // colon would cut the condition in half.
+ expect(propertyValue(join, "Detail")).toContain("ON @3 < 10:::INT8");
+ expect(propertyValue(join, "Lookup join on")).toBe("@2");
+ });
+
+ test("hangs both inputs of a processor that joins two streams", () => {
+ const tree = parse(
+ JSON.stringify({
+ processors: [
+ { core: { title: "TableReader/0", details: ["a@a_pkey"] } },
+ { core: { title: "TableReader/1", details: ["b@b_pkey"] } },
+ { core: { title: "HashJoiner/2", details: [] } },
+ ],
+ edges: [
+ { sourceProc: 0, destProc: 2, destInput: 0 },
+ { sourceProc: 1, destProc: 2, destInput: 1 },
+ ],
+ })
+ );
+
+ expect(outline(tree)).toEqual([
+ "0 HashJoiner",
+ "0.0 TableReader",
+ "0.1 TableReader",
+ ]);
+ });
+
+ test("draws what it can of a flow whose streams form a cycle", () => {
+ const tree = parse(
+ JSON.stringify({
+ processors: [
+ { core: { title: "Response/-1", details: [] } },
+ { core: { title: "Sorter/1", details: [] } },
+ ],
+ // The sorter reads itself, which a walk would follow forever.
+ edges: [
+ { sourceProc: 1, destProc: 0 },
+ { sourceProc: 1, destProc: 1 },
+ ],
+ })
+ );
+
+ expect(outline(tree)).toEqual(["0 Response", "0.0 Sorter"]);
+ });
+
+ test("reports a plan it cannot read", () => {
+ expect(parseCockroachdbPlan(" ")).toEqual({
+ ok: false,
+ message: COCKROACHDB_PLAN_EMPTY_MESSAGE,
+ });
+ expect(parseCockroachdbPlan("not json")).toEqual({
+ ok: false,
+ message: COCKROACHDB_PLAN_INVALID_JSON_MESSAGE,
+ });
+ // The text plan, which every other EXPLAIN of CockroachDB's returns.
+ expect(parseCockroachdbPlan("• group (hash)")).toEqual({
+ ok: false,
+ message: COCKROACHDB_PLAN_INVALID_JSON_MESSAGE,
+ });
+ expect(parseCockroachdbPlan('{"edges": []}')).toEqual({
+ ok: false,
+ message: COCKROACHDB_PLAN_NO_PLAN_MESSAGE,
+ });
+ });
+
+ test("gives up on a flow that expands past the operators it draws", () => {
+ // Without a budget this builds every copy before anything counts them,
+ // which for 30 stages means over two billion nodes.
+ expect(parseCockroachdbPlan(repartitionedPlan(30))).toEqual({
+ ok: false,
+ message: PLAN_TOO_MANY_NODES_MESSAGE,
+ });
+ // A flow small enough to draw still draws every path through it.
+ expect(parse(repartitionedPlan(4)).nodes).toHaveLength(31);
+ });
+
+ test("gives up past the depth it can draw", () => {
+ expect(parseCockroachdbPlan(nestedPlan(400)).ok).toBe(true);
+ expect(parseCockroachdbPlan(nestedPlan(2000))).toEqual({
+ ok: false,
+ message: PLAN_TOO_DEEP_MESSAGE,
+ });
+ });
+});
diff --git a/frontend/src/apps/explain-visualizer/cockroachdb-plan.ts b/frontend/src/apps/explain-visualizer/cockroachdb-plan.ts
new file mode 100644
index 0000000000..42020e6dcf
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/cockroachdb-plan.ts
@@ -0,0 +1,213 @@
+import {
+ addPlanProperty,
+ checkPlanDepth,
+ isJsonRecord,
+ type JsonRecord,
+ PLAN_FULL_TABLE_SCAN,
+ type PlanNode,
+ type PlanParseResult,
+ type PlanProperty,
+ type PlanRelation,
+ type PlanWarning,
+ parseWithDepthLimit,
+ planLabel,
+ planSizeBudget,
+} from "./plan-model";
+
+/**
+ * Maps the plan behind `EXPLAIN (DISTSQL)` onto the engine-neutral plan model.
+ *
+ * CockroachDB publishes no plan as a document: every option its EXPLAIN takes
+ * returns text. What DISTSQL adds is a link to a diagram of the physical flow,
+ * and the payload in that link is a plan a parser can read — processors and the
+ * streams between them. The server decodes it, so what arrives here is the
+ * document CockroachDB's own diagram page would draw.
+ *
+ * It is a graph rather than a tree: the processor nothing reads from is the
+ * root, and an edge names the processor feeding it. Nothing in it is estimated
+ * — the row counts a reader wants are in the text plan beside the link, not in
+ * the link — so these plans rank nothing.
+ */
+
+const PROCESSORS_KEY = "processors";
+const EDGES_KEY = "edges";
+
+/** A processor's title, which ends in the index it has in the list. */
+const PROCESSOR_TITLE = /^(.*?)(?:\/-?\d+)?$/;
+
+/** How a reader names a table it reads: `table@index`. */
+const TABLE_AND_INDEX = /^([^@\s]+)@([^@\s]+)$/;
+
+/**
+ * A detail CockroachDB labelled, such as `Columns: id, total`. The colon has
+ * to be followed by a space and preceded by words alone: a detail like
+ * `ON @3 < 10:::INT8` carries a cast, not a label.
+ */
+const DETAIL_LABEL = /^([A-Za-z][A-Za-z0-9 ]*): (.*)$/;
+
+/** The detail naming the keys a read covers; `-` is all of them. */
+const SPANS_DETAIL = /^Spans:\s*(.*)$/;
+const ALL_SPANS = "-";
+
+export const COCKROACHDB_PLAN_EMPTY_MESSAGE =
+ "CockroachDB returned no query plan for this statement.";
+export const COCKROACHDB_PLAN_INVALID_JSON_MESSAGE =
+ "The query plan is not valid JSON. The diagram EXPLAIN (DISTSQL) encodes is expected.";
+export const COCKROACHDB_PLAN_NO_PLAN_MESSAGE =
+ 'The query plan JSON contains no "processors" to draw.';
+
+function stringValue(value: unknown): string | undefined {
+ return typeof value === "string" && value ? value : undefined;
+}
+
+function optionalNumber(value: unknown): number | undefined {
+ return typeof value === "number" && Number.isFinite(value)
+ ? value
+ : undefined;
+}
+
+function detailsOf(raw: JsonRecord): string[] {
+ const core = isJsonRecord(raw.core) ? raw.core : {};
+ const details = Array.isArray(core.details) ? core.details : [];
+ return details
+ .map(stringValue)
+ .filter((detail): detail is string => !!detail);
+}
+
+function titleOf(raw: JsonRecord): string {
+ const core = isJsonRecord(raw.core) ? raw.core : {};
+ const title = stringValue(core.title);
+ if (!title) return "Unknown";
+ return PROCESSOR_TITLE.exec(title)?.[1] || title;
+}
+
+/**
+ * The table a processor reads.
+ *
+ * CockroachDB names the stored table even where the statement aliased it, so a
+ * node answers a lookup without the alias ambiguity the MySQL family has. It
+ * does not qualify the name, which the connected database settles.
+ */
+function toRelation(details: readonly string[]): PlanRelation | undefined {
+ const named = details.map((detail) => TABLE_AND_INDEX.exec(detail))[0];
+ return named ? { table: named[1] } : undefined;
+}
+
+function toWarnings(details: readonly string[]): PlanWarning[] {
+ // A read whose spans are unbounded covers the whole index, which is the
+ // thing a reader opens a CockroachDB plan to find. There is no row estimate
+ // here to weigh it against, so it is always worth saying.
+ const spans = details
+ .map((detail) => SPANS_DETAIL.exec(detail)?.[1]?.trim())
+ .find((value) => value !== undefined);
+ return spans === ALL_SPANS ? [PLAN_FULL_TABLE_SCAN] : [];
+}
+
+function toProperties(
+ raw: JsonRecord,
+ details: readonly string[]
+): PlanProperty[] {
+ const properties: PlanProperty[] = [];
+ for (const detail of details) {
+ const label = DETAIL_LABEL.exec(detail);
+ if (label) {
+ addPlanProperty(properties, planLabel(label[1]), label[2].trim());
+ } else {
+ addPlanProperty(properties, "Detail", detail);
+ }
+ }
+ for (const [key, value] of Object.entries(raw)) {
+ if (key === "core" || key === "inputs" || key === "outputs") continue;
+ addPlanProperty(properties, planLabel(key), String(value));
+ }
+ return properties;
+}
+
+/**
+ * @param seen - The processors on the path to this one. A flow whose streams
+ * form a cycle would never finish; the rest of it still draws.
+ * @param count - The size budget, since a processor that feeds several others
+ * is drawn under each of them.
+ */
+function toPlanNode(
+ processors: readonly JsonRecord[],
+ feeders: ReadonlyMap<number, number[]>,
+ index: number,
+ id: string,
+ seen: Set<number>,
+ depth: number,
+ count: () => void
+): PlanNode {
+ checkPlanDepth(depth);
+ count();
+ seen.add(index);
+ const raw = processors[index];
+ const children = (feeders.get(index) ?? [])
+ .filter((source) => !seen.has(source) && processors[source])
+ .map((source, position) =>
+ toPlanNode(
+ processors,
+ feeders,
+ source,
+ `${id}.${position}`,
+ seen,
+ depth + 1,
+ count
+ )
+ );
+ seen.delete(index);
+
+ const details = detailsOf(raw);
+ return {
+ id,
+ nodeType: titleOf(raw),
+ subject: details[0],
+ relation: toRelation(details),
+ properties: toProperties(raw, details),
+ warnings: toWarnings(details),
+ children,
+ };
+}
+
+export function parseCockroachdbPlan(source: string): PlanParseResult {
+ const trimmed = source.trim();
+ if (!trimmed) {
+ return { ok: false, message: COCKROACHDB_PLAN_EMPTY_MESSAGE };
+ }
+
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(trimmed);
+ } catch {
+ return { ok: false, message: COCKROACHDB_PLAN_INVALID_JSON_MESSAGE };
+ }
+
+ const raw = isJsonRecord(parsed) ? parsed[PROCESSORS_KEY] : undefined;
+ const processors = (Array.isArray(raw) ? raw : []).filter(isJsonRecord);
+ if (processors.length === 0) {
+ return { ok: false, message: COCKROACHDB_PLAN_NO_PLAN_MESSAGE };
+ }
+
+ // An edge names the processors either end of one stream, by their position
+ // in the list. The one nothing reads from is where the query's rows come
+ // out, and so the root.
+ const feeders = new Map<number, number[]>();
+ const feeds = new Set<number>();
+ const edges = isJsonRecord(parsed) ? parsed[EDGES_KEY] : undefined;
+ for (const edge of (Array.isArray(edges) ? edges : []).filter(isJsonRecord)) {
+ const source = optionalNumber(edge.sourceProc);
+ const destination = optionalNumber(edge.destProc);
+ if (source === undefined || destination === undefined) continue;
+ feeders.set(destination, [...(feeders.get(destination) ?? []), source]);
+ feeds.add(source);
+ }
+ const root = processors.findIndex((_, index) => !feeds.has(index));
+ if (root < 0) {
+ return { ok: false, message: COCKROACHDB_PLAN_NO_PLAN_MESSAGE };
+ }
+
+ const count = planSizeBudget();
+ return parseWithDepthLimit(() =>
+ toPlanNode(processors, feeders, root, "0", new Set(), 0, count)
+ );
+}
diff --git a/frontend/src/apps/explain-visualizer/mongodb-plan.test.ts b/frontend/src/apps/explain-visualizer/mongodb-plan.test.ts
new file mode 100644
index 0000000000..fb70a236fc
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/mongodb-plan.test.ts
@@ -0,0 +1,294 @@
+import { describe, expect, test } from "vitest";
+import {
+ MONGODB_PLAN_EMPTY_MESSAGE,
+ MONGODB_PLAN_INVALID_JSON_MESSAGE,
+ MONGODB_PLAN_NO_PLAN_MESSAGE,
+ parseMongodbPlan,
+} from "./mongodb-plan";
+import {
+ PLAN_FULL_TABLE_SCAN,
+ PLAN_TOO_DEEP_MESSAGE,
+ type PlanNode,
+ type PlanTree,
+} from "./plan-model";
+import aggregateGroup from "./test-data/mongodb/aggregate-group.json";
+import collectionScan from "./test-data/mongodb/collection-scan.json";
+import indexScanSort from "./test-data/mongodb/index-scan-sort.json";
+import measuredAggregateGroup from "./test-data/mongodb/measured-aggregate-group.json";
+import measuredCollectionScan from "./test-data/mongodb/measured-collection-scan.json";
+import measuredShardedIndexScan from "./test-data/mongodb/measured-sharded-index-scan.json";
+import measuredSlotBasedJoin from "./test-data/mongodb/measured-slot-based-join.json";
+import shardedAggregateGroup from "./test-data/mongodb/sharded-aggregate-group.json";
+import shardedIndexScan from "./test-data/mongodb/sharded-index-scan.json";
+import slotBasedIndexScan from "./test-data/mongodb/slot-based-index-scan.json";
+
+/** A chain of `depth` stages, which is what drives the depth limit. */
+const nestedPlan = (depth: number): string => {
+ let plan: Record<string, unknown> = { stage: "COLLSCAN" };
+ for (let level = 1; level < depth; level += 1) {
+ plan = { stage: "FETCH", inputStage: plan };
+ }
+ return JSON.stringify({ queryPlanner: { winningPlan: plan } });
+};
+
+const parse = (source: string): PlanTree => {
+ const result = parseMongodbPlan(source);
+ if (!result.ok)
+ throw new Error(`expected a parsable plan: ${result.message}`);
+ return result.tree;
+};
+
+const parseFixture = (fixture: unknown): PlanTree =>
+ parse(JSON.stringify(fixture));
+
+const outline = (tree: PlanTree): string[] =>
+ tree.nodes.map((node) => `${node.id} ${node.nodeType}`);
+
+const propertyValue = (node: PlanNode, label: string): string | undefined =>
+ node.properties.find((property) => property.label === label)?.value;
+
+const byId = (tree: PlanTree, id: string): PlanNode => {
+ const node = tree.nodes.find((candidate) => candidate.id === id);
+ if (!node) throw new Error(`no node ${id} in ${outline(tree).join(", ")}`);
+ return node;
+};
+
+describe("parseMongodbPlan", () => {
+ test("draws the winning plan and flags a read of the whole collection", () => {
+ const tree = parseFixture(collectionScan);
+
+ expect(outline(tree)).toEqual(["0 COLLSCAN"]);
+ expect(tree.root.subject).toBe('{"total":{"$gt":880}}');
+ expect(tree.root.warnings).toEqual([PLAN_FULL_TABLE_SCAN]);
+ expect(propertyValue(tree.root, "Direction")).toBe("forward");
+ });
+
+ test("keeps what a measured pipeline stage returned and spent", () => {
+ const tree = parseFixture(measuredAggregateGroup);
+ const group = byId(tree, "0.0");
+
+ expect(outline(tree)).toEqual([
+ "0 $sort",
+ "0.0 $group",
+ "0.0.0 PROJECTION_SIMPLE",
+ "0.0.0.0 COLLSCAN",
+ ]);
+ // A stage states these beside itself rather than inside its body, so
+ // reading the body alone loses both the rows and the spill diagnostics.
+ expect(group.actualRows).toBe(500);
+ expect(propertyValue(group, "Used disk")).toBe("false");
+ expect(propertyValue(group, "Spilled records")).toBe("0");
+ // The read under the pipeline keeps reporting its own.
+ expect(byId(tree, "0.0.0.0").actualRows).toBe(5000);
+ });
+
+ test("draws each shard's own plan under the merge that reads them", () => {
+ const tree = parseFixture(shardedIndexScan);
+
+ // A sharded collection is planned a shard at a time, and the merge holds
+ // each shard's plan under `shards` rather than as an input stage.
+ expect(outline(tree)).toEqual([
+ "0 SHARD_MERGE",
+ "0.0 SHARDING_FILTER",
+ "0.0.0 FETCH",
+ "0.0.0.0 IXSCAN",
+ "0.1 SHARDING_FILTER",
+ "0.1.0 FETCH",
+ "0.1.0.0 IXSCAN",
+ ]);
+ expect(propertyValue(byId(tree, "0.0"), "Shard")).toBe("sh1");
+ expect(propertyValue(byId(tree, "0.1"), "Shard")).toBe("sh2");
+ // Each shard states the namespace it read, so its scans answer a lookup.
+ expect(byId(tree, "0.0.0.0").relation).toEqual({
+ database: "qp",
+ table: "orders",
+ });
+ // The merge reads its shards, not the collection.
+ expect(tree.root.relation).toBeUndefined();
+ });
+
+ test("reads what each shard returned from a measured sharded plan", () => {
+ const tree = parseFixture(measuredShardedIndexScan);
+
+ expect(tree.root.actualRows).toBe(2785);
+ expect(byId(tree, "0.0").actualRows).toBe(1420);
+ expect(byId(tree, "0.1").actualRows).toBe(1365);
+ // A shard's execution stages state no namespace of their own, so it comes
+ // from the planner's shards, which name the one collection they all read.
+ expect(byId(tree, "0.1.0.0").relation).toEqual({
+ database: "qp",
+ table: "orders",
+ });
+ });
+
+ test("follows a slot-based join to both of the sides it reads", () => {
+ const tree = parseFixture(measuredSlotBasedJoin);
+
+ // The slot-based engine spells a join's two sides `outerStage` and
+ // `innerStage`, so following `inputStage` alone stops at the join and
+ // leaves the seek that does the reading inside a property.
+ expect(outline(tree)).toEqual([
+ "0 filter",
+ "0.0 nlj",
+ "0.0.0 ixseek",
+ "0.0.1 limit",
+ "0.0.1.0 seek",
+ ]);
+ expect(byId(tree, "0.0").actualRows).toBe(5000);
+ });
+
+ test("draws a pipeline split across shards under the stage that merges it", () => {
+ const tree = parseFixture(shardedAggregateGroup);
+
+ // A split pipeline states no `stages` of its own: the merger's part is
+ // the plan, and each shard's part runs under `$mergeCursors`.
+ expect(outline(tree).slice(0, 4)).toEqual([
+ "0 $sort",
+ "0.0 $group",
+ "0.0.0 $mergeCursors",
+ "0.0.0.0 $group",
+ ]);
+ expect(propertyValue(byId(tree, "0.0.0.0"), "Shard")).toBe("sh1");
+ expect(propertyValue(byId(tree, "0.0.0.1"), "Shard")).toBe("sh2");
+ // Each shard's own read is drawn, down to the collection it scanned.
+ expect(byId(tree, "0.0.0.0.0.0.0").relation).toEqual({
+ database: "qp",
+ table: "orders",
+ });
+ });
+
+ test("reads the tree the slot-based engine wraps", () => {
+ // MongoDB's slot-based engine reports the operator tree under
+ // `winningPlan.queryPlan`, beside the plan it compiled for itself; the
+ // classic engine puts the tree directly under `winningPlan`. Taking the
+ // wrapper for the tree draws one nameless node and hides the read.
+ const tree = parseFixture(slotBasedIndexScan);
+
+ expect(outline(tree)).toEqual(["0 FETCH", "0.0 IXSCAN"]);
+ expect(propertyValue(byId(tree, "0.0"), "Index name")).toBe("customerId_1");
+ expect(tree.root.warnings).toEqual([]);
+ });
+
+ test("ranks nothing, because MongoDB's planner publishes no estimate", () => {
+ const tree = parseFixture(indexScanSort);
+
+ expect(tree.estimates).toEqual({
+ cost: false,
+ startupCost: false,
+ rows: false,
+ width: false,
+ });
+ expect(tree.measured).toEqual({ time: false, rows: false });
+ });
+
+ test("nests a scan under what consumes it, and names the index it reads", () => {
+ const tree = parseFixture(indexScanSort);
+ const scan = byId(tree, "0.0.0");
+
+ expect(outline(tree)).toEqual(["0 SORT", "0.0 FETCH", "0.0.0 IXSCAN"]);
+ expect(scan.subject).toBe("customer_id_1");
+ expect(propertyValue(scan, "Index bounds")).toContain("[42, 42]");
+ // An index read is not a read of the whole collection.
+ expect(scan.warnings).toEqual([]);
+ });
+
+ test("answers only the stage that reaches the collection", () => {
+ const tree = parseFixture(indexScanSort);
+
+ // MongoDB states the namespace once, on the plan, so the stage that reads
+ // it carries it; a sort reads its input rather than a collection.
+ expect(byId(tree, "0.0.0").relation).toMatchObject({ table: "orders" });
+ expect(tree.root.relation).toBeUndefined();
+ expect(byId(tree, "0.0").relation).toBeUndefined();
+ });
+
+ test("reads an aggregation backwards, with its cursor's plan at the bottom", () => {
+ const tree = parseFixture(aggregateGroup);
+
+ // The pipeline runs first to last, so the stage producing the result is
+ // the root and the $cursor feeding it becomes the query plan below.
+ expect(outline(tree)).toEqual([
+ "0 $group",
+ "0.0 PROJECTION_SIMPLE",
+ "0.0.0 COLLSCAN",
+ ]);
+ expect(tree.root.subject).toContain("$sum");
+ expect(byId(tree, "0.0.0").warnings).toEqual([PLAN_FULL_TABLE_SCAN]);
+ });
+
+ test("reads a measured plan for its rows and not its timings", () => {
+ const tree = parseFixture(measuredCollectionScan);
+
+ expect(tree.measured).toEqual({ rows: true, time: false });
+ expect(tree.root.actualRows).toBe(145);
+ expect(tree.root.actualTime).toBeUndefined();
+ // MongoDB calls the per-stage time an estimate, and reports 0 on a query
+ // that finishes quickly, so it stays a property.
+ expect(
+ propertyValue(tree.root, "Execution time millis estimate")
+ ).toBeDefined();
+ expect(propertyValue(tree.root, "Docs examined")).toBe("5000");
+ });
+
+ test("leaves a small collection scan unflagged", () => {
+ const small = parse(
+ JSON.stringify({
+ executionStats: {
+ executionStages: {
+ stage: "COLLSCAN",
+ docsExamined: 12,
+ nReturned: 3,
+ },
+ },
+ })
+ );
+
+ expect(small.root.warnings).toEqual([]);
+ });
+
+ test("hangs every branch of a stage that merges several", () => {
+ const tree = parse(
+ JSON.stringify({
+ queryPlanner: {
+ winningPlan: {
+ stage: "OR",
+ inputStages: [
+ { stage: "IXSCAN", indexName: "a_1" },
+ { stage: "IXSCAN", indexName: "b_1" },
+ ],
+ },
+ },
+ })
+ );
+
+ expect(outline(tree)).toEqual(["0 OR", "0.0 IXSCAN", "0.1 IXSCAN"]);
+ });
+
+ test("reports a plan it cannot read", () => {
+ expect(parseMongodbPlan(" ")).toEqual({
+ ok: false,
+ message: MONGODB_PLAN_EMPTY_MESSAGE,
+ });
+ expect(parseMongodbPlan("not json")).toEqual({
+ ok: false,
+ message: MONGODB_PLAN_INVALID_JSON_MESSAGE,
+ });
+ // An ordinary document, which is what a query returns.
+ expect(parseMongodbPlan('{"_id": 1, "total": 100}')).toEqual({
+ ok: false,
+ message: MONGODB_PLAN_NO_PLAN_MESSAGE,
+ });
+ expect(parseMongodbPlan("[]")).toEqual({
+ ok: false,
+ message: MONGODB_PLAN_INVALID_JSON_MESSAGE,
+ });
+ });
+
+ test("gives up past the depth it can draw", () => {
+ expect(parseMongodbPlan(nestedPlan(400)).ok).toBe(true);
+ expect(parseMongodbPlan(nestedPlan(2000))).toEqual({
+ ok: false,
+ message: PLAN_TOO_DEEP_MESSAGE,
+ });
+ });
+});
diff --git a/frontend/src/apps/explain-visualizer/mongodb-plan.ts b/frontend/src/apps/explain-visualizer/mongodb-plan.ts
new file mode 100644
index 0000000000..6f976661ee
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/mongodb-plan.ts
@@ -0,0 +1,417 @@
+import {
+ addPlanProperty,
+ checkPlanDepth,
+ isJsonRecord,
+ type JsonRecord,
+ PLAN_FULL_TABLE_SCAN,
+ type PlanNode,
+ type PlanParseResult,
+ type PlanProperty,
+ type PlanRelation,
+ type PlanWarning,
+ parseWithDepthLimit,
+ planLabel,
+} from "./plan-model";
+
+/**
+ * Maps MongoDB's `explain()` output onto the engine-neutral plan model.
+ *
+ * MongoDB returns one of two shapes. A query explains to `queryPlanner`, whose
+ * `winningPlan` is a tree nested through `inputStage`; an aggregation explains
+ * to a `stages` pipeline, which runs first to last, so the list is read
+ * backwards to put the stage producing the result at the root and the `$cursor`
+ * that feeds it at the bottom — where it expands into a `queryPlanner` tree of
+ * its own.
+ *
+ * Nothing here is estimated. MongoDB's planner publishes no row or cost
+ * estimate at all, so the plan is shape and index usage, and the viewer says it
+ * ranks nothing. A measured plan — `explain("executionStats")`, which runs the
+ * query — adds the rows each stage returned. Its `executionTimeMillisEstimate`
+ * is left a property: MongoDB calls it an estimate itself, and on a query that
+ * finishes quickly every stage reports 0, so a ranking built on it would be
+ * arbitrary.
+ *
+ * `rejectedPlans` is not drawn. It holds the plans the optimizer discarded,
+ * which is a different question from what this query will do.
+ */
+
+/**
+ * Where a stage puts a child. The classic engine nests one under `inputStage`;
+ * the slot-based engine spells a join's two sides `outerStage` and
+ * `innerStage`, and a branch's two arms `thenStage` and `elseStage`.
+ */
+const CHILD_KEYS = [
+ "inputStage",
+ "outerStage",
+ "innerStage",
+ "thenStage",
+ "elseStage",
+];
+const CHILDREN_KEY = "inputStages";
+const SHARDS_KEY = "shards";
+/** The stage a split pipeline's merger reads its shards' output through. */
+const MERGE_CURSORS = "$mergeCursors";
+const STAGE_KEY = "stage";
+
+/** Keys the model promotes to typed fields, so the property list drops them. */
+const PROMOTED_KEYS = new Set([
+ STAGE_KEY,
+ ...CHILD_KEYS,
+ CHILDREN_KEY,
+ SHARDS_KEY,
+ "nReturned",
+]);
+
+/** Whether this stage reads another, by any of the names one is nested under. */
+function readsAnotherStage(raw: JsonRecord): boolean {
+ return (
+ CHILD_KEYS.some((key) => isJsonRecord(raw[key])) ||
+ Boolean(raw[CHILDREN_KEY]) ||
+ Boolean(raw[SHARDS_KEY])
+ );
+}
+
+/** The operator that reads a whole collection, having no index to use. */
+const COLLECTION_SCAN = "COLLSCAN";
+
+/**
+ * Documents a read examines before reading all of a collection is worth
+ * flagging. A scan MongoDB gave no count for is flagged anyway: a collection
+ * scan is the one thing a reader opens a MongoDB plan to find, and without a
+ * count there is nothing to rule it out with.
+ */
+const FULL_SCAN_DOCS_THRESHOLD = 1000;
+
+export const MONGODB_PLAN_EMPTY_MESSAGE =
+ "MongoDB returned no query plan for this statement.";
+export const MONGODB_PLAN_INVALID_JSON_MESSAGE =
+ "The query plan is not valid JSON. MongoDB's explain() output is expected.";
+export const MONGODB_PLAN_NO_PLAN_MESSAGE =
+ 'The query plan JSON has neither a "queryPlanner" nor a "stages" pipeline to draw.';
+
+function optionalNumber(value: unknown): number | undefined {
+ if (typeof value === "number" && Number.isFinite(value)) return value;
+ if (typeof value === "string" && value.trim()) {
+ const parsed = Number(value);
+ if (Number.isFinite(parsed)) return parsed;
+ }
+ return undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+ return typeof value === "string" && value ? value : undefined;
+}
+
+function formatValue(value: unknown): string {
+ if (value === null || value === undefined) return "";
+ if (typeof value === "string") return value;
+ if (typeof value === "number" || typeof value === "boolean") {
+ return String(value);
+ }
+ return JSON.stringify(value);
+}
+
+/**
+ * The collection a scan reads, from the namespace of the plan it belongs to.
+ *
+ * MongoDB states `database.collection` once, on the plan rather than on each
+ * stage, so the stages that read it carry it down. Only the stages that reach
+ * the collection get one: a sort or a projection reads its input, and a merge
+ * reads its shards, not a collection.
+ */
+function toRelation(
+ raw: JsonRecord,
+ namespace: string | undefined
+): PlanRelation | undefined {
+ if (!namespace || readsAnotherStage(raw)) return undefined;
+ const separator = namespace.indexOf(".");
+ if (separator <= 0 || separator === namespace.length - 1) return undefined;
+ return {
+ database: namespace.slice(0, separator),
+ table: namespace.slice(separator + 1),
+ };
+}
+
+function toWarnings(stage: string, raw: JsonRecord): PlanWarning[] {
+ if (stage !== COLLECTION_SCAN) return [];
+ const examined =
+ optionalNumber(raw.docsExamined) ?? optionalNumber(raw.nReturned);
+ return examined !== undefined && examined < FULL_SCAN_DOCS_THRESHOLD
+ ? []
+ : [PLAN_FULL_TABLE_SCAN];
+}
+
+function toProperties(raw: JsonRecord): PlanProperty[] {
+ const properties: PlanProperty[] = [];
+ for (const [key, value] of Object.entries(raw)) {
+ if (PROMOTED_KEYS.has(key)) continue;
+ addPlanProperty(properties, planLabel(key), formatValue(value));
+ }
+ return properties;
+}
+
+/**
+ * What a stage is doing, for the node's card: the index it reads, or else the
+ * condition or key that makes this stage different from the next one like it.
+ */
+function toSubject(raw: JsonRecord): string | undefined {
+ const index = stringValue(raw.indexName);
+ if (index) return index;
+ for (const key of ["filter", "sortPattern", "transformBy", "keyPattern"]) {
+ const value = raw[key];
+ if (value !== undefined && value !== null) {
+ const formatted = formatValue(value);
+ if (formatted && formatted !== "{}") return formatted;
+ }
+ }
+ return undefined;
+}
+
+/**
+ * The plan one entry of a `shards` list holds: `winningPlan` where the query
+ * was planned, `executionStages` where it ran. The planned one carries the
+ * slot-based wrapper like any other.
+ */
+function shardPlan(raw: JsonRecord): JsonRecord | undefined {
+ const planned = raw.winningPlan;
+ if (isJsonRecord(planned)) {
+ return isJsonRecord(planned.queryPlan) ? planned.queryPlan : planned;
+ }
+ return isJsonRecord(raw.executionStages) ? raw.executionStages : undefined;
+}
+
+function toPlanNode(
+ raw: JsonRecord,
+ namespace: string | undefined,
+ id: string,
+ depth: number
+): PlanNode {
+ checkPlanDepth(depth);
+ const children: PlanNode[] = [];
+ for (const key of CHILD_KEYS) {
+ const child = raw[key];
+ if (isJsonRecord(child)) {
+ children.push(
+ toPlanNode(child, namespace, `${id}.${children.length}`, depth + 1)
+ );
+ }
+ }
+ const siblings = raw[CHILDREN_KEY];
+ if (Array.isArray(siblings)) {
+ for (const each of siblings.filter(isJsonRecord)) {
+ children.push(
+ toPlanNode(each, namespace, `${id}.${children.length}`, depth + 1)
+ );
+ }
+ }
+ // A sharded collection is planned a shard at a time, and the merge stage
+ // holds each shard's own plan rather than an input stage. Each entry names
+ // the shard that ran it and the namespace it read.
+ const shards = raw[SHARDS_KEY];
+ if (Array.isArray(shards)) {
+ for (const each of shards.filter(isJsonRecord)) {
+ const plan = shardPlan(each);
+ if (!plan) continue;
+ const node = toPlanNode(
+ plan,
+ stringValue(each.namespace) ?? namespace,
+ `${id}.${children.length}`,
+ depth + 1
+ );
+ const shard = stringValue(each.shardName);
+ children.push(
+ shard
+ ? {
+ ...node,
+ properties: [
+ { label: "Shard", value: shard },
+ ...node.properties,
+ ],
+ }
+ : node
+ );
+ }
+ }
+
+ const stage = stringValue(raw[STAGE_KEY]) ?? "Unknown";
+ return {
+ id,
+ nodeType: stage,
+ subject: toSubject(raw),
+ relation: toRelation(raw, namespace),
+ actualRows: optionalNumber(raw.nReturned),
+ properties: toProperties(raw),
+ warnings: toWarnings(stage, raw),
+ children,
+ };
+}
+
+/**
+ * The namespace a sharded explain names, which it states on each shard's entry
+ * rather than on the planner, since a shard answers for its own part of the
+ * collection. They all read the one collection the statement named.
+ */
+function shardedNamespace(planner: JsonRecord): string | undefined {
+ const winning = isJsonRecord(planner.winningPlan)
+ ? planner.winningPlan
+ : undefined;
+ const shards = winning?.[SHARDS_KEY];
+ if (!Array.isArray(shards)) return undefined;
+ for (const each of shards) {
+ const namespace = isJsonRecord(each)
+ ? stringValue(each.namespace)
+ : undefined;
+ if (namespace) return namespace;
+ }
+ return undefined;
+}
+
+/** The tree a `queryPlanner` holds: the measured one where the query ran. */
+function planTreeOf(
+ explained: JsonRecord
+): { root: JsonRecord; namespace?: string } | undefined {
+ const stats = isJsonRecord(explained.executionStats)
+ ? explained.executionStats
+ : undefined;
+ const planner = isJsonRecord(explained.queryPlanner)
+ ? explained.queryPlanner
+ : undefined;
+ const namespace = planner
+ ? (stringValue(planner.namespace) ?? shardedNamespace(planner))
+ : undefined;
+ const measured =
+ stats && isJsonRecord(stats.executionStages)
+ ? stats.executionStages
+ : undefined;
+ if (measured) return { root: measured, namespace };
+ const winning =
+ planner && isJsonRecord(planner.winningPlan)
+ ? planner.winningPlan
+ : undefined;
+ if (!winning) return undefined;
+ // The slot-based engine reports the operator tree under `queryPlan`, beside
+ // the plan it compiled for its own machine. The classic engine puts the tree
+ // itself here, and which engine ran is not the reader's question.
+ const root = isJsonRecord(winning.queryPlan) ? winning.queryPlan : winning;
+ return { root, namespace };
+}
+
+/**
+ * An aggregation's stages, read backwards so the stage that produces the
+ * result is the root. The `$cursor` that feeds the pipeline is not a stage of
+ * its own: it holds the query plan for the read, which takes its place.
+ */
+/**
+ * @param shards - Each shard's own pipeline, where the pipeline was split
+ * across shards. They hang under the stage that reads them.
+ */
+function aggregateNode(
+ stages: readonly unknown[],
+ index: number,
+ id: string,
+ depth: number,
+ shards?: JsonRecord
+): PlanNode | undefined {
+ checkPlanDepth(depth);
+ if (index < 0) return undefined;
+ const stage = stages[index];
+ if (!isJsonRecord(stage)) {
+ return aggregateNode(stages, index - 1, id, depth);
+ }
+ const [name, body] = Object.entries(stage)[0] ?? [];
+ if (!name) return aggregateNode(stages, index - 1, id, depth);
+
+ if (name === "$cursor" && isJsonRecord(body)) {
+ const plan = planTreeOf(body);
+ if (plan) return toPlanNode(plan.root, plan.namespace, id, depth);
+ }
+
+ const children: PlanNode[] = [];
+ if (name === MERGE_CURSORS && shards) {
+ for (const [shard, each] of Object.entries(shards)) {
+ const ran = isJsonRecord(each) ? each.stages : undefined;
+ if (!Array.isArray(ran) || ran.length === 0) continue;
+ const node = aggregateNode(
+ ran,
+ ran.length - 1,
+ `${id}.${children.length}`,
+ depth + 1
+ );
+ if (!node) continue;
+ children.push({
+ ...node,
+ properties: [{ label: "Shard", value: shard }, ...node.properties],
+ });
+ }
+ }
+ const child =
+ children.length > 0
+ ? undefined
+ : aggregateNode(stages, index - 1, `${id}.0`, depth + 1, shards);
+ if (child) children.push(child);
+ const properties = isJsonRecord(body) ? toProperties(body) : [];
+ // What the stage returned and what it spent sit beside the stage rather
+ // than inside it: the rows, the time it estimates, and whether it had to
+ // spill to disk.
+ for (const [key, value] of Object.entries(stage)) {
+ if (key === name || PROMOTED_KEYS.has(key)) continue;
+ addPlanProperty(properties, planLabel(key), formatValue(value));
+ }
+ return {
+ id,
+ nodeType: name,
+ subject: body === undefined ? undefined : formatValue(body) || undefined,
+ actualRows: optionalNumber(stage.nReturned),
+ properties,
+ warnings: [],
+ children,
+ };
+}
+
+export function parseMongodbPlan(source: string): PlanParseResult {
+ const trimmed = source.trim();
+ if (!trimmed) {
+ return { ok: false, message: MONGODB_PLAN_EMPTY_MESSAGE };
+ }
+
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(trimmed);
+ } catch {
+ return { ok: false, message: MONGODB_PLAN_INVALID_JSON_MESSAGE };
+ }
+ if (!isJsonRecord(parsed)) {
+ return { ok: false, message: MONGODB_PLAN_INVALID_JSON_MESSAGE };
+ }
+
+ // A pipeline split across shards states each shard's part under `shards`
+ // and the merger's own under `splitPipeline`, where no single `stages` is
+ // the plan. The merger is the plan, and the shards run under the stage that
+ // reads them.
+ const split = isJsonRecord(parsed.splitPipeline)
+ ? parsed.splitPipeline
+ : undefined;
+ const shards = isJsonRecord(parsed[SHARDS_KEY])
+ ? parsed[SHARDS_KEY]
+ : undefined;
+ const merger = split?.mergerPart;
+ const stages =
+ shards && Array.isArray(merger) && merger.length > 0
+ ? merger
+ : parsed.stages;
+ if (Array.isArray(stages) && stages.length > 0) {
+ return parseWithDepthLimit(() => {
+ const root = aggregateNode(stages, stages.length - 1, "0", 0, shards);
+ if (!root) throw new Error(MONGODB_PLAN_NO_PLAN_MESSAGE);
+ return root;
+ });
+ }
+
+ const plan = planTreeOf(parsed);
+ if (!plan) {
+ return { ok: false, message: MONGODB_PLAN_NO_PLAN_MESSAGE };
+ }
+ return parseWithDepthLimit(() =>
+ toPlanNode(plan.root, plan.namespace, "0", 0)
+ );
+}
diff --git a/frontend/src/apps/explain-visualizer/mssql-plan.test.ts b/frontend/src/apps/explain-visualizer/mssql-plan.test.ts
index b34afe258e..0102ba52b4 100644
--- a/frontend/src/apps/explain-visualizer/mssql-plan.test.ts
+++ b/frontend/src/apps/explain-visualizer/mssql-plan.test.ts
@@ -415,7 +415,8 @@ describe("parseMssqlPlan", () => {
`<StmtSimple StatementType="SELECT"><QueryPlan><MissingIndexes><MissingIndexGroup Impact="50"><MissingIndex Schema="[dbo]" Table="[customer_order_history]"><ColumnGroup Usage="EQUALITY">${columns}</ColumnGroup></MissingIndex></MissingIndexGroup></MissingIndexes></QueryPlan></StmtSimple>`
)
);
- const name = /INDEX \[([^\]]+)\]/.exec(root.warnings[0].detail)?.[1] ?? "";
+ const detail = root.warnings[0].detail ?? "";
+ const name = /INDEX \[([^\]]+)\]/.exec(detail)?.[1] ?? "";
expect(name).toHaveLength(128);
expect(name.startsWith("idx_customer_order_history_")).toBe(true);
diff --git a/frontend/src/apps/explain-visualizer/mysql-plan.test.ts b/frontend/src/apps/explain-visualizer/mysql-plan.test.ts
new file mode 100644
index 0000000000..74a974bbab
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/mysql-plan.test.ts
@@ -0,0 +1,323 @@
+import { describe, expect, test } from "vitest";
+import {
+ MYSQL_PLAN_EMPTY_MESSAGE,
+ MYSQL_PLAN_INVALID_JSON_MESSAGE,
+ MYSQL_PLAN_NO_PLAN_MESSAGE,
+ parseMysqlPlan,
+} from "./mysql-plan";
+import {
+ PLAN_FULL_INDEX_SCAN,
+ PLAN_FULL_TABLE_SCAN,
+ PLAN_TOO_DEEP_MESSAGE,
+ type PlanNode,
+ type PlanTree,
+} from "./plan-model";
+import attachedSubquery from "./test-data/mysql/attached-subquery.json";
+import derivedTable from "./test-data/mysql/derived-table.json";
+import fullScanFilter from "./test-data/mysql/full-scan-filter.json";
+import groupSortJoin from "./test-data/mysql/group-sort-join.json";
+import mariadbBlockNlJoin from "./test-data/mysql/mariadb-block-nl-join.json";
+import mariadbSortTemporaryJoin from "./test-data/mysql/mariadb-sort-temporary-join.json";
+import orderingFilesort from "./test-data/mysql/ordering-filesort.json";
+import unionDistinct from "./test-data/mysql/union-distinct.json";
+
+/** A chain of `depth` nested operators, which is what drives the depth limit. */
+const nestedPlan = (depth: number): string => {
+ let plan: Record<string, unknown> = { table: { table_name: "orders" } };
+ for (let level = 1; level < depth; level += 1) {
+ plan = { materialized_from_subquery: plan };
+ }
+ return JSON.stringify({ query_block: plan });
+};
+
+const parse = (source: string): PlanTree => {
+ const result = parseMysqlPlan(source);
+ if (!result.ok)
+ throw new Error(`expected a parsable plan: ${result.message}`);
+ return result.tree;
+};
+
+const parseFixture = (fixture: unknown): PlanTree =>
+ parse(JSON.stringify(fixture));
+
+const outline = (tree: PlanTree): string[] =>
+ tree.nodes.map(
+ (node) => `${node.id} ${node.nodeType} ${node.subject ?? "-"}`
+ );
+
+const propertyValue = (node: PlanNode, label: string): string | undefined =>
+ node.properties.find((property) => property.label === label)?.value;
+
+const byId = (tree: PlanTree, id: string): PlanNode => {
+ const node = tree.nodes.find((candidate) => candidate.id === id);
+ if (!node) throw new Error(`no node ${id} in ${outline(tree).join(", ")}`);
+ return node;
+};
+
+describe("parseMysqlPlan", () => {
+ test("maps a query block over a single scan", () => {
+ const tree = parseFixture(fullScanFilter);
+ const scan = byId(tree, "0.0");
+
+ expect(outline(tree)).toEqual([
+ "0 Query block -",
+ "0.0 Full Table Scan orders",
+ ]);
+ expect(scan).toMatchObject({
+ // read_cost + eval_cost is this operator's own; prefix_cost covers the
+ // whole join prefix, so it is not.
+ totalCost: 3233.41 + 1596.34,
+ selfCost: 3233.41 + 1596.34,
+ rows: 15963,
+ relation: { table: "orders" },
+ children: [],
+ });
+ expect(scan.warnings).toEqual([PLAN_FULL_TABLE_SCAN]);
+ expect(propertyValue(scan, "Attached condition")).toBe(
+ "(`qp`.`orders`.`total` > 880)"
+ );
+ expect(propertyValue(scan, "Rows examined per scan")).toBe("47895");
+ // A list of names reads as one line.
+ expect(propertyValue(scan, "Used columns")).toBe(
+ "id, customer_id, total, status, placed_on"
+ );
+ });
+
+ test("keeps typed fields out of the property list", () => {
+ const labels = byId(parseFixture(fullScanFilter), "0.0").properties.map(
+ (property) => property.label
+ );
+
+ expect(labels).not.toContain("Table name");
+ expect(labels).not.toContain("Access type");
+ expect(labels).not.toContain("Rows produced per join");
+ });
+
+ test("names each level of the plan after the key that holds it", () => {
+ expect(outline(parseFixture(groupSortJoin))).toEqual([
+ "0 Query block -",
+ "0.0 Order -",
+ "0.0.0 Group -",
+ "0.0.0.0 Full Table Scan o",
+ "0.0.0.1 Unique Key Lookup c",
+ ]);
+ });
+
+ test("charges an operator between the block and its tables what its tables cost", () => {
+ const tree = parseFixture(groupSortJoin);
+ const tables = [byId(tree, "0.0.0.0"), byId(tree, "0.0.0.1")];
+ const tableCost = tables.reduce(
+ (sum, table) => sum + (table.totalCost ?? 0),
+ 0
+ );
+
+ // MySQL states a cost on the query block and on each table, nothing in
+ // between. Were the levels between left without one, the block above would
+ // keep the whole query's cost as its own and rank first in every plan.
+ for (const id of ["0.0", "0.0.0"]) {
+ expect(byId(tree, id).totalCost).toBeCloseTo(tableCost, 5);
+ expect(byId(tree, id).selfCost).toBe(0);
+ }
+ expect(tree.root.selfCost).toBe(0);
+ expect(tree.costBasis).toBeCloseTo(tableCost, 5);
+ expect(tables.map((table) => table.selfCost)).toEqual(
+ tables.map((table) => table.totalCost)
+ );
+ });
+
+ test("hangs each union branch off the union, with the branch's own keys on it", () => {
+ const tree = parseFixture(unionDistinct);
+ const union = byId(tree, "0.0");
+ const branch = byId(tree, "0.0.0");
+
+ expect(outline(tree)).toEqual([
+ "0 Query block -",
+ "0.0 Union <union1,2>",
+ "0.0.0 Query block -",
+ "0.0.0.0 Full Table Scan orders",
+ "0.0.1 Query block -",
+ "0.0.1.0 Full Table Scan customers",
+ ]);
+ // The object listing a branch is not a level of the plan, so what it says
+ // about the branch belongs to the branch.
+ expect(propertyValue(branch, "Cacheable")).toBe("true");
+ expect(propertyValue(branch, "Dependent")).toBe("false");
+ // A result MySQL materialized for itself is no table to look up.
+ expect(union.relation).toBeUndefined();
+ expect(union.totalCost).toBeCloseTo(4829.75 + 503.75, 5);
+ });
+
+ test("reads the table a subquery is attached to, which is still a read", () => {
+ const tree = parseFixture(attachedSubquery);
+ const scan = byId(tree, "0.0");
+
+ // The scan carries the subquery's own operators under
+ // `attached_subqueries`, which is a subquery run against the table rather
+ // than a result standing in for it — so it is still a read of `o`, and
+ // reading every row of it is still worth flagging.
+ expect(scan.nodeType).toBe("Full Table Scan");
+ expect(scan.children).toHaveLength(1);
+ expect(scan.relation).toEqual({ table: "o", unresolved: true });
+ expect(scan.rows).toBe(50184);
+ expect(scan.warnings).toEqual([PLAN_FULL_TABLE_SCAN]);
+ // What MySQL materialized for the subquery is not a table of its own.
+ expect(byId(tree, "0.0.0.0").nodeType).toBe("Materialize");
+ expect(byId(tree, "0.0.0.0").relation).toBeUndefined();
+ });
+
+ test("charges a sort what MySQL says sorting costs", () => {
+ const tree = parseFixture(orderingFilesort);
+ const order = byId(tree, "0.0");
+ const scan = byId(tree, "0.0.0");
+
+ // `sort_cost` is the sort's alone, and the block's `query_cost` is the two
+ // together. Left unread the sort looks free and the block ranks first,
+ // which is not an operator a reader can do anything about.
+ expect(order.nodeType).toBe("Order");
+ expect(order.selfCost).toBe(50184);
+ expect(order.totalCost).toBeCloseTo(50184 + 5058.65, 5);
+ expect(scan.selfCost).toBeCloseTo(5058.65, 5);
+ expect(tree.root.totalCost).toBeCloseTo(55242.65, 5);
+ });
+
+ test("charges a table its own cost, not what its subquery cost", () => {
+ const tree = parseFixture(derivedTable);
+ const derived = byId(tree, "0.0");
+ const inner = byId(tree, "0.0.0.0.0.0");
+
+ // `read_cost` and `eval_cost` are what reading and filtering that table
+ // costs, and cover nothing below it: the subquery materialized for it is
+ // costed apart, and the block's own `query_cost` leaves it out too. Taking
+ // the subquery out of the table's cost charged the outer read a tenth of
+ // what MySQL said, and ranked the inner scan above it.
+ expect(derived.selfCost).toBeCloseTo(601.19 + 4789.5, 5);
+ expect(derived.totalCost).toBeCloseTo(601.19 + 4789.5 + 4829.75, 5);
+ expect(inner.selfCost).toBeCloseTo(40.25 + 4789.5, 5);
+ // The whole plan is the two reads, so neither is more than all of it.
+ expect(tree.costBasis).toBeCloseTo(601.19 + 4789.5 + 4829.75, 5);
+ });
+
+ test("leaves a derived table unanswered and unflagged", () => {
+ const tree = parseFixture(derivedTable);
+ const derived = byId(tree, "0.0");
+ const scan = byId(tree, "0.0.0.0.0.0");
+
+ expect(outline(tree)).toEqual([
+ "0 Query block -",
+ "0.0 Full Table Scan s",
+ "0.0.0 Materialize -",
+ "0.0.0.0 Query block -",
+ "0.0.0.0.0 Group -",
+ "0.0.0.0.0.0 Full Index Scan orders",
+ ]);
+ // `s` is the statement's name for the subquery, not a table, and reading
+ // all of what MySQL materialized is not a read an index would change.
+ expect(derived.relation).toBeUndefined();
+ expect(derived.warnings).toEqual([]);
+ expect(scan.relation).toEqual({ table: "orders", unresolved: true });
+ expect(scan.warnings).toEqual([PLAN_FULL_INDEX_SCAN]);
+ });
+
+ describe("MariaDB", () => {
+ test("reads the same shape under its own keys", () => {
+ const tree = parseFixture(mariadbSortTemporaryJoin);
+ const scan = byId(tree, "0.0.0.0");
+
+ expect(outline(tree)).toEqual([
+ "0 Query block -",
+ "0.0 Sort sum(o.total) desc",
+ "0.0.0 Temporary table -",
+ "0.0.0.0 Full Table Scan o",
+ "0.0.0.1 Unique Key Lookup c",
+ ]);
+ // MariaDB states one `cost` per operator and `rows` where MySQL says
+ // `rows_examined_per_scan`.
+ expect(scan).toMatchObject({ totalCost: 8.3654308, rows: 50416 });
+ expect(scan.warnings).toEqual([PLAN_FULL_TABLE_SCAN]);
+ expect(tree.root.totalCost).toBe(53.47180584);
+ });
+
+ test("draws a block nested loop join and what it buffers", () => {
+ const tree = parseFixture(mariadbBlockNlJoin);
+ const join = byId(tree, "0.0.0.1");
+
+ expect(outline(tree)).toEqual([
+ "0 Query block -",
+ "0.0 Sort o.total desc",
+ "0.0.0 Temporary table -",
+ "0.0.0.0 Full Table Scan c",
+ "0.0.0.1 Block nested loop join o.`status` = c.country",
+ "0.0.0.1.0 Full Table Scan o",
+ ]);
+ expect(propertyValue(join, "Join type")).toBe("BNL");
+ expect(propertyValue(join, "Buffer size")).toBe("256KiB");
+ // The sort MariaDB charges to the query is the difference between the
+ // query's cost and the tables', and the query block is the only operator
+ // that reports it.
+ expect(tree.root.selfCost).toBeCloseTo(200622.7147 - 23419.168862, 5);
+ });
+ });
+
+ test("carries an operator it has never heard of rather than dropping it", () => {
+ const tree = parse(
+ JSON.stringify({
+ query_block: {
+ regrouping_operation: { kept: "yes", table: { table_name: "t" } },
+ },
+ })
+ );
+
+ expect(outline(tree)).toEqual([
+ "0 Query block -",
+ "0.0 Regrouping operation -",
+ "0.0.0 Table t",
+ ]);
+ expect(propertyValue(byId(tree, "0.0"), "Kept")).toBe("yes");
+ });
+
+ test("leaves a small read unflagged", () => {
+ const small = parse(
+ JSON.stringify({
+ query_block: {
+ table: {
+ table_name: "countries",
+ access_type: "ALL",
+ rows_examined_per_scan: 200,
+ },
+ },
+ })
+ );
+
+ expect(byId(small, "0.0").warnings).toEqual([]);
+ });
+
+ test("reports a plan it cannot read", () => {
+ expect(parseMysqlPlan(" ")).toEqual({
+ ok: false,
+ message: MYSQL_PLAN_EMPTY_MESSAGE,
+ });
+ expect(parseMysqlPlan("not json")).toEqual({
+ ok: false,
+ message: MYSQL_PLAN_INVALID_JSON_MESSAGE,
+ });
+ expect(parseMysqlPlan('{"rows": []}')).toEqual({
+ ok: false,
+ message: MYSQL_PLAN_NO_PLAN_MESSAGE,
+ });
+ // A tabular EXPLAIN, which is what an unknown format can turn out to be.
+ expect(parseMysqlPlan("id\tselect_type\ttable\n1\tSIMPLE\torders")).toEqual(
+ {
+ ok: false,
+ message: MYSQL_PLAN_INVALID_JSON_MESSAGE,
+ }
+ );
+ });
+
+ test("gives up past the depth it can draw", () => {
+ expect(parseMysqlPlan(nestedPlan(400)).ok).toBe(true);
+ expect(parseMysqlPlan(nestedPlan(2000))).toEqual({
+ ok: false,
+ message: PLAN_TOO_DEEP_MESSAGE,
+ });
+ });
+});
diff --git a/frontend/src/apps/explain-visualizer/mysql-plan.ts b/frontend/src/apps/explain-visualizer/mysql-plan.ts
new file mode 100644
index 0000000000..e149b99e20
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/mysql-plan.ts
@@ -0,0 +1,340 @@
+import {
+ addPlanProperty,
+ checkPlanDepth,
+ isJsonRecord,
+ type JsonRecord,
+ PLAN_FULL_INDEX_SCAN,
+ PLAN_FULL_TABLE_SCAN,
+ type PlanNode,
+ type PlanParseResult,
+ type PlanProperty,
+ type PlanWarning,
+ parseWithDepthLimit,
+ planLabel,
+ planSelfCost,
+ planSubtreeCost,
+} from "./plan-model";
+
+/**
+ * Maps `EXPLAIN FORMAT=JSON` output onto the engine-neutral plan model, for
+ * MySQL and for MariaDB.
+ *
+ * Neither engine emits a list of operators. The plan is a tree of named
+ * objects under `query_block`, where the name says what the level does —
+ * `grouping_operation`, `filesort`, `materialized_from_subquery`, `table` —
+ * and the leaves are the tables read. So the shape itself is the rule here:
+ * every nested object is an operator named after its key, and everything else
+ * is one of that operator's properties. The two dialects then differ only in
+ * which keys they use, which is why one parser reads both, and a key neither
+ * server emits yet still draws rather than disappearing.
+ */
+
+const QUERY_BLOCK_KEY = "query_block";
+const TABLE_KEY = "table";
+
+/**
+ * Objects that describe the operator they sit on rather than one below it.
+ * Their own entries are read as that operator's properties.
+ */
+const METADATA_OBJECTS = new Set(["cost_info", "r_engine_stats"]);
+
+/**
+ * Keys the model promotes to typed fields, dropped from the property list
+ * because the node card and the table already show them. The rest of what the
+ * engine reports about rows — `rows_examined_per_scan`, `filtered` — stays, as
+ * those are different facts and a MySQL reader knows them by these names.
+ */
+const PROMOTED_KEYS = new Set([
+ "table_name",
+ "access_type",
+ "cost",
+ "rows",
+ "rows_produced_per_join",
+]);
+
+/** Operators whose key alone does not read as a name for them. */
+const NODE_LABELS: Record<string, string> = {
+ [QUERY_BLOCK_KEY]: "Query block",
+ ordering_operation: "Order",
+ grouping_operation: "Group",
+ duplicates_removal: "Distinct",
+ union_result: "Union",
+ materialized_from_subquery: "Materialize",
+ materialized: "Materialize",
+ filesort: "Sort",
+ "block-nl-join": "Block nested loop join",
+ windowing: "Window functions",
+};
+
+/**
+ * How a table is read, in the words MySQL Workbench's own visual explain uses:
+ * a reader who has seen one plan drawn has seen these names.
+ */
+const ACCESS_TYPES: Record<string, string> = {
+ ALL: "Full Table Scan",
+ index: "Full Index Scan",
+ range: "Index Range Scan",
+ index_merge: "Index Merge",
+ ref: "Non-Unique Key Lookup",
+ eq_ref: "Unique Key Lookup",
+ ref_or_null: "Key Lookup or Null",
+ const: "Single Row (constant)",
+ system: "Single Row (system)",
+ fulltext: "Fulltext Index Search",
+ unique_subquery: "Unique Key Subquery",
+ index_subquery: "Index Subquery",
+};
+
+/** A result MySQL materialized for itself: `<derived2>`, `<union1,2>`. */
+const INTERNAL_TABLE = /^<.*>$/;
+
+/** What a `table` entry holds when it stands in for a materialized result. */
+const MATERIALIZED_KEY = "materialized_from_subquery";
+
+/**
+ * Rows a read examines before reading all of them is worth flagging.
+ *
+ * A full scan of a few hundred rows is a page or two that no index lookup
+ * would beat, and warning about it would bury the scans a reader can act on.
+ */
+const FULL_SCAN_ROWS_THRESHOLD = 1000;
+
+export const MYSQL_PLAN_EMPTY_MESSAGE =
+ "No query plan came back for this statement.";
+export const MYSQL_PLAN_INVALID_JSON_MESSAGE =
+ "The query plan is not valid JSON. EXPLAIN FORMAT=JSON output is expected.";
+export const MYSQL_PLAN_NO_PLAN_MESSAGE =
+ 'The query plan JSON does not contain a "query_block" object.';
+
+function optionalNumber(value: unknown): number | undefined {
+ if (typeof value === "number" && Number.isFinite(value)) return value;
+ if (typeof value === "string" && value.trim()) {
+ const parsed = Number(value);
+ if (Number.isFinite(parsed)) return parsed;
+ }
+ return undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+ return typeof value === "string" && value ? value : undefined;
+}
+
+function isOperatorList(value: unknown): boolean {
+ return Array.isArray(value) && value.some(isJsonRecord);
+}
+
+function formatValue(value: unknown): string {
+ if (value === null || value === undefined) return "";
+ if (typeof value === "string") return value;
+ if (typeof value === "number" || typeof value === "boolean") {
+ return String(value);
+ }
+ if (Array.isArray(value)) {
+ return value.map((entry) => formatValue(entry)).join(", ");
+ }
+ return JSON.stringify(value);
+}
+
+function toNodeType(key: string, raw: JsonRecord): string {
+ if (key !== TABLE_KEY) return NODE_LABELS[key] ?? planLabel(key);
+ const access = stringValue(raw.access_type);
+ if (!access) return "Table";
+ return ACCESS_TYPES[access] ?? planLabel(access);
+}
+
+function toSubject(raw: JsonRecord): string | undefined {
+ return (
+ stringValue(raw.table_name) ??
+ stringValue(raw.sort_key) ??
+ stringValue(raw.attached_condition) ??
+ stringValue(raw.having_condition)
+ );
+}
+
+/**
+ * The stored table this operator reads, where it reads one.
+ *
+ * A `table` entry can stand in for a result the engine materialized for
+ * itself. Those name the subquery they were built from, and are named after
+ * the derived result — `<derived2>` — or after the alias the statement gave
+ * the subquery, so they are neither a table Bytebase can describe nor a read
+ * an index would change. A real table's entry carries operators too, in
+ * `attached_subqueries`, which is a subquery run against the table rather than
+ * a result standing in for it: that is still a read of the table.
+ *
+ * What is left is the name the statement used for a real table, which is the
+ * alias where it gave one, and neither engine qualifies it. Nothing in the
+ * plan says which it is, so the name is carried as the statement's: it names
+ * the read, and no table is looked up by it.
+ */
+function baseTable(key: string, raw: JsonRecord): string | undefined {
+ if (key !== TABLE_KEY || isJsonRecord(raw[MATERIALIZED_KEY])) {
+ return undefined;
+ }
+ const table = stringValue(raw.table_name);
+ return table && !INTERNAL_TABLE.test(table) ? table : undefined;
+}
+
+function toWarnings(table: string | undefined, raw: JsonRecord): PlanWarning[] {
+ if (!table) return [];
+ const examined =
+ optionalNumber(raw.rows_examined_per_scan) ?? optionalNumber(raw.rows);
+ if (examined !== undefined && examined < FULL_SCAN_ROWS_THRESHOLD) return [];
+ switch (stringValue(raw.access_type)) {
+ case "ALL":
+ return [PLAN_FULL_TABLE_SCAN];
+ case "index":
+ return [PLAN_FULL_INDEX_SCAN];
+ default:
+ return [];
+ }
+}
+
+function toProperties(raw: JsonRecord, inherited: JsonRecord): PlanProperty[] {
+ const properties: PlanProperty[] = [];
+ const collect = (record: JsonRecord) => {
+ for (const [key, value] of Object.entries(record)) {
+ if (PROMOTED_KEYS.has(key)) continue;
+ if (isJsonRecord(value)) {
+ if (METADATA_OBJECTS.has(key)) collect(value);
+ continue;
+ }
+ if (isOperatorList(value)) continue;
+ addPlanProperty(properties, planLabel(key), formatValue(value));
+ }
+ };
+ collect(raw);
+ collect(inherited);
+ return properties;
+}
+
+/**
+ * What this operator costs on its own, covering nothing below it: reading and
+ * filtering a table, or sorting what a sort was given. MariaDB spells a
+ * table's as `cost`. `prefix_cost` is the whole join prefix, so it is not
+ * this operator's.
+ */
+function exclusiveCost(key: string, raw: JsonRecord): number | undefined {
+ const info = isJsonRecord(raw.cost_info) ? raw.cost_info : undefined;
+ const sort = info ? optionalNumber(info.sort_cost) : undefined;
+ if (sort !== undefined) return sort;
+ if (key !== TABLE_KEY) return undefined;
+ const read = info ? optionalNumber(info.read_cost) : undefined;
+ const evaluate = info ? optionalNumber(info.eval_cost) : undefined;
+ if (read !== undefined || evaluate !== undefined) {
+ return (read ?? 0) + (evaluate ?? 0);
+ }
+ return optionalNumber(raw.cost);
+}
+
+/** What this operator costs including everything under it. */
+function cumulativeCost(raw: JsonRecord): number | undefined {
+ const info = isJsonRecord(raw.cost_info) ? raw.cost_info : undefined;
+ return (
+ (info ? optionalNumber(info.query_cost) : undefined) ??
+ optionalNumber(raw.cost)
+ );
+}
+
+/**
+ * @param inherited - Keys of the object that wrapped this operator in a list,
+ * such as `dependent` on a union branch: they describe this operator, and the
+ * wrapper is not a level of the plan.
+ */
+function toPlanNode(
+ key: string,
+ raw: JsonRecord,
+ id: string,
+ depth: number,
+ inherited: JsonRecord
+): PlanNode {
+ checkPlanDepth(depth);
+ const children = toChildren(raw, id, depth);
+ const subtree = planSubtreeCost(children);
+ // A table and a sort each state what they cost and nothing below them: a
+ // subquery materialized for a table is costed apart, and the block's
+ // `query_cost` covers the lot.
+ const own = exclusiveCost(key, raw);
+ const totalCost =
+ own !== undefined ? own + (subtree ?? 0) : (cumulativeCost(raw) ?? subtree);
+ const table = baseTable(key, raw);
+ return {
+ id,
+ nodeType: toNodeType(key, raw),
+ subject: toSubject(raw),
+ relation: table ? { table, unresolved: true } : undefined,
+ totalCost,
+ selfCost: own ?? planSelfCost(totalCost, children),
+ rows:
+ optionalNumber(raw.rows_produced_per_join) ??
+ optionalNumber(raw.rows) ??
+ optionalNumber(raw.rows_examined_per_scan),
+ properties: toProperties(raw, inherited),
+ warnings: toWarnings(table, raw),
+ children,
+ };
+}
+
+function toChildren(
+ raw: JsonRecord,
+ id: string,
+ depth: number
+): readonly PlanNode[] {
+ const children: PlanNode[] = [];
+ const add = (key: string, value: JsonRecord, inherited: JsonRecord) =>
+ children.push(
+ toPlanNode(key, value, `${id}.${children.length}`, depth + 1, inherited)
+ );
+
+ for (const [key, value] of Object.entries(raw)) {
+ if (isJsonRecord(value)) {
+ if (!METADATA_OBJECTS.has(key)) add(key, value, {});
+ continue;
+ }
+ if (!Array.isArray(value)) continue;
+ // A list of operators: `nested_loop`'s joined tables, `query_specifications`'
+ // union branches. The list is not a level of the plan, its entries are.
+ for (const entry of value) {
+ if (!isJsonRecord(entry)) continue;
+ const operators = Object.entries(entry).filter(
+ ([entryKey, entryValue]) =>
+ isJsonRecord(entryValue) && !METADATA_OBJECTS.has(entryKey)
+ );
+ if (operators.length === 0) {
+ add(key, entry, {});
+ continue;
+ }
+ const named = new Set(operators.map(([operatorKey]) => operatorKey));
+ const inherited = Object.fromEntries(
+ Object.entries(entry).filter(([entryKey]) => !named.has(entryKey))
+ );
+ for (const [operatorKey, operator] of operators) {
+ add(operatorKey, operator as JsonRecord, inherited);
+ }
+ }
+ }
+ return children;
+}
+
+export function parseMysqlPlan(source: string): PlanParseResult {
+ const trimmed = source.trim();
+ if (!trimmed) {
+ return { ok: false, message: MYSQL_PLAN_EMPTY_MESSAGE };
+ }
+
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(trimmed);
+ } catch {
+ return { ok: false, message: MYSQL_PLAN_INVALID_JSON_MESSAGE };
+ }
+
+ const block = isJsonRecord(parsed) ? parsed[QUERY_BLOCK_KEY] : undefined;
+ if (!isJsonRecord(block)) {
+ return { ok: false, message: MYSQL_PLAN_NO_PLAN_MESSAGE };
+ }
+
+ return parseWithDepthLimit(() =>
+ toPlanNode(QUERY_BLOCK_KEY, block, "0", 0, {})
+ );
+}
diff --git a/frontend/src/apps/explain-visualizer/oceanbase-plan.test.ts b/frontend/src/apps/explain-visualizer/oceanbase-plan.test.ts
new file mode 100644
index 0000000000..50590776fa
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/oceanbase-plan.test.ts
@@ -0,0 +1,143 @@
+import { describe, expect, test } from "vitest";
+import {
+ OCEANBASE_PLAN_EMPTY_MESSAGE,
+ OCEANBASE_PLAN_INVALID_JSON_MESSAGE,
+ OCEANBASE_PLAN_NO_PLAN_MESSAGE,
+ parseOceanbasePlan,
+} from "./oceanbase-plan";
+import {
+ PLAN_FULL_TABLE_SCAN,
+ PLAN_TOO_DEEP_MESSAGE,
+ type PlanNode,
+ type PlanTree,
+} from "./plan-model";
+import fullScanFilter from "./test-data/oceanbase/full-scan-filter.json";
+import hashJoinGroupSort from "./test-data/oceanbase/hash-join-group-sort.json";
+import indexLookup from "./test-data/oceanbase/index-lookup.json";
+import unionDistinct from "./test-data/oceanbase/union-distinct.json";
+
+/** A chain of `depth` operators, which is what drives the depth limit. */
+const nestedPlan = (depth: number): string => {
+ let plan: Record<string, unknown> = { OPERATOR: "TABLE FULL SCAN" };
+ for (let level = 1; level < depth; level += 1) {
+ plan = { OPERATOR: "SUBPLAN SCAN", CHILD_1: plan };
+ }
+ return JSON.stringify(plan);
+};
+
+const parse = (source: string): PlanTree => {
+ const result = parseOceanbasePlan(source);
+ if (!result.ok)
+ throw new Error(`expected a parsable plan: ${result.message}`);
+ return result.tree;
+};
+
+const parseFixture = (fixture: unknown): PlanTree =>
+ parse(JSON.stringify(fixture));
+
+const outline = (tree: PlanTree): string[] =>
+ tree.nodes.map(
+ (node) => `${node.id} ${node.nodeType} ${node.subject ?? "-"}`
+ );
+
+const propertyValue = (node: PlanNode, label: string): string | undefined =>
+ node.properties.find((property) => property.label === label)?.value;
+
+const byId = (tree: PlanTree, id: string): PlanNode => {
+ const node = tree.nodes.find((candidate) => candidate.id === id);
+ if (!node) throw new Error(`no node ${id} in ${outline(tree).join(", ")}`);
+ return node;
+};
+
+describe("parseOceanbasePlan", () => {
+ test("reads the operator tree, trimming the names OceanBase pads", () => {
+ const tree = parseFixture(fullScanFilter);
+
+ expect(outline(tree)).toEqual(["0 TABLE FULL SCAN orders"]);
+ expect(tree.root.relation).toEqual({ table: "orders", unresolved: true });
+ expect(tree.root.warnings).toEqual([PLAN_FULL_TABLE_SCAN]);
+ expect(propertyValue(tree.root, "Output")).toContain("orders.total");
+ });
+
+ test("hangs children off the CHILD_n keys, in the order they are numbered", () => {
+ expect(outline(parseFixture(hashJoinGroupSort))).toEqual([
+ "0 SORT -",
+ "0.0 HASH GROUP BY -",
+ "0.0.0 HASH JOIN -",
+ "0.0.0.0 TABLE FULL SCAN c",
+ "0.0.0.1 TABLE FULL SCAN o",
+ ]);
+ expect(outline(parseFixture(unionDistinct))[0]).toBe(
+ "0 MERGE UNION DISTINCT -"
+ );
+ });
+
+ test("ranks by the time the optimizer expects, which covers each subtree", () => {
+ const tree = parseFixture(hashJoinGroupSort);
+ const join = byId(tree, "0.0.0");
+ const scans = [byId(tree, "0.0.0.0"), byId(tree, "0.0.0.1")];
+ const scanned = scans.reduce((sum, scan) => sum + (scan.totalCost ?? 0), 0);
+
+ // EST.TIME(us) covers an operator and everything below it, so the join's
+ // own share is what it adds on top of its two reads.
+ expect(join.totalCost).toBeGreaterThan(scanned);
+ expect(join.selfCost).toBe((join.totalCost ?? 0) - scanned);
+ expect(tree.estimates.cost).toBe(true);
+ expect(tree.estimates.rows).toBe(true);
+ });
+
+ test("leaves an operator that reads no object without a table", () => {
+ const tree = parseFixture(hashJoinGroupSort);
+
+ expect(byId(tree, "0.0.0").relation).toBeUndefined();
+ // The name is the one the statement used, which is the alias it gave, so
+ // it names the read and nothing is looked up by it.
+ expect(byId(tree, "0.0.0.0").relation).toEqual({
+ table: "c",
+ unresolved: true,
+ });
+ });
+
+ test("does not flag a range scan, or a small full read", () => {
+ const tree = parseFixture(indexLookup);
+ expect(tree.root.nodeType).toBe("TABLE RANGE SCAN");
+ expect(tree.root.warnings).toEqual([]);
+
+ const small = parse(
+ JSON.stringify({
+ OPERATOR: "TABLE FULL SCAN",
+ NAME: "countries",
+ "EST.ROWS": 200,
+ })
+ );
+ expect(small.root.warnings).toEqual([]);
+ });
+
+ test("reports a plan it cannot read", () => {
+ expect(parseOceanbasePlan(" ")).toEqual({
+ ok: false,
+ message: OCEANBASE_PLAN_EMPTY_MESSAGE,
+ });
+ expect(parseOceanbasePlan("not json")).toEqual({
+ ok: false,
+ message: OCEANBASE_PLAN_INVALID_JSON_MESSAGE,
+ });
+ expect(parseOceanbasePlan("{}")).toEqual({
+ ok: false,
+ message: OCEANBASE_PLAN_NO_PLAN_MESSAGE,
+ });
+ // The tabular plan every other OceanBase EXPLAIN returns.
+ expect(parseOceanbasePlan("| ID | OPERATOR | NAME |")).toEqual({
+ ok: false,
+ message: OCEANBASE_PLAN_INVALID_JSON_MESSAGE,
+ });
+ });
+
+ test("gives up past the depth it can draw", () => {
+ expect(parseOceanbasePlan(nestedPlan(400)).ok).toBe(true);
+ expect(parseOceanbasePlan(nestedPlan(2000))).toEqual({
+ ok: false,
+ message: PLAN_TOO_DEEP_MESSAGE,
+ });
+ });
+});
diff --git a/frontend/src/apps/explain-visualizer/oceanbase-plan.ts b/frontend/src/apps/explain-visualizer/oceanbase-plan.ts
new file mode 100644
index 0000000000..87d799d240
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/oceanbase-plan.ts
@@ -0,0 +1,157 @@
+import {
+ addPlanProperty,
+ checkPlanDepth,
+ isJsonRecord,
+ type JsonRecord,
+ PLAN_FULL_INDEX_SCAN,
+ PLAN_FULL_TABLE_SCAN,
+ type PlanNode,
+ type PlanParseResult,
+ type PlanProperty,
+ type PlanRelation,
+ type PlanWarning,
+ parseWithDepthLimit,
+ planLabel,
+ planSelfCost,
+} from "./plan-model";
+
+/**
+ * Maps OceanBase's `EXPLAIN FORMAT=JSON` output onto the engine-neutral plan
+ * model.
+ *
+ * OceanBase returns the operator tree directly, each operator naming its
+ * children under `CHILD_1`, `CHILD_2` and so on rather than listing them. Its
+ * estimate is a time, `EST.TIME(us)`, and it covers an operator and everything
+ * below it, so it reads as the plan's cost: the model's self cost is the
+ * difference, and what the viewer ranks is microseconds the optimizer expects
+ * rather than units of its own.
+ */
+
+const OPERATOR_KEY = "OPERATOR";
+const CHILD_KEY = /^CHILD_(\d+)$/;
+const COST_KEY = "EST.TIME(us)";
+const ROWS_KEY = "EST.ROWS";
+const NAME_KEY = "NAME";
+
+/** Keys the model promotes to typed fields, so the property list drops them. */
+const PROMOTED_KEYS = new Set([OPERATOR_KEY, NAME_KEY, COST_KEY, ROWS_KEY]);
+
+/**
+ * Rows a read is estimated to return before reading all of a table or index is
+ * worth flagging, as in the other parsers.
+ */
+const FULL_SCAN_ROWS_THRESHOLD = 1000;
+
+export const OCEANBASE_PLAN_EMPTY_MESSAGE =
+ "OceanBase returned no query plan for this statement.";
+export const OCEANBASE_PLAN_INVALID_JSON_MESSAGE =
+ "The query plan is not valid JSON. OceanBase's EXPLAIN FORMAT=JSON output is expected.";
+export const OCEANBASE_PLAN_NO_PLAN_MESSAGE =
+ "The query plan JSON names no operator, so there is nothing to draw.";
+
+function optionalNumber(value: unknown): number | undefined {
+ if (typeof value === "number" && Number.isFinite(value)) return value;
+ if (typeof value === "string" && value.trim()) {
+ const parsed = Number(value);
+ if (Number.isFinite(parsed)) return parsed;
+ }
+ return undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+ // OceanBase pads an operator name to a fixed width.
+ const text = typeof value === "string" ? value.trim() : "";
+ return text || undefined;
+}
+
+function formatValue(value: unknown): string {
+ if (value === null || value === undefined) return "";
+ if (typeof value === "string") return value.trim();
+ if (typeof value === "number" || typeof value === "boolean") {
+ return String(value);
+ }
+ return JSON.stringify(value);
+}
+
+/** The children of an operator, in the order OceanBase numbered them. */
+function childrenOf(raw: JsonRecord): JsonRecord[] {
+ return Object.entries(raw)
+ .map(([key, value]) => [CHILD_KEY.exec(key), value] as const)
+ .filter(
+ (entry): entry is readonly [RegExpExecArray, JsonRecord] =>
+ entry[0] !== null && isJsonRecord(entry[1])
+ )
+ .sort(([a], [b]) => Number(a[1]) - Number(b[1]))
+ .map(([, child]) => child);
+}
+
+/**
+ * The table this operator reads.
+ *
+ * `NAME` is the name the statement used, which is the alias where it gave one,
+ * and OceanBase does not qualify it, so the name is carried as the statement's
+ * and no table is looked up by it — as for MySQL. An operator that reads no
+ * object leaves it empty.
+ */
+function toRelation(raw: JsonRecord): PlanRelation | undefined {
+ const table = stringValue(raw[NAME_KEY]);
+ return table ? { table, unresolved: true } : undefined;
+}
+
+function toWarnings(operator: string, raw: JsonRecord): PlanWarning[] {
+ const rows = optionalNumber(raw[ROWS_KEY]);
+ if (rows !== undefined && rows < FULL_SCAN_ROWS_THRESHOLD) return [];
+ if (operator.startsWith("TABLE FULL SCAN")) return [PLAN_FULL_TABLE_SCAN];
+ if (operator.startsWith("INDEX FULL SCAN")) return [PLAN_FULL_INDEX_SCAN];
+ return [];
+}
+
+function toProperties(raw: JsonRecord): PlanProperty[] {
+ const properties: PlanProperty[] = [];
+ for (const [key, value] of Object.entries(raw)) {
+ if (PROMOTED_KEYS.has(key) || CHILD_KEY.test(key)) continue;
+ addPlanProperty(properties, planLabel(key), formatValue(value));
+ }
+ return properties;
+}
+
+function toPlanNode(raw: JsonRecord, id: string, depth: number): PlanNode {
+ checkPlanDepth(depth);
+ const children = childrenOf(raw).map((child, index) =>
+ toPlanNode(child, `${id}.${index}`, depth + 1)
+ );
+ const operator = stringValue(raw[OPERATOR_KEY]) ?? "Unknown";
+ const totalCost = optionalNumber(raw[COST_KEY]);
+ return {
+ id,
+ nodeType: operator,
+ subject: stringValue(raw[NAME_KEY]),
+ relation: toRelation(raw),
+ totalCost,
+ selfCost: planSelfCost(totalCost, children),
+ rows: optionalNumber(raw[ROWS_KEY]),
+ properties: toProperties(raw),
+ warnings: toWarnings(operator, raw),
+ children,
+ };
+}
+
+export function parseOceanbasePlan(source: string): PlanParseResult {
+ const trimmed = source.trim();
+ if (!trimmed) {
+ return { ok: false, message: OCEANBASE_PLAN_EMPTY_MESSAGE };
+ }
+
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(trimmed);
+ } catch {
+ return { ok: false, message: OCEANBASE_PLAN_INVALID_JSON_MESSAGE };
+ }
+
+ if (!isJsonRecord(parsed) || !stringValue(parsed[OPERATOR_KEY])) {
+ return { ok: false, message: OCEANBASE_PLAN_NO_PLAN_MESSAGE };
+ }
+
+ return parseWithDepthLimit(() => toPlanNode(parsed as JsonRecord, "0", 0));
+}
diff --git a/frontend/src/apps/explain-visualizer/oracle-plan.test.ts b/frontend/src/apps/explain-visualizer/oracle-plan.test.ts
new file mode 100644
index 0000000000..022995df8a
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/oracle-plan.test.ts
@@ -0,0 +1,189 @@
+import { describe, expect, test } from "vitest";
+import {
+ ORACLE_PLAN_EMPTY_MESSAGE,
+ ORACLE_PLAN_INVALID_JSON_MESSAGE,
+ ORACLE_PLAN_NO_PLAN_MESSAGE,
+ parseOraclePlan,
+} from "./oracle-plan";
+import {
+ PLAN_FULL_TABLE_SCAN,
+ PLAN_TOO_DEEP_MESSAGE,
+ type PlanNode,
+ type PlanTree,
+} from "./plan-model";
+import fullScanFilter from "./test-data/oracle/full-scan-filter.json";
+import hashJoinGroupSort from "./test-data/oracle/hash-join-group-sort.json";
+import indexRangeScan from "./test-data/oracle/index-range-scan.json";
+import unionDistinct from "./test-data/oracle/union-distinct.json";
+
+/** A chain of `depth` steps, which is what drives the depth limit. */
+const nestedPlan = (depth: number): string => {
+ const steps = [{ id: "0", operation: "SELECT STATEMENT" }];
+ for (let level = 1; level < depth; level += 1) {
+ steps.push({
+ id: String(level),
+ parent_id: String(level - 1),
+ operation: "NESTED LOOPS",
+ position: "1",
+ } as never);
+ }
+ return JSON.stringify(steps);
+};
+
+const parse = (source: string): PlanTree => {
+ const result = parseOraclePlan(source);
+ if (!result.ok)
+ throw new Error(`expected a parsable plan: ${result.message}`);
+ return result.tree;
+};
+
+const parseFixture = (fixture: unknown): PlanTree =>
+ parse(JSON.stringify(fixture));
+
+const outline = (tree: PlanTree): string[] =>
+ tree.nodes.map(
+ (node) => `${node.id} ${node.nodeType} ${node.subject ?? "-"}`
+ );
+
+const propertyValue = (node: PlanNode, label: string): string | undefined =>
+ node.properties.find((property) => property.label === label)?.value;
+
+const byId = (tree: PlanTree, id: string): PlanNode => {
+ const node = tree.nodes.find((candidate) => candidate.id === id);
+ if (!node) throw new Error(`no node ${id} in ${outline(tree).join(", ")}`);
+ return node;
+};
+
+describe("parseOraclePlan", () => {
+ test("rebuilds the tree from the parent links in the plan table", () => {
+ const tree = parseFixture(fullScanFilter);
+ const scan = byId(tree, "0.0");
+
+ expect(outline(tree)).toEqual([
+ "0 SELECT STATEMENT -",
+ "0.0 TABLE ACCESS FULL ORDERS",
+ ]);
+ // Oracle's COST covers an operator and everything below it, so the scan
+ // owns all of what the statement costs.
+ expect(tree.root.totalCost).toBe(48);
+ expect(tree.root.selfCost).toBe(0);
+ expect(scan).toMatchObject({ totalCost: 48, selfCost: 48, rows: 1613 });
+ expect(scan.warnings).toEqual([PLAN_FULL_TABLE_SCAN]);
+ expect(propertyValue(scan, "Filter predicates")).toBe('"TOTAL">880');
+ });
+
+ test("names an operator the way DBMS_XPLAN prints it", () => {
+ expect(outline(parseFixture(indexRangeScan))).toEqual([
+ "0 SELECT STATEMENT -",
+ "0.0 TABLE ACCESS BY INDEX ROWID BATCHED ORDERS",
+ "0.0.0 INDEX RANGE SCAN ORDERS_CUSTOMER_ID_IDX",
+ ]);
+ expect(outline(parseFixture(unionDistinct)).slice(0, 3)).toEqual([
+ "0 SELECT STATEMENT -",
+ "0.0 HASH UNIQUE -",
+ "0.0.0 UNION-ALL -",
+ ]);
+ });
+
+ test("answers a table with the schema Oracle named, and leaves an index alone", () => {
+ const tree = parseFixture(indexRangeScan);
+
+ // Oracle writes the owner on every object it reads, so the lookup is not
+ // left guessing which schema's ORDERS this is.
+ expect(byId(tree, "0.0").relation).toEqual({
+ table: "ORDERS",
+ schema: "SYSTEM",
+ });
+ // An index is not a table, and the table it belongs to is the step above.
+ expect(byId(tree, "0.0.0").relation).toBeUndefined();
+ expect(propertyValue(byId(tree, "0.0.0"), "Access predicates")).toBe(
+ '"CUSTOMER_ID"=42'
+ );
+ });
+
+ test("carries a step's cost down to the operator that spends it", () => {
+ const tree = parseFixture(hashJoinGroupSort);
+
+ // Oracle leaves COST off a step that adds none. Were those left without
+ // one, the operator above would keep the subtree's cost as its own.
+ const collector = tree.nodes.find(
+ (node) => node.nodeType === "STATISTICS COLLECTOR"
+ );
+ expect(collector?.totalCost).toBe(7);
+ expect(collector?.selfCost).toBe(0);
+ const customers = tree.nodes.find(
+ (node) => node.relation?.table === "CUSTOMERS"
+ );
+ expect(customers?.selfCost).toBe(7);
+ });
+
+ test("orders an operator's children the way Oracle runs them", () => {
+ const tree = parseFixture(hashJoinGroupSort);
+ const join = tree.nodes.find((node) => node.nodeType === "HASH JOIN");
+
+ // POSITION orders siblings; the build side is 1 and the probe side 2.
+ expect(join?.children.map((child) => child.nodeType)).toEqual([
+ "NESTED LOOPS",
+ "TABLE ACCESS FULL",
+ ]);
+ });
+
+ test("leaves a small read unflagged", () => {
+ const small = parse(
+ JSON.stringify([
+ { id: "0", operation: "SELECT STATEMENT" },
+ {
+ id: "1",
+ parent_id: "0",
+ operation: "TABLE ACCESS",
+ options: "FULL",
+ object_name: "COUNTRIES",
+ object_type: "TABLE",
+ cardinality: "200",
+ },
+ ])
+ );
+
+ expect(byId(small, "0.0").warnings).toEqual([]);
+ });
+
+ test("draws what it can of a plan whose parent links form a cycle", () => {
+ // A step that is its own parent is its own child, which a walk would
+ // follow forever. The rest of the plan is still worth drawing.
+ const tree = parse(
+ JSON.stringify([
+ { id: "0", parent_id: "0", operation: "SELECT STATEMENT" },
+ { id: "1", parent_id: "0", operation: "HASH JOIN" },
+ ])
+ );
+
+ expect(outline(tree)).toEqual(["0 SELECT STATEMENT -", "0.0 HASH JOIN -"]);
+ });
+
+ test("reports a plan it cannot read", () => {
+ expect(parseOraclePlan(" ")).toEqual({
+ ok: false,
+ message: ORACLE_PLAN_EMPTY_MESSAGE,
+ });
+ expect(parseOraclePlan("not json")).toEqual({
+ ok: false,
+ message: ORACLE_PLAN_INVALID_JSON_MESSAGE,
+ });
+ expect(parseOraclePlan("[]")).toEqual({
+ ok: false,
+ message: ORACLE_PLAN_EMPTY_MESSAGE,
+ });
+ // Every step claiming a parent leaves no operator to start from.
+ expect(
+ parseOraclePlan('[{"id":"1","parent_id":"2"},{"id":"2","parent_id":"1"}]')
+ ).toEqual({ ok: false, message: ORACLE_PLAN_NO_PLAN_MESSAGE });
+ });
+
+ test("gives up past the depth it can draw", () => {
+ expect(parseOraclePlan(nestedPlan(400)).ok).toBe(true);
+ expect(parseOraclePlan(nestedPlan(2000))).toEqual({
+ ok: false,
+ message: PLAN_TOO_DEEP_MESSAGE,
+ });
+ });
+});
diff --git a/frontend/src/apps/explain-visualizer/oracle-plan.ts b/frontend/src/apps/explain-visualizer/oracle-plan.ts
new file mode 100644
index 0000000000..2b32f70c56
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/oracle-plan.ts
@@ -0,0 +1,233 @@
+import {
+ addPlanProperty,
+ checkPlanDepth,
+ isJsonRecord,
+ type JsonRecord,
+ PLAN_FULL_INDEX_SCAN,
+ PLAN_FULL_TABLE_SCAN,
+ type PlanNode,
+ type PlanParseResult,
+ type PlanProperty,
+ type PlanRelation,
+ type PlanWarning,
+ parseWithDepthLimit,
+ planLabel,
+ planSelfCost,
+ planSubtreeCost,
+} from "./plan-model";
+
+/**
+ * Maps Oracle's plan table onto the engine-neutral plan model.
+ *
+ * Oracle states a plan as rows rather than as a document: one row per operator
+ * in `PLAN_TABLE`, each naming its parent and its position among its parent's
+ * children. No EXPLAIN option renders that as a tree, so the driver sends the
+ * rows as a JSON array — lower-cased column names, columns the optimizer said
+ * nothing about left out — and the tree is rebuilt here.
+ *
+ * `COST` covers an operator and everything below it, as PostgreSQL's does, so
+ * the model's self cost is the difference and the ranking is of operators
+ * rather than of the statement.
+ */
+
+const ROOT_ID = "0";
+
+/** Keys the model promotes to typed fields, so the property list drops them. */
+const PROMOTED_KEYS = new Set([
+ "id",
+ "parent_id",
+ "position",
+ "operation",
+ "options",
+ "object_name",
+ "cost",
+ "cardinality",
+]);
+
+/** `OBJECT_TYPE` values that name a table a lookup can be keyed on. */
+const TABLE_OBJECT_TYPES = new Set(["TABLE", "TABLE (TEMP)", "MAT_VIEW"]);
+
+/**
+ * Rows a read is estimated to return before reading all of a table or index is
+ * worth flagging, as in the other parsers: a full scan of a few hundred rows is
+ * not one a reader can improve on.
+ */
+const FULL_SCAN_ROWS_THRESHOLD = 1000;
+
+export const ORACLE_PLAN_EMPTY_MESSAGE =
+ "Oracle returned no query plan for this statement.";
+export const ORACLE_PLAN_INVALID_JSON_MESSAGE =
+ "The query plan is not valid JSON. Oracle's plan table is expected, as the server renders it.";
+export const ORACLE_PLAN_NO_PLAN_MESSAGE =
+ "The query plan has no step without a parent, so it has no operator to start from.";
+
+function optionalNumber(value: unknown): number | undefined {
+ if (typeof value === "number" && Number.isFinite(value)) return value;
+ if (typeof value === "string" && value.trim()) {
+ const parsed = Number(value);
+ if (Number.isFinite(parsed)) return parsed;
+ }
+ return undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+ if (typeof value === "string" && value.trim()) return value;
+ if (typeof value === "number") return String(value);
+ return undefined;
+}
+
+/**
+ * The operator's name as `DBMS_XPLAN` prints it: the operation and the option
+ * that qualifies it, such as "TABLE ACCESS FULL" or "INDEX RANGE SCAN".
+ */
+function toNodeType(step: JsonRecord): string {
+ const operation = stringValue(step.operation);
+ if (!operation) return "Unknown";
+ const options = stringValue(step.options);
+ return options ? `${operation} ${options}` : operation;
+}
+
+/**
+ * The table this operator reads.
+ *
+ * Oracle names the owning schema on every object it reads, so a lookup is
+ * answered with the schema the plan states rather than with whichever synced
+ * table happens to share the name. An index is left out: its name is not a
+ * table, and the table it belongs to is the step above it.
+ */
+function toRelation(step: JsonRecord): PlanRelation | undefined {
+ const table = stringValue(step.object_name);
+ const type = stringValue(step.object_type);
+ if (!table || !type || !TABLE_OBJECT_TYPES.has(type.toUpperCase())) {
+ return undefined;
+ }
+ return { table, schema: stringValue(step.object_owner) };
+}
+
+function toWarnings(step: JsonRecord): PlanWarning[] {
+ const rows = optionalNumber(step.cardinality);
+ if (rows !== undefined && rows < FULL_SCAN_ROWS_THRESHOLD) return [];
+ const operation = stringValue(step.operation)?.toUpperCase();
+ const options = stringValue(step.options)?.toUpperCase();
+ if (operation === "TABLE ACCESS" && options === "FULL") {
+ return [PLAN_FULL_TABLE_SCAN];
+ }
+ if (operation === "INDEX" && options?.startsWith("FULL SCAN")) {
+ return [PLAN_FULL_INDEX_SCAN];
+ }
+ return [];
+}
+
+function toProperties(step: JsonRecord): PlanProperty[] {
+ const properties: PlanProperty[] = [];
+ for (const [key, value] of Object.entries(step)) {
+ if (PROMOTED_KEYS.has(key)) continue;
+ const text = stringValue(value);
+ if (text) addPlanProperty(properties, planLabel(key), text);
+ }
+ return properties;
+}
+
+/**
+ * The children of one step, in the order Oracle runs them.
+ *
+ * `POSITION` orders an operator's children; on the root it holds the
+ * statement's total cost instead, which is why the root's own children are
+ * ordered by id.
+ */
+function childrenOf(
+ byParent: Map<string, JsonRecord[]>,
+ id: string
+): JsonRecord[] {
+ const children = byParent.get(id) ?? [];
+ return [...children].sort((a, b) => {
+ const order =
+ (optionalNumber(a.position) ?? 0) - (optionalNumber(b.position) ?? 0);
+ return order !== 0
+ ? order
+ : (optionalNumber(a.id) ?? 0) - (optionalNumber(b.id) ?? 0);
+ });
+}
+
+/**
+ * @param seen - The ids on the path from the root. A plan table whose parent
+ * links form a cycle would otherwise never finish; the rest of it still draws.
+ */
+function toPlanNode(
+ step: JsonRecord,
+ byParent: Map<string, JsonRecord[]>,
+ id: string,
+ seen: Set<string>,
+ depth: number
+): PlanNode {
+ checkPlanDepth(depth);
+ const stepID = stringValue(step.id) ?? "";
+ seen.add(stepID);
+ const children = childrenOf(byParent, stepID)
+ .filter((child) => !seen.has(stringValue(child.id) ?? ""))
+ .map((child, index) =>
+ toPlanNode(child, byParent, `${id}.${index}`, seen, depth + 1)
+ );
+ seen.delete(stepID);
+
+ // Oracle leaves COST off a step that adds none, and off both halves of an
+ // adaptive plan's unchosen path.
+ const totalCost = optionalNumber(step.cost) ?? planSubtreeCost(children);
+ return {
+ id,
+ nodeType: toNodeType(step),
+ subject:
+ stringValue(step.object_name) ??
+ stringValue(step.access_predicates) ??
+ stringValue(step.filter_predicates),
+ relation: toRelation(step),
+ totalCost,
+ selfCost: planSelfCost(totalCost, children),
+ rows: optionalNumber(step.cardinality),
+ properties: toProperties(step),
+ warnings: toWarnings(step),
+ children,
+ };
+}
+
+export function parseOraclePlan(source: string): PlanParseResult {
+ const trimmed = source.trim();
+ if (!trimmed) {
+ return { ok: false, message: ORACLE_PLAN_EMPTY_MESSAGE };
+ }
+
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(trimmed);
+ } catch {
+ return { ok: false, message: ORACLE_PLAN_INVALID_JSON_MESSAGE };
+ }
+
+ const steps = (Array.isArray(parsed) ? parsed : []).filter(isJsonRecord);
+ const byParent = new Map<string, JsonRecord[]>();
+ for (const step of steps) {
+ const parent = stringValue(step.parent_id);
+ if (parent === undefined) continue;
+ const siblings = byParent.get(parent);
+ if (siblings) siblings.push(step);
+ else byParent.set(parent, [step]);
+ }
+
+ // The statement itself is the step no other step is the parent of, which
+ // Oracle numbers 0. A plan whose root is missing is one we cannot walk.
+ const root =
+ steps.find((step) => stringValue(step.parent_id) === undefined) ??
+ steps.find((step) => stringValue(step.id) === ROOT_ID);
+ if (!root) {
+ return {
+ ok: false,
+ message: steps.length
+ ? ORACLE_PLAN_NO_PLAN_MESSAGE
+ : ORACLE_PLAN_EMPTY_MESSAGE,
+ };
+ }
+
+ return parseWithDepthLimit(() =>
+ toPlanNode(root, byParent, "0", new Set(), 0)
+ );
+}
diff --git a/frontend/src/apps/explain-visualizer/plan-i18n.tsx b/frontend/src/apps/explain-visualizer/plan-i18n.tsx
index 95bc2277be..adb2555263 100644
--- a/frontend/src/apps/explain-visualizer/plan-i18n.tsx
+++ b/frontend/src/apps/explain-visualizer/plan-i18n.tsx
@@ -1,4 +1,5 @@
import { createContext, type ReactNode, useContext } from "react";
+import type { PlanWarning } from "./plan-model";
const ENGLISH = {
"copy.copied": "Copied",
@@ -23,12 +24,48 @@ const ENGLISH = {
"The query plan is not valid XML. SHOWPLAN_XML output is expected.",
"error.mssql-no-plan":
"The query plan XML is not a SQL Server showplan with at least one statement.",
+ "error.clickhouse-empty":
+ "ClickHouse returned no query plan for this statement.",
+ "error.clickhouse-invalid":
+ "The query plan is not valid JSON. EXPLAIN json = 1 output is expected.",
+ "error.clickhouse-no-plan":
+ 'The ClickHouse query plan JSON does not contain a "Plan" object.',
+ "error.cockroachdb-empty":
+ "CockroachDB returned no query plan for this statement.",
+ "error.cockroachdb-invalid":
+ "The query plan is not valid JSON. The diagram EXPLAIN (DISTSQL) encodes is expected.",
+ "error.cockroachdb-no-plan":
+ 'The query plan JSON contains no "processors" to draw.',
+ "error.mongodb-empty": "MongoDB returned no query plan for this statement.",
+ "error.mongodb-invalid":
+ "The query plan is not valid JSON. MongoDB's explain() output is expected.",
+ "error.mongodb-no-plan":
+ 'The query plan JSON has neither a "queryPlanner" nor a "stages" pipeline to draw.',
+ "error.mysql-empty": "No query plan came back for this statement.",
+ "error.mysql-invalid":
+ "The query plan is not valid JSON. EXPLAIN FORMAT=JSON output is expected.",
+ "error.mysql-no-plan":
+ 'The query plan JSON does not contain a "query_block" object.',
+ "error.oceanbase-empty":
+ "OceanBase returned no query plan for this statement.",
+ "error.oceanbase-invalid":
+ "The query plan is not valid JSON. OceanBase's EXPLAIN FORMAT=JSON output is expected.",
+ "error.oceanbase-no-plan":
+ "The query plan JSON names no operator, so there is nothing to draw.",
+ "error.oracle-empty": "Oracle returned no query plan for this statement.",
+ "error.oracle-invalid":
+ "The query plan is not valid JSON. Oracle's plan table is expected, as the server renders it.",
+ "error.oracle-no-plan":
+ "The query plan has no step without a parent, so it has no operator to start from.",
"error.postgres-empty":
"PostgreSQL returned no query plan for this statement.",
"error.postgres-invalid":
"The query plan is not valid JSON. EXPLAIN (FORMAT JSON) output is expected.",
"error.postgres-no-plan":
'The query plan JSON does not contain a "Plan" object.',
+ "error.redshift-empty": "Redshift returned no query plan for this statement.",
+ "error.redshift-no-plan":
+ "The query plan has no operator in it: a Redshift plan states a cost for every one.",
"error.spanner-emulator":
"Spanner returned no query plan for this statement. The Spanner emulator returns none for any statement, so explain it on a Spanner instance to see one.",
"error.spanner-empty": "Spanner returned no query plan for this statement.",
@@ -36,6 +73,19 @@ const ENGLISH = {
"The query plan is not valid JSON. A Spanner query plan is expected.",
"error.spanner-no-plan":
'The query plan JSON does not contain a "planNodes" list with an operator at its root.',
+ "error.starrocks-empty": "The statement produced no query plan to draw.",
+ "error.starrocks-no-plan":
+ "The query plan has no numbered operator in any of its fragments.",
+ "error.tidb-empty": "TiDB returned no query plan for this statement.",
+ "error.tidb-invalid":
+ "The query plan is not valid JSON. EXPLAIN FORMAT=tidb_json output is expected.",
+ "error.tidb-no-plan":
+ "The query plan JSON does not contain an operator at its root.",
+ "error.trino-empty": "Trino returned no query plan for this statement.",
+ "error.trino-invalid":
+ "The query plan is not valid JSON. Trino's EXPLAIN (FORMAT JSON) output is expected.",
+ "error.trino-no-plan":
+ "The query plan JSON contains no plan fragment to start from.",
"error.too-deep":
"The query plan is nested too deeply for this visualizer to draw.",
"error.too-many-nodes":
@@ -110,6 +160,15 @@ const ENGLISH = {
"totals.estimated-cost": "estimated cost {{cost}}",
"totals.measured-time": "measured time {{time}} ms",
"totals.nodes": "{{count}} nodes",
+ "warning.data-redistribution.detail":
+ "This join moves rows between slices before it can match them. Distributing both tables on their join column, or making the smaller one ALL, lets the join run where the rows already are.",
+ "warning.data-redistribution.title": "Data redistribution",
+ "warning.full-index-scan.detail":
+ "Reads every entry of this index. If the query needs only a few of them, a condition on the index's leading columns could avoid the full read.",
+ "warning.full-index-scan.title": "Full index scan",
+ "warning.full-table-scan.detail":
+ "Reads every row of this table. If the query needs only a few of them, an index on the filtered columns could avoid the full read.",
+ "warning.full-table-scan.title": "Full table scan",
} as const;
export type QueryPlanTranslationKey = keyof typeof ENGLISH;
@@ -148,3 +207,21 @@ export function QueryPlanI18nProvider({
export function useQueryPlanTranslation(): QueryPlanTranslate {
return useContext(QueryPlanI18nContext) ?? fallbackTranslate;
}
+
+/**
+ * The words a warning is shown in. This viewer's own advice is read in the
+ * reader's language; a warning the engine reported keeps the engine's words,
+ * as the plan's own operator names and values do.
+ */
+export function planWarningText(
+ warning: PlanWarning,
+ translate: QueryPlanTranslate
+): { title: string; detail: string } {
+ if (!warning.key) {
+ return { title: warning.title ?? "", detail: warning.detail ?? "" };
+ }
+ return {
+ title: translate(`warning.${warning.key}.title`),
+ detail: translate(`warning.${warning.key}.detail`),
+ };
+}
diff --git a/frontend/src/apps/explain-visualizer/plan-model.test.ts b/frontend/src/apps/explain-visualizer/plan-model.test.ts
index 6f5306c64e..7868361deb 100644
--- a/frontend/src/apps/explain-visualizer/plan-model.test.ts
+++ b/frontend/src/apps/explain-visualizer/plan-model.test.ts
@@ -34,7 +34,9 @@ import {
planSelfCostShare,
planSelfShare,
planSelfTime,
+ planSizeBudget,
planWarningGroups,
+ planWarningIdentity,
} from "./plan-model";
import { parsePostgresPlan } from "./postgres-plan";
import cteNestedLoopInitplan from "./test-data/postgres/cte-nested-loop-initplan.json";
@@ -160,6 +162,18 @@ describe("parseWithDepthLimit", () => {
expect(result).toEqual({ ok: false, message: PLAN_TOO_MANY_NODES_MESSAGE });
});
+ test("stops a parser expanding a graph as soon as it passes the cap", () => {
+ const count = planSizeBudget();
+ const result = parseWithDepthLimit(() => {
+ // A parser that splices a graph into a tree draws a node several paths
+ // reach once per path, so the copies have to be counted as they are
+ // made rather than after the whole tree is built.
+ for (let drawn = 0; drawn < 5000; drawn += 1) count();
+ return bareNode("0");
+ });
+ expect(result).toEqual({ ok: false, message: PLAN_TOO_MANY_NODES_MESSAGE });
+ });
+
test("turns a build that went too deep into the depth message", () => {
const chain = (depth: number): PlanNode => {
checkPlanDepth(depth);
@@ -676,11 +690,11 @@ describe("planWarningGroups", () => {
test("keeps an engine diagnostic whatever the node costs", () => {
expect(
planWarningGroups(mixedTree()).map((group) => [
- group.warning.title,
+ planWarningIdentity(group.warning),
group.nodes.map((entry) => entry.id),
])
).toEqual([
- ["Full table scan", ["0.0"]],
+ ["full-table-scan", ["0.0"]],
["Columns with no statistics", ["0.2"]],
]);
});
@@ -715,9 +729,9 @@ describe("planWarningGroups", () => {
{ ...bareNode("0.0"), warnings: [PLAN_FULL_TABLE_SCAN] },
]),
});
- expect(planWarningGroups(tree).map((group) => group.warning.title)).toEqual(
- ["Full table scan"]
- );
+ expect(
+ planWarningGroups(tree).map((group) => planWarningIdentity(group.warning))
+ ).toEqual(["full-table-scan"]);
});
test("is empty for a plan nothing is wrong with", () => {
diff --git a/frontend/src/apps/explain-visualizer/plan-model.ts b/frontend/src/apps/explain-visualizer/plan-model.ts
index 38e215c9b4..cb01a7548b 100644
--- a/frontend/src/apps/explain-visualizer/plan-model.ts
+++ b/frontend/src/apps/explain-visualizer/plan-model.ts
@@ -20,11 +20,29 @@ export interface PlanProperty {
/** Where a warning came from, which decides whether relevance can hide it. */
export type PlanWarningSource = "engine" | "heuristic";
-/** Something about a node worth a reader's attention, and what it means. */
+/** A warning this viewer raises itself, named by the words it shows for it. */
+export type PlanWarningKey =
+ | "full-table-scan"
+ | "full-index-scan"
+ | "data-redistribution";
+
+/**
+ * Something about a node worth a reader's attention, and what it means.
+ *
+ * This viewer's own advice names a key and the viewer holds its words, so they
+ * are read in the reader's language. A warning the engine itself reported
+ * carries the engine's words, as the plan's own operator names do.
+ */
export interface PlanWarning {
- readonly title: string;
- readonly detail: string;
readonly source: PlanWarningSource;
+ readonly key?: PlanWarningKey;
+ readonly title?: string;
+ readonly detail?: string;
+}
+
+/** What one warning is, for grouping and for telling two of them apart. */
+export function planWarningIdentity(warning: PlanWarning): string {
+ return warning.key ?? warning.title ?? "";
}
export interface PlanNode {
@@ -144,6 +162,24 @@ const PLAN_MAX_NODES = 1000;
export const PLAN_TOO_MANY_NODES_MESSAGE = `The query plan has more than ${PLAN_MAX_NODES} operators, which is more than this visualizer draws.`;
+/** Raised by a size budget and caught by `parseWithDepthLimit` alone. */
+const PLAN_TOO_MANY_NODES = new Error(PLAN_TOO_MANY_NODES_MESSAGE);
+
+/**
+ * A budget for a parser that expands a graph into a tree. A node that several
+ * paths reach is drawn under each of them, so the copies multiply with the
+ * paths — a flow of 35 processors in two-way stages expands into 262,143 of
+ * them. Counting the finished tree would mean building every copy first, so a
+ * parser that splices calls this for each node it draws and stops there.
+ */
+export function planSizeBudget(): () => void {
+ let drawn = 0;
+ return () => {
+ drawn += 1;
+ if (drawn > PLAN_MAX_NODES) throw PLAN_TOO_MANY_NODES;
+ };
+}
+
/**
* A parser's tree from `build`, or the depth message when it went too deep or
* the node-cap message when it is too large to draw.
@@ -156,8 +192,13 @@ export function parseWithDepthLimit(build: () => PlanNode): PlanParseResult {
}
return { ok: true, tree };
} catch (error) {
- if (error !== PLAN_TOO_DEEP) throw error;
- return { ok: false, message: PLAN_TOO_DEEP_MESSAGE };
+ if (error === PLAN_TOO_DEEP) {
+ return { ok: false, message: PLAN_TOO_DEEP_MESSAGE };
+ }
+ if (error === PLAN_TOO_MANY_NODES) {
+ return { ok: false, message: PLAN_TOO_MANY_NODES_MESSAGE };
+ }
+ throw error;
}
}
@@ -210,6 +251,25 @@ export function planSelfCost(
return planSelfValue(totalCost, children, (child) => child.totalCost);
}
+/**
+ * What an operator that states no cost of its own carries: its children's.
+ *
+ * Engines leave the cost off an operator that adds none — MySQL states one on
+ * the query block and on each table and nothing in between, Oracle leaves it
+ * off a step like `STATISTICS COLLECTOR` — and without this the operator above
+ * would keep that subtree's cost as its own and rank ahead of the operator
+ * that really spends it. Undefined when no child states a cost either, which
+ * is a plan with no costs rather than a plan that costs nothing.
+ */
+export function planSubtreeCost(
+ children: readonly PlanNode[]
+): number | undefined {
+ const costs = children
+ .map((child) => child.totalCost)
+ .filter((cost): cost is number => cost !== undefined);
+ return costs.length ? costs.reduce((sum, cost) => sum + cost, 0) : undefined;
+}
+
/**
* A node's measured time minus its children's, on the same rule as
* `planSelfCost`: the time the operator itself spent, which is what a reader
@@ -222,19 +282,29 @@ export function planSelfTime(
return planSelfValue(actualTime, children, (child) => child.actualTime);
}
+/**
+ * A key from an engine's plan as a label: `access_predicates` and `taskType`
+ * both read "Access predicates" and "Task type". Engines that already report
+ * their keys as prose, such as PostgreSQL's "Node Type", need none of this.
+ */
+export function planLabel(key: string): string {
+ const words = key
+ .replace(/([a-z\d])([A-Z])/g, "$1 $2")
+ .replace(/[_-]+/g, " ")
+ .trim();
+ if (!words) return key;
+ return words[0].toUpperCase() + words.slice(1).toLowerCase();
+}
+
/** Warning for a read of a whole table, attached by each engine's parser. */
export const PLAN_FULL_TABLE_SCAN: PlanWarning = {
- title: "Full table scan",
- detail:
- "Reads every row of this table. If the query needs only a few of them, an index on the filtered columns could avoid the full read.",
+ key: "full-table-scan",
source: "heuristic",
};
/** Warning for a read of a whole index, attached by each engine's parser. */
export const PLAN_FULL_INDEX_SCAN: PlanWarning = {
- title: "Full index scan",
- detail:
- "Reads every entry of this index. If the query needs only a few of them, a condition on the index's leading columns could avoid the full read.",
+ key: "full-index-scan",
source: "heuristic",
};
@@ -249,6 +319,13 @@ export interface PlanRelation {
readonly table: string;
readonly database?: string;
readonly schema?: string;
+ /**
+ * The name is the one the statement used, which is the alias where it gave
+ * one, and the engine did not resolve it to the table it read. It names the
+ * read for a reader, but nothing is looked up by it: a stored table that
+ * happens to share an alias would answer with the wrong table's facts.
+ */
+ readonly unresolved?: boolean;
}
/** One index on a table an operator reads, as Bytebase last synced it. */
@@ -649,9 +726,10 @@ export function planWarningGroups(tree: PlanTree): PlanWarningGroup[] {
) {
continue;
}
- const group = groups.get(warning.title);
+ const identity = planWarningIdentity(warning);
+ const group = groups.get(identity);
if (group) group.nodes.push(node);
- else groups.set(warning.title, { warning, nodes: [node] });
+ else groups.set(identity, { warning, nodes: [node] });
}
}
return [...groups.values()].map(({ warning, nodes }) => ({
diff --git a/frontend/src/apps/explain-visualizer/plan-parsers.ts b/frontend/src/apps/explain-visualizer/plan-parsers.ts
index b639784d30..839710496e 100644
--- a/frontend/src/apps/explain-visualizer/plan-parsers.ts
+++ b/frontend/src/apps/explain-visualizer/plan-parsers.ts
@@ -1,9 +1,19 @@
import { Engine } from "@/types/proto-es/v1/common_pb";
import type { VisualizerEngine } from "@/utils/queryPlanEngines";
+import { parseClickhousePlan } from "./clickhouse-plan";
+import { parseCockroachdbPlan } from "./cockroachdb-plan";
+import { parseMongodbPlan } from "./mongodb-plan";
import { parseMssqlPlan } from "./mssql-plan";
+import { parseMysqlPlan } from "./mysql-plan";
+import { parseOceanbasePlan } from "./oceanbase-plan";
+import { parseOraclePlan } from "./oracle-plan";
import type { PlanParseResult } from "./plan-model";
import { parsePostgresPlan } from "./postgres-plan";
+import { parseRedshiftPlan } from "./redshift-plan";
import { parseSpannerPlan } from "./spanner-plan";
+import { parseStarrocksPlan } from "./starrocks-plan";
+import { parseTidbPlan } from "./tidb-plan";
+import { parseTrinoPlan } from "./trino-plan";
/**
* Each engine's explain output on the engine-neutral model, keyed on the same
@@ -14,6 +24,31 @@ const PARSERS: Record<VisualizerEngine, (source: string) => PlanParseResult> = {
[Engine.POSTGRES]: parsePostgresPlan,
[Engine.MSSQL]: parseMssqlPlan,
[Engine.SPANNER]: parseSpannerPlan,
+ // MySQL and MariaDB differ in which keys they put in FORMAT=JSON, not in its
+ // shape, so one parser reads both.
+ [Engine.MYSQL]: parseMysqlPlan,
+ [Engine.MARIADB]: parseMysqlPlan,
+ [Engine.TIDB]: parseTidbPlan,
+ // Oracle states its plan as plan-table rows, which the server renders as
+ // JSON because no EXPLAIN option of its own does.
+ [Engine.ORACLE]: parseOraclePlan,
+ [Engine.CLICKHOUSE]: parseClickhousePlan,
+ [Engine.TRINO]: parseTrinoPlan,
+ // OceanBase spells its plan FORMAT=JSON as MySQL does, but returns an
+ // operator tree rather than MySQL's nested query block.
+ [Engine.OCEANBASE]: parseOceanbasePlan,
+ // MongoDB asks for a plan with a cursor method rather than a keyword, and
+ // states it as one document.
+ [Engine.MONGODB]: parseMongodbPlan,
+ // CockroachDB publishes no plan as a document; the server decodes the one it
+ // encodes in the diagram link EXPLAIN (DISTSQL) prints.
+ [Engine.COCKROACHDB]: parseCockroachdbPlan,
+ // The text plans drawn here, because none of these engines publishes
+ // anything else. StarRocks forked from Doris and their plans still agree on
+ // the fragments and the tree, so one parser reads both.
+ [Engine.REDSHIFT]: parseRedshiftPlan,
+ [Engine.STARROCKS]: parseStarrocksPlan,
+ [Engine.DORIS]: parseStarrocksPlan,
};
export function parsePlan(
diff --git a/frontend/src/apps/explain-visualizer/redshift-plan.test.ts b/frontend/src/apps/explain-visualizer/redshift-plan.test.ts
new file mode 100644
index 0000000000..15b2b66c08
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/redshift-plan.test.ts
@@ -0,0 +1,173 @@
+import { describe, expect, test } from "vitest";
+import {
+ PLAN_TOO_DEEP_MESSAGE,
+ type PlanNode,
+ type PlanTree,
+ planWarningIdentity,
+} from "./plan-model";
+import {
+ parseRedshiftPlan,
+ REDSHIFT_PLAN_EMPTY_MESSAGE,
+ REDSHIFT_PLAN_NO_PLAN_MESSAGE,
+} from "./redshift-plan";
+import hashAggregate from "./test-data/redshift/hash-aggregate.txt?raw";
+import hashJoinBroadcast from "./test-data/redshift/hash-join-broadcast.txt?raw";
+import postgresSameGrammar from "./test-data/redshift/postgres-same-grammar.txt?raw";
+import scanFilter from "./test-data/redshift/scan-filter.txt?raw";
+import threeWayJoin from "./test-data/redshift/three-way-join.txt?raw";
+
+/** A chain of `depth` operators, which is what drives the depth limit. */
+const nestedPlan = (depth: number): string =>
+ Array.from({ length: depth }, (_, level) =>
+ level === 0
+ ? "XN Limit (cost=0.00..1.00 rows=1 width=1)"
+ : `${" ".repeat(level * 2)}-> XN Nested Loop (cost=0.00..1.00 rows=1 width=1)`
+ ).join("\n");
+
+const parse = (source: string): PlanTree => {
+ const result = parseRedshiftPlan(source);
+ if (!result.ok)
+ throw new Error(`expected a parsable plan: ${result.message}`);
+ return result.tree;
+};
+
+const outline = (tree: PlanTree): string[] =>
+ tree.nodes.map((node) => `${node.id} ${node.nodeType}`);
+
+const propertyValue = (node: PlanNode, label: string): string | undefined =>
+ node.properties.find((property) => property.label === label)?.value;
+
+const byId = (tree: PlanTree, id: string): PlanNode => {
+ const node = tree.nodes.find((candidate) => candidate.id === id);
+ if (!node) throw new Error(`no node ${id} in ${outline(tree).join(", ")}`);
+ return node;
+};
+
+describe("parseRedshiftPlan", () => {
+ test("builds the tree from how far each operator is indented", () => {
+ const tree = parse(hashJoinBroadcast);
+
+ expect(outline(tree)).toEqual([
+ "0 Hash Join",
+ "0.0 Seq Scan",
+ "0.1 Hash",
+ "0.1.0 Seq Scan",
+ ]);
+ // Redshift indents the whole plan by one space in this one, so the depths
+ // are relative to each other rather than to the left margin.
+ expect(byId(tree, "0.1.0").relation).toEqual({ table: "category" });
+ });
+
+ test("reads cost, rows and width, and charges each operator its own", () => {
+ const tree = parse(hashJoinBroadcast);
+ const join = tree.root;
+ const scan = byId(tree, "0.0");
+
+ // Cost covers an operator and everything below it, as PostgreSQL's does.
+ expect(join).toMatchObject({
+ startupCost: 0.14,
+ totalCost: 6600286.07,
+ rows: 8798,
+ width: 84,
+ });
+ expect(scan.selfCost).toBe(87.98);
+ expect(join.selfCost).toBeCloseTo(6600286.07 - 87.98 - 0.11, 2);
+ });
+
+ test("names the table a scan reads, and not the statement's alias", () => {
+ const tree = parse(threeWayJoin);
+
+ expect(byId(tree, "0.0.0").relation).toEqual({ table: "listing" });
+ expect(byId(tree, "0.0.1").relation).toEqual({ table: "sales" });
+ // A join reads its inputs, not a table.
+ expect(tree.root.relation).toBeUndefined();
+ });
+
+ test("flags a join that has to move rows between slices", () => {
+ const broadcast = parse(hashJoinBroadcast).root;
+ const merge = byId(parse(threeWayJoin), "0.0");
+
+ expect(propertyValue(broadcast, "Distribution")).toBe("DS_BCAST_INNER");
+ // The viewer holds this warning's words, so what the parser attaches is
+ // which warning it is.
+ expect(broadcast.warnings.map(planWarningIdentity)).toEqual([
+ "data-redistribution",
+ ]);
+ // DS_DIST_NONE is the join that did not have to move anything.
+ expect(propertyValue(merge, "Distribution")).toBe("DS_DIST_NONE");
+ expect(merge.warnings).toEqual([]);
+ });
+
+ test("keeps what an operator says about itself", () => {
+ expect(propertyValue(parse(scanFilter).root, "Filter")).toBe(
+ "(venueseats IS NOT NULL)"
+ );
+ expect(outline(parse(hashAggregate))).toEqual([
+ "0 HashAggregate",
+ "0.0 Seq Scan",
+ ]);
+ });
+
+ test("reads a PostgreSQL text plan, which is the grammar Redshift inherited", () => {
+ // Captured from a real PostgreSQL server. Redshift cannot be run from this
+ // repository's tests, so this is what pins the shape of the grammar to
+ // output a server actually produced rather than to one written by hand.
+ const tree = parse(postgresSameGrammar);
+
+ expect(outline(tree)).toEqual([
+ "0 Limit",
+ "0.0 Sort",
+ "0.0.0 HashAggregate",
+ "0.0.0.0 Hash Join",
+ "0.0.0.0.0 Seq Scan",
+ "0.0.0.0.1 Hash",
+ "0.0.0.0.1.0 Seq Scan",
+ ]);
+ expect(byId(tree, "0.0.0.0.0").relation).toEqual({ table: "orders" });
+ expect(propertyValue(byId(tree, "0.0.0.0.0"), "Filter")).toBe(
+ "(total > 880)"
+ );
+ });
+
+ test("does not take a line inside a value for an operator", () => {
+ // The hazard §4 of the design names: a text plan has no escaping, so a
+ // literal holding a newline puts its own lines into the output. An
+ // operator is recognized only by a whole cost tuple, which is what a value
+ // would have to reproduce to be mistaken for one.
+ const tree = parse(
+ [
+ "XN Seq Scan on venue (cost=0.00..2.02 rows=187 width=45)",
+ " Filter: (name = 'line one",
+ " -> XN Seq Scan on secrets (cost=1.00)",
+ " -> XN Seq Scan on secrets rows=1',)",
+ ].join("\n")
+ );
+
+ expect(outline(tree)).toEqual(["0 Seq Scan"]);
+ expect(tree.root.relation).toEqual({ table: "venue" });
+ });
+
+ test("reports a plan it cannot read", () => {
+ expect(parseRedshiftPlan(" ")).toEqual({
+ ok: false,
+ message: REDSHIFT_PLAN_EMPTY_MESSAGE,
+ });
+ expect(parseRedshiftPlan("Filter: (venueseats IS NOT NULL)")).toEqual({
+ ok: false,
+ message: REDSHIFT_PLAN_NO_PLAN_MESSAGE,
+ });
+ // JSON, which is what every other engine here returns.
+ expect(parseRedshiftPlan('{"Plan": {}}')).toEqual({
+ ok: false,
+ message: REDSHIFT_PLAN_NO_PLAN_MESSAGE,
+ });
+ });
+
+ test("gives up past the depth it can draw", () => {
+ expect(parseRedshiftPlan(nestedPlan(400)).ok).toBe(true);
+ expect(parseRedshiftPlan(nestedPlan(2000))).toEqual({
+ ok: false,
+ message: PLAN_TOO_DEEP_MESSAGE,
+ });
+ });
+});
diff --git a/frontend/src/apps/explain-visualizer/redshift-plan.ts b/frontend/src/apps/explain-visualizer/redshift-plan.ts
new file mode 100644
index 0000000000..a148a0591f
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/redshift-plan.ts
@@ -0,0 +1,200 @@
+import {
+ addPlanProperty,
+ checkPlanDepth,
+ type PlanNode,
+ type PlanParseResult,
+ type PlanProperty,
+ type PlanRelation,
+ type PlanWarning,
+ parseWithDepthLimit,
+ planSelfCost,
+} from "./plan-model";
+
+/**
+ * Maps Redshift's `EXPLAIN` text onto the engine-neutral plan model.
+ *
+ * Redshift publishes no plan as a document: its EXPLAIN takes no format, and
+ * the one structured copy it keeps is in the `STL_EXPLAIN` system table, which
+ * nothing outside a running cluster can read. So this is the one parser here
+ * that reads text, and §4 of the query-plan design is why that is not the
+ * default: a text plan has no escaping, so a string holding a newline can put
+ * a line into the output that looks like an operator.
+ *
+ * Two things make it safe enough to do here, where the alternative is no
+ * picture at all. Redshift returns the plan one row per line, so the row
+ * boundaries are the engine's own and a newline inside a literal stays inside
+ * its row. And an operator is recognized only by a whole cost tuple —
+ * `(cost=0.00..87.98 rows=8798 width=35)` — which a value would have to
+ * reproduce exactly to be mistaken for one.
+ *
+ * The grammar is PostgreSQL's own text format, which Redshift inherited and
+ * prefixed with `XN`, so this reads a PostgreSQL text plan too. That is what
+ * lets the parser be checked against output captured from a real server.
+ */
+
+/**
+ * An operator: its depth in the tree, its name, and the estimate that makes it
+ * one. The `XN` prefix is Redshift's; PostgreSQL's own text plans omit it.
+ */
+const OPERATOR =
+ /^(\s*)(?:->\s+)?(?:XN\s+)?(\S.*?)\s+\(cost=([\d.]+)\.\.([\d.]+)\s+rows=(\d+)\s+width=(\d+)\)\s*$/;
+
+/** An attribute of the operator above it, such as `Hash Cond: (...)`. */
+const ATTRIBUTE = /^\s*([A-Z][A-Za-z ]*?):\s*(.*)$/;
+
+/** How Redshift says it moved data to make a join work. */
+const DISTRIBUTION = /\s+(DS_[A-Z_]+)$/;
+
+/** The table a scan reads, which Redshift names before any alias. */
+const SCANNED_TABLE = /\son\s+(\S+)/;
+
+/**
+ * The strategies that move data between slices to join it. They are the first
+ * thing a reader of a Redshift plan looks for, because they are what a
+ * distribution key is chosen to avoid.
+ */
+const REDISTRIBUTING = new Set([
+ "DS_BCAST_INNER",
+ "DS_DIST_INNER",
+ "DS_DIST_BOTH",
+]);
+
+const DATA_REDISTRIBUTION: PlanWarning = {
+ key: "data-redistribution",
+ source: "heuristic",
+};
+
+export const REDSHIFT_PLAN_EMPTY_MESSAGE =
+ "Redshift returned no query plan for this statement.";
+export const REDSHIFT_PLAN_NO_PLAN_MESSAGE =
+ "The query plan has no operator in it: a Redshift plan states a cost for every one.";
+
+interface Parsed {
+ readonly indent: number;
+ readonly nodeType: string;
+ readonly startupCost: number;
+ readonly totalCost: number;
+ readonly rows: number;
+ readonly width: number;
+ readonly relation?: PlanRelation;
+ readonly subject?: string;
+ readonly properties: PlanProperty[];
+ readonly children: Parsed[];
+}
+
+/** Where the operator sits: at its arrow, or at its name when it has none. */
+function indentOf(line: string): number {
+ const arrow = line.indexOf("->");
+ return arrow >= 0 ? arrow : line.length - line.trimStart().length;
+}
+
+function parseOperator(line: string): Parsed | undefined {
+ const matched = OPERATOR.exec(line);
+ if (!matched) return undefined;
+ const [, , name, startup, total, rows, width] = matched;
+
+ const properties: PlanProperty[] = [];
+ let nodeType = name;
+ const distribution = DISTRIBUTION.exec(nodeType);
+ if (distribution) {
+ nodeType = nodeType.slice(0, distribution.index);
+ addPlanProperty(properties, "Distribution", distribution[1]);
+ }
+
+ // A scan names its table, and then whatever the statement called it.
+ const scanned = SCANNED_TABLE.exec(nodeType);
+ if (scanned) {
+ nodeType = nodeType.slice(0, scanned.index);
+ }
+ const table = scanned?.[1];
+
+ return {
+ indent: indentOf(line),
+ nodeType: nodeType.trim() || "Unknown",
+ startupCost: Number(startup),
+ totalCost: Number(total),
+ rows: Number(rows),
+ width: Number(width),
+ relation: table ? { table } : undefined,
+ subject: table,
+ properties,
+ children: [],
+ };
+}
+
+function toPlanNode(parsed: Parsed, id: string, depth: number): PlanNode {
+ checkPlanDepth(depth);
+ const children = parsed.children.map((child, index) =>
+ toPlanNode(child, `${id}.${index}`, depth + 1)
+ );
+ const warnings = parsed.properties.some(
+ (property) =>
+ property.label === "Distribution" && REDISTRIBUTING.has(property.value)
+ )
+ ? [DATA_REDISTRIBUTION]
+ : [];
+ return {
+ id,
+ nodeType: parsed.nodeType,
+ subject:
+ parsed.subject ??
+ parsed.properties.find((property) => property.label.endsWith("Cond"))
+ ?.value,
+ relation: parsed.relation,
+ startupCost: parsed.startupCost,
+ totalCost: parsed.totalCost,
+ selfCost: planSelfCost(parsed.totalCost, children),
+ rows: parsed.rows,
+ width: parsed.width,
+ properties: parsed.properties,
+ warnings,
+ children,
+ };
+}
+
+export function parseRedshiftPlan(source: string): PlanParseResult {
+ if (!source.trim()) {
+ return { ok: false, message: REDSHIFT_PLAN_EMPTY_MESSAGE };
+ }
+
+ let root: Parsed | undefined;
+ // The operators from the root down to the one being read, so a line's indent
+ // says which of them it belongs under.
+ const open: Parsed[] = [];
+ for (const line of source.split("\n")) {
+ if (!line.trim()) continue;
+ const operator = parseOperator(line);
+ if (!operator) {
+ // Anything that is not an operator describes the one above it.
+ const current = open[open.length - 1];
+ if (!current) continue;
+ const attribute = ATTRIBUTE.exec(line);
+ if (attribute) {
+ addPlanProperty(current.properties, attribute[1], attribute[2]);
+ } else {
+ addPlanProperty(current.properties, "Detail", line.trim());
+ }
+ continue;
+ }
+
+ while (open.length > 0 && open[open.length - 1].indent >= operator.indent) {
+ open.pop();
+ }
+ const parent = open[open.length - 1];
+ if (parent) {
+ parent.children.push(operator);
+ } else if (!root) {
+ root = operator;
+ } else {
+ // A second operator with nothing above it is not something Redshift
+ // prints; keeping it under the first draws all of what arrived.
+ root.children.push(operator);
+ }
+ open.push(operator);
+ }
+
+ if (!root) {
+ return { ok: false, message: REDSHIFT_PLAN_NO_PLAN_MESSAGE };
+ }
+ return parseWithDepthLimit(() => toPlanNode(root, "0", 0));
+}
diff --git a/frontend/src/apps/explain-visualizer/starrocks-plan.test.ts b/frontend/src/apps/explain-visualizer/starrocks-plan.test.ts
new file mode 100644
index 0000000000..7e55d8b893
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/starrocks-plan.test.ts
@@ -0,0 +1,262 @@
+import { describe, expect, test } from "vitest";
+import {
+ PLAN_TOO_DEEP_MESSAGE,
+ PLAN_TOO_MANY_NODES_MESSAGE,
+ type PlanNode,
+ type PlanTree,
+} from "./plan-model";
+import {
+ parseStarrocksPlan,
+ STARROCKS_PLAN_EMPTY_MESSAGE,
+ STARROCKS_PLAN_NO_PLAN_MESSAGE,
+} from "./starrocks-plan";
+import dorisAnalyzedJoin from "./test-data/doris/analyzed-join.txt?raw";
+import dorisJoinExchange from "./test-data/doris/join-exchange.txt?raw";
+import dorisScanAggregate from "./test-data/doris/scan-aggregate.txt?raw";
+import dorisSingleScan from "./test-data/doris/single-scan.txt?raw";
+import joinExchange from "./test-data/starrocks/join-exchange.txt?raw";
+import nestedJoinBranch from "./test-data/starrocks/nested-join-branch.txt?raw";
+import scanAggregate from "./test-data/starrocks/scan-aggregate.txt?raw";
+import singleScan from "./test-data/starrocks/single-scan.txt?raw";
+
+/** A chain of `depth` operators in one fragment, which drives the depth limit. */
+const nestedPlan = (depth: number): string =>
+ [
+ "PLAN FRAGMENT 0",
+ ...Array.from({ length: depth }, (_, level) => ` ${level}:Project`),
+ ].join("\n");
+
+/**
+ * `stages` fragments, each joining two exchanges that both read the next one,
+ * so every path through the plan splices the rest of it again and the tree
+ * doubles per fragment: 30 would be 2^31 nodes if they were all built first.
+ */
+const repartitionedPlan = (stages: number): string => {
+ const lines: string[] = [];
+ for (let stage = 0; stage < stages; stage += 1) {
+ lines.push(`PLAN FRAGMENT ${stage}`);
+ if (stage > 0) lines.push(` EXCHANGE ID: 0${stage}`);
+ lines.push(
+ " 0:HASH JOIN",
+ ` |----${stage + 1}:EXCHANGE`,
+ ` ${stage + 1}:EXCHANGE`
+ );
+ }
+ lines.push(
+ `PLAN FRAGMENT ${stages}`,
+ ` EXCHANGE ID: 0${stages}`,
+ " 0:OlapScanNode"
+ );
+ return lines.join("\n");
+};
+
+const parse = (source: string): PlanTree => {
+ const result = parseStarrocksPlan(source);
+ if (!result.ok)
+ throw new Error(`expected a parsable plan: ${result.message}`);
+ return result.tree;
+};
+
+const outline = (tree: PlanTree): string[] =>
+ tree.nodes.map((node) => `${node.id} ${node.nodeType}`);
+
+const propertyValue = (node: PlanNode, label: string): string | undefined =>
+ node.properties.find((property) => property.label === label)?.value;
+
+const byId = (tree: PlanTree, id: string): PlanNode => {
+ const node = tree.nodes.find((candidate) => candidate.id === id);
+ if (!node) throw new Error(`no node ${id} in ${outline(tree).join(", ")}`);
+ return node;
+};
+
+describe("parseStarrocksPlan", () => {
+ test("joins the fragments where one sends to the other's exchange", () => {
+ const tree = parse(singleScan);
+
+ // Two fragments: the scan sends to exchange 1, which fragment 0 reads.
+ expect(outline(tree)).toEqual(["0 EXCHANGE", "0.0 OlapScanNode"]);
+ expect(byId(tree, "0.0").relation).toEqual({ table: "orders" });
+ });
+
+ test("reads what a scan states about the rows it expects", () => {
+ const scan = byId(parse(singleScan), "0.0");
+
+ expect(scan).toMatchObject({ rows: 2500, width: 4 });
+ expect(propertyValue(scan, "Predicates")).toBe("3: total > 880");
+ expect(propertyValue(scan, "Preaggregation")).toBe("ON");
+ // StarRocks states no cost in the plan the editor asks for.
+ expect(parse(singleScan).estimates.cost).toBe(false);
+ });
+
+ test("follows the chain through every fragment of an aggregation", () => {
+ expect(outline(parse(scanAggregate))).toEqual([
+ "0 EXCHANGE",
+ "0.0 AGGREGATE (merge finalize)",
+ "0.0.0 EXCHANGE",
+ "0.0.0.0 AGGREGATE (update serialize)",
+ "0.0.0.0.0 OlapScanNode",
+ ]);
+ });
+
+ test("hangs both inputs of a join off it", () => {
+ const tree = parse(joinExchange);
+ const join = byId(tree, "0.0.0.0.0.0");
+
+ expect(join.nodeType).toBe("HASH JOIN");
+ expect(propertyValue(join, "Join op")).toBe("INNER JOIN (PARTITIONED)");
+ expect(join.children).toHaveLength(2);
+ // Each side reaches its own table through an exchange.
+ expect(byId(tree, "0.0.0.0.0.0.0.0").relation).toEqual({
+ table: "customers",
+ });
+ expect(byId(tree, "0.0.0.0.0.0.1.0").relation).toEqual({ table: "orders" });
+ });
+
+ test("reads a branch drawn inside another, bars and all", () => {
+ const tree = parse(nestedJoinBranch);
+ const inner = byId(tree, "0.0.0.0.0.0.0.0.0");
+
+ // StarRocks draws a second input under `|----` and continues it behind a
+ // bar, so which operator a line belongs to is the column it starts at.
+ expect(inner.nodeType).toBe("HASH JOIN");
+ expect(inner.children.map((child) => child.nodeType)).toEqual([
+ "Project",
+ "OlapScanNode",
+ ]);
+ expect(byId(tree, "0.0.0.0.0.0.0.0.0.0.0").relation).toEqual({
+ table: "customers",
+ });
+ expect(
+ propertyValue(byId(tree, "0.0.0.0.0.0.0.0.0.0.0"), "Predicates")
+ ).toContain("country = 'JP'");
+ });
+
+ test("does not take a line inside a value for an operator", () => {
+ // A value holding a newline puts its own lines into the plan. An operator
+ // is its number and name at the head of a line, which a predicate's
+ // continuation is not.
+ const tree = parse(
+ [
+ "PLAN FRAGMENT 0",
+ " 0:OlapScanNode",
+ " TABLE: venue",
+ " PREDICATES: 1: name = 'line one",
+ " 1:OlapScanNode",
+ " TABLE: secrets'",
+ ].join("\n")
+ );
+
+ expect(outline(tree)).toEqual(["0 OlapScanNode", "0.0 OlapScanNode"]);
+ // The faked line is still read as an operator; what it cannot do is claim
+ // a table the statement never named, because the relation comes from the
+ // line after it.
+ expect(tree.root.relation).toEqual({ table: "venue" });
+ });
+
+ test("reports a plan it cannot read", () => {
+ expect(parseStarrocksPlan(" ")).toEqual({
+ ok: false,
+ message: STARROCKS_PLAN_EMPTY_MESSAGE,
+ });
+ expect(parseStarrocksPlan("PLAN FRAGMENT 0\n RESULT SINK")).toEqual({
+ ok: false,
+ message: STARROCKS_PLAN_NO_PLAN_MESSAGE,
+ });
+ expect(parseStarrocksPlan('{"Plan": {}}')).toEqual({
+ ok: false,
+ message: STARROCKS_PLAN_NO_PLAN_MESSAGE,
+ });
+ });
+
+ test("reads Doris, which spells the same plan its own way", () => {
+ const tree = parse(dorisSingleScan);
+ const scan = byId(tree, "0.0");
+
+ // Doris prefixes the vectorized operators with V, and prints the
+ // planner's own id after the name.
+ expect(outline(tree)).toEqual(["0 VEXCHANGE", "0.0 VOlapScanNode"]);
+ expect(propertyValue(scan, "Plan node id")).toBe("85");
+ // It names the table qualified, and then what the statement called it.
+ expect(scan.relation).toEqual({ database: "qp", table: "orders" });
+ });
+
+ test("splits the attributes Doris packs onto one line", () => {
+ const scan = byId(parse(dorisScanAggregate), "0.0.0.0.0");
+
+ expect(propertyValue(scan, "Cardinality")).toBe("1");
+ expect(propertyValue(scan, "Num nodes")).toBe("1");
+ expect(propertyValue(scan, "Preaggregation")).toBe("ON");
+ // A value with a space in it is one value, not several attributes: the
+ // tablets stay on their own line and the predicate stays whole.
+ expect(propertyValue(scan, "Tablet list")).toBe(
+ "1793041799804,1793041799806"
+ );
+ expect(propertyValue(scan, "Predicates")).toBe("(total[#2] > 880)");
+ expect(propertyValue(scan, "Final projections")).toBe(
+ "customer_id[#1], total[#2]"
+ );
+ });
+
+ test("reads the rows and width Doris states, once it has statistics", () => {
+ const analyzed = parse(dorisAnalyzedJoin);
+ const scan = byId(analyzed, "0.0.0.0.0.1");
+ const join = byId(analyzed, "0.0.0.0.0");
+ const unanalyzed = byId(parse(dorisSingleScan), "0.0");
+
+ expect(scan).toMatchObject({ rows: 5000, width: 8.398 });
+ // Doris groups a standalone cardinality by thousands, and prints the same
+ // number plain where it packs it onto a line beside the width.
+ expect(propertyValue(join, "Cardinality")).toBe("4,499");
+ expect(join.rows).toBe(4499);
+ // The same scan before Doris had analyzed the table: avgRowSize=0.0 is
+ // what it prints with no column statistics, and no row is zero bytes
+ // wide, so that is not a width it stated.
+ expect(propertyValue(unanalyzed, "Avg row size")).toBe("0.0");
+ expect(unanalyzed.width).toBeUndefined();
+ expect(parse(dorisSingleScan).estimates.width).toBe(false);
+ });
+
+ test("leaves the statistics Doris prints after the plan out of it", () => {
+ const tree = parse(dorisJoinExchange);
+
+ expect(outline(tree)).toEqual([
+ "0 VEXCHANGE",
+ "0.0 VAGGREGATE (merge finalize)",
+ "0.0.0 VEXCHANGE",
+ "0.0.0.0 VAGGREGATE (update serialize)",
+ "0.0.0.0.0 VHASH JOIN",
+ "0.0.0.0.0.0 VEXCHANGE",
+ "0.0.0.0.0.0.0 VOlapScanNode",
+ "0.0.0.0.0.1 VOlapScanNode",
+ ]);
+ // The statistics follow the plan under a rule of equals signs, so they
+ // would otherwise describe whichever operator Doris printed last — the
+ // scan of the join's build side, which comes in the final fragment.
+ const printedLast = byId(tree, "0.0.0.0.0.0.0");
+ expect(printedLast.relation).toEqual({
+ database: "qp",
+ table: "customers",
+ });
+ expect(propertyValue(printedLast, "Detail")).toBeUndefined();
+ });
+
+ test("gives up on a plan that expands past the operators it draws", () => {
+ // Without a budget this builds every copy before anything counts them,
+ // which for 30 fragments means over two billion nodes.
+ expect(parseStarrocksPlan(repartitionedPlan(30))).toEqual({
+ ok: false,
+ message: PLAN_TOO_MANY_NODES_MESSAGE,
+ });
+ // A plan small enough to draw still draws every path through it: each
+ // fragment is a join and two exchanges over two copies of the next.
+ expect(parse(repartitionedPlan(3)).nodes).toHaveLength(29);
+ });
+
+ test("gives up past the depth it can draw", () => {
+ expect(parseStarrocksPlan(nestedPlan(400)).ok).toBe(true);
+ expect(parseStarrocksPlan(nestedPlan(2000))).toEqual({
+ ok: false,
+ message: PLAN_TOO_DEEP_MESSAGE,
+ });
+ });
+});
diff --git a/frontend/src/apps/explain-visualizer/starrocks-plan.ts b/frontend/src/apps/explain-visualizer/starrocks-plan.ts
new file mode 100644
index 0000000000..c756ff598f
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/starrocks-plan.ts
@@ -0,0 +1,277 @@
+import {
+ addPlanProperty,
+ checkPlanDepth,
+ type PlanNode,
+ type PlanParseResult,
+ type PlanProperty,
+ type PlanRelation,
+ parseWithDepthLimit,
+ planLabel,
+ planSizeBudget,
+} from "./plan-model";
+
+/**
+ * Maps StarRocks' and Doris's `EXPLAIN` text onto the engine-neutral plan
+ * model. StarRocks forked from Doris, and the plan is what did not diverge:
+ * the same fragments, the same tree, the same attributes. What differs is how
+ * an operator spells itself, which is why one parser reads both.
+ *
+ * Neither publishes a plan as a document — asked for one they reject the
+ * statement — so this reads text, for the reason the Redshift parser does and
+ * with the same two things holding off the hazard §4 of the design names: the
+ * plan arrives one row per line, so a newline inside a literal stays inside
+ * its row, and an operator is recognized only by its own numbered heading.
+ *
+ * What it reads is two nested structures. A plan is a list of fragments, each
+ * the piece of work one set of nodes does, joined where an `EXCHANGE` operator
+ * in one fragment names the exchange another fragment sends to. Within a
+ * fragment the operators are drawn as a tree: each is printed under the one it
+ * feeds, and a second input is introduced by `|----` and drawn in a branch of
+ * its own. Which operator a line belongs to is therefore the column its number
+ * starts at, counting through the branch bars.
+ *
+ * Neither states a cost, so these plans rank nothing. What a scan does state
+ * is the table, the predicates pushed into it, and the rows it expects.
+ */
+
+/** `PLAN FRAGMENT 2`, optionally followed by the planner's own id. */
+const FRAGMENT = /^\s*PLAN FRAGMENT\s+(\d+)/;
+
+/** An operator: ` 4:HASH JOIN`, or ` |----3:Project` to start a branch. */
+const OPERATOR = /^([\s|-]*?)(\d+):(\S.*)$/;
+
+/** The exchange a fragment sends its rows to, which names where it plugs in. */
+const SINK_EXCHANGE = /^\s*(?:EXCHANGE ID|OutPut Exchange Id):\s*0*(\d+)/;
+
+/** An operator's own line, `key: value` or `key=value`. */
+const ATTRIBUTE = /^([A-Za-z][A-Za-z0-9 _]*?)\s*[:=]\s*(.*)$/;
+
+/**
+ * The planner's own id for an operator, which Doris prints after its name.
+ * Keeping it as a property leaves the name alone, which is what a reader
+ * recognizes an operator by.
+ */
+const PLAN_NODE_ID = /\((\d+)\)$/;
+
+/** A scanned table: qualified, then whatever the statement called it. */
+const SCANNED_TABLE = /^([^\s(]+)(?:\([^)]*\))?$/;
+
+/**
+ * The rule Doris prints its statistics under, once the plan is done. The whole
+ * line is that rule, which is what keeps a value from ending the plan early.
+ */
+const SEPARATOR = /^\s*={5,}[A-Z\s]*={5,}\s*$/;
+
+export const STARROCKS_PLAN_EMPTY_MESSAGE =
+ "The statement produced no query plan to draw.";
+export const STARROCKS_PLAN_NO_PLAN_MESSAGE =
+ "The query plan has no numbered operator in any of its fragments.";
+
+interface Parsed {
+ readonly column: number;
+ readonly id: string;
+ readonly nodeType: string;
+ readonly properties: PlanProperty[];
+ readonly children: Parsed[];
+}
+
+interface Fragment {
+ root?: Parsed;
+ /** The exchange this fragment feeds, by its operator number. */
+ sink?: string;
+}
+
+/**
+ * What one line says about its operator. Doris packs several onto a line —
+ * `cardinality=1, avgRowSize=0.0` — where StarRocks gives each its own, so a
+ * line is split only where every piece is a key and a value with no space in
+ * it. A predicate, a join condition or a list of ids has a space, and stays
+ * whole.
+ */
+function attributesIn(text: string): [string, string][] {
+ const pieces = text.split(", ");
+ const packed: [string, string][] = [];
+ for (const piece of pieces) {
+ const attribute = ATTRIBUTE.exec(piece);
+ if (!attribute || attribute[2].includes(" ")) break;
+ packed.push([planLabel(attribute[1]), attribute[2]]);
+ }
+ if (pieces.length > 1 && packed.length === pieces.length) return packed;
+
+ const whole = ATTRIBUTE.exec(text);
+ return whole ? [[planLabel(whole[1]), whole[2]]] : [["Detail", text]];
+}
+
+/**
+ * The table a scan reads. Doris qualifies it with the database and adds what
+ * the statement called it; StarRocks writes the stored name alone.
+ */
+function toRelation(
+ properties: readonly PlanProperty[]
+): PlanRelation | undefined {
+ const named = properties.find((property) => property.label === "Table");
+ const scanned = named ? SCANNED_TABLE.exec(named.value) : null;
+ if (!scanned) return undefined;
+ const qualified = scanned[1];
+ const separator = qualified.lastIndexOf(".");
+ const table = qualified.slice(separator + 1);
+ if (!table) return undefined;
+ return separator > 0
+ ? { database: qualified.slice(0, separator), table }
+ : { table };
+}
+
+/**
+ * A number an operator stated. Doris groups a standalone cardinality by
+ * thousands — `cardinality=4,499` — and prints the same number plain where it
+ * packs it onto a line, so the separators come off before it is read.
+ */
+function numberOf(
+ properties: readonly PlanProperty[],
+ label: string
+): number | undefined {
+ const value = properties.find((property) => property.label === label)?.value;
+ const parsed =
+ value === undefined ? Number.NaN : Number(value.replaceAll(",", ""));
+ return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+/**
+ * @param exchanges - The fragment root each `EXCHANGE` operator reads from, so
+ * the fragments are drawn as the one tree they describe.
+ * @param seen - The exchanges already spliced on this path, since a plan whose
+ * fragments fed each other would never finish.
+ * @param count - The size budget, since a fragment read by two exchanges is
+ * drawn under each of them.
+ */
+function toPlanNode(
+ parsed: Parsed,
+ exchanges: ReadonlyMap<string, Parsed>,
+ id: string,
+ seen: Set<string>,
+ depth: number,
+ count: () => void
+): PlanNode {
+ checkPlanDepth(depth);
+ count();
+ const children = [...parsed.children];
+ const source = exchanges.get(parsed.id);
+ if (source && !seen.has(parsed.id)) {
+ seen.add(parsed.id);
+ children.push(source);
+ }
+ const drawn = children.map((child, index) =>
+ toPlanNode(child, exchanges, `${id}.${index}`, seen, depth + 1, count)
+ );
+ if (source) seen.delete(parsed.id);
+
+ const relation = toRelation(parsed.properties);
+ const width = numberOf(parsed.properties, "Avg row size");
+ return {
+ id,
+ nodeType: parsed.nodeType,
+ subject:
+ relation?.table ??
+ parsed.properties.find((property) =>
+ ["Predicates", "Equal join conjunct", "Group by"].includes(
+ property.label
+ )
+ )?.value,
+ relation,
+ rows: numberOf(parsed.properties, "Cardinality"),
+ // Doris prints `avgRowSize=0.0` where it has no column statistics, and no
+ // row is zero bytes wide, so that is not a width it stated.
+ width: width === 0 ? undefined : width,
+ properties: parsed.properties,
+ warnings: [],
+ children: drawn,
+ };
+}
+
+export function parseStarrocksPlan(source: string): PlanParseResult {
+ if (!source.trim()) {
+ return { ok: false, message: STARROCKS_PLAN_EMPTY_MESSAGE };
+ }
+
+ const fragments: Fragment[] = [];
+ let fragment: Fragment | undefined;
+ // The operators from the fragment's root down to the one being read; an
+ // operator's column says which of them it hangs under.
+ let open: Parsed[] = [];
+ let current: Parsed | undefined;
+
+ for (const line of source.split("\n")) {
+ if (FRAGMENT.test(line)) {
+ fragment = {};
+ fragments.push(fragment);
+ open = [];
+ current = undefined;
+ continue;
+ }
+ if (SEPARATOR.test(line)) {
+ // Nothing past the statistics describes an operator.
+ fragment = undefined;
+ current = undefined;
+ continue;
+ }
+ if (!fragment) continue;
+
+ const sink = SINK_EXCHANGE.exec(line);
+ if (sink && !current) {
+ fragment.sink = sink[1];
+ continue;
+ }
+
+ const operator = OPERATOR.exec(line);
+ if (operator) {
+ const [, lead, number, name] = operator;
+ const properties: PlanProperty[] = [];
+ let nodeType = name.trim();
+ const planNode = PLAN_NODE_ID.exec(nodeType);
+ if (planNode) {
+ nodeType = nodeType.slice(0, planNode.index).trim();
+ addPlanProperty(properties, "Plan node id", planNode[1]);
+ }
+ const node: Parsed = {
+ column: lead.length,
+ id: number,
+ nodeType,
+ properties,
+ children: [],
+ };
+ while (open.length > 0 && open[open.length - 1].column > node.column) {
+ open.pop();
+ }
+ const parent = open[open.length - 1];
+ if (parent) parent.children.push(node);
+ else if (!fragment.root) fragment.root = node;
+ else fragment.root.children.push(node);
+ open.push(node);
+ current = node;
+ continue;
+ }
+
+ // Anything else describes the operator above it, once the bars drawing the
+ // branch it sits in are taken off.
+ if (!current) continue;
+ const text = line.replace(/^[\s|]+/, "").trim();
+ if (!text) continue;
+ for (const [label, value] of attributesIn(text)) {
+ addPlanProperty(current.properties, label, value);
+ }
+ }
+
+ const root = fragments.find((each) => each.root)?.root;
+ if (!root) {
+ return { ok: false, message: STARROCKS_PLAN_NO_PLAN_MESSAGE };
+ }
+ const exchanges = new Map<string, Parsed>();
+ for (const each of fragments) {
+ if (each.sink && each.root) exchanges.set(each.sink, each.root);
+ }
+
+ const count = planSizeBudget();
+ return parseWithDepthLimit(() =>
+ toPlanNode(root, exchanges, "0", new Set(), 0, count)
+ );
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/README.md b/frontend/src/apps/explain-visualizer/test-data/README.md
index f3e0fe0852..0d35869cc2 100644
--- a/frontend/src/apps/explain-visualizer/test-data/README.md
+++ b/frontend/src/apps/explain-visualizer/test-data/README.md
@@ -60,6 +60,257 @@ from its output:
printf 'SET SHOWPLAN_XML ON;\nGO\n<statement>\nGO\n' | sqlcmd -S localhost -U sa -C -d plandb -y 0
```
+## `cockroachdb/`
+
+Not an EXPLAIN format: CockroachDB has none that returns a document. These are
+the payloads behind the diagram link `EXPLAIN (DISTSQL)` prints beside its text
+plan, decoded by the driver, captured from CockroachDB 24.3. Processors with
+the streams between them, and no estimate of any kind — the row counts are in
+the text plan, not in the link.
+
+| File | Shape it covers |
+| --- | --- |
+| `scan-filter-group.json` | A read, a filter and an aggregator in one chain |
+| `index-join.json` | A bounded index read feeding a lookup join, each naming its own table |
+| `sort-limit.json` | A top-K sorter over a read whose spans cover everything |
+
+To add one, run `EXPLAIN (DISTSQL) <query>` through the driver with
+`QueryContext{Explain: true}` and `ExplainFormat_JSON`, which is what decodes
+the link.
+
+## `mongodb/`
+
+`explain()` output from MongoDB 5, captured through the driver so each file is
+exactly what Bytebase hands the viewer. The database name in a namespace is the
+one the test container generated, which is why it reads `test_1` rather than
+anything meaningful — these are verbatim.
+
+MongoDB's planner publishes no estimate at all, so the plans carry shape and
+index usage; only `executionStats` adds numbers, and only by running the query.
+
+| File | Shape it covers |
+| --- | --- |
+| `collection-scan.json` | A `COLLSCAN` with a filter — a query with no index to use |
+| `index-scan-sort.json` | `SORT` over `FETCH` over `IXSCAN`, with the index bounds |
+| `aggregate-group.json` | An aggregation's `stages` pipeline, whose `$cursor` holds the read's own plan |
+| `measured-collection-scan.json` | `explain("executionStats")`: the same tree with rows returned and documents examined |
+| `measured-aggregate-group.json` | A measured pipeline, where each stage states its rows and its spill counters beside itself rather than in its body |
+| `slot-based-index-scan.json` | The slot-based engine's shape: the tree under `winningPlan.queryPlan`, beside the plan it compiled for itself |
+| `sharded-index-scan.json` | A sharded collection: each shard's own plan under the `SHARD_MERGE` that reads them, each naming its shard and namespace |
+| `measured-sharded-index-scan.json` | The same query run, where a shard's entry holds `executionStages` and states no namespace |
+| `measured-slot-based-join.json` | A measured slot-based plan, whose `nlj` holds its two sides under `outerStage` and `innerStage` |
+| `sharded-aggregate-group.json` | A pipeline split across shards: no `stages` of its own, each shard's part under `shards` and the merger's under `splitPipeline` |
+
+The slot-based one is from MongoDB 7, which runs the classic engine by
+default; `db.adminCommand({ setParameter: 1, internalQueryFrameworkControl:
+"trySbeEngine" })` is what makes it choose the other one. The sharded pair is
+from a cluster of two single-node shards behind a `mongos`, explained through
+the router on a collection sharded by a hashed key.
+
+To add one, run the statement through the driver with
+`QueryContext{Explain: true}`, or in `mongosh`:
+
+```
+db.orders.find({ total: { $gt: 880 } }).explain()
+```
+
+## `mysql/`
+
+`EXPLAIN FORMAT=JSON` output against the same schema, with
+`orders_customer_id_idx` on `orders(customer_id)` and both tables analyzed.
+MySQL 8.0 and MariaDB 11.8 put the same shape under different keys, so one
+parser reads both and the `mariadb-` files are the second dialect's.
+
+| File | Server | Shape it covers |
+| --- | --- | --- |
+| `full-scan-filter.json` | MySQL | A query block over one scan — the smallest real plan |
+| `group-sort-join.json` | MySQL | An ordering over a grouping over a two-table join |
+| `derived-table.json` | MySQL | A derived table materialized from its own query block |
+| `attached-subquery.json` | MySQL | A real table's scan carrying a subquery's operators under `attached_subqueries`, which a derived table's `materialized_from_subquery` is not |
+| `ordering-filesort.json` | MySQL | A filesort, whose `sort_cost` is the sort's alone where the block's `query_cost` is the whole |
+| `union-distinct.json` | MySQL | A union result over two query specifications |
+| `mariadb-sort-temporary-join.json` | MariaDB | `filesort` and `temporary_table` where MySQL says `ordering_operation` and `grouping_operation` |
+| `mariadb-block-nl-join.json` | MariaDB | `block-nl-join`, a join wrapper holding the table it buffers |
+
+To add one:
+
+```bash
+docker exec <container> mysql -uroot -p<password> <database> -N -B -r \
+ -e "EXPLAIN FORMAT=JSON <query>" > mysql/<shape>.json
+```
+
+## `starrocks/`
+
+`EXPLAIN` output from StarRocks 3.4 against the same schema. StarRocks rejects
+every JSON spelling, so its text plan is what there is. A plan is a list of
+fragments joined where one sends to another's exchange, and within a fragment
+the operators are drawn as a tree, a second input introduced by `|----` and
+drawn in a branch behind a bar.
+
+`EXPLAIN COSTS` would state a cardinality on every operator rather than on the
+scans alone, but it is a different plan from the one a plain EXPLAIN returns,
+and the editor asks for the plain one.
+
+| File | Shape it covers |
+| --- | --- |
+| `single-scan.txt` | Two fragments: a scan sending to the exchange that reads it |
+| `scan-aggregate.txt` | A partial and a final aggregate either side of an exchange |
+| `join-exchange.txt` | A join whose two inputs each arrive over their own exchange |
+| `nested-join-branch.txt` | A join drawn inside another's `|----` branch, bars and all |
+
+To add one:
+
+```bash
+docker exec <container> mysql -h127.0.0.1 -P9030 -uroot <database> -N -B -r \
+ -e "EXPLAIN <query>" > starrocks/<shape>.txt
+```
+
+## `doris/`
+
+`EXPLAIN` output from Apache Doris 3.1 against the same schema, read by the
+StarRocks parser: StarRocks forked from Doris and their plans still agree on
+the fragments and the tree. Doris rejects every JSON spelling too, so its text
+plan is what there is.
+
+What differs is how an operator spells itself. Doris prefixes the vectorized
+operators with `V`, prints its own plan node id after the name, packs an
+operator's numbers onto one line, qualifies a scanned table with its database,
+and prints the statistics it planned from under a rule of equals signs.
+
+| File | Shape it covers |
+| --- | --- |
+| `single-scan.txt` | Two fragments, and the `avgRowSize=0.0` Doris prints with no column statistics |
+| `analyzed-join.txt` | The same tables once Doris had analyzed them, so it states rows and width — and groups a standalone cardinality by thousands |
+| `scan-aggregate.txt` | A partial and a final aggregate either side of an exchange |
+| `join-exchange.txt` | A broadcast join, and the statistics that follow the operator printed last |
+
+To add one, the same client as above against a Doris frontend.
+
+## `tidb/`
+
+`EXPLAIN FORMAT=tidb_json` output from TiDB 8.5 against the same schema. TiDB
+reports no cost in this format or any other the editor can ask for, so these
+plans carry rows alone.
+
+| File | Shape it covers |
+| --- | --- |
+| `table-reader-selection.json` | A reader over a coprocessor selection over a full scan |
+| `index-hash-join.json` | A join's build and probe sides, and an index lookup's own two reads |
+| `union-hash-agg.json` | A union under a hash aggregate |
+| `measured-hash-join.json` | `EXPLAIN ANALYZE`: actual rows, and the `executeInfo` string the parser does not read timings from |
+
+To add one, `EXPLAIN FORMAT=tidb_json` through the same client as above.
+
+## `oracle/`
+
+Oracle states a plan as rows of `PLAN_TABLE`, so these are what the driver
+renders those rows as — a JSON array, one object per operator, lower-cased
+column names, columns the optimizer said nothing about left out. Captured from
+Oracle Free 23ai against the same schema, with `orders_customer_id_idx` on
+`orders(customer_id)` and the schema analyzed. Numbers arrive as strings
+because that is how the Oracle driver returns `NUMBER`.
+
+| File | Shape it covers |
+| --- | --- |
+| `full-scan-filter.json` | A statement over one full scan — the smallest real plan |
+| `hash-join-group-sort.json` | An adaptive join: a hash join beside the nested loops and statistics collector Oracle keeps as the alternative |
+| `index-range-scan.json` | A table read by rowid from an index range scan |
+| `union-distinct.json` | `UNION-ALL` under the `HASH UNIQUE` that makes it distinct |
+
+To add one, `EXPLAIN PLAN SET STATEMENT_ID = '<id>' FOR <query>` and then select
+the columns `planStepsQuery` lists (see `backend/plugin/db/oracle/oracle.go`)
+from `PLAN_TABLE` where `statement_id = '<id>'`, ordered by `id`.
+
+## `clickhouse/`
+
+`EXPLAIN json = 1, indexes = 1` output from ClickHouse 24.8 against an `orders`
+table of 50,000 rows. ClickHouse publishes no cost or row estimate in any
+EXPLAIN it offers, so these plans carry shape, descriptions and index
+accounting alone.
+
+| File | Shape it covers |
+| --- | --- |
+| `read-filter-aggregate.json` | The pipeline from a read up through an aggregate, a sort and a limit |
+| `primary-key-range.json` | A read whose primary-key index entry reports the parts and granules it kept |
+| `join-two-tables.json` | A join over a table read and a table function, which names no table |
+
+To add one:
+
+```bash
+curl -s -u default:<password> --data-binary \
+ "EXPLAIN json = 1, indexes = 1 <query> FORMAT TSVRaw" http://localhost:8123/ \
+ > clickhouse/<shape>.json
+```
+
+`FORMAT TSVRaw` matters: the HTTP interface otherwise escapes the plan's
+newlines into a TSV cell, which is not what the driver hands the viewer.
+
+## `trino/`
+
+`EXPLAIN (FORMAT JSON)` output from Trino 482 against the `tpch` connector's
+`sf1` schema, which has statistics behind it. Trino returns the fragments it
+would distribute, keyed by number, so these files are objects rather than
+trees; the parser splices them at each `RemoteSource`.
+
+| File | Shape it covers |
+| --- | --- |
+| `scan-filter-project.json` | A single fragment whose one operator fuses a scan, a filter and a projection, each with its own estimate |
+| `join-aggregate-fragments.json` | Three fragments: a partial and a final aggregate either side of a join |
+| `sort-limit.json` | Two fragments of partial top-N under a final one |
+
+To add one:
+
+```bash
+docker exec <container> trino --server localhost:8080 --catalog tpch \
+ --schema sf1 --output-format TSV --execute "EXPLAIN (FORMAT JSON) <query>"
+```
+
+The client returns it as a quoted, escaped TSV cell; unescape it before saving.
+
+## `oceanbase/`
+
+`EXPLAIN FORMAT=JSON` output from OceanBase CE 4.3 against the same schema,
+with `orders_customer_id_idx` on `orders(customer_id)`. Each operator names its
+children under `CHILD_1`, `CHILD_2`, and `EST.TIME(us)` covers an operator and
+everything below it.
+
+| File | Shape it covers |
+| --- | --- |
+| `full-scan-filter.json` | One operator — the smallest real plan |
+| `hash-join-group-sort.json` | A sort over a group-by over a two-table hash join |
+| `index-lookup.json` | A range scan, which is not a read of a whole table |
+| `union-distinct.json` | A merge union with its two branches |
+
+To add one, `EXPLAIN FORMAT=JSON <query>` through `obclient -N -B -r`.
+
+## `redshift/`
+
+Redshift's text plan, which is the only plan it publishes. Unlike every other
+directory here these were not captured by this repository: Redshift runs
+nowhere but a cluster, so the four `XN` plans are AWS's own documented output
+over the TICKIT sample schema, which the affected-rows estimator in
+`backend/plugin/db/redshift/stats.go` already pins against.
+
+`postgres-same-grammar.txt` is the exception, and the point of it. Redshift
+inherited PostgreSQL's text format and prefixed its operators with `XN`, so a
+plan captured from a real PostgreSQL 17 server exercises the same indentation,
+the same cost tuple and the same attribute lines — which is what checks the
+grammar against output a server actually produced.
+
+| File | Server | Shape it covers |
+| --- | --- | --- |
+| `hash-join-broadcast.txt` | Redshift (AWS docs) | A broadcast join over two scans, the whole plan indented one space |
+| `three-way-join.txt` | Redshift (AWS docs) | A merge join under a hash join, with both distribution strategies |
+| `hash-aggregate.txt` | Redshift (AWS docs) | An aggregate over a scan |
+| `scan-filter.txt` | Redshift (AWS docs) | One scan and its filter |
+| `postgres-same-grammar.txt` | PostgreSQL 17 | The same grammar without the `XN` prefix, captured here |
+
+To add a PostgreSQL one:
+
+```bash
+psql -At -c "EXPLAIN <query>" > redshift/<shape>.txt
+```
+
## `spanner/`
The Spanner emulator does not plan queries, so these are production Spanner
diff --git a/frontend/src/apps/explain-visualizer/test-data/clickhouse/join-two-tables.json b/frontend/src/apps/explain-visualizer/test-data/clickhouse/join-two-tables.json
new file mode 100644
index 0000000000..4e36d8f20c
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/clickhouse/join-two-tables.json
@@ -0,0 +1,45 @@
+[
+ {
+ "Plan": {
+ "Node Type": "Expression",
+ "Description": "(Project names + (Projection + DROP unused columns after JOIN))",
+ "Plans": [
+ {
+ "Node Type": "Join",
+ "Description": "JOIN FillRightFirst",
+ "Plans": [
+ {
+ "Node Type": "Expression",
+ "Description": "(JOIN actions + Change column names to column identifiers)",
+ "Plans": [
+ {
+ "Node Type": "ReadFromMergeTree",
+ "Description": "default.orders",
+ "Indexes": [
+ {
+ "Type": "PrimaryKey",
+ "Condition": "true",
+ "Initial Parts": 1,
+ "Selected Parts": 1,
+ "Initial Granules": 6,
+ "Selected Granules": 6
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "Node Type": "Expression",
+ "Description": "(JOIN actions + (Change column names to column identifiers + (Project names + (Projection + Change column names to column identifiers))))",
+ "Plans": [
+ {
+ "Node Type": "ReadFromSystemNumbers"
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ }
+]
diff --git a/frontend/src/apps/explain-visualizer/test-data/clickhouse/primary-key-range.json b/frontend/src/apps/explain-visualizer/test-data/clickhouse/primary-key-range.json
new file mode 100644
index 0000000000..46bc447351
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/clickhouse/primary-key-range.json
@@ -0,0 +1,30 @@
+[
+ {
+ "Plan": {
+ "Node Type": "Expression",
+ "Description": "(Project names + Projection)",
+ "Plans": [
+ {
+ "Node Type": "Expression",
+ "Plans": [
+ {
+ "Node Type": "ReadFromMergeTree",
+ "Description": "default.orders",
+ "Indexes": [
+ {
+ "Type": "PrimaryKey",
+ "Keys": ["id"],
+ "Condition": "and((id in (-Inf, 200]), (id in [100, +Inf)))",
+ "Initial Parts": 1,
+ "Selected Parts": 1,
+ "Initial Granules": 6,
+ "Selected Granules": 1
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ }
+]
diff --git a/frontend/src/apps/explain-visualizer/test-data/clickhouse/read-filter-aggregate.json b/frontend/src/apps/explain-visualizer/test-data/clickhouse/read-filter-aggregate.json
new file mode 100644
index 0000000000..beaaaad1a0
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/clickhouse/read-filter-aggregate.json
@@ -0,0 +1,58 @@
+[
+ {
+ "Plan": {
+ "Node Type": "Expression",
+ "Description": "Project names",
+ "Plans": [
+ {
+ "Node Type": "Limit",
+ "Description": "preliminary LIMIT (without OFFSET)",
+ "Plans": [
+ {
+ "Node Type": "Sorting",
+ "Description": "Sorting for ORDER BY",
+ "Plans": [
+ {
+ "Node Type": "Expression",
+ "Description": "(Before ORDER BY + Projection)",
+ "Plans": [
+ {
+ "Node Type": "Aggregating",
+ "Plans": [
+ {
+ "Node Type": "Expression",
+ "Description": "Before GROUP BY",
+ "Plans": [
+ {
+ "Node Type": "Expression",
+ "Plans": [
+ {
+ "Node Type": "ReadFromMergeTree",
+ "Description": "default.orders",
+ "Indexes": [
+ {
+ "Type": "PrimaryKey",
+ "Condition": "true",
+ "Initial Parts": 1,
+ "Selected Parts": 1,
+ "Initial Granules": 6,
+ "Selected Granules": 6
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ }
+]
diff --git a/frontend/src/apps/explain-visualizer/test-data/cockroachdb/index-join.json b/frontend/src/apps/explain-visualizer/test-data/cockroachdb/index-join.json
new file mode 100644
index 0000000000..7604ecbd20
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/cockroachdb/index-join.json
@@ -0,0 +1,64 @@
+{
+ "sql": "EXPLAIN (DISTSQL) SELECT o.id, c.country FROM orders AS o JOIN customers AS c ON c.id = o.customer_id WHERE o.customer_id \u003c 10",
+ "nodeNames": ["1"],
+ "processors": [
+ {
+ "nodeIdx": 0,
+ "inputs": [],
+ "core": {
+ "title": "TableReader/0",
+ "details": [
+ "orders@idx_customer",
+ "Columns: id, customer_id",
+ "Spans: /!NULL-/10"
+ ]
+ },
+ "outputs": [],
+ "stage": 1,
+ "processorID": 0
+ },
+ {
+ "nodeIdx": 0,
+ "inputs": [],
+ "core": {
+ "title": "JoinReader/1",
+ "details": [
+ "customers@customers_pkey",
+ "Lookup join on: @2",
+ "ON @3 \u003c 10:::INT8",
+ "Columns: id, country",
+ "Out: @1,@4"
+ ]
+ },
+ "outputs": [],
+ "stage": 2,
+ "processorID": 1
+ },
+ {
+ "nodeIdx": 0,
+ "inputs": [],
+ "core": { "title": "Response", "details": [] },
+ "outputs": [],
+ "stage": 0,
+ "processorID": -1
+ }
+ ],
+ "edges": [
+ {
+ "sourceProc": 0,
+ "sourceOutput": 0,
+ "destProc": 1,
+ "destInput": 0,
+ "streamID": 0
+ },
+ {
+ "sourceProc": 1,
+ "sourceOutput": 0,
+ "destProc": 2,
+ "destInput": 0,
+ "streamID": 0
+ }
+ ],
+ "flow_id": "5fc3c44f-5d74-4d53-9b4d-dcda13f0dadd",
+ "flags": { "ShowInputTypes": false, "MakeDeterministic": false }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/cockroachdb/scan-filter-group.json b/frontend/src/apps/explain-visualizer/test-data/cockroachdb/scan-filter-group.json
new file mode 100644
index 0000000000..f079ca16bf
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/cockroachdb/scan-filter-group.json
@@ -0,0 +1,76 @@
+{
+ "sql": "EXPLAIN (DISTSQL) SELECT customer_id, sum(total) FROM orders WHERE total \u003e 880 GROUP BY customer_id",
+ "nodeNames": ["1"],
+ "processors": [
+ {
+ "nodeIdx": 0,
+ "inputs": [],
+ "core": {
+ "title": "TableReader/0",
+ "details": [
+ "orders@orders_pkey",
+ "Columns: customer_id, total",
+ "Spans: -"
+ ]
+ },
+ "outputs": [],
+ "stage": 1,
+ "processorID": 0
+ },
+ {
+ "nodeIdx": 0,
+ "inputs": [],
+ "core": {
+ "title": "Filterer/1",
+ "details": ["Filter: @2 \u003e 880:::INT8"]
+ },
+ "outputs": [],
+ "stage": 2,
+ "processorID": 1
+ },
+ {
+ "nodeIdx": 0,
+ "inputs": [],
+ "core": {
+ "title": "Aggregator/2",
+ "details": ["@1", "ANY_NOT_NULL(@1)", "SUM(@2)"]
+ },
+ "outputs": [],
+ "stage": 3,
+ "processorID": 2
+ },
+ {
+ "nodeIdx": 0,
+ "inputs": [],
+ "core": { "title": "Response", "details": [] },
+ "outputs": [],
+ "stage": 0,
+ "processorID": -1
+ }
+ ],
+ "edges": [
+ {
+ "sourceProc": 0,
+ "sourceOutput": 0,
+ "destProc": 1,
+ "destInput": 0,
+ "streamID": 0
+ },
+ {
+ "sourceProc": 1,
+ "sourceOutput": 0,
+ "destProc": 2,
+ "destInput": 0,
+ "streamID": 1
+ },
+ {
+ "sourceProc": 2,
+ "sourceOutput": 0,
+ "destProc": 3,
+ "destInput": 0,
+ "streamID": 0
+ }
+ ],
+ "flow_id": "a6c7cbb4-51a8-4efe-a974-f81a2db05a29",
+ "flags": { "ShowInputTypes": false, "MakeDeterministic": false }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/cockroachdb/sort-limit.json b/frontend/src/apps/explain-visualizer/test-data/cockroachdb/sort-limit.json
new file mode 100644
index 0000000000..be9ec75002
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/cockroachdb/sort-limit.json
@@ -0,0 +1,51 @@
+{
+ "sql": "EXPLAIN (DISTSQL) SELECT id, total FROM orders ORDER BY total DESC LIMIT 5",
+ "nodeNames": ["1"],
+ "processors": [
+ {
+ "nodeIdx": 0,
+ "inputs": [],
+ "core": {
+ "title": "TableReader/0",
+ "details": ["orders@orders_pkey", "Columns: id, total", "Spans: -"]
+ },
+ "outputs": [],
+ "stage": 1,
+ "processorID": 0
+ },
+ {
+ "nodeIdx": 0,
+ "inputs": [],
+ "core": { "title": "Sorter/1", "details": ["@2-", "TopK: 5"] },
+ "outputs": [],
+ "stage": 2,
+ "processorID": 1
+ },
+ {
+ "nodeIdx": 0,
+ "inputs": [],
+ "core": { "title": "Response", "details": [] },
+ "outputs": [],
+ "stage": 0,
+ "processorID": -1
+ }
+ ],
+ "edges": [
+ {
+ "sourceProc": 0,
+ "sourceOutput": 0,
+ "destProc": 1,
+ "destInput": 0,
+ "streamID": 0
+ },
+ {
+ "sourceProc": 1,
+ "sourceOutput": 0,
+ "destProc": 2,
+ "destInput": 0,
+ "streamID": 0
+ }
+ ],
+ "flow_id": "72d594d7-ec44-4a78-ac68-c57689169bec",
+ "flags": { "ShowInputTypes": false, "MakeDeterministic": false }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/doris/analyzed-join.txt b/frontend/src/apps/explain-visualizer/test-data/doris/analyzed-join.txt
new file mode 100644
index 0000000000..ef362bc785
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/doris/analyzed-join.txt
@@ -0,0 +1,103 @@
+PLAN FRAGMENT 0
+ OUTPUT EXPRS:
+ country[#19]
+ sum(o.total)[#20]
+ PARTITION: UNPARTITIONED
+
+ HAS_COLO_PLAN_NODE: false
+
+ VRESULT SINK
+ MYSQL_PROTOCAL
+
+ 7:VEXCHANGE
+ offset: 0
+ distribute expr lists: country[#19]
+
+PLAN FRAGMENT 1
+
+ PARTITION: HASH_PARTITIONED: country[#17]
+
+ HAS_COLO_PLAN_NODE: true
+
+ STREAM DATA SINK
+ EXCHANGE ID: 07
+ UNPARTITIONED
+
+ 6:VAGGREGATE (merge finalize)(456)
+ | output: sum(partial_sum(total)[#18])[#20]
+ | group by: country[#17]
+ | sortByGroupKey:false
+ | cardinality=4
+ | distribute expr lists: country[#17]
+ |
+ 5:VEXCHANGE
+ offset: 0
+ distribute expr lists:
+
+PLAN FRAGMENT 2
+
+ PARTITION: HASH_PARTITIONED: id[#5]
+
+ HAS_COLO_PLAN_NODE: false
+
+ STREAM DATA SINK
+ EXCHANGE ID: 05
+ HASH_PARTITIONED: country[#17]
+
+ 4:VAGGREGATE (update serialize)(446)
+ | STREAMING
+ | output: partial_sum(total[#16])[#18]
+ | group by: country[#15]
+ | sortByGroupKey:false
+ | cardinality=4
+ | distribute expr lists:
+ |
+ 3:VHASH JOIN(436)
+ | join op: INNER JOIN(BROADCAST)[]
+ | equal join conjunct: (customer_id[#9] = id[#3])
+ | cardinality=4,499
+ | vec output tuple id: 5
+ | output tuple id: 5
+ | vIntermediate tuple ids: 4
+ | hash output slot ids: 4 10
+ | final projections: country[#14], total[#12]
+ | final project output tuple id: 5
+ | distribute expr lists:
+ | distribute expr lists:
+ |
+ |----1:VEXCHANGE
+ | offset: 0
+ | distribute expr lists: id[#3]
+ |
+ 2:VOlapScanNode(410)
+ TABLE: qp.orders(orders), PREAGGREGATION: ON
+ PREDICATES: (total[#7] > 100)
+ partitions=1/1 (orders)
+ tablets=2/2, tabletList=1793041799804,1793041799806
+ cardinality=5000, avgRowSize=8.398, numNodes=1
+ pushAggOp=NONE
+ final projections: customer_id[#6], total[#7]
+ final project output tuple id: 3
+
+PLAN FRAGMENT 3
+
+ PARTITION: HASH_PARTITIONED: id[#0]
+
+ HAS_COLO_PLAN_NODE: false
+
+ STREAM DATA SINK
+ EXCHANGE ID: 01
+ UNPARTITIONED
+
+ 0:VOlapScanNode(421)
+ TABLE: qp.customers(customers), PREAGGREGATION: ON
+ partitions=1/1 (customers)
+ tablets=2/2, tabletList=1793041799797,1793041799799
+ cardinality=500, avgRowSize=57.19, numNodes=1
+ pushAggOp=NONE
+ final projections: id[#0], country[#2]
+ final project output tuple id: 1
+
+
+
+========== STATISTICS ==========
diff --git a/frontend/src/apps/explain-visualizer/test-data/doris/join-exchange.txt b/frontend/src/apps/explain-visualizer/test-data/doris/join-exchange.txt
new file mode 100644
index 0000000000..c3a9116e56
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/doris/join-exchange.txt
@@ -0,0 +1,104 @@
+PLAN FRAGMENT 0
+ OUTPUT EXPRS:
+ country[#19]
+ sum(o.total)[#20]
+ PARTITION: UNPARTITIONED
+
+ HAS_COLO_PLAN_NODE: false
+
+ VRESULT SINK
+ MYSQL_PROTOCAL
+
+ 7:VEXCHANGE
+ offset: 0
+ distribute expr lists: country[#19]
+
+PLAN FRAGMENT 1
+
+ PARTITION: HASH_PARTITIONED: country[#17]
+
+ HAS_COLO_PLAN_NODE: true
+
+ STREAM DATA SINK
+ EXCHANGE ID: 07
+ UNPARTITIONED
+
+ 6:VAGGREGATE (merge finalize)(425)
+ | output: sum(partial_sum(total)[#18])[#20]
+ | group by: country[#17]
+ | sortByGroupKey:false
+ | cardinality=1
+ | distribute expr lists: country[#17]
+ |
+ 5:VEXCHANGE
+ offset: 0
+ distribute expr lists:
+
+PLAN FRAGMENT 2
+
+ PARTITION: HASH_PARTITIONED: id[#5]
+
+ HAS_COLO_PLAN_NODE: false
+
+ STREAM DATA SINK
+ EXCHANGE ID: 05
+ HASH_PARTITIONED: country[#17]
+
+ 4:VAGGREGATE (update serialize)(415)
+ | STREAMING
+ | output: partial_sum(total[#16])[#18]
+ | group by: country[#15]
+ | sortByGroupKey:false
+ | cardinality=1
+ | distribute expr lists:
+ |
+ 3:VHASH JOIN(405)
+ | join op: INNER JOIN(BROADCAST)[]
+ | equal join conjunct: (customer_id[#9] = id[#3])
+ | cardinality=1
+ | vec output tuple id: 5
+ | output tuple id: 5
+ | vIntermediate tuple ids: 4
+ | hash output slot ids: 4 10
+ | final projections: country[#14], total[#12]
+ | final project output tuple id: 5
+ | distribute expr lists:
+ | distribute expr lists:
+ |
+ |----1:VEXCHANGE
+ | offset: 0
+ | distribute expr lists: id[#3]
+ |
+ 2:VOlapScanNode(379)
+ TABLE: qp.orders(orders), PREAGGREGATION: ON
+ PREDICATES: (total[#7] > 880)
+ partitions=1/1 (orders)
+ tablets=2/2, tabletList=1793041799804,1793041799806
+ cardinality=1, avgRowSize=0.0, numNodes=1
+ pushAggOp=NONE
+ final projections: customer_id[#6], total[#7]
+ final project output tuple id: 3
+
+PLAN FRAGMENT 3
+
+ PARTITION: HASH_PARTITIONED: id[#0]
+
+ HAS_COLO_PLAN_NODE: false
+
+ STREAM DATA SINK
+ EXCHANGE ID: 01
+ UNPARTITIONED
+
+ 0:VOlapScanNode(390)
+ TABLE: qp.customers(customers), PREAGGREGATION: ON
+ partitions=1/1 (customers)
+ tablets=2/2, tabletList=1793041799797,1793041799799
+ cardinality=1, avgRowSize=0.0, numNodes=1
+ pushAggOp=NONE
+ final projections: id[#0], country[#2]
+ final project output tuple id: 1
+
+
+
+========== STATISTICS ==========
+planed with unknown column statistics
diff --git a/frontend/src/apps/explain-visualizer/test-data/doris/scan-aggregate.txt b/frontend/src/apps/explain-visualizer/test-data/doris/scan-aggregate.txt
new file mode 100644
index 0000000000..30e1830b5d
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/doris/scan-aggregate.txt
@@ -0,0 +1,68 @@
+PLAN FRAGMENT 0
+ OUTPUT EXPRS:
+ customer_id[#8]
+ sum(total)[#9]
+ PARTITION: UNPARTITIONED
+
+ HAS_COLO_PLAN_NODE: false
+
+ VRESULT SINK
+ MYSQL_PROTOCAL
+
+ 4:VEXCHANGE
+ offset: 0
+ distribute expr lists: customer_id[#8]
+
+PLAN FRAGMENT 1
+
+ PARTITION: HASH_PARTITIONED: customer_id[#6]
+
+ HAS_COLO_PLAN_NODE: true
+
+ STREAM DATA SINK
+ EXCHANGE ID: 04
+ UNPARTITIONED
+
+ 3:VAGGREGATE (merge finalize)(237)
+ | output: sum(partial_sum(total)[#7])[#9]
+ | group by: customer_id[#6]
+ | sortByGroupKey:false
+ | cardinality=0
+ | distribute expr lists: customer_id[#6]
+ |
+ 2:VEXCHANGE
+ offset: 0
+ distribute expr lists:
+
+PLAN FRAGMENT 2
+
+ PARTITION: HASH_PARTITIONED: id[#0]
+
+ HAS_COLO_PLAN_NODE: false
+
+ STREAM DATA SINK
+ EXCHANGE ID: 02
+ HASH_PARTITIONED: customer_id[#6]
+
+ 1:VAGGREGATE (update serialize)(227)
+ | STREAMING
+ | output: partial_sum(total[#5])[#7]
+ | group by: customer_id[#4]
+ | sortByGroupKey:false
+ | cardinality=0
+ | distribute expr lists:
+ |
+ 0:VOlapScanNode(212)
+ TABLE: qp.orders(orders), PREAGGREGATION: ON
+ PREDICATES: (total[#2] > 880)
+ partitions=1/1 (orders)
+ tablets=2/2, tabletList=1793041799804,1793041799806
+ cardinality=1, avgRowSize=0.0, numNodes=1
+ pushAggOp=NONE
+ final projections: customer_id[#1], total[#2]
+ final project output tuple id: 1
+
+
+
+========== STATISTICS ==========
+planed with unknown column statistics
diff --git a/frontend/src/apps/explain-visualizer/test-data/doris/single-scan.txt b/frontend/src/apps/explain-visualizer/test-data/doris/single-scan.txt
new file mode 100644
index 0000000000..be1e0d4789
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/doris/single-scan.txt
@@ -0,0 +1,39 @@
+PLAN FRAGMENT 0
+ OUTPUT EXPRS:
+ id[#0]
+ customer_id[#1]
+ total[#2]
+ status[#3]
+ PARTITION: UNPARTITIONED
+
+ HAS_COLO_PLAN_NODE: false
+
+ VRESULT SINK
+ MYSQL_PROTOCAL
+
+ 1:VEXCHANGE
+ offset: 0
+ distribute expr lists: id[#0]
+
+PLAN FRAGMENT 1
+
+ PARTITION: HASH_PARTITIONED: id[#0]
+
+ HAS_COLO_PLAN_NODE: false
+
+ STREAM DATA SINK
+ EXCHANGE ID: 01
+ UNPARTITIONED
+
+ 0:VOlapScanNode(85)
+ TABLE: qp.orders(orders), PREAGGREGATION: ON
+ PREDICATES: (total[#2] > 880)
+ partitions=1/1 (orders)
+ tablets=2/2, tabletList=1793041799804,1793041799806
+ cardinality=1, avgRowSize=0.0, numNodes=1
+ pushAggOp=NONE
+
+
+
+========== STATISTICS ==========
+planed with unknown column statistics
diff --git a/frontend/src/apps/explain-visualizer/test-data/mongodb/aggregate-group.json b/frontend/src/apps/explain-visualizer/test-data/mongodb/aggregate-group.json
new file mode 100644
index 0000000000..7339693a13
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mongodb/aggregate-group.json
@@ -0,0 +1,56 @@
+{
+ "explainVersion": "1",
+ "stages": [
+ {
+ "$cursor": {
+ "queryPlanner": {
+ "namespace": "test_1.orders",
+ "indexFilterSet": false,
+ "parsedQuery": { "status": { "$eq": "open" } },
+ "queryHash": "8C054E6F",
+ "planCacheKey": "B16D32BC",
+ "maxIndexedOrSolutionsReached": false,
+ "maxIndexedAndSolutionsReached": false,
+ "maxScansToExplodeReached": false,
+ "winningPlan": {
+ "stage": "PROJECTION_SIMPLE",
+ "transformBy": { "customer_id": 1, "total": 1, "_id": 0 },
+ "inputStage": {
+ "stage": "COLLSCAN",
+ "filter": { "status": { "$eq": "open" } },
+ "direction": "forward"
+ }
+ },
+ "rejectedPlans": []
+ }
+ }
+ },
+ { "$group": { "_id": "$customer_id", "total": { "$sum": "$total" } } }
+ ],
+ "serverInfo": {
+ "host": "9814f86922bc",
+ "port": 27017,
+ "version": "5.0.31",
+ "gitVersion": "973237567d45610d6976d5d489dfaaef6a52c2f9"
+ },
+ "serverParameters": {
+ "internalQueryFacetBufferSizeBytes": 104857600,
+ "internalQueryFacetMaxOutputDocSizeBytes": 104857600,
+ "internalLookupStageIntermediateDocumentMaxSizeBytes": 104857600,
+ "internalDocumentSourceGroupMaxMemoryBytes": 104857600,
+ "internalQueryMaxBlockingSortMemoryUsageBytes": 104857600,
+ "internalQueryProhibitBlockingMergeOnMongoS": 0,
+ "internalQueryMaxAddToSetBytes": 104857600,
+ "internalDocumentSourceSetWindowFieldsMaxMemoryBytes": 104857600
+ },
+ "command": {
+ "aggregate": "orders",
+ "pipeline": [
+ { "$match": { "status": "open" } },
+ { "$group": { "_id": "$customer_id", "total": { "$sum": "$total" } } }
+ ],
+ "cursor": {},
+ "$db": "test_1"
+ },
+ "ok": 1
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mongodb/collection-scan.json b/frontend/src/apps/explain-visualizer/test-data/mongodb/collection-scan.json
new file mode 100644
index 0000000000..863813654a
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mongodb/collection-scan.json
@@ -0,0 +1,41 @@
+{
+ "explainVersion": "1",
+ "queryPlanner": {
+ "namespace": "test_1.orders",
+ "indexFilterSet": false,
+ "parsedQuery": { "total": { "$gt": 880 } },
+ "queryHash": "1D1F928B",
+ "planCacheKey": "4B39C5A0",
+ "maxIndexedOrSolutionsReached": false,
+ "maxIndexedAndSolutionsReached": false,
+ "maxScansToExplodeReached": false,
+ "winningPlan": {
+ "stage": "COLLSCAN",
+ "filter": { "total": { "$gt": 880 } },
+ "direction": "forward"
+ },
+ "rejectedPlans": []
+ },
+ "command": {
+ "find": "orders",
+ "filter": { "total": { "$gt": 880 } },
+ "$db": "test_1"
+ },
+ "serverInfo": {
+ "host": "9814f86922bc",
+ "port": 27017,
+ "version": "5.0.31",
+ "gitVersion": "973237567d45610d6976d5d489dfaaef6a52c2f9"
+ },
+ "serverParameters": {
+ "internalQueryFacetBufferSizeBytes": 104857600,
+ "internalQueryFacetMaxOutputDocSizeBytes": 104857600,
+ "internalLookupStageIntermediateDocumentMaxSizeBytes": 104857600,
+ "internalDocumentSourceGroupMaxMemoryBytes": 104857600,
+ "internalQueryMaxBlockingSortMemoryUsageBytes": 104857600,
+ "internalQueryProhibitBlockingMergeOnMongoS": 0,
+ "internalQueryMaxAddToSetBytes": 104857600,
+ "internalDocumentSourceSetWindowFieldsMaxMemoryBytes": 104857600
+ },
+ "ok": 1
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mongodb/index-scan-sort.json b/frontend/src/apps/explain-visualizer/test-data/mongodb/index-scan-sort.json
new file mode 100644
index 0000000000..621c323f1a
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mongodb/index-scan-sort.json
@@ -0,0 +1,59 @@
+{
+ "explainVersion": "1",
+ "queryPlanner": {
+ "namespace": "test_1.orders",
+ "indexFilterSet": false,
+ "parsedQuery": { "customer_id": { "$eq": 42 } },
+ "queryHash": "B106C1A2",
+ "planCacheKey": "4D4EE1D0",
+ "maxIndexedOrSolutionsReached": false,
+ "maxIndexedAndSolutionsReached": false,
+ "maxScansToExplodeReached": false,
+ "winningPlan": {
+ "stage": "SORT",
+ "sortPattern": { "total": -1 },
+ "memLimit": 104857600,
+ "type": "simple",
+ "inputStage": {
+ "stage": "FETCH",
+ "inputStage": {
+ "stage": "IXSCAN",
+ "keyPattern": { "customer_id": 1 },
+ "indexName": "customer_id_1",
+ "isMultiKey": false,
+ "multiKeyPaths": { "customer_id": [] },
+ "isUnique": false,
+ "isSparse": false,
+ "isPartial": false,
+ "indexVersion": 2,
+ "direction": "forward",
+ "indexBounds": { "customer_id": ["[42, 42]"] }
+ }
+ }
+ },
+ "rejectedPlans": []
+ },
+ "command": {
+ "find": "orders",
+ "filter": { "customer_id": 42 },
+ "sort": { "total": -1 },
+ "$db": "test_1"
+ },
+ "serverInfo": {
+ "host": "9814f86922bc",
+ "port": 27017,
+ "version": "5.0.31",
+ "gitVersion": "973237567d45610d6976d5d489dfaaef6a52c2f9"
+ },
+ "serverParameters": {
+ "internalQueryFacetBufferSizeBytes": 104857600,
+ "internalQueryFacetMaxOutputDocSizeBytes": 104857600,
+ "internalLookupStageIntermediateDocumentMaxSizeBytes": 104857600,
+ "internalDocumentSourceGroupMaxMemoryBytes": 104857600,
+ "internalQueryMaxBlockingSortMemoryUsageBytes": 104857600,
+ "internalQueryProhibitBlockingMergeOnMongoS": 0,
+ "internalQueryMaxAddToSetBytes": 104857600,
+ "internalDocumentSourceSetWindowFieldsMaxMemoryBytes": 104857600
+ },
+ "ok": 1
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mongodb/measured-aggregate-group.json b/frontend/src/apps/explain-visualizer/test-data/mongodb/measured-aggregate-group.json
new file mode 100644
index 0000000000..6bb77c3859
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mongodb/measured-aggregate-group.json
@@ -0,0 +1,110 @@
+{
+ "explainVersion": "1",
+ "stages": [
+ {
+ "$cursor": {
+ "queryPlanner": {
+ "namespace": "qp.orders",
+ "indexFilterSet": false,
+ "parsedQuery": {},
+ "queryHash": "8AD89786",
+ "planCacheKey": "8AD89786",
+ "optimizationTimeMillis": 0,
+ "maxIndexedOrSolutionsReached": false,
+ "maxIndexedAndSolutionsReached": false,
+ "maxScansToExplodeReached": false,
+ "winningPlan": {
+ "stage": "PROJECTION_SIMPLE",
+ "transformBy": { "customerId": 1, "total": 1, "_id": 0 },
+ "inputStage": { "stage": "COLLSCAN", "direction": "forward" }
+ },
+ "rejectedPlans": []
+ },
+ "executionStats": {
+ "executionSuccess": true,
+ "nReturned": 5000,
+ "executionTimeMillis": 6,
+ "totalKeysExamined": 0,
+ "totalDocsExamined": 5000,
+ "executionStages": {
+ "stage": "PROJECTION_SIMPLE",
+ "nReturned": 5000,
+ "executionTimeMillisEstimate": 0,
+ "works": 5001,
+ "advanced": 5000,
+ "needTime": 0,
+ "needYield": 0,
+ "saveState": 6,
+ "restoreState": 6,
+ "isEOF": 1,
+ "transformBy": { "customerId": 1, "total": 1, "_id": 0 },
+ "inputStage": {
+ "stage": "COLLSCAN",
+ "nReturned": 5000,
+ "executionTimeMillisEstimate": 0,
+ "works": 5001,
+ "advanced": 5000,
+ "needTime": 0,
+ "needYield": 0,
+ "saveState": 6,
+ "restoreState": 6,
+ "isEOF": 1,
+ "direction": "forward",
+ "docsExamined": 5000
+ }
+ }
+ }
+ },
+ "nReturned": 5000,
+ "executionTimeMillisEstimate": 4
+ },
+ {
+ "$group": { "_id": "$customerId", "n": { "$sum": "$total" } },
+ "maxAccumulatorMemoryUsageBytes": { "n": 48000 },
+ "totalOutputDataSizeBytes": 122500,
+ "usedDisk": false,
+ "spills": 0,
+ "spilledDataStorageSize": 0,
+ "numBytesSpilledEstimate": 0,
+ "spilledRecords": 0,
+ "nReturned": 500,
+ "executionTimeMillisEstimate": 4
+ },
+ {
+ "$sort": { "sortKey": { "n": -1 } },
+ "totalDataSizeSortedBytesEstimate": 126500,
+ "usedDisk": false,
+ "spills": 0,
+ "spilledDataStorageSize": 0,
+ "nReturned": 500,
+ "executionTimeMillisEstimate": 4
+ }
+ ],
+ "serverInfo": {
+ "host": "d1186ea972c8",
+ "port": 27017,
+ "version": "7.0.45",
+ "gitVersion": "a52313e13ab55c9bddf7c3ff91dab286fa381796"
+ },
+ "serverParameters": {
+ "internalQueryFacetBufferSizeBytes": 104857600,
+ "internalQueryFacetMaxOutputDocSizeBytes": 104857600,
+ "internalLookupStageIntermediateDocumentMaxSizeBytes": 104857600,
+ "internalDocumentSourceGroupMaxMemoryBytes": 104857600,
+ "internalQueryMaxBlockingSortMemoryUsageBytes": 104857600,
+ "internalQueryProhibitBlockingMergeOnMongoS": 0,
+ "internalQueryMaxAddToSetBytes": 104857600,
+ "internalDocumentSourceSetWindowFieldsMaxMemoryBytes": 104857600,
+ "internalQueryFrameworkControl": "forceClassicEngine"
+ },
+ "command": {
+ "aggregate": "orders",
+ "pipeline": [
+ { "$group": { "_id": "$customerId", "n": { "$sum": "$total" } } },
+ { "$sort": { "n": -1 } }
+ ],
+ "cursor": {},
+ "$db": "qp"
+ },
+ "ok": 1
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mongodb/measured-collection-scan.json b/frontend/src/apps/explain-visualizer/test-data/mongodb/measured-collection-scan.json
new file mode 100644
index 0000000000..1ef2504a3c
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mongodb/measured-collection-scan.json
@@ -0,0 +1,61 @@
+{
+ "explainVersion": "1",
+ "queryPlanner": {
+ "namespace": "test_1.orders",
+ "indexFilterSet": false,
+ "parsedQuery": { "total": { "$gt": 880 } },
+ "maxIndexedOrSolutionsReached": false,
+ "maxIndexedAndSolutionsReached": false,
+ "maxScansToExplodeReached": false,
+ "winningPlan": {
+ "stage": "COLLSCAN",
+ "filter": { "total": { "$gt": 880 } },
+ "direction": "forward"
+ },
+ "rejectedPlans": []
+ },
+ "executionStats": {
+ "executionSuccess": true,
+ "nReturned": 145,
+ "executionTimeMillis": 2,
+ "totalKeysExamined": 0,
+ "totalDocsExamined": 5000,
+ "executionStages": {
+ "stage": "COLLSCAN",
+ "filter": { "total": { "$gt": 880 } },
+ "nReturned": 145,
+ "executionTimeMillisEstimate": 0,
+ "works": 5002,
+ "advanced": 145,
+ "needTime": 4856,
+ "needYield": 0,
+ "saveState": 5,
+ "restoreState": 5,
+ "isEOF": 1,
+ "direction": "forward",
+ "docsExamined": 5000
+ }
+ },
+ "command": {
+ "find": "orders",
+ "filter": { "total": { "$gt": 880 } },
+ "$db": "test_1"
+ },
+ "serverInfo": {
+ "host": "9814f86922bc",
+ "port": 27017,
+ "version": "5.0.31",
+ "gitVersion": "973237567d45610d6976d5d489dfaaef6a52c2f9"
+ },
+ "serverParameters": {
+ "internalQueryFacetBufferSizeBytes": 104857600,
+ "internalQueryFacetMaxOutputDocSizeBytes": 104857600,
+ "internalLookupStageIntermediateDocumentMaxSizeBytes": 104857600,
+ "internalDocumentSourceGroupMaxMemoryBytes": 104857600,
+ "internalQueryMaxBlockingSortMemoryUsageBytes": 104857600,
+ "internalQueryProhibitBlockingMergeOnMongoS": 0,
+ "internalQueryMaxAddToSetBytes": 104857600,
+ "internalDocumentSourceSetWindowFieldsMaxMemoryBytes": 104857600
+ },
+ "ok": 1
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mongodb/measured-sharded-index-scan.json b/frontend/src/apps/explain-visualizer/test-data/mongodb/measured-sharded-index-scan.json
new file mode 100644
index 0000000000..925f282723
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mongodb/measured-sharded-index-scan.json
@@ -0,0 +1,317 @@
+{
+ "queryPlanner": {
+ "mongosPlannerVersion": 1,
+ "winningPlan": {
+ "stage": "SHARD_MERGE",
+ "shards": [
+ {
+ "shardName": "sh1",
+ "connectionString": "sh1/qp-sh1:27018",
+ "serverInfo": {
+ "host": "fe4c19987c05",
+ "port": 27018,
+ "version": "7.0.45",
+ "gitVersion": "a52313e13ab55c9bddf7c3ff91dab286fa381796"
+ },
+ "namespace": "qp.orders",
+ "indexFilterSet": false,
+ "parsedQuery": {
+ "total": {
+ "$gt": 880
+ }
+ },
+ "queryHash": "CACA99B3",
+ "planCacheKey": "12DCEA8D",
+ "optimizationTimeMillis": 0,
+ "maxIndexedOrSolutionsReached": false,
+ "maxIndexedAndSolutionsReached": false,
+ "maxScansToExplodeReached": false,
+ "winningPlan": {
+ "stage": "SHARDING_FILTER",
+ "inputStage": {
+ "stage": "FETCH",
+ "inputStage": {
+ "stage": "IXSCAN",
+ "keyPattern": {
+ "total": 1
+ },
+ "indexName": "total_1",
+ "isMultiKey": false,
+ "multiKeyPaths": {
+ "total": []
+ },
+ "isUnique": false,
+ "isSparse": false,
+ "isPartial": false,
+ "indexVersion": 2,
+ "direction": "forward",
+ "indexBounds": {
+ "total": ["(880, inf.0]"]
+ }
+ }
+ }
+ },
+ "rejectedPlans": []
+ },
+ {
+ "shardName": "sh2",
+ "connectionString": "sh2/qp-sh2:27018",
+ "serverInfo": {
+ "host": "b209ed3472e1",
+ "port": 27018,
+ "version": "7.0.45",
+ "gitVersion": "a52313e13ab55c9bddf7c3ff91dab286fa381796"
+ },
+ "namespace": "qp.orders",
+ "indexFilterSet": false,
+ "parsedQuery": {
+ "total": {
+ "$gt": 880
+ }
+ },
+ "queryHash": "CACA99B3",
+ "planCacheKey": "12DCEA8D",
+ "optimizationTimeMillis": 0,
+ "maxIndexedOrSolutionsReached": false,
+ "maxIndexedAndSolutionsReached": false,
+ "maxScansToExplodeReached": false,
+ "winningPlan": {
+ "stage": "SHARDING_FILTER",
+ "inputStage": {
+ "stage": "FETCH",
+ "inputStage": {
+ "stage": "IXSCAN",
+ "keyPattern": {
+ "total": 1
+ },
+ "indexName": "total_1",
+ "isMultiKey": false,
+ "multiKeyPaths": {
+ "total": []
+ },
+ "isUnique": false,
+ "isSparse": false,
+ "isPartial": false,
+ "indexVersion": 2,
+ "direction": "forward",
+ "indexBounds": {
+ "total": ["(880, inf.0]"]
+ }
+ }
+ }
+ },
+ "rejectedPlans": []
+ }
+ ]
+ }
+ },
+ "executionStats": {
+ "nReturned": 2785,
+ "executionTimeMillis": 7,
+ "totalKeysExamined": 2785,
+ "totalDocsExamined": 2785,
+ "executionStages": {
+ "stage": "SHARD_MERGE",
+ "nReturned": 2785,
+ "executionTimeMillis": 7,
+ "totalKeysExamined": 2785,
+ "totalDocsExamined": 2785,
+ "totalChildMillis": {
+ "high": 0,
+ "low": 12,
+ "unsigned": false
+ },
+ "shards": [
+ {
+ "shardName": "sh1",
+ "executionSuccess": true,
+ "nReturned": 1420,
+ "executionTimeMillis": 6,
+ "totalKeysExamined": 1420,
+ "totalDocsExamined": 1420,
+ "executionStages": {
+ "stage": "SHARDING_FILTER",
+ "nReturned": 1420,
+ "executionTimeMillisEstimate": 0,
+ "works": 1421,
+ "advanced": 1420,
+ "needTime": 0,
+ "needYield": 0,
+ "saveState": 1,
+ "restoreState": 1,
+ "isEOF": 1,
+ "chunkSkips": 0,
+ "inputStage": {
+ "stage": "FETCH",
+ "nReturned": 1420,
+ "executionTimeMillisEstimate": 0,
+ "works": 1421,
+ "advanced": 1420,
+ "needTime": 0,
+ "needYield": 0,
+ "saveState": 1,
+ "restoreState": 1,
+ "isEOF": 1,
+ "docsExamined": 1420,
+ "alreadyHasObj": 0,
+ "inputStage": {
+ "stage": "IXSCAN",
+ "nReturned": 1420,
+ "executionTimeMillisEstimate": 0,
+ "works": 1421,
+ "advanced": 1420,
+ "needTime": 0,
+ "needYield": 0,
+ "saveState": 1,
+ "restoreState": 1,
+ "isEOF": 1,
+ "keyPattern": {
+ "total": 1
+ },
+ "indexName": "total_1",
+ "isMultiKey": false,
+ "multiKeyPaths": {
+ "total": []
+ },
+ "isUnique": false,
+ "isSparse": false,
+ "isPartial": false,
+ "indexVersion": 2,
+ "direction": "forward",
+ "indexBounds": {
+ "total": ["(880, inf.0]"]
+ },
+ "keysExamined": 1420,
+ "seeks": 1,
+ "dupsTested": 0,
+ "dupsDropped": 0
+ }
+ }
+ }
+ },
+ {
+ "shardName": "sh2",
+ "executionSuccess": true,
+ "nReturned": 1365,
+ "executionTimeMillis": 6,
+ "totalKeysExamined": 1365,
+ "totalDocsExamined": 1365,
+ "executionStages": {
+ "stage": "SHARDING_FILTER",
+ "nReturned": 1365,
+ "executionTimeMillisEstimate": 0,
+ "works": 1366,
+ "advanced": 1365,
+ "needTime": 0,
+ "needYield": 0,
+ "saveState": 1,
+ "restoreState": 1,
+ "isEOF": 1,
+ "chunkSkips": 0,
+ "inputStage": {
+ "stage": "FETCH",
+ "nReturned": 1365,
+ "executionTimeMillisEstimate": 0,
+ "works": 1366,
+ "advanced": 1365,
+ "needTime": 0,
+ "needYield": 0,
+ "saveState": 1,
+ "restoreState": 1,
+ "isEOF": 1,
+ "docsExamined": 1365,
+ "alreadyHasObj": 0,
+ "inputStage": {
+ "stage": "IXSCAN",
+ "nReturned": 1365,
+ "executionTimeMillisEstimate": 0,
+ "works": 1366,
+ "advanced": 1365,
+ "needTime": 0,
+ "needYield": 0,
+ "saveState": 1,
+ "restoreState": 1,
+ "isEOF": 1,
+ "keyPattern": {
+ "total": 1
+ },
+ "indexName": "total_1",
+ "isMultiKey": false,
+ "multiKeyPaths": {
+ "total": []
+ },
+ "isUnique": false,
+ "isSparse": false,
+ "isPartial": false,
+ "indexVersion": 2,
+ "direction": "forward",
+ "indexBounds": {
+ "total": ["(880, inf.0]"]
+ },
+ "keysExamined": 1365,
+ "seeks": 1,
+ "dupsTested": 0,
+ "dupsDropped": 0
+ }
+ }
+ }
+ }
+ ]
+ }
+ },
+ "serverInfo": {
+ "host": "25432bf7811b",
+ "port": 27017,
+ "version": "7.0.45",
+ "gitVersion": "a52313e13ab55c9bddf7c3ff91dab286fa381796"
+ },
+ "serverParameters": {
+ "internalQueryFacetBufferSizeBytes": 104857600,
+ "internalQueryFacetMaxOutputDocSizeBytes": 104857600,
+ "internalLookupStageIntermediateDocumentMaxSizeBytes": 104857600,
+ "internalDocumentSourceGroupMaxMemoryBytes": 104857600,
+ "internalQueryMaxBlockingSortMemoryUsageBytes": 104857600,
+ "internalQueryProhibitBlockingMergeOnMongoS": 0,
+ "internalQueryMaxAddToSetBytes": 104857600,
+ "internalDocumentSourceSetWindowFieldsMaxMemoryBytes": 104857600,
+ "internalQueryFrameworkControl": "forceClassicEngine"
+ },
+ "command": {
+ "find": "orders",
+ "filter": {
+ "total": {
+ "$gt": 880
+ }
+ },
+ "lsid": {
+ "id": "4d375229-467a-4f9d-a622-6c7684c0a7ae"
+ },
+ "$clusterTime": {
+ "clusterTime": {
+ "$timestamp": "7701197595216969729"
+ },
+ "signature": {
+ "hash": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+ "keyId": 0
+ }
+ },
+ "$db": "qp"
+ },
+ "ok": 1,
+ "$clusterTime": {
+ "clusterTime": {
+ "$timestamp": "7701197595216969729"
+ },
+ "signature": {
+ "hash": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+ "keyId": {
+ "high": 0,
+ "low": 0,
+ "unsigned": false
+ }
+ }
+ },
+ "operationTime": {
+ "$timestamp": "7701197543677362487"
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mongodb/measured-slot-based-join.json b/frontend/src/apps/explain-visualizer/test-data/mongodb/measured-slot-based-join.json
new file mode 100644
index 0000000000..11c4f0bbdc
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mongodb/measured-slot-based-join.json
@@ -0,0 +1,162 @@
+{
+ "explainVersion": "2",
+ "queryPlanner": {
+ "namespace": "qp.orders",
+ "indexFilterSet": false,
+ "parsedQuery": { "total": { "$gt": 880 } },
+ "queryHash": "B84B8321",
+ "planCacheKey": "4488A477",
+ "optimizationTimeMillis": 0,
+ "maxIndexedOrSolutionsReached": false,
+ "maxIndexedAndSolutionsReached": false,
+ "maxScansToExplodeReached": false,
+ "winningPlan": {
+ "queryPlan": {
+ "stage": "FETCH",
+ "planNodeId": 2,
+ "filter": { "total": { "$gt": 880 } },
+ "inputStage": {
+ "stage": "IXSCAN",
+ "planNodeId": 1,
+ "keyPattern": { "customerId": 1 },
+ "indexName": "customerId_1",
+ "isMultiKey": false,
+ "multiKeyPaths": { "customerId": [] },
+ "isUnique": false,
+ "isSparse": false,
+ "isPartial": false,
+ "indexVersion": 2,
+ "direction": "forward",
+ "indexBounds": { "customerId": ["[MinKey, MaxKey]"] }
+ }
+ },
+ "slotBasedPlan": {
+ "slots": "$$RESULT=s9 env: { s8 = {\"customerId\" : 1}, s3 = 1793077814025 (NOW), s12 = 880, s1 = TimeZoneDatabase(America/Argentina/Catamarca...Asia/Ashkhabad) (timeZoneDB), s2 = Nothing (SEARCH_META) }",
+ "stages": "[2] filter {traverseF(s11, lambda(l1.0) { ((l1.0 > s12) ?: false) }, false)} \n[2] nlj inner [] [s4, s5, s6, s7, s8] \n left \n [1] ixseek KS(0A0104) KS(F0FE04) s7 s4 s5 s6 lowPriority [] @\"08d16d58-e66d-45f0-8409-ff7a999f483e\" @\"customerId_1\" true \n right \n [2] limit 1ll \n [2] seek s4 s9 s10 s5 s6 s7 s8 [s11 = total] @\"08d16d58-e66d-45f0-8409-ff7a999f483e\" true false \n"
+ }
+ },
+ "rejectedPlans": []
+ },
+ "executionStats": {
+ "executionSuccess": true,
+ "nReturned": 2785,
+ "executionTimeMillis": 7,
+ "totalKeysExamined": 5000,
+ "totalDocsExamined": 5000,
+ "executionStages": {
+ "stage": "filter",
+ "planNodeId": 2,
+ "nReturned": 2785,
+ "executionTimeMillisEstimate": 8,
+ "opens": 1,
+ "closes": 1,
+ "saveState": 5,
+ "restoreState": 5,
+ "isEOF": 1,
+ "numTested": 5000,
+ "filter": "traverseF(s11, lambda(l1.0) { ((l1.0 > s12) ?: false) }, false) ",
+ "inputStage": {
+ "stage": "nlj",
+ "planNodeId": 2,
+ "nReturned": 5000,
+ "executionTimeMillisEstimate": 8,
+ "opens": 1,
+ "closes": 1,
+ "saveState": 5,
+ "restoreState": 5,
+ "isEOF": 1,
+ "totalDocsExamined": 5000,
+ "totalKeysExamined": 5000,
+ "collectionScans": 0,
+ "collectionSeeks": 5000,
+ "indexScans": 0,
+ "indexSeeks": 1,
+ "indexesUsed": ["customerId_1"],
+ "innerOpens": 5000,
+ "innerCloses": 1,
+ "outerProjects": [],
+ "outerCorrelated": [4, 5, 6, 7, 8],
+ "outerStage": {
+ "stage": "ixseek",
+ "planNodeId": 1,
+ "nReturned": 5000,
+ "executionTimeMillisEstimate": 8,
+ "opens": 1,
+ "closes": 1,
+ "saveState": 5,
+ "restoreState": 5,
+ "isEOF": 1,
+ "indexName": "customerId_1",
+ "keysExamined": 5000,
+ "seeks": 1,
+ "numReads": 5001,
+ "indexKeySlot": 7,
+ "recordIdSlot": 4,
+ "snapshotIdSlot": 5,
+ "indexIdentSlot": 6,
+ "outputSlots": [],
+ "indexKeysToInclude": "00000000000000000000000000000000",
+ "seekKeyLow": "KS(0A0104) ",
+ "seekKeyHigh": "KS(F0FE04) "
+ },
+ "innerStage": {
+ "stage": "limit",
+ "planNodeId": 2,
+ "nReturned": 5000,
+ "executionTimeMillisEstimate": 0,
+ "opens": 5000,
+ "closes": 1,
+ "saveState": 5,
+ "restoreState": 5,
+ "isEOF": 1,
+ "limit": 1,
+ "inputStage": {
+ "stage": "seek",
+ "planNodeId": 2,
+ "nReturned": 5000,
+ "executionTimeMillisEstimate": 0,
+ "opens": 5000,
+ "closes": 1,
+ "saveState": 5,
+ "restoreState": 5,
+ "isEOF": 0,
+ "numReads": 5000,
+ "recordSlot": 9,
+ "recordIdSlot": 10,
+ "seekKeySlot": 4,
+ "snapshotIdSlot": 5,
+ "indexIdentSlot": 6,
+ "indexKeySlot": 7,
+ "indexKeyPatternSlot": 8,
+ "fields": ["total"],
+ "outputSlots": [11]
+ }
+ }
+ }
+ }
+ },
+ "command": {
+ "find": "orders",
+ "filter": { "total": { "$gt": 880 } },
+ "sort": { "customerId": 1 },
+ "$db": "qp"
+ },
+ "serverInfo": {
+ "host": "65056f72b82f",
+ "port": 27017,
+ "version": "7.0.45",
+ "gitVersion": "a52313e13ab55c9bddf7c3ff91dab286fa381796"
+ },
+ "serverParameters": {
+ "internalQueryFacetBufferSizeBytes": 104857600,
+ "internalQueryFacetMaxOutputDocSizeBytes": 104857600,
+ "internalLookupStageIntermediateDocumentMaxSizeBytes": 104857600,
+ "internalDocumentSourceGroupMaxMemoryBytes": 104857600,
+ "internalQueryMaxBlockingSortMemoryUsageBytes": 104857600,
+ "internalQueryProhibitBlockingMergeOnMongoS": 0,
+ "internalQueryMaxAddToSetBytes": 104857600,
+ "internalDocumentSourceSetWindowFieldsMaxMemoryBytes": 104857600,
+ "internalQueryFrameworkControl": "trySbeEngine"
+ },
+ "ok": 1
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mongodb/sharded-aggregate-group.json b/frontend/src/apps/explain-visualizer/test-data/mongodb/sharded-aggregate-group.json
new file mode 100644
index 0000000000..49a97dbb50
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mongodb/sharded-aggregate-group.json
@@ -0,0 +1,139 @@
+{
+ "serverInfo": {
+ "host": "5b7b536ff83f",
+ "port": 27017,
+ "version": "7.0.45",
+ "gitVersion": "a52313e13ab55c9bddf7c3ff91dab286fa381796"
+ },
+ "serverParameters": {
+ "internalQueryFacetBufferSizeBytes": 104857600,
+ "internalQueryFacetMaxOutputDocSizeBytes": 104857600,
+ "internalLookupStageIntermediateDocumentMaxSizeBytes": 104857600,
+ "internalDocumentSourceGroupMaxMemoryBytes": 104857600,
+ "internalQueryMaxBlockingSortMemoryUsageBytes": 104857600,
+ "internalQueryProhibitBlockingMergeOnMongoS": 0,
+ "internalQueryMaxAddToSetBytes": 104857600,
+ "internalDocumentSourceSetWindowFieldsMaxMemoryBytes": 104857600,
+ "internalQueryFrameworkControl": "forceClassicEngine"
+ },
+ "mergeType": "mongos",
+ "splitPipeline": {
+ "shardsPart": [
+ { "$group": { "_id": "$status", "n": { "$sum": "$total" } } }
+ ],
+ "mergerPart": [
+ {
+ "$mergeCursors": {
+ "lsid": {
+ "id": {
+ "$binary": {
+ "base64": "bB0ZWnVbS+ujkw78P3U4/Q==",
+ "subType": "04"
+ }
+ },
+ "uid": {
+ "$binary": {
+ "base64": "47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",
+ "subType": "00"
+ }
+ }
+ },
+ "compareWholeSortKey": false,
+ "tailableMode": "normal",
+ "nss": "qp.orders",
+ "allowPartialResults": false,
+ "recordRemoteOpWaitTime": false
+ }
+ },
+ {
+ "$group": {
+ "_id": "$$ROOT._id",
+ "n": { "$sum": "$$ROOT.n" },
+ "$doingMerge": true
+ }
+ },
+ { "$sort": { "sortKey": { "n": -1 } } }
+ ]
+ },
+ "shards": {
+ "sh1": {
+ "host": "qp-sh1:27018",
+ "stages": [
+ {
+ "$cursor": {
+ "queryPlanner": {
+ "namespace": "qp.orders",
+ "indexFilterSet": false,
+ "parsedQuery": {},
+ "queryHash": "B8F0391B",
+ "planCacheKey": "B8F0391B",
+ "optimizationTimeMillis": 0,
+ "maxIndexedOrSolutionsReached": false,
+ "maxIndexedAndSolutionsReached": false,
+ "maxScansToExplodeReached": false,
+ "winningPlan": {
+ "stage": "PROJECTION_SIMPLE",
+ "transformBy": { "status": 1, "total": 1, "_id": 0 },
+ "inputStage": {
+ "stage": "SHARDING_FILTER",
+ "inputStage": { "stage": "COLLSCAN", "direction": "forward" }
+ }
+ },
+ "rejectedPlans": []
+ }
+ }
+ },
+ { "$group": { "_id": "$status", "n": { "$sum": "$total" } } }
+ ]
+ },
+ "sh2": {
+ "host": "qp-sh2:27018",
+ "stages": [
+ {
+ "$cursor": {
+ "queryPlanner": {
+ "namespace": "qp.orders",
+ "indexFilterSet": false,
+ "parsedQuery": {},
+ "queryHash": "B8F0391B",
+ "planCacheKey": "B8F0391B",
+ "optimizationTimeMillis": 0,
+ "maxIndexedOrSolutionsReached": false,
+ "maxIndexedAndSolutionsReached": false,
+ "maxScansToExplodeReached": false,
+ "winningPlan": {
+ "stage": "PROJECTION_SIMPLE",
+ "transformBy": { "status": 1, "total": 1, "_id": 0 },
+ "inputStage": {
+ "stage": "SHARDING_FILTER",
+ "inputStage": { "stage": "COLLSCAN", "direction": "forward" }
+ }
+ },
+ "rejectedPlans": []
+ }
+ }
+ },
+ { "$group": { "_id": "$status", "n": { "$sum": "$total" } } }
+ ]
+ }
+ },
+ "command": {
+ "aggregate": "orders",
+ "pipeline": [
+ { "$group": { "_id": "$status", "n": { "$sum": "$total" } } },
+ { "$sort": { "n": -1 } }
+ ],
+ "cursor": {}
+ },
+ "ok": 1,
+ "$clusterTime": {
+ "clusterTime": { "$timestamp": { "t": 1793077694, "i": 1 } },
+ "signature": {
+ "hash": {
+ "$binary": { "base64": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=", "subType": "00" }
+ },
+ "keyId": 0
+ }
+ },
+ "operationTime": { "$timestamp": { "t": 1793077691, "i": 1 } }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mongodb/sharded-index-scan.json b/frontend/src/apps/explain-visualizer/test-data/mongodb/sharded-index-scan.json
new file mode 100644
index 0000000000..101ab746a6
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mongodb/sharded-index-scan.json
@@ -0,0 +1,163 @@
+{
+ "queryPlanner": {
+ "mongosPlannerVersion": 1,
+ "winningPlan": {
+ "stage": "SHARD_MERGE",
+ "shards": [
+ {
+ "shardName": "sh1",
+ "connectionString": "sh1/qp-sh1:27018",
+ "serverInfo": {
+ "host": "fe4c19987c05",
+ "port": 27018,
+ "version": "7.0.45",
+ "gitVersion": "a52313e13ab55c9bddf7c3ff91dab286fa381796"
+ },
+ "namespace": "qp.orders",
+ "indexFilterSet": false,
+ "parsedQuery": {
+ "total": {
+ "$gt": 880
+ }
+ },
+ "queryHash": "CACA99B3",
+ "planCacheKey": "12DCEA8D",
+ "optimizationTimeMillis": 0,
+ "maxIndexedOrSolutionsReached": false,
+ "maxIndexedAndSolutionsReached": false,
+ "maxScansToExplodeReached": false,
+ "winningPlan": {
+ "stage": "SHARDING_FILTER",
+ "inputStage": {
+ "stage": "FETCH",
+ "inputStage": {
+ "stage": "IXSCAN",
+ "keyPattern": {
+ "total": 1
+ },
+ "indexName": "total_1",
+ "isMultiKey": false,
+ "multiKeyPaths": {
+ "total": []
+ },
+ "isUnique": false,
+ "isSparse": false,
+ "isPartial": false,
+ "indexVersion": 2,
+ "direction": "forward",
+ "indexBounds": {
+ "total": ["(880, inf.0]"]
+ }
+ }
+ }
+ },
+ "rejectedPlans": []
+ },
+ {
+ "shardName": "sh2",
+ "connectionString": "sh2/qp-sh2:27018",
+ "serverInfo": {
+ "host": "b209ed3472e1",
+ "port": 27018,
+ "version": "7.0.45",
+ "gitVersion": "a52313e13ab55c9bddf7c3ff91dab286fa381796"
+ },
+ "namespace": "qp.orders",
+ "indexFilterSet": false,
+ "parsedQuery": {
+ "total": {
+ "$gt": 880
+ }
+ },
+ "queryHash": "CACA99B3",
+ "planCacheKey": "12DCEA8D",
+ "optimizationTimeMillis": 0,
+ "maxIndexedOrSolutionsReached": false,
+ "maxIndexedAndSolutionsReached": false,
+ "maxScansToExplodeReached": false,
+ "winningPlan": {
+ "stage": "SHARDING_FILTER",
+ "inputStage": {
+ "stage": "FETCH",
+ "inputStage": {
+ "stage": "IXSCAN",
+ "keyPattern": {
+ "total": 1
+ },
+ "indexName": "total_1",
+ "isMultiKey": false,
+ "multiKeyPaths": {
+ "total": []
+ },
+ "isUnique": false,
+ "isSparse": false,
+ "isPartial": false,
+ "indexVersion": 2,
+ "direction": "forward",
+ "indexBounds": {
+ "total": ["(880, inf.0]"]
+ }
+ }
+ }
+ },
+ "rejectedPlans": []
+ }
+ ]
+ }
+ },
+ "serverInfo": {
+ "host": "25432bf7811b",
+ "port": 27017,
+ "version": "7.0.45",
+ "gitVersion": "a52313e13ab55c9bddf7c3ff91dab286fa381796"
+ },
+ "serverParameters": {
+ "internalQueryFacetBufferSizeBytes": 104857600,
+ "internalQueryFacetMaxOutputDocSizeBytes": 104857600,
+ "internalLookupStageIntermediateDocumentMaxSizeBytes": 104857600,
+ "internalDocumentSourceGroupMaxMemoryBytes": 104857600,
+ "internalQueryMaxBlockingSortMemoryUsageBytes": 104857600,
+ "internalQueryProhibitBlockingMergeOnMongoS": 0,
+ "internalQueryMaxAddToSetBytes": 104857600,
+ "internalDocumentSourceSetWindowFieldsMaxMemoryBytes": 104857600,
+ "internalQueryFrameworkControl": "forceClassicEngine"
+ },
+ "command": {
+ "find": "orders",
+ "filter": {
+ "total": {
+ "$gt": 880
+ }
+ },
+ "lsid": {
+ "id": "ebc5de65-b950-49a6-9d67-04a838549069"
+ },
+ "$clusterTime": {
+ "clusterTime": {
+ "$timestamp": "7701197590922002433"
+ },
+ "signature": {
+ "hash": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+ "keyId": 0
+ }
+ },
+ "$db": "qp"
+ },
+ "ok": 1,
+ "$clusterTime": {
+ "clusterTime": {
+ "$timestamp": "7701197590922002433"
+ },
+ "signature": {
+ "hash": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+ "keyId": {
+ "high": 0,
+ "low": 0,
+ "unsigned": false
+ }
+ }
+ },
+ "operationTime": {
+ "$timestamp": "7701197543677362487"
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mongodb/slot-based-index-scan.json b/frontend/src/apps/explain-visualizer/test-data/mongodb/slot-based-index-scan.json
new file mode 100644
index 0000000000..09c6d43843
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mongodb/slot-based-index-scan.json
@@ -0,0 +1,84 @@
+{
+ "explainVersion": "2",
+ "queryPlanner": {
+ "namespace": "qp.orders",
+ "indexFilterSet": false,
+ "parsedQuery": {
+ "total": {
+ "$gt": 880
+ }
+ },
+ "queryHash": "B84B8321",
+ "planCacheKey": "95079DFC",
+ "optimizationTimeMillis": 0,
+ "maxIndexedOrSolutionsReached": false,
+ "maxIndexedAndSolutionsReached": false,
+ "maxScansToExplodeReached": false,
+ "winningPlan": {
+ "queryPlan": {
+ "stage": "FETCH",
+ "planNodeId": 2,
+ "filter": {
+ "total": {
+ "$gt": 880
+ }
+ },
+ "inputStage": {
+ "stage": "IXSCAN",
+ "planNodeId": 1,
+ "keyPattern": {
+ "customerId": 1
+ },
+ "indexName": "customerId_1",
+ "isMultiKey": false,
+ "multiKeyPaths": {
+ "customerId": []
+ },
+ "isUnique": false,
+ "isSparse": false,
+ "isPartial": false,
+ "indexVersion": 2,
+ "direction": "forward",
+ "indexBounds": {
+ "customerId": ["[MinKey, MaxKey]"]
+ }
+ }
+ },
+ "slotBasedPlan": {
+ "slots": "$$RESULT=s9 env: { s2 = Nothing (SEARCH_META), s8 = {\"customerId\" : 1}, s3 = 1793070381533 (NOW), s12 = 880, s1 = TimeZoneDatabase(Atlantic/Madeira...Asia/Baghdad) (timeZoneDB) }",
+ "stages": "[2] filter {traverseF(s11, lambda(l1.0) { ((l1.0 > s12) ?: false) }, false)} \n[2] nlj inner [] [s4, s5, s6, s7, s8] \n left \n [1] ixseek KS(0A0104) KS(F0FE04) s7 s4 s5 s6 lowPriority [] @\"dbdda938-ec63-471c-92b9-7d390a98b326\" @\"customerId_1\" true \n right \n [2] limit 1ll \n [2] seek s4 s9 s10 s5 s6 s7 s8 [s11 = total] @\"dbdda938-ec63-471c-92b9-7d390a98b326\" true false \n"
+ }
+ },
+ "rejectedPlans": []
+ },
+ "command": {
+ "find": "orders",
+ "filter": {
+ "total": {
+ "$gt": 880
+ }
+ },
+ "sort": {
+ "customerId": 1
+ },
+ "$db": "qp"
+ },
+ "serverInfo": {
+ "host": "001bb39b8dbf",
+ "port": 27017,
+ "version": "7.0.45",
+ "gitVersion": "a52313e13ab55c9bddf7c3ff91dab286fa381796"
+ },
+ "serverParameters": {
+ "internalQueryFacetBufferSizeBytes": 104857600,
+ "internalQueryFacetMaxOutputDocSizeBytes": 104857600,
+ "internalLookupStageIntermediateDocumentMaxSizeBytes": 104857600,
+ "internalDocumentSourceGroupMaxMemoryBytes": 104857600,
+ "internalQueryMaxBlockingSortMemoryUsageBytes": 104857600,
+ "internalQueryProhibitBlockingMergeOnMongoS": 0,
+ "internalQueryMaxAddToSetBytes": 104857600,
+ "internalDocumentSourceSetWindowFieldsMaxMemoryBytes": 104857600,
+ "internalQueryFrameworkControl": "trySbeEngine"
+ },
+ "ok": 1
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mysql/attached-subquery.json b/frontend/src/apps/explain-visualizer/test-data/mysql/attached-subquery.json
new file mode 100644
index 0000000000..0efa1ab099
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mysql/attached-subquery.json
@@ -0,0 +1,67 @@
+{
+ "query_block": {
+ "select_id": 1,
+ "cost_info": {
+ "query_cost": "5058.65"
+ },
+ "table": {
+ "table_name": "o",
+ "access_type": "ALL",
+ "rows_examined_per_scan": 50184,
+ "rows_produced_per_join": 50184,
+ "filtered": "100.00",
+ "cost_info": {
+ "read_cost": "40.25",
+ "eval_cost": "5018.40",
+ "prefix_cost": "5058.65",
+ "data_read_per_join": "2M"
+ },
+ "used_columns": ["id", "customer_id", "total", "status"],
+ "attached_condition": "<in_optimizer>(`qp`.`o`.`customer_id`,`qp`.`o`.`customer_id` in ( <materialize> (/* select#2 */ select `qp`.`c`.`id` from `qp`.`customers` `c` where (`qp`.`c`.`tier` = 'gold') group by `qp`.`c`.`id` having (count(0) > 0) ), <primary_index_lookup>(`qp`.`o`.`customer_id` in <temporary table> on <auto_distinct_key> where ((`qp`.`o`.`customer_id` = `<materialized_subquery>`.`id`)))))",
+ "attached_subqueries": [
+ {
+ "table": {
+ "table_name": "<materialized_subquery>",
+ "access_type": "eq_ref",
+ "key": "<auto_key>",
+ "key_length": "4",
+ "rows_examined_per_scan": 1,
+ "materialized_from_subquery": {
+ "using_temporary_table": true,
+ "dependent": true,
+ "cacheable": false,
+ "query_block": {
+ "select_id": 2,
+ "cost_info": {
+ "query_cost": "503.25"
+ },
+ "grouping_operation": {
+ "using_filesort": false,
+ "table": {
+ "table_name": "c",
+ "access_type": "index",
+ "possible_keys": ["PRIMARY"],
+ "key": "PRIMARY",
+ "used_key_parts": ["id"],
+ "key_length": "4",
+ "rows_examined_per_scan": 5000,
+ "rows_produced_per_join": 500,
+ "filtered": "10.00",
+ "cost_info": {
+ "read_cost": "453.25",
+ "eval_cost": "50.00",
+ "prefix_cost": "503.25",
+ "data_read_per_join": "23K"
+ },
+ "used_columns": ["id", "tier"],
+ "attached_condition": "(`qp`.`c`.`tier` = 'gold')"
+ }
+ }
+ }
+ }
+ }
+ }
+ ]
+ }
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mysql/derived-table.json b/frontend/src/apps/explain-visualizer/test-data/mysql/derived-table.json
new file mode 100644
index 0000000000..acbcdccc43
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mysql/derived-table.json
@@ -0,0 +1,54 @@
+{
+ "query_block": {
+ "select_id": 1,
+ "cost_info": {
+ "query_cost": "5390.69"
+ },
+ "table": {
+ "table_name": "s",
+ "access_type": "ALL",
+ "rows_examined_per_scan": 47895,
+ "rows_produced_per_join": 47895,
+ "filtered": "100.00",
+ "cost_info": {
+ "read_cost": "601.19",
+ "eval_cost": "4789.50",
+ "prefix_cost": "5390.69",
+ "data_read_per_join": "1M"
+ },
+ "used_columns": ["customer_id", "t"],
+ "materialized_from_subquery": {
+ "using_temporary_table": true,
+ "dependent": false,
+ "cacheable": true,
+ "query_block": {
+ "select_id": 2,
+ "cost_info": {
+ "query_cost": "4829.75"
+ },
+ "grouping_operation": {
+ "using_filesort": false,
+ "table": {
+ "table_name": "orders",
+ "access_type": "index",
+ "possible_keys": ["orders_customer_id_idx"],
+ "key": "orders_customer_id_idx",
+ "used_key_parts": ["customer_id"],
+ "key_length": "5",
+ "rows_examined_per_scan": 47895,
+ "rows_produced_per_join": 47895,
+ "filtered": "100.00",
+ "cost_info": {
+ "read_cost": "40.25",
+ "eval_cost": "4789.50",
+ "prefix_cost": "4829.75",
+ "data_read_per_join": "4M"
+ },
+ "used_columns": ["id", "customer_id", "total"]
+ }
+ }
+ }
+ }
+ }
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mysql/full-scan-filter.json b/frontend/src/apps/explain-visualizer/test-data/mysql/full-scan-filter.json
new file mode 100644
index 0000000000..4953f2b91c
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mysql/full-scan-filter.json
@@ -0,0 +1,23 @@
+{
+ "query_block": {
+ "select_id": 1,
+ "cost_info": {
+ "query_cost": "4829.75"
+ },
+ "table": {
+ "table_name": "orders",
+ "access_type": "ALL",
+ "rows_examined_per_scan": 47895,
+ "rows_produced_per_join": 15963,
+ "filtered": "33.33",
+ "cost_info": {
+ "read_cost": "3233.41",
+ "eval_cost": "1596.34",
+ "prefix_cost": "4829.75",
+ "data_read_per_join": "1M"
+ },
+ "used_columns": ["id", "customer_id", "total", "status", "placed_on"],
+ "attached_condition": "(`qp`.`orders`.`total` > 880)"
+ }
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mysql/group-sort-join.json b/frontend/src/apps/explain-visualizer/test-data/mysql/group-sort-join.json
new file mode 100644
index 0000000000..aa2fc823bd
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mysql/group-sort-join.json
@@ -0,0 +1,56 @@
+{
+ "query_block": {
+ "select_id": 1,
+ "cost_info": {
+ "query_cost": "6506.07"
+ },
+ "ordering_operation": {
+ "using_filesort": true,
+ "grouping_operation": {
+ "using_temporary_table": true,
+ "using_filesort": false,
+ "nested_loop": [
+ {
+ "table": {
+ "table_name": "o",
+ "access_type": "ALL",
+ "possible_keys": ["orders_customer_id_idx"],
+ "rows_examined_per_scan": 47895,
+ "rows_produced_per_join": 4789,
+ "filtered": "10.00",
+ "cost_info": {
+ "read_cost": "4350.80",
+ "eval_cost": "478.95",
+ "prefix_cost": "4829.75",
+ "data_read_per_join": "411K"
+ },
+ "used_columns": ["id", "customer_id", "total", "status"],
+ "attached_condition": "((`qp`.`o`.`status` = 'open') and (`qp`.`o`.`customer_id` is not null))"
+ }
+ },
+ {
+ "table": {
+ "table_name": "c",
+ "access_type": "eq_ref",
+ "possible_keys": ["PRIMARY"],
+ "key": "PRIMARY",
+ "used_key_parts": ["id"],
+ "key_length": "4",
+ "ref": ["qp.o.customer_id"],
+ "rows_examined_per_scan": 1,
+ "rows_produced_per_join": 4789,
+ "filtered": "100.00",
+ "cost_info": {
+ "read_cost": "1197.38",
+ "eval_cost": "478.95",
+ "prefix_cost": "6506.08",
+ "data_read_per_join": "1M"
+ },
+ "used_columns": ["id", "country"]
+ }
+ }
+ ]
+ }
+ }
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mysql/mariadb-block-nl-join.json b/frontend/src/apps/explain-visualizer/test-data/mysql/mariadb-block-nl-join.json
new file mode 100644
index 0000000000..9733e8228c
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mysql/mariadb-block-nl-join.json
@@ -0,0 +1,39 @@
+{
+ "query_block": {
+ "select_id": 1,
+ "cost": 200622.7147,
+ "filesort": {
+ "sort_key": "o.total desc",
+ "temporary_table": {
+ "nested_loop": [
+ {
+ "table": {
+ "table_name": "c",
+ "access_type": "ALL",
+ "loops": 1,
+ "rows": 5000,
+ "cost": 0.837822,
+ "filtered": 100
+ }
+ },
+ {
+ "block-nl-join": {
+ "table": {
+ "table_name": "o",
+ "access_type": "ALL",
+ "loops": 5000,
+ "rows": 50416,
+ "cost": 23418.33104,
+ "filtered": 100
+ },
+ "buffer_type": "flat",
+ "buffer_size": "256KiB",
+ "join_type": "BNL",
+ "attached_condition": "o.`status` = c.country"
+ }
+ }
+ ]
+ }
+ }
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mysql/mariadb-sort-temporary-join.json b/frontend/src/apps/explain-visualizer/test-data/mysql/mariadb-sort-temporary-join.json
new file mode 100644
index 0000000000..b645976de8
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mysql/mariadb-sort-temporary-join.json
@@ -0,0 +1,40 @@
+{
+ "query_block": {
+ "select_id": 1,
+ "cost": 53.47180584,
+ "filesort": {
+ "sort_key": "sum(o.total) desc",
+ "temporary_table": {
+ "nested_loop": [
+ {
+ "table": {
+ "table_name": "o",
+ "access_type": "ALL",
+ "possible_keys": ["orders_customer_id_idx"],
+ "loops": 1,
+ "rows": 50416,
+ "cost": 8.3654308,
+ "filtered": 100,
+ "attached_condition": "o.`status` = 'open' and o.customer_id is not null"
+ }
+ },
+ {
+ "table": {
+ "table_name": "c",
+ "access_type": "eq_ref",
+ "possible_keys": ["PRIMARY"],
+ "key": "PRIMARY",
+ "key_length": "4",
+ "used_key_parts": ["id"],
+ "ref": ["qp.o.customer_id"],
+ "loops": 50416,
+ "rows": 1,
+ "cost": 45.10637504,
+ "filtered": 100
+ }
+ }
+ ]
+ }
+ }
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mysql/ordering-filesort.json b/frontend/src/apps/explain-visualizer/test-data/mysql/ordering-filesort.json
new file mode 100644
index 0000000000..46dcec6ef9
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mysql/ordering-filesort.json
@@ -0,0 +1,28 @@
+{
+ "query_block": {
+ "select_id": 1,
+ "cost_info": {
+ "query_cost": "55242.65"
+ },
+ "ordering_operation": {
+ "using_filesort": true,
+ "cost_info": {
+ "sort_cost": "50184.00"
+ },
+ "table": {
+ "table_name": "orders",
+ "access_type": "ALL",
+ "rows_examined_per_scan": 50184,
+ "rows_produced_per_join": 50184,
+ "filtered": "100.00",
+ "cost_info": {
+ "read_cost": "40.25",
+ "eval_cost": "5018.40",
+ "prefix_cost": "5058.65",
+ "data_read_per_join": "2M"
+ },
+ "used_columns": ["id", "customer_id", "total", "status"]
+ }
+ }
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/mysql/union-distinct.json b/frontend/src/apps/explain-visualizer/test-data/mysql/union-distinct.json
new file mode 100644
index 0000000000..ba3b636513
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/mysql/union-distinct.json
@@ -0,0 +1,62 @@
+{
+ "query_block": {
+ "union_result": {
+ "using_temporary_table": true,
+ "select_id": 3,
+ "table_name": "<union1,2>",
+ "access_type": "ALL",
+ "query_specifications": [
+ {
+ "dependent": false,
+ "cacheable": true,
+ "query_block": {
+ "select_id": 1,
+ "cost_info": {
+ "query_cost": "4829.75"
+ },
+ "table": {
+ "table_name": "orders",
+ "access_type": "ALL",
+ "rows_examined_per_scan": 47895,
+ "rows_produced_per_join": 15963,
+ "filtered": "33.33",
+ "cost_info": {
+ "read_cost": "3233.41",
+ "eval_cost": "1596.34",
+ "prefix_cost": "4829.75",
+ "data_read_per_join": "1M"
+ },
+ "used_columns": ["id", "total"],
+ "attached_condition": "(`qp`.`orders`.`total` > 900)"
+ }
+ }
+ },
+ {
+ "dependent": false,
+ "cacheable": true,
+ "query_block": {
+ "select_id": 2,
+ "cost_info": {
+ "query_cost": "503.75"
+ },
+ "table": {
+ "table_name": "customers",
+ "access_type": "ALL",
+ "rows_examined_per_scan": 5000,
+ "rows_produced_per_join": 500,
+ "filtered": "10.00",
+ "cost_info": {
+ "read_cost": "453.75",
+ "eval_cost": "50.00",
+ "prefix_cost": "503.75",
+ "data_read_per_join": "195K"
+ },
+ "used_columns": ["id", "country"],
+ "attached_condition": "(`qp`.`customers`.`country` = 'JP')"
+ }
+ }
+ }
+ ]
+ }
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/oceanbase/full-scan-filter.json b/frontend/src/apps/explain-visualizer/test-data/oceanbase/full-scan-filter.json
new file mode 100644
index 0000000000..1fdcd6aae6
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/oceanbase/full-scan-filter.json
@@ -0,0 +1,8 @@
+{
+ "ID": 0,
+ "OPERATOR": "TABLE FULL SCAN",
+ "NAME": "orders",
+ "EST.ROWS": 5000,
+ "EST.TIME(us)": 2382,
+ "output": "output([orders.id], [orders.customer_id], [orders.total], [orders.status])"
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/oceanbase/hash-join-group-sort.json b/frontend/src/apps/explain-visualizer/test-data/oceanbase/hash-join-group-sort.json
new file mode 100644
index 0000000000..05c560f352
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/oceanbase/hash-join-group-sort.json
@@ -0,0 +1,40 @@
+{
+ "ID": 0,
+ "OPERATOR": "SORT",
+ "NAME": "",
+ "EST.ROWS": 4,
+ "EST.TIME(us)": 6945,
+ "output": "output([c.country], [T_FUN_COUNT(*)], [T_FUN_SUM(o.total)])",
+ "CHILD_1": {
+ "ID": 1,
+ "OPERATOR": "HASH GROUP BY",
+ "NAME": "",
+ "EST.ROWS": 4,
+ "EST.TIME(us)": 6944,
+ "output": "output([T_FUN_SUM(o.total)], [c.country], [T_FUN_COUNT(*)])",
+ "CHILD_1": {
+ "ID": 2,
+ "OPERATOR": "HASH JOIN ",
+ "NAME": "",
+ "EST.ROWS": 12100,
+ "EST.TIME(us)": 5556,
+ "output": "output([c.country], [o.total])",
+ "CHILD_1": {
+ "ID": 3,
+ "OPERATOR": "TABLE FULL SCAN",
+ "NAME": "c",
+ "EST.ROWS": 5000,
+ "EST.TIME(us)": 177,
+ "output": "output([c.id], [c.country])"
+ },
+ "CHILD_2": {
+ "ID": 4,
+ "OPERATOR": "TABLE FULL SCAN",
+ "NAME": "o",
+ "EST.ROWS": 12317,
+ "EST.TIME(us)": 2864,
+ "output": "output([o.customer_id], [o.total])"
+ }
+ }
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/oceanbase/index-lookup.json b/frontend/src/apps/explain-visualizer/test-data/oceanbase/index-lookup.json
new file mode 100644
index 0000000000..272b40ba91
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/oceanbase/index-lookup.json
@@ -0,0 +1,8 @@
+{
+ "ID": 0,
+ "OPERATOR": "TABLE RANGE SCAN",
+ "NAME": "orders(orders_customer_id_idx)",
+ "EST.ROWS": 10,
+ "EST.TIME(us)": 31,
+ "output": "output([orders.id], [orders.total])"
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/oceanbase/union-distinct.json b/frontend/src/apps/explain-visualizer/test-data/oceanbase/union-distinct.json
new file mode 100644
index 0000000000..c125e68012
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/oceanbase/union-distinct.json
@@ -0,0 +1,24 @@
+{
+ "ID": 0,
+ "OPERATOR": "MERGE UNION DISTINCT",
+ "NAME": "",
+ "EST.ROWS": 5050,
+ "EST.TIME(us)": 2829,
+ "output": "output([UNION([1])])",
+ "CHILD_1": {
+ "ID": 1,
+ "OPERATOR": "TABLE FULL SCAN",
+ "NAME": "customers",
+ "EST.ROWS": 50,
+ "EST.TIME(us)": 250,
+ "output": "output([customers.id])"
+ },
+ "CHILD_2": {
+ "ID": 2,
+ "OPERATOR": "TABLE FULL SCAN",
+ "NAME": "orders",
+ "EST.ROWS": 5000,
+ "EST.TIME(us)": 2244,
+ "output": "output([orders.id])"
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/oracle/full-scan-filter.json b/frontend/src/apps/explain-visualizer/test-data/oracle/full-scan-filter.json
new file mode 100644
index 0000000000..36ba068577
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/oracle/full-scan-filter.json
@@ -0,0 +1,26 @@
+[
+ {
+ "bytes": "32260",
+ "cardinality": "1613",
+ "cost": "48",
+ "id": "0",
+ "operation": "SELECT STATEMENT",
+ "optimizer": "ALL_ROWS",
+ "position": "48"
+ },
+ {
+ "bytes": "32260",
+ "cardinality": "1613",
+ "cost": "48",
+ "filter_predicates": "\"TOTAL\"\u003e880",
+ "id": "1",
+ "object_name": "ORDERS",
+ "object_owner": "SYSTEM",
+ "object_type": "TABLE",
+ "operation": "TABLE ACCESS",
+ "optimizer": "ANALYZED",
+ "options": "FULL",
+ "parent_id": "0",
+ "position": "1"
+ }
+]
diff --git a/frontend/src/apps/explain-visualizer/test-data/oracle/hash-join-group-sort.json b/frontend/src/apps/explain-visualizer/test-data/oracle/hash-join-group-sort.json
new file mode 100644
index 0000000000..4a47b4a1b9
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/oracle/hash-join-group-sort.json
@@ -0,0 +1,113 @@
+[
+ {
+ "bytes": "88",
+ "cardinality": "4",
+ "cost": "58",
+ "id": "0",
+ "operation": "SELECT STATEMENT",
+ "optimizer": "ALL_ROWS",
+ "position": "58"
+ },
+ {
+ "bytes": "88",
+ "cardinality": "4",
+ "cost": "58",
+ "id": "1",
+ "operation": "SORT",
+ "options": "ORDER BY",
+ "parent_id": "0",
+ "position": "1"
+ },
+ {
+ "bytes": "88",
+ "cardinality": "4",
+ "cost": "58",
+ "id": "2",
+ "operation": "HASH",
+ "options": "GROUP BY",
+ "parent_id": "1",
+ "position": "1"
+ },
+ {
+ "access_predicates": "\"C\".\"ID\"=\"O\".\"CUSTOMER_ID\"",
+ "bytes": "366674",
+ "cardinality": "16667",
+ "cost": "55",
+ "id": "3",
+ "operation": "HASH JOIN",
+ "parent_id": "2",
+ "position": "1"
+ },
+ {
+ "bytes": "366674",
+ "cardinality": "16667",
+ "cost": "55",
+ "id": "4",
+ "operation": "NESTED LOOPS",
+ "parent_id": "3",
+ "position": "1"
+ },
+ { "id": "5", "operation": "NESTED LOOPS", "parent_id": "4", "position": "1" },
+ {
+ "id": "6",
+ "operation": "STATISTICS COLLECTOR",
+ "parent_id": "5",
+ "position": "1"
+ },
+ {
+ "bytes": "35000",
+ "cardinality": "5000",
+ "cost": "7",
+ "id": "7",
+ "object_name": "CUSTOMERS",
+ "object_owner": "SYSTEM",
+ "object_type": "TABLE",
+ "operation": "TABLE ACCESS",
+ "optimizer": "ANALYZED",
+ "options": "FULL",
+ "parent_id": "6",
+ "position": "1"
+ },
+ {
+ "access_predicates": "\"C\".\"ID\"=\"O\".\"CUSTOMER_ID\"",
+ "id": "8",
+ "object_name": "ORDERS_CUSTOMER_ID_IDX",
+ "object_owner": "SYSTEM",
+ "object_type": "INDEX",
+ "operation": "INDEX",
+ "optimizer": "ANALYZED",
+ "options": "RANGE SCAN",
+ "parent_id": "5",
+ "position": "2"
+ },
+ {
+ "bytes": "45",
+ "cardinality": "3",
+ "cost": "48",
+ "filter_predicates": "\"O\".\"STATUS\"='open'",
+ "id": "9",
+ "object_name": "ORDERS",
+ "object_owner": "SYSTEM",
+ "object_type": "TABLE",
+ "operation": "TABLE ACCESS",
+ "optimizer": "ANALYZED",
+ "options": "BY INDEX ROWID",
+ "parent_id": "4",
+ "position": "2"
+ },
+ {
+ "bytes": "250005",
+ "cardinality": "16667",
+ "cost": "48",
+ "filter_predicates": "\"O\".\"STATUS\"='open'",
+ "id": "10",
+ "object_name": "ORDERS",
+ "object_owner": "SYSTEM",
+ "object_type": "TABLE",
+ "operation": "TABLE ACCESS",
+ "optimizer": "ANALYZED",
+ "options": "FULL",
+ "parent_id": "3",
+ "position": "2"
+ }
+]
diff --git a/frontend/src/apps/explain-visualizer/test-data/oracle/index-range-scan.json b/frontend/src/apps/explain-visualizer/test-data/oracle/index-range-scan.json
new file mode 100644
index 0000000000..fb807b274e
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/oracle/index-range-scan.json
@@ -0,0 +1,39 @@
+[
+ {
+ "bytes": "130",
+ "cardinality": "10",
+ "cost": "11",
+ "id": "0",
+ "operation": "SELECT STATEMENT",
+ "optimizer": "ALL_ROWS",
+ "position": "11"
+ },
+ {
+ "bytes": "130",
+ "cardinality": "10",
+ "cost": "11",
+ "id": "1",
+ "object_name": "ORDERS",
+ "object_owner": "SYSTEM",
+ "object_type": "TABLE",
+ "operation": "TABLE ACCESS",
+ "optimizer": "ANALYZED",
+ "options": "BY INDEX ROWID BATCHED",
+ "parent_id": "0",
+ "position": "1"
+ },
+ {
+ "access_predicates": "\"CUSTOMER_ID\"=42",
+ "cardinality": "10",
+ "cost": "1",
+ "id": "2",
+ "object_name": "ORDERS_CUSTOMER_ID_IDX",
+ "object_owner": "SYSTEM",
+ "object_type": "INDEX",
+ "operation": "INDEX",
+ "optimizer": "ANALYZED",
+ "options": "RANGE SCAN",
+ "parent_id": "1",
+ "position": "1"
+ }
+]
diff --git a/frontend/src/apps/explain-visualizer/test-data/oracle/union-distinct.json b/frontend/src/apps/explain-visualizer/test-data/oracle/union-distinct.json
new file mode 100644
index 0000000000..88306613f8
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/oracle/union-distinct.json
@@ -0,0 +1,60 @@
+[
+ {
+ "bytes": "13259",
+ "cardinality": "1751",
+ "cost": "57",
+ "id": "0",
+ "operation": "SELECT STATEMENT",
+ "optimizer": "ALL_ROWS",
+ "position": "57"
+ },
+ {
+ "bytes": "13259",
+ "cardinality": "1751",
+ "cost": "57",
+ "id": "1",
+ "operation": "HASH",
+ "options": "UNIQUE",
+ "parent_id": "0",
+ "position": "1"
+ },
+ {
+ "bytes": "13259",
+ "cardinality": "1751",
+ "cost": "57",
+ "id": "2",
+ "operation": "UNION-ALL",
+ "parent_id": "1",
+ "position": "1"
+ },
+ {
+ "bytes": "4509",
+ "cardinality": "501",
+ "cost": "48",
+ "filter_predicates": "\"TOTAL\"\u003e900",
+ "id": "3",
+ "object_name": "ORDERS",
+ "object_owner": "SYSTEM",
+ "object_type": "TABLE",
+ "operation": "TABLE ACCESS",
+ "optimizer": "ANALYZED",
+ "options": "FULL",
+ "parent_id": "2",
+ "position": "1"
+ },
+ {
+ "bytes": "8750",
+ "cardinality": "1250",
+ "cost": "7",
+ "filter_predicates": "\"COUNTRY\"='JP'",
+ "id": "4",
+ "object_name": "CUSTOMERS",
+ "object_owner": "SYSTEM",
+ "object_type": "TABLE",
+ "operation": "TABLE ACCESS",
+ "optimizer": "ANALYZED",
+ "options": "FULL",
+ "parent_id": "2",
+ "position": "2"
+ }
+]
diff --git a/frontend/src/apps/explain-visualizer/test-data/redshift/hash-aggregate.txt b/frontend/src/apps/explain-visualizer/test-data/redshift/hash-aggregate.txt
new file mode 100644
index 0000000000..3bc54cf634
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/redshift/hash-aggregate.txt
@@ -0,0 +1,2 @@
+XN HashAggregate (cost=131.97..133.41 rows=576 width=17)
+ -> XN Seq Scan on event (cost=0.00..87.98 rows=8798 width=17)
diff --git a/frontend/src/apps/explain-visualizer/test-data/redshift/hash-join-broadcast.txt b/frontend/src/apps/explain-visualizer/test-data/redshift/hash-join-broadcast.txt
new file mode 100644
index 0000000000..8177acea7e
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/redshift/hash-join-broadcast.txt
@@ -0,0 +1,5 @@
+ XN Hash Join DS_BCAST_INNER (cost=0.14..6600286.07 rows=8798 width=84)
+ Hash Cond: ("outer".catid = "inner".catid)
+ -> XN Seq Scan on event (cost=0.00..87.98 rows=8798 width=35)
+ -> XN Hash (cost=0.11..0.11 rows=11 width=49)
+ -> XN Seq Scan on category (cost=0.00..0.11 rows=11 width=49)
diff --git a/frontend/src/apps/explain-visualizer/test-data/redshift/postgres-same-grammar.txt b/frontend/src/apps/explain-visualizer/test-data/redshift/postgres-same-grammar.txt
new file mode 100644
index 0000000000..659c9ac69d
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/redshift/postgres-same-grammar.txt
@@ -0,0 +1,11 @@
+Limit (cost=1096.94..1096.95 rows=1 width=11)
+ -> Sort (cost=1096.94..1096.95 rows=1 width=11)
+ Sort Key: (sum(o.total)) DESC
+ -> HashAggregate (cost=1096.92..1096.93 rows=1 width=11)
+ Group Key: c.country
+ -> Hash Join (cost=140.50..1088.78 rows=1629 width=7)
+ Hash Cond: (o.customer_id = c.id)
+ -> Seq Scan on orders o (cost=0.00..944.00 rows=1629 width=8)
+ Filter: (total > 880)
+ -> Hash (cost=78.00..78.00 rows=5000 width=7)
+ -> Seq Scan on customers c (cost=0.00..78.00 rows=5000 width=7)
diff --git a/frontend/src/apps/explain-visualizer/test-data/redshift/scan-filter.txt b/frontend/src/apps/explain-visualizer/test-data/redshift/scan-filter.txt
new file mode 100644
index 0000000000..92288aa770
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/redshift/scan-filter.txt
@@ -0,0 +1,2 @@
+XN Seq Scan on venue (cost=0.00..2.02 rows=187 width=45)
+Filter: (venueseats IS NOT NULL)
diff --git a/frontend/src/apps/explain-visualizer/test-data/redshift/three-way-join.txt b/frontend/src/apps/explain-visualizer/test-data/redshift/three-way-join.txt
new file mode 100644
index 0000000000..a6188d832d
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/redshift/three-way-join.txt
@@ -0,0 +1,8 @@
+XN Hash Join DS_BCAST_INNER (cost=109.98..3871130276.17 rows=172456 width=132)
+ Hash Cond: ("outer".eventid = "inner".eventid)
+ -> XN Merge Join DS_DIST_NONE (cost=0.00..6285.93 rows=172456 width=97)
+ Merge Cond: ("outer".listid = "inner".listid)
+ -> XN Seq Scan on listing (cost=0.00..1924.97 rows=192497 width=44)
+ -> XN Seq Scan on sales (cost=0.00..1724.56 rows=172456 width=53)
+ -> XN Hash (cost=87.98..87.98 rows=8798 width=35)
+ -> XN Seq Scan on event (cost=0.00..87.98 rows=8798 width=35)
diff --git a/frontend/src/apps/explain-visualizer/test-data/starrocks/join-exchange.txt b/frontend/src/apps/explain-visualizer/test-data/starrocks/join-exchange.txt
new file mode 100644
index 0000000000..4299a3bd81
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/starrocks/join-exchange.txt
@@ -0,0 +1,85 @@
+PLAN FRAGMENT 0
+ OUTPUT EXPRS:7: country | 8: sum
+ PARTITION: UNPARTITIONED
+
+ RESULT SINK
+
+ 9:EXCHANGE
+
+PLAN FRAGMENT 1
+ OUTPUT EXPRS:
+ PARTITION: HASH_PARTITIONED: 7: country
+
+ STREAM DATA SINK
+ EXCHANGE ID: 09
+ UNPARTITIONED
+
+ 8:AGGREGATE (merge finalize)
+ | output: sum(8: sum)
+ | group by: 7: country
+ |
+ 7:EXCHANGE
+
+PLAN FRAGMENT 2
+ OUTPUT EXPRS:
+ PARTITION: HASH_PARTITIONED: 2: customer_id
+
+ STREAM DATA SINK
+ EXCHANGE ID: 07
+ HASH_PARTITIONED: 7: country
+
+ 6:AGGREGATE (update serialize)
+ | STREAMING
+ | output: sum(3: total)
+ | group by: 7: country
+ |
+ 5:Project
+ | <slot 3> : 3: total
+ | <slot 7> : 7: country
+ |
+ 4:HASH JOIN
+ | join op: INNER JOIN (PARTITIONED)
+ | colocate: false, reason:
+ | equal join conjunct: 2: customer_id = 5: id
+ |
+ |----3:EXCHANGE
+ |
+ 1:EXCHANGE
+
+PLAN FRAGMENT 3
+ OUTPUT EXPRS:
+ PARTITION: RANDOM
+
+ STREAM DATA SINK
+ EXCHANGE ID: 03
+ HASH_PARTITIONED: 5: id
+
+ 2:OlapScanNode
+ TABLE: customers
+ PREAGGREGATION: ON
+ PREDICATES: 5: id IS NOT NULL
+ partitions=1/1
+ rollup: customers
+ tabletRatio=2/2
+ tabletList=10007,10009
+ cardinality=450
+ avgRowSize=2.0
+
+PLAN FRAGMENT 4
+ OUTPUT EXPRS:
+ PARTITION: RANDOM
+
+ STREAM DATA SINK
+ EXCHANGE ID: 01
+ HASH_PARTITIONED: 2: customer_id
+
+ 0:OlapScanNode
+ TABLE: orders
+ PREAGGREGATION: ON
+ PREDICATES: 3: total > 880
+ partitions=1/1
+ rollup: orders
+ tabletRatio=2/2
+ tabletList=10015,10017
+ cardinality=2500
+ avgRowSize=2.0
diff --git a/frontend/src/apps/explain-visualizer/test-data/starrocks/nested-join-branch.txt b/frontend/src/apps/explain-visualizer/test-data/starrocks/nested-join-branch.txt
new file mode 100644
index 0000000000..f4155f6ed0
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/starrocks/nested-join-branch.txt
@@ -0,0 +1,100 @@
+PLAN FRAGMENT 0
+ OUTPUT EXPRS:7: country | 4: status | 11: count
+ PARTITION: UNPARTITIONED
+
+ RESULT SINK
+
+ 12:EXCHANGE
+
+PLAN FRAGMENT 1
+ OUTPUT EXPRS:
+ PARTITION: HASH_PARTITIONED: 7: country, 4: status
+
+ STREAM DATA SINK
+ EXCHANGE ID: 12
+ UNPARTITIONED
+
+ 11:AGGREGATE (merge finalize)
+ | output: count(11: count)
+ | group by: 7: country, 4: status
+ |
+ 10:EXCHANGE
+
+PLAN FRAGMENT 2
+ OUTPUT EXPRS:
+ colocate exec groups: ExecGroup{groupId=1, nodeIds=[0, 7, 8, 9]}
+ PARTITION: RANDOM
+
+ STREAM DATA SINK
+ EXCHANGE ID: 10
+ HASH_PARTITIONED: 7: country, 4: status
+
+ 9:AGGREGATE (update serialize)
+ | STREAMING
+ | output: count(*)
+ | group by: 7: country, 4: status
+ |
+ 8:Project
+ | <slot 4> : 4: status
+ | <slot 7> : 7: country
+ |
+ 7:HASH JOIN
+ | join op: INNER JOIN (BROADCAST)
+ | colocate: false, reason:
+ | equal join conjunct: 2: customer_id = 5: id
+ |
+ |----6:EXCHANGE
+ |
+ 0:OlapScanNode
+ TABLE: orders
+ PREAGGREGATION: ON
+ PREDICATES: 2: customer_id IS NOT NULL
+ partitions=1/1
+ rollup: orders
+ tabletRatio=2/2
+ tabletList=10015,10017
+ cardinality=4500
+ avgRowSize=2.0
+
+PLAN FRAGMENT 3
+ OUTPUT EXPRS:
+ colocate exec groups: ExecGroup{groupId=3, nodeIds=[1, 2, 3, 4, 5]}
+ PARTITION: RANDOM
+
+ STREAM DATA SINK
+ EXCHANGE ID: 06
+ UNPARTITIONED
+
+ 5:Project
+ | <slot 5> : 5: id
+ | <slot 7> : 7: country
+ |
+ 4:HASH JOIN
+ | join op: INNER JOIN (COLOCATE)
+ | colocate: true
+ | equal join conjunct: 5: id = 8: id
+ |
+ |----3:Project
+ | | <slot 8> : 8: id
+ | |
+ | 2:OlapScanNode
+ | TABLE: customers
+ | PREAGGREGATION: ON
+ | PREDICATES: 8: id IS NOT NULL, 10: country = 'JP'
+ | partitions=1/1
+ | rollup: customers
+ | tabletRatio=2/2
+ | tabletList=10007,10009
+ | cardinality=450
+ | avgRowSize=2.0
+ |
+ 1:OlapScanNode
+ TABLE: customers
+ PREAGGREGATION: ON
+ PREDICATES: 5: id IS NOT NULL
+ partitions=1/1
+ rollup: customers
+ tabletRatio=2/2
+ tabletList=10007,10009
+ cardinality=450
+ avgRowSize=2.0
diff --git a/frontend/src/apps/explain-visualizer/test-data/starrocks/scan-aggregate.txt b/frontend/src/apps/explain-visualizer/test-data/starrocks/scan-aggregate.txt
new file mode 100644
index 0000000000..323772c86c
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/starrocks/scan-aggregate.txt
@@ -0,0 +1,46 @@
+PLAN FRAGMENT 0
+ OUTPUT EXPRS:2: customer_id | 5: sum
+ PARTITION: UNPARTITIONED
+
+ RESULT SINK
+
+ 4:EXCHANGE
+
+PLAN FRAGMENT 1
+ OUTPUT EXPRS:
+ PARTITION: HASH_PARTITIONED: 2: customer_id
+
+ STREAM DATA SINK
+ EXCHANGE ID: 04
+ UNPARTITIONED
+
+ 3:AGGREGATE (merge finalize)
+ | output: sum(5: sum)
+ | group by: 2: customer_id
+ |
+ 2:EXCHANGE
+
+PLAN FRAGMENT 2
+ OUTPUT EXPRS:
+ colocate exec groups: ExecGroup{groupId=1, nodeIds=[0, 1]}
+ PARTITION: RANDOM
+
+ STREAM DATA SINK
+ EXCHANGE ID: 02
+ HASH_PARTITIONED: 2: customer_id
+
+ 1:AGGREGATE (update serialize)
+ | STREAMING
+ | output: sum(3: total)
+ | group by: 2: customer_id
+ |
+ 0:OlapScanNode
+ TABLE: orders
+ PREAGGREGATION: ON
+ PREDICATES: 3: total > 880
+ partitions=1/1
+ rollup: orders
+ tabletRatio=2/2
+ tabletList=10015,10017
+ cardinality=2500
+ avgRowSize=2.0
diff --git a/frontend/src/apps/explain-visualizer/test-data/starrocks/single-scan.txt b/frontend/src/apps/explain-visualizer/test-data/starrocks/single-scan.txt
new file mode 100644
index 0000000000..d011fe4d0d
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/starrocks/single-scan.txt
@@ -0,0 +1,26 @@
+PLAN FRAGMENT 0
+ OUTPUT EXPRS:1: id | 2: customer_id | 3: total | 4: status
+ PARTITION: UNPARTITIONED
+
+ RESULT SINK
+
+ 1:EXCHANGE
+
+PLAN FRAGMENT 1
+ OUTPUT EXPRS:
+ PARTITION: RANDOM
+
+ STREAM DATA SINK
+ EXCHANGE ID: 01
+ UNPARTITIONED
+
+ 0:OlapScanNode
+ TABLE: orders
+ PREAGGREGATION: ON
+ PREDICATES: 3: total > 880
+ partitions=1/1
+ rollup: orders
+ tabletRatio=2/2
+ tabletList=10015,10017
+ cardinality=2500
+ avgRowSize=4.0
diff --git a/frontend/src/apps/explain-visualizer/test-data/tidb/index-hash-join.json b/frontend/src/apps/explain-visualizer/test-data/tidb/index-hash-join.json
new file mode 100644
index 0000000000..3e21d48a75
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/tidb/index-hash-join.json
@@ -0,0 +1,54 @@
+[
+ {
+ "id": "IndexHashJoin_16",
+ "estRows": "90.00",
+ "taskType": "root",
+ "operatorInfo": "inner join, inner:IndexLookUp_13, outer key:qp.customers.id, inner key:qp.orders.customer_id, equal cond:eq(qp.customers.id, qp.orders.customer_id)",
+ "subOperators": [
+ {
+ "id": "TableReader_44(Build)",
+ "estRows": "9.00",
+ "taskType": "root",
+ "operatorInfo": "data:TableRangeScan_43",
+ "subOperators": [
+ {
+ "id": "TableRangeScan_43",
+ "estRows": "9.00",
+ "taskType": "cop[tikv]",
+ "accessObject": "table:c",
+ "operatorInfo": "range:[-inf,10), keep order:false"
+ }
+ ]
+ },
+ {
+ "id": "IndexLookUp_13(Probe)",
+ "estRows": "90.00",
+ "taskType": "root",
+ "subOperators": [
+ {
+ "id": "Selection_12(Build)",
+ "estRows": "90.00",
+ "taskType": "cop[tikv]",
+ "operatorInfo": "lt(qp.orders.customer_id, 10), not(isnull(qp.orders.customer_id))",
+ "subOperators": [
+ {
+ "id": "IndexRangeScan_10",
+ "estRows": "50000.00",
+ "taskType": "cop[tikv]",
+ "accessObject": "table:o, index:orders_customer_id_idx(customer_id)",
+ "operatorInfo": "range: decided by [eq(qp.orders.customer_id, qp.customers.id)], keep order:false"
+ }
+ ]
+ },
+ {
+ "id": "TableRowIDScan_11(Probe)",
+ "estRows": "90.00",
+ "taskType": "cop[tikv]",
+ "accessObject": "table:o",
+ "operatorInfo": "keep order:false"
+ }
+ ]
+ }
+ ]
+ }
+]
diff --git a/frontend/src/apps/explain-visualizer/test-data/tidb/measured-hash-join.json b/frontend/src/apps/explain-visualizer/test-data/tidb/measured-hash-join.json
new file mode 100644
index 0000000000..970a122011
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/tidb/measured-hash-join.json
@@ -0,0 +1,96 @@
+[
+ {
+ "id": "Projection_10",
+ "estRows": "4.00",
+ "actRows": "4",
+ "taskType": "root",
+ "executeInfo": "time:24.7ms, loops:5, RU:19.42, Concurrency:OFF",
+ "operatorInfo": "qp.customers.country, Column#9",
+ "memoryInfo": "1016 Bytes",
+ "diskInfo": "N/A",
+ "subOperators": [
+ {
+ "id": "HashAgg_11",
+ "estRows": "4.00",
+ "actRows": "4",
+ "taskType": "root",
+ "executeInfo": "time:24.7ms, loops:5, partial_worker:{wall_time:24.667086ms, concurrency:5, task_num:17, tot_wait:118.935759ms, tot_exec:3.893439ms, tot_time:123.157709ms, max:24.64161ms, p95:24.64161ms}, final_worker:{wall_time:24.720906ms, concurrency:5, task_num:21, tot_wait:8.187µs, tot_exec:9.928µs, tot_time:123.40608ms, max:24.700178ms, p95:24.700178ms}",
+ "operatorInfo": "group by:qp.customers.country, funcs:count(1)->Column#9, funcs:firstrow(qp.customers.country)->qp.customers.country",
+ "memoryInfo": "341.5 KB",
+ "diskInfo": "0 Bytes",
+ "subOperators": [
+ {
+ "id": "HashJoin_40",
+ "estRows": "16666.00",
+ "actRows": "16666",
+ "taskType": "root",
+ "executeInfo": "time:24.4ms, loops:18, build_hash_table:{total:2.38ms, fetch:1.54ms, build:836.7µs}, probe:{concurrency:5, total:121.6ms, max:24.4ms, probe:9.37ms, fetch and wait:112.2ms}",
+ "operatorInfo": "inner join, equal:[eq(qp.customers.id, qp.orders.customer_id)]",
+ "memoryInfo": "363.5 KB",
+ "diskInfo": "0 Bytes",
+ "subOperators": [
+ {
+ "id": "TableReader_49(Build)",
+ "estRows": "5000.00",
+ "actRows": "5000",
+ "taskType": "root",
+ "executeInfo": "time:1.92ms, loops:6, cop_task: {num: 6, max: 589.2µs, min: 126.8µs, avg: 285.4µs, p95: 589.2µs, copr_cache_hit_ratio: 0.00, build_task_duration: 14.8µs, max_distsql_concurrency: 1}, rpc_info:{Cop:{num_rpc:6, total_time:1.65ms}}",
+ "operatorInfo": "data:TableFullScan_48",
+ "memoryInfo": "58.2 KB",
+ "diskInfo": "N/A",
+ "subOperators": [
+ {
+ "id": "TableFullScan_48",
+ "estRows": "5000.00",
+ "actRows": "5000",
+ "taskType": "cop[tikv]",
+ "accessObject": "table:c",
+ "executeInfo": "tikv_task:{proc max:536.1µs, min:107.1µs, avg: 247.4µs, p80:301.2µs, p95:536.1µs, iters:0, tasks:6}",
+ "operatorInfo": "keep order:false",
+ "memoryInfo": "N/A",
+ "diskInfo": "N/A"
+ }
+ ]
+ },
+ {
+ "id": "TableReader_52(Probe)",
+ "estRows": "16666.00",
+ "actRows": "16666",
+ "taskType": "root",
+ "executeInfo": "time:23.3ms, loops:18, cop_task: {num: 8, max: 11ms, min: 442.3µs, avg: 2.92ms, p95: 11ms, tot_proc: 18ms, copr_cache_hit_ratio: 0.00, build_task_duration: 2.12µs, max_distsql_concurrency: 1}, rpc_info:{Cop:{num_rpc:8, total_time:23.1ms}}",
+ "operatorInfo": "data:Selection_51",
+ "memoryInfo": "252.8 KB",
+ "diskInfo": "N/A",
+ "subOperators": [
+ {
+ "id": "Selection_51",
+ "estRows": "16666.00",
+ "actRows": "16666",
+ "taskType": "cop[tikv]",
+ "executeInfo": "tikv_task:{proc max:10.8ms, min:371.4µs, avg: 2.83ms, p80:5.43ms, p95:10.8ms, iters:0, tasks:8}, time_detail: {total_process_time: 18ms}",
+ "operatorInfo": "eq(qp.orders.status, \"open\"), not(isnull(qp.orders.customer_id))",
+ "memoryInfo": "N/A",
+ "diskInfo": "N/A",
+ "subOperators": [
+ {
+ "id": "TableFullScan_50",
+ "estRows": "50000.00",
+ "actRows": "50000",
+ "taskType": "cop[tikv]",
+ "accessObject": "table:o",
+ "executeInfo": "tikv_task:{proc max:10.8ms, min:371.4µs, avg: 2.83ms, p80:5.43ms, p95:10.8ms, iters:0, tasks:8}",
+ "operatorInfo": "keep order:false",
+ "memoryInfo": "N/A",
+ "diskInfo": "N/A"
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+]
diff --git a/frontend/src/apps/explain-visualizer/test-data/tidb/table-reader-selection.json b/frontend/src/apps/explain-visualizer/test-data/tidb/table-reader-selection.json
new file mode 100644
index 0000000000..7ecd7f5e19
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/tidb/table-reader-selection.json
@@ -0,0 +1,25 @@
+[
+ {
+ "id": "TableReader_7",
+ "estRows": "1594.44",
+ "taskType": "root",
+ "operatorInfo": "data:Selection_6",
+ "subOperators": [
+ {
+ "id": "Selection_6",
+ "estRows": "1594.44",
+ "taskType": "cop[tikv]",
+ "operatorInfo": "gt(qp.orders.total, 880)",
+ "subOperators": [
+ {
+ "id": "TableFullScan_5",
+ "estRows": "50000.00",
+ "taskType": "cop[tikv]",
+ "accessObject": "table:orders",
+ "operatorInfo": "keep order:false"
+ }
+ ]
+ }
+ ]
+ }
+]
diff --git a/frontend/src/apps/explain-visualizer/test-data/tidb/union-hash-agg.json b/frontend/src/apps/explain-visualizer/test-data/tidb/union-hash-agg.json
new file mode 100644
index 0000000000..73b5a7e484
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/tidb/union-hash-agg.json
@@ -0,0 +1,79 @@
+[
+ {
+ "id": "HashAgg_11",
+ "estRows": "1744.44",
+ "taskType": "root",
+ "operatorInfo": "group by:Column#9, funcs:firstrow(Column#9)->Column#9",
+ "subOperators": [
+ {
+ "id": "Union_12",
+ "estRows": "1744.44",
+ "taskType": "root",
+ "subOperators": [
+ {
+ "id": "TableReader_20",
+ "estRows": "494.44",
+ "taskType": "root",
+ "operatorInfo": "data:Projection_14",
+ "subOperators": [
+ {
+ "id": "Projection_14",
+ "estRows": "494.44",
+ "taskType": "cop[tikv]",
+ "operatorInfo": "qp.orders.id->Column#9",
+ "subOperators": [
+ {
+ "id": "Selection_19",
+ "estRows": "494.44",
+ "taskType": "cop[tikv]",
+ "operatorInfo": "gt(qp.orders.total, 900)",
+ "subOperators": [
+ {
+ "id": "TableFullScan_18",
+ "estRows": "50000.00",
+ "taskType": "cop[tikv]",
+ "accessObject": "table:orders",
+ "operatorInfo": "keep order:false"
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "id": "TableReader_28",
+ "estRows": "1250.00",
+ "taskType": "root",
+ "operatorInfo": "data:Projection_22",
+ "subOperators": [
+ {
+ "id": "Projection_22",
+ "estRows": "1250.00",
+ "taskType": "cop[tikv]",
+ "operatorInfo": "qp.customers.id->Column#9",
+ "subOperators": [
+ {
+ "id": "Selection_27",
+ "estRows": "1250.00",
+ "taskType": "cop[tikv]",
+ "operatorInfo": "eq(qp.customers.country, \"JP\")",
+ "subOperators": [
+ {
+ "id": "TableFullScan_26",
+ "estRows": "5000.00",
+ "taskType": "cop[tikv]",
+ "accessObject": "table:customers",
+ "operatorInfo": "keep order:false"
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+]
diff --git a/frontend/src/apps/explain-visualizer/test-data/trino/join-aggregate-fragments.json b/frontend/src/apps/explain-visualizer/test-data/trino/join-aggregate-fragments.json
new file mode 100644
index 0000000000..7afcf82eda
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/trino/join-aggregate-fragments.json
@@ -0,0 +1,288 @@
+{
+ "0": {
+ "id": "16",
+ "name": "Output",
+ "descriptor": {
+ "columnNames": "[name, _col1]"
+ },
+ "outputs": [
+ {
+ "type": "varchar(25)",
+ "name": "name"
+ },
+ {
+ "type": "double",
+ "name": "sum"
+ }
+ ],
+ "details": ["_col1 := sum"],
+ "estimates": [
+ {
+ "outputRowCount": "NaN",
+ "outputSizeInBytes": "NaN",
+ "cpuCost": 0.0,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ }
+ ],
+ "children": [
+ {
+ "id": "11",
+ "name": "Aggregate",
+ "descriptor": {
+ "type": "FINAL",
+ "keys": "[name]"
+ },
+ "outputs": [
+ {
+ "type": "varchar(25)",
+ "name": "name"
+ },
+ {
+ "type": "double",
+ "name": "sum"
+ }
+ ],
+ "details": ["sum := sum(sum_3)"],
+ "estimates": [
+ {
+ "outputRowCount": "NaN",
+ "outputSizeInBytes": "NaN",
+ "cpuCost": "NaN",
+ "memoryCost": "NaN",
+ "networkCost": 0.0
+ }
+ ],
+ "children": [
+ {
+ "id": "355",
+ "name": "LocalExchange",
+ "descriptor": {
+ "partitioning": "HASH",
+ "isReplicateNullsAndAny": "",
+ "arguments": "[name::varchar(25)]"
+ },
+ "outputs": [
+ {
+ "type": "varchar(25)",
+ "name": "name"
+ },
+ {
+ "type": "double",
+ "name": "sum_3"
+ }
+ ],
+ "details": [],
+ "estimates": [
+ {
+ "outputRowCount": "NaN",
+ "outputSizeInBytes": "NaN",
+ "cpuCost": "NaN",
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ }
+ ],
+ "children": [
+ {
+ "id": "361",
+ "name": "RemoteSource",
+ "descriptor": {
+ "sourceFragmentIds": "[1]"
+ },
+ "outputs": [
+ {
+ "type": "varchar(25)",
+ "name": "name"
+ },
+ {
+ "type": "double",
+ "name": "sum_3"
+ }
+ ],
+ "details": [],
+ "estimates": [],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ "1": {
+ "id": "359",
+ "name": "Aggregate",
+ "descriptor": {
+ "type": "PARTIAL",
+ "keys": "[name]"
+ },
+ "outputs": [
+ {
+ "type": "varchar(25)",
+ "name": "name"
+ },
+ {
+ "type": "double",
+ "name": "sum_3"
+ }
+ ],
+ "details": ["sum_3 := sum(totalprice)"],
+ "estimates": [],
+ "children": [
+ {
+ "id": "6",
+ "name": "InnerJoin",
+ "descriptor": {
+ "criteria": "(custkey = custkey_1)",
+ "distribution": "REPLICATED"
+ },
+ "outputs": [
+ {
+ "type": "double",
+ "name": "totalprice"
+ },
+ {
+ "type": "varchar(25)",
+ "name": "name"
+ }
+ ],
+ "details": [
+ "Distribution: REPLICATED",
+ "dynamicFilterAssignments = {custkey_1 -> #df_291}"
+ ],
+ "estimates": [
+ {
+ "outputRowCount": "NaN",
+ "outputSizeInBytes": "NaN",
+ "cpuCost": "NaN",
+ "memoryCost": 4800000.0,
+ "networkCost": 0.0
+ }
+ ],
+ "children": [
+ {
+ "id": "292",
+ "name": "ScanFilter",
+ "descriptor": {
+ "table": "tpch:sf1:orders",
+ "filterPredicate": "",
+ "dynamicFilters": "{custkey = #df_291}"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "custkey"
+ },
+ {
+ "type": "double",
+ "name": "totalprice"
+ }
+ ],
+ "details": [
+ "totalprice := tpch:totalprice",
+ "custkey := tpch:custkey",
+ "tpch:orderstatus",
+ " :: [[O]]"
+ ],
+ "estimates": [
+ {
+ "outputRowCount": 732044.0,
+ "outputSizeInBytes": 1.3176792e7,
+ "cpuCost": 1.3176792e7,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ },
+ {
+ "outputRowCount": 732044.0,
+ "outputSizeInBytes": 1.3176792e7,
+ "cpuCost": 1.3176792e7,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ }
+ ],
+ "children": []
+ },
+ {
+ "id": "327",
+ "name": "LocalExchange",
+ "descriptor": {
+ "partitioning": "SINGLE",
+ "isReplicateNullsAndAny": "",
+ "arguments": "[]"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "custkey_1"
+ },
+ {
+ "type": "varchar(25)",
+ "name": "name"
+ }
+ ],
+ "details": [],
+ "estimates": [
+ {
+ "outputRowCount": 150000.0,
+ "outputSizeInBytes": 4800000.0,
+ "cpuCost": 0.0,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ }
+ ],
+ "children": [
+ {
+ "id": "265",
+ "name": "RemoteSource",
+ "descriptor": {
+ "sourceFragmentIds": "[2]"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "custkey_1"
+ },
+ {
+ "type": "varchar(25)",
+ "name": "name"
+ }
+ ],
+ "details": [],
+ "estimates": [],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ "2": {
+ "id": "1",
+ "name": "TableScan",
+ "descriptor": {
+ "table": "tpch:sf1:customer"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "custkey_1"
+ },
+ {
+ "type": "varchar(25)",
+ "name": "name"
+ }
+ ],
+ "details": ["custkey_1 := tpch:custkey", "name := tpch:name"],
+ "estimates": [
+ {
+ "outputRowCount": 150000.0,
+ "outputSizeInBytes": 4800000.0,
+ "cpuCost": 4800000.0,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ }
+ ],
+ "children": []
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/trino/scan-filter-project.json b/frontend/src/apps/explain-visualizer/test-data/trino/scan-filter-project.json
new file mode 100644
index 0000000000..b7e1e3ac23
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/trino/scan-filter-project.json
@@ -0,0 +1,78 @@
+{
+ "0": {
+ "id": "6",
+ "name": "Output",
+ "descriptor": {
+ "columnNames": "[custkey, name]"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "custkey"
+ },
+ {
+ "type": "varchar(25)",
+ "name": "name"
+ }
+ ],
+ "details": [],
+ "estimates": [
+ {
+ "outputRowCount": 6000.0,
+ "outputSizeInBytes": 192000.0,
+ "cpuCost": 0.0,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ }
+ ],
+ "children": [
+ {
+ "id": "19",
+ "name": "ScanFilterProject",
+ "descriptor": {
+ "table": "tpch:sf1:customer",
+ "filterPredicate": "(nationkey = bigint '1')"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "custkey"
+ },
+ {
+ "type": "varchar(25)",
+ "name": "name"
+ }
+ ],
+ "details": [
+ "name := tpch:name",
+ "nationkey := tpch:nationkey",
+ "custkey := tpch:custkey"
+ ],
+ "estimates": [
+ {
+ "outputRowCount": 150000.0,
+ "outputSizeInBytes": 4800000.0,
+ "cpuCost": 6150000.0,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ },
+ {
+ "outputRowCount": 6000.0,
+ "outputSizeInBytes": 192000.0,
+ "cpuCost": 6150000.0,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ },
+ {
+ "outputRowCount": 6000.0,
+ "outputSizeInBytes": 192000.0,
+ "cpuCost": 192000.0,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/test-data/trino/sort-limit.json b/frontend/src/apps/explain-visualizer/test-data/trino/sort-limit.json
new file mode 100644
index 0000000000..88054743e7
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/test-data/trino/sort-limit.json
@@ -0,0 +1,297 @@
+{
+ "0": {
+ "id": "8",
+ "name": "Output",
+ "descriptor": {
+ "columnNames": "[orderkey, totalprice]"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "orderkey"
+ },
+ {
+ "type": "double",
+ "name": "totalprice"
+ }
+ ],
+ "details": [],
+ "estimates": [
+ {
+ "outputRowCount": 10.0,
+ "outputSizeInBytes": 180.0,
+ "cpuCost": 0.0,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ }
+ ],
+ "children": [
+ {
+ "id": "105",
+ "name": "TopN",
+ "descriptor": {
+ "count": "10",
+ "orderBy": "[totalprice DESC NULLS LAST]"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "orderkey"
+ },
+ {
+ "type": "double",
+ "name": "totalprice"
+ }
+ ],
+ "details": [],
+ "estimates": [
+ {
+ "outputRowCount": 10.0,
+ "outputSizeInBytes": 180.0,
+ "cpuCost": "NaN",
+ "memoryCost": "NaN",
+ "networkCost": "NaN"
+ }
+ ],
+ "children": [
+ {
+ "id": "152",
+ "name": "LocalExchange",
+ "descriptor": {
+ "partitioning": "SINGLE",
+ "isReplicateNullsAndAny": "",
+ "arguments": "[]"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "orderkey"
+ },
+ {
+ "type": "double",
+ "name": "totalprice"
+ }
+ ],
+ "details": [],
+ "estimates": [
+ {
+ "outputRowCount": 10.0,
+ "outputSizeInBytes": 180.0,
+ "cpuCost": 0.0,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ }
+ ],
+ "children": [
+ {
+ "id": "123",
+ "name": "RemoteSource",
+ "descriptor": {
+ "sourceFragmentIds": "[1]"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "orderkey"
+ },
+ {
+ "type": "double",
+ "name": "totalprice"
+ }
+ ],
+ "details": [],
+ "estimates": [],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ },
+ "1": {
+ "id": "160",
+ "name": "TopNPartial",
+ "descriptor": {
+ "count": "10",
+ "orderBy": "[totalprice DESC NULLS LAST]"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "orderkey"
+ },
+ {
+ "type": "double",
+ "name": "totalprice"
+ }
+ ],
+ "details": [],
+ "estimates": [
+ {
+ "outputRowCount": 10.0,
+ "outputSizeInBytes": 180.0,
+ "cpuCost": "NaN",
+ "memoryCost": "NaN",
+ "networkCost": "NaN"
+ }
+ ],
+ "children": [
+ {
+ "id": "161",
+ "name": "LocalExchange",
+ "descriptor": {
+ "partitioning": "SINGLE",
+ "isReplicateNullsAndAny": "",
+ "arguments": "[]"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "orderkey"
+ },
+ {
+ "type": "double",
+ "name": "totalprice"
+ }
+ ],
+ "details": [],
+ "estimates": [
+ {
+ "outputRowCount": 10.0,
+ "outputSizeInBytes": 180.0,
+ "cpuCost": 0.0,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ }
+ ],
+ "children": [
+ {
+ "id": "158",
+ "name": "TopNPartial",
+ "descriptor": {
+ "count": "10",
+ "orderBy": "[totalprice DESC NULLS LAST]"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "orderkey"
+ },
+ {
+ "type": "double",
+ "name": "totalprice"
+ }
+ ],
+ "details": [],
+ "estimates": [
+ {
+ "outputRowCount": 10.0,
+ "outputSizeInBytes": 180.0,
+ "cpuCost": "NaN",
+ "memoryCost": "NaN",
+ "networkCost": "NaN"
+ }
+ ],
+ "children": [
+ {
+ "id": "159",
+ "name": "LocalExchange",
+ "descriptor": {
+ "partitioning": "ROUND_ROBIN",
+ "isReplicateNullsAndAny": "",
+ "arguments": "[]"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "orderkey"
+ },
+ {
+ "type": "double",
+ "name": "totalprice"
+ }
+ ],
+ "details": [],
+ "estimates": [
+ {
+ "outputRowCount": 15.0,
+ "outputSizeInBytes": 270.0,
+ "cpuCost": 270.0,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ }
+ ],
+ "children": [
+ {
+ "id": "104",
+ "name": "TopNPartial",
+ "descriptor": {
+ "count": "10",
+ "orderBy": "[totalprice DESC NULLS LAST]"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "orderkey"
+ },
+ {
+ "type": "double",
+ "name": "totalprice"
+ }
+ ],
+ "details": [],
+ "estimates": [
+ {
+ "outputRowCount": 15.0,
+ "outputSizeInBytes": 270.0,
+ "cpuCost": "NaN",
+ "memoryCost": "NaN",
+ "networkCost": "NaN"
+ }
+ ],
+ "children": [
+ {
+ "id": "0",
+ "name": "TableScan",
+ "descriptor": {
+ "table": "tpch:sf1:orders"
+ },
+ "outputs": [
+ {
+ "type": "bigint",
+ "name": "orderkey"
+ },
+ {
+ "type": "double",
+ "name": "totalprice"
+ }
+ ],
+ "details": [
+ "totalprice := tpch:totalprice",
+ "orderkey := tpch:orderkey",
+ "tpch:orderstatus",
+ " :: [[F], [O], [P]]"
+ ],
+ "estimates": [
+ {
+ "outputRowCount": 1500000.0,
+ "outputSizeInBytes": 2.7e7,
+ "cpuCost": 2.7e7,
+ "memoryCost": 0.0,
+ "networkCost": 0.0
+ }
+ ],
+ "children": []
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/frontend/src/apps/explain-visualizer/tidb-plan.test.ts b/frontend/src/apps/explain-visualizer/tidb-plan.test.ts
new file mode 100644
index 0000000000..a962303137
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/tidb-plan.test.ts
@@ -0,0 +1,206 @@
+import { describe, expect, test } from "vitest";
+import {
+ PLAN_FULL_INDEX_SCAN,
+ PLAN_FULL_TABLE_SCAN,
+ PLAN_TOO_DEEP_MESSAGE,
+ type PlanNode,
+ type PlanTree,
+} from "./plan-model";
+import indexHashJoin from "./test-data/tidb/index-hash-join.json";
+import measuredHashJoin from "./test-data/tidb/measured-hash-join.json";
+import tableReaderSelection from "./test-data/tidb/table-reader-selection.json";
+import unionHashAgg from "./test-data/tidb/union-hash-agg.json";
+import {
+ parseTidbPlan,
+ TIDB_PLAN_EMPTY_MESSAGE,
+ TIDB_PLAN_INVALID_JSON_MESSAGE,
+ TIDB_PLAN_NO_PLAN_MESSAGE,
+} from "./tidb-plan";
+
+/** A chain of `depth` operators, which is what drives the depth limit. */
+const nestedPlan = (depth: number): string => {
+ let plan: Record<string, unknown> = { id: "TableFullScan_1" };
+ for (let level = 1; level < depth; level += 1) {
+ plan = { id: `Selection_${level + 1}`, subOperators: [plan] };
+ }
+ return JSON.stringify([plan]);
+};
+
+const parse = (source: string): PlanTree => {
+ const result = parseTidbPlan(source);
+ if (!result.ok)
+ throw new Error(`expected a parsable plan: ${result.message}`);
+ return result.tree;
+};
+
+const parseFixture = (fixture: unknown): PlanTree =>
+ parse(JSON.stringify(fixture));
+
+const outline = (tree: PlanTree): string[] =>
+ tree.nodes.map(
+ (node) => `${node.id} ${node.nodeType} ${node.subject ?? "-"}`
+ );
+
+const propertyValue = (node: PlanNode, label: string): string | undefined =>
+ node.properties.find((property) => property.label === label)?.value;
+
+const byId = (tree: PlanTree, id: string): PlanNode => {
+ const node = tree.nodes.find((candidate) => candidate.id === id);
+ if (!node) throw new Error(`no node ${id} in ${outline(tree).join(", ")}`);
+ return node;
+};
+
+describe("parseTidbPlan", () => {
+ test("names each operator as TiDB's own plan does, without its sequence number", () => {
+ const tree = parseFixture(tableReaderSelection);
+ const scan = byId(tree, "0.0.0");
+
+ expect(outline(tree)).toEqual([
+ "0 TableReader data:Selection_6",
+ "0.0 Selection gt(qp.orders.total, 880)",
+ "0.0.0 TableFullScan orders",
+ ]);
+ expect(scan).toMatchObject({
+ rows: 50000,
+ relation: { table: "orders" },
+ children: [],
+ });
+ expect(scan.warnings).toEqual([PLAN_FULL_TABLE_SCAN]);
+ // The id TiDB prints stays on the node, so a reader can match it against
+ // the text plan they already have.
+ expect(propertyValue(scan, "Operator")).toBe("TableFullScan_5");
+ expect(propertyValue(scan, "Task type")).toBe("cop[tikv]");
+ });
+
+ test("ranks nothing, because no TiDB plan format carries a cost", () => {
+ const tree = parseFixture(indexHashJoin);
+
+ expect(tree.estimates.cost).toBe(false);
+ expect(tree.costBasis).toBe(0);
+ expect(tree.estimates.rows).toBe(true);
+ for (const node of tree.nodes) {
+ expect(node.totalCost).toBeUndefined();
+ expect(node.selfCost).toBeUndefined();
+ }
+ });
+
+ test("reads which side of a join an operator feeds off its id", () => {
+ const tree = parseFixture(indexHashJoin);
+
+ expect(outline(tree)).toEqual([
+ "0 IndexHashJoin inner join, inner:IndexLookUp_13, outer key:qp.customers.id, inner key:qp.orders.customer_id, equal cond:eq(qp.customers.id, qp.orders.customer_id)",
+ "0.0 TableReader data:TableRangeScan_43",
+ "0.0.0 TableRangeScan c",
+ "0.1 IndexLookUp -",
+ "0.1.0 Selection lt(qp.orders.customer_id, 10), not(isnull(qp.orders.customer_id))",
+ "0.1.0.0 IndexRangeScan o",
+ "0.1.1 TableRowIDScan o",
+ ]);
+ expect(byId(tree, "0.0").relationship).toBe("Build");
+ expect(byId(tree, "0.1").relationship).toBe("Probe");
+ expect(byId(tree, "0.0.0").relationship).toBeUndefined();
+ });
+
+ test("splits an access object into the table it reads and the index it uses", () => {
+ const indexScan = byId(parseFixture(indexHashJoin), "0.1.0.0");
+
+ // `o` is the statement's name for the table, which TiDB does not resolve,
+ // so it names the read and nothing is looked up by it.
+ expect(indexScan.relation).toEqual({ table: "o", unresolved: true });
+ expect(propertyValue(indexScan, "Table")).toBe("o");
+ // The index names its columns in parentheses, where a comma separates
+ // columns rather than parts of the access object.
+ expect(propertyValue(indexScan, "Index")).toBe(
+ "orders_customer_id_idx(customer_id)"
+ );
+ // A range read of an index is not a read of all of it.
+ expect(indexScan.warnings).toEqual([]);
+ });
+
+ test("hangs both halves of a union off it", () => {
+ const tree = parseFixture(unionHashAgg);
+
+ expect(outline(tree).slice(0, 3)).toEqual([
+ "0 HashAgg group by:Column#9, funcs:firstrow(Column#9)->Column#9",
+ "0.0 Union -",
+ "0.0.0 TableReader data:Projection_14",
+ ]);
+ expect(byId(tree, "0.0").children).toHaveLength(2);
+ expect(byId(tree, "0.0.0.0.0.0").relation).toEqual({
+ table: "orders",
+ unresolved: true,
+ });
+ expect(byId(tree, "0.0.1.0.0.0").relation).toEqual({
+ table: "customers",
+ unresolved: true,
+ });
+ });
+
+ test("reads a measured plan for its rows and not its timings", () => {
+ const tree = parseFixture(measuredHashJoin);
+ const join = byId(tree, "0.0.0");
+
+ expect(tree.measured).toEqual({ rows: true, time: false });
+ expect(join.actualRows).toBe(16666);
+ expect(join.rows).toBe(16666);
+ expect(join.actualTime).toBeUndefined();
+ // `time:` covers an operator and its subtree, and the operators pushed
+ // down to a coprocessor report none, so the string stays a property rather
+ // than becoming a number anything ranks by.
+ expect(propertyValue(join, "Execute info")).toContain("time:");
+ expect(
+ propertyValue(byId(tree, "0.0.0.0.0"), "Execute info")
+ ).not.toContain("time:");
+ });
+
+ test("flags a read of every row of an index, and leaves a small one alone", () => {
+ const full = parse(
+ JSON.stringify([
+ {
+ id: "IndexFullScan_5",
+ estRows: "50000",
+ accessObject: "table:orders, index:i(total)",
+ },
+ ])
+ );
+ const small = parse(
+ JSON.stringify([
+ {
+ id: "IndexFullScan_5",
+ estRows: "200",
+ accessObject: "table:countries, index:i(name)",
+ },
+ ])
+ );
+
+ expect(full.root.warnings).toEqual([PLAN_FULL_INDEX_SCAN]);
+ expect(small.root.warnings).toEqual([]);
+ });
+
+ test("reports a plan it cannot read", () => {
+ expect(parseTidbPlan(" ")).toEqual({
+ ok: false,
+ message: TIDB_PLAN_EMPTY_MESSAGE,
+ });
+ expect(parseTidbPlan("not json")).toEqual({
+ ok: false,
+ message: TIDB_PLAN_INVALID_JSON_MESSAGE,
+ });
+ expect(parseTidbPlan("[]")).toEqual({
+ ok: false,
+ message: TIDB_PLAN_NO_PLAN_MESSAGE,
+ });
+ // A tabular EXPLAIN, which is what every other TiDB format returns.
+ expect(
+ parseTidbPlan("id\testRows\ttask\nTableReader_7\t5.00\troot")
+ ).toEqual({ ok: false, message: TIDB_PLAN_INVALID_JSON_MESSAGE });
+ });
+
+ test("gives up past the depth it can draw", () => {
+ expect(parseTidbPlan(nestedPlan(400)).ok).toBe(true);
+ expect(parseTidbPlan(nestedPlan(2000))).toEqual({
+ ok: false,
+ message: PLAN_TOO_DEEP_MESSAGE,
+ });
+ });
+});
diff --git a/frontend/src/apps/explain-visualizer/tidb-plan.ts b/frontend/src/apps/explain-visualizer/tidb-plan.ts
new file mode 100644
index 0000000000..e6ab67a191
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/tidb-plan.ts
@@ -0,0 +1,202 @@
+import {
+ addPlanProperty,
+ checkPlanDepth,
+ isJsonRecord,
+ type JsonRecord,
+ PLAN_FULL_INDEX_SCAN,
+ PLAN_FULL_TABLE_SCAN,
+ type PlanNode,
+ type PlanParseResult,
+ type PlanProperty,
+ type PlanRelation,
+ type PlanWarning,
+ parseWithDepthLimit,
+ planLabel,
+} from "./plan-model";
+
+/**
+ * Maps `EXPLAIN FORMAT=tidb_json` output onto the engine-neutral plan model.
+ *
+ * TiDB returns the operator tree directly: one object per operator, children
+ * under `subOperators`, and the operator's own id — `HashJoin_40` — as the
+ * name TiDB's text plan prints too. What it does not return is a cost, in this
+ * format or any other the editor can ask for, so a TiDB plan ranks nothing and
+ * the viewer says so.
+ *
+ * A measured plan, from a typed `EXPLAIN ANALYZE FORMAT=tidb_json`, is read
+ * for its rows alone. Its timings live in a free-form `executeInfo` string
+ * where `time:` covers an operator and its subtree, and the operators pushed
+ * down to a coprocessor report no `time:` at all — so a ranking built on it
+ * would be wrong for half of the plan. The string stays on the node, where a
+ * reader sees it next to the operator it belongs to.
+ */
+
+const CHILDREN_KEY = "subOperators";
+
+/** Keys the model promotes to typed fields, so the property list drops them. */
+const PROMOTED_KEYS = new Set([
+ "estRows",
+ "actRows",
+ "accessObject",
+ CHILDREN_KEY,
+]);
+
+/**
+ * An operator id: a name, the plan-wide sequence number TiDB gives it, and for
+ * a join input the side it feeds — `TableReader_49(Build)`.
+ */
+const OPERATOR_ID = /^(.*?)_(\d+)(?:\(([^)]*)\))?$/;
+
+/** Operators that read every row of a table or an index. */
+const FULL_SCANS: Record<string, PlanWarning> = {
+ TableFullScan: PLAN_FULL_TABLE_SCAN,
+ IndexFullScan: PLAN_FULL_INDEX_SCAN,
+};
+
+/**
+ * Rows a read examines before reading all of them is worth flagging, as in the
+ * other parsers: a full scan of a few hundred rows is not one a reader can
+ * improve on.
+ */
+const FULL_SCAN_ROWS_THRESHOLD = 1000;
+
+export const TIDB_PLAN_EMPTY_MESSAGE =
+ "TiDB returned no query plan for this statement.";
+export const TIDB_PLAN_INVALID_JSON_MESSAGE =
+ "The query plan is not valid JSON. EXPLAIN FORMAT=tidb_json output is expected.";
+export const TIDB_PLAN_NO_PLAN_MESSAGE =
+ "The query plan JSON does not contain an operator at its root.";
+
+function optionalNumber(value: unknown): number | undefined {
+ if (typeof value === "number" && Number.isFinite(value)) return value;
+ if (typeof value === "string" && value.trim()) {
+ const parsed = Number(value);
+ if (Number.isFinite(parsed)) return parsed;
+ }
+ return undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+ return typeof value === "string" && value ? value : undefined;
+}
+
+/**
+ * The parts of an `accessObject` such as
+ * `table:orders, index:orders_customer_id_idx(customer_id)`. An index names
+ * its columns in parentheses, where a comma does not separate parts.
+ */
+function accessObjectParts(accessObject: string): [string, string][] {
+ const parts: string[] = [];
+ let depth = 0;
+ let start = 0;
+ for (let index = 0; index < accessObject.length; index++) {
+ const character = accessObject[index];
+ if (character === "(") depth++;
+ else if (character === ")") depth = Math.max(0, depth - 1);
+ else if (character === "," && depth === 0) {
+ parts.push(accessObject.slice(start, index));
+ start = index + 1;
+ }
+ }
+ parts.push(accessObject.slice(start));
+ const named: [string, string][] = [];
+ for (const part of parts) {
+ const separator = part.indexOf(":");
+ if (separator <= 0) continue;
+ const label = part.slice(0, separator).trim();
+ const value = part.slice(separator + 1).trim();
+ if (label && value) named.push([label, value]);
+ }
+ return named;
+}
+
+function accessObjectOf(raw: JsonRecord): [string, string][] {
+ const accessObject = stringValue(raw.accessObject);
+ return accessObject ? accessObjectParts(accessObject) : [];
+}
+
+/**
+ * The table this operator reads.
+ *
+ * TiDB prints the name the statement used, which is the alias where it gave
+ * one, and never qualifies it, so the name is carried as the statement's and
+ * no table is looked up by it — as for MySQL.
+ */
+function toRelation(raw: JsonRecord): PlanRelation | undefined {
+ const table = accessObjectOf(raw).find(([label]) => label === "table");
+ return table ? { table: table[1], unresolved: true } : undefined;
+}
+
+function toProperties(raw: JsonRecord): PlanProperty[] {
+ const properties: PlanProperty[] = [];
+ for (const [label, value] of accessObjectOf(raw)) {
+ addPlanProperty(properties, planLabel(label), value);
+ }
+ for (const [key, value] of Object.entries(raw)) {
+ if (PROMOTED_KEYS.has(key)) continue;
+ addPlanProperty(
+ properties,
+ // The id with its sequence number is how TiDB's own text plan names this
+ // operator, which is what a reader has in front of them.
+ key === "id" ? "Operator" : planLabel(key),
+ typeof value === "string" ? value : JSON.stringify(value)
+ );
+ }
+ return properties;
+}
+
+function toWarnings(nodeType: string, raw: JsonRecord): PlanWarning[] {
+ const warning = FULL_SCANS[nodeType];
+ if (!warning) return [];
+ const read = optionalNumber(raw.estRows) ?? optionalNumber(raw.actRows);
+ return read !== undefined && read < FULL_SCAN_ROWS_THRESHOLD ? [] : [warning];
+}
+
+function toPlanNode(raw: JsonRecord, id: string, depth: number): PlanNode {
+ checkPlanDepth(depth);
+ const rawChildren = Array.isArray(raw[CHILDREN_KEY]) ? raw[CHILDREN_KEY] : [];
+ const children = rawChildren
+ .filter(isJsonRecord)
+ .map((child, index) => toPlanNode(child, `${id}.${index}`, depth + 1));
+
+ const operator = stringValue(raw.id) ?? "";
+ const named = OPERATOR_ID.exec(operator);
+ const nodeType = named?.[1] || operator || "Unknown";
+ const table = accessObjectOf(raw).find(([label]) => label === "table");
+ return {
+ id,
+ nodeType,
+ // An operator TiDB names no object for says what it does instead, which is
+ // the condition on a Selection and the join keys on a join.
+ subject: table?.[1] ?? stringValue(raw.operatorInfo),
+ relation: toRelation(raw),
+ relationship: named?.[3] || undefined,
+ rows: optionalNumber(raw.estRows),
+ actualRows: optionalNumber(raw.actRows),
+ properties: toProperties(raw),
+ warnings: toWarnings(nodeType, raw),
+ children,
+ };
+}
+
+export function parseTidbPlan(source: string): PlanParseResult {
+ const trimmed = source.trim();
+ if (!trimmed) {
+ return { ok: false, message: TIDB_PLAN_EMPTY_MESSAGE };
+ }
+
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(trimmed);
+ } catch {
+ return { ok: false, message: TIDB_PLAN_INVALID_JSON_MESSAGE };
+ }
+
+ // TiDB wraps the plan in a one-element list, the root operator inside it.
+ const root = Array.isArray(parsed) ? parsed[0] : parsed;
+ if (!isJsonRecord(root) || !stringValue(root.id)) {
+ return { ok: false, message: TIDB_PLAN_NO_PLAN_MESSAGE };
+ }
+
+ return parseWithDepthLimit(() => toPlanNode(root, "0", 0));
+}
diff --git a/frontend/src/apps/explain-visualizer/trino-plan.test.ts b/frontend/src/apps/explain-visualizer/trino-plan.test.ts
new file mode 100644
index 0000000000..cadcbeb3d3
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/trino-plan.test.ts
@@ -0,0 +1,221 @@
+import { describe, expect, test } from "vitest";
+import {
+ PLAN_TOO_DEEP_MESSAGE,
+ PLAN_TOO_MANY_NODES_MESSAGE,
+ type PlanNode,
+ type PlanTree,
+} from "./plan-model";
+import joinAggregateFragments from "./test-data/trino/join-aggregate-fragments.json";
+import scanFilterProject from "./test-data/trino/scan-filter-project.json";
+import sortLimit from "./test-data/trino/sort-limit.json";
+import {
+ parseTrinoPlan,
+ TRINO_PLAN_EMPTY_MESSAGE,
+ TRINO_PLAN_INVALID_JSON_MESSAGE,
+ TRINO_PLAN_NO_PLAN_MESSAGE,
+} from "./trino-plan";
+
+/** A chain of `depth` operators, which is what drives the depth limit. */
+const nestedPlan = (depth: number): string => {
+ let plan: Record<string, unknown> = { name: "TableScan" };
+ for (let level = 1; level < depth; level += 1) {
+ plan = { name: "Project", children: [plan] };
+ }
+ return JSON.stringify({ "0": plan });
+};
+
+/**
+ * `stages` fragments, each joining two remote sources that both read the next
+ * one, which is the shape a repartitioning join takes. Every path through the
+ * plan splices the rest of it again, so the tree doubles per fragment: 30
+ * would be 2^31 nodes if they were all built before anything counted them.
+ */
+const repartitionedPlan = (stages: number): string => {
+ const fragments: Record<string, unknown> = {};
+ const remote = (id: string) => ({
+ name: "RemoteSource",
+ descriptor: { sourceFragmentIds: `[${id}]` },
+ children: [],
+ });
+ for (let stage = 0; stage < stages; stage += 1) {
+ fragments[String(stage)] = {
+ name: "Join",
+ descriptor: {},
+ children: [remote(String(stage + 1)), remote(String(stage + 1))],
+ };
+ }
+ fragments[String(stages)] = { name: "TableScan", descriptor: {} };
+ return JSON.stringify(fragments);
+};
+
+const parse = (source: string): PlanTree => {
+ const result = parseTrinoPlan(source);
+ if (!result.ok)
+ throw new Error(`expected a parsable plan: ${result.message}`);
+ return result.tree;
+};
+
+const parseFixture = (fixture: unknown): PlanTree =>
+ parse(JSON.stringify(fixture));
+
+const outline = (tree: PlanTree): string[] =>
+ tree.nodes.map((node) => `${node.id} ${node.nodeType}`);
+
+const propertyValue = (node: PlanNode, label: string): string | undefined =>
+ node.properties.find((property) => property.label === label)?.value;
+
+const byId = (tree: PlanTree, id: string): PlanNode => {
+ const node = tree.nodes.find((candidate) => candidate.id === id);
+ if (!node) throw new Error(`no node ${id} in ${outline(tree).join(", ")}`);
+ return node;
+};
+
+describe("parseTrinoPlan", () => {
+ test("reads a single-fragment plan", () => {
+ const tree = parseFixture(scanFilterProject);
+ const scan = byId(tree, "0.0");
+
+ expect(outline(tree)).toEqual(["0 Output", "0.0 ScanFilterProject"]);
+ // Trino fuses a scan, a filter and a projection into one operator and
+ // estimates each step; the last of them is what leaves the operator.
+ expect(scan.rows).toBe(6000);
+ expect(tree.root.rows).toBe(6000);
+ });
+
+ test("splices the fragments a RemoteSource names into one tree", () => {
+ const tree = parseFixture(joinAggregateFragments);
+
+ // Three fragments, read as the one plan Trino would run across them.
+ expect(outline(tree)).toEqual([
+ "0 Output",
+ "0.0 Aggregate",
+ "0.0.0 LocalExchange",
+ "0.0.0.0 RemoteSource",
+ "0.0.0.0.0 Aggregate",
+ "0.0.0.0.0.0 InnerJoin",
+ "0.0.0.0.0.0.0 ScanFilter",
+ "0.0.0.0.0.0.1 LocalExchange",
+ "0.0.0.0.0.0.1.0 RemoteSource",
+ "0.0.0.0.0.0.1.0.0 TableScan",
+ ]);
+ expect(propertyValue(byId(tree, "0.0.0.0"), "Source fragment ids")).toBe(
+ "[1]"
+ );
+ });
+
+ test("answers a scan with the catalog and schema Trino qualified it by", () => {
+ const tree = parseFixture(joinAggregateFragments);
+
+ expect(byId(tree, "0.0.0.0.0.0.0").relation).toEqual({
+ database: "tpch",
+ schema: "sf1",
+ table: "orders",
+ });
+ expect(byId(tree, "0.0.0.0.0.0.1.0.0").relation).toEqual({
+ database: "tpch",
+ schema: "sf1",
+ table: "customer",
+ });
+ // An operator that reads no table names none.
+ expect(byId(tree, "0.0").relation).toBeUndefined();
+ });
+
+ test("reads rows and leaves the cost estimates unranked", () => {
+ const tree = parseFixture(sortLimit);
+ const scan = byId(tree, "0.0.0.0.0.0.0.0.0.0");
+
+ expect(tree.estimates.rows).toBe(true);
+ expect(tree.estimates.cost).toBe(false);
+ expect(tree.costBasis).toBe(0);
+ expect(scan.rows).toBe(1500000);
+ for (const node of tree.nodes) {
+ expect(node.totalCost).toBeUndefined();
+ expect(node.selfCost).toBeUndefined();
+ }
+ // The numbers are still on the node, in Trino's own words.
+ expect(propertyValue(scan, "Estimate")).toContain("Cpu cost:");
+ });
+
+ test("keeps an estimate Trino could not make off the row count", () => {
+ const tree = parse(
+ JSON.stringify({
+ "0": {
+ name: "Aggregate",
+ estimates: [
+ { outputRowCount: "NaN", cpuCost: "NaN", memoryCost: "NaN" },
+ ],
+ },
+ })
+ );
+
+ expect(tree.root.rows).toBeUndefined();
+ expect(propertyValue(tree.root, "Estimate")).toContain("NaN");
+ });
+
+ test("draws what it can of a plan whose fragments read each other", () => {
+ // A fragment that reads itself would never finish.
+ const tree = parse(
+ JSON.stringify({
+ "0": {
+ name: "Output",
+ children: [
+ { name: "RemoteSource", descriptor: { sourceFragmentIds: "[1]" } },
+ ],
+ },
+ "1": {
+ name: "Aggregate",
+ children: [
+ { name: "RemoteSource", descriptor: { sourceFragmentIds: "[0]" } },
+ ],
+ },
+ })
+ );
+
+ expect(outline(tree)).toEqual([
+ "0 Output",
+ "0.0 RemoteSource",
+ "0.0.0 Aggregate",
+ "0.0.0.0 RemoteSource",
+ ]);
+ });
+
+ test("reports a plan it cannot read", () => {
+ expect(parseTrinoPlan(" ")).toEqual({
+ ok: false,
+ message: TRINO_PLAN_EMPTY_MESSAGE,
+ });
+ expect(parseTrinoPlan("not json")).toEqual({
+ ok: false,
+ message: TRINO_PLAN_INVALID_JSON_MESSAGE,
+ });
+ // Trino's text plan, which is what every other EXPLAIN of its returns.
+ expect(parseTrinoPlan("Fragment 0 [SINGLE]")).toEqual({
+ ok: false,
+ message: TRINO_PLAN_INVALID_JSON_MESSAGE,
+ });
+ expect(parseTrinoPlan("{}")).toEqual({
+ ok: false,
+ message: TRINO_PLAN_NO_PLAN_MESSAGE,
+ });
+ });
+
+ test("gives up on a plan that expands past the operators it draws", () => {
+ // A fragment two remote sources read is drawn under each of them, so
+ // without a budget this builds every copy before anything counts them.
+ expect(parseTrinoPlan(repartitionedPlan(30))).toEqual({
+ ok: false,
+ message: PLAN_TOO_MANY_NODES_MESSAGE,
+ });
+ // A plan small enough to draw still draws every path through it: each
+ // fragment is a join and two remote sources over two copies of the next.
+ expect(parse(repartitionedPlan(3)).nodes).toHaveLength(29);
+ });
+
+ test("gives up past the depth it can draw", () => {
+ expect(parseTrinoPlan(nestedPlan(400)).ok).toBe(true);
+ expect(parseTrinoPlan(nestedPlan(2000))).toEqual({
+ ok: false,
+ message: PLAN_TOO_DEEP_MESSAGE,
+ });
+ });
+});
diff --git a/frontend/src/apps/explain-visualizer/trino-plan.ts b/frontend/src/apps/explain-visualizer/trino-plan.ts
new file mode 100644
index 0000000000..78e4244c9c
--- /dev/null
+++ b/frontend/src/apps/explain-visualizer/trino-plan.ts
@@ -0,0 +1,248 @@
+import {
+ addPlanProperty,
+ checkPlanDepth,
+ isJsonRecord,
+ type JsonRecord,
+ type PlanNode,
+ type PlanParseResult,
+ type PlanProperty,
+ type PlanRelation,
+ parseWithDepthLimit,
+ planLabel,
+ planSizeBudget,
+} from "./plan-model";
+
+/**
+ * Maps `EXPLAIN (FORMAT JSON)` output onto the engine-neutral plan model.
+ *
+ * Trino does not return one tree. It returns the fragments it would distribute
+ * across the cluster, keyed by number, and each `RemoteSource` names the
+ * fragments feeding it — so the tree is spliced back together here, which is
+ * what Trino's own text plan shows a reader anyway.
+ *
+ * Its row estimates are read and its cost estimates are not. `cpuCost` is each
+ * operation's own rather than its subtree's, an operator Trino fused reports
+ * one per fused step, and most operators report `NaN` outright on a query
+ * whose statistics are incomplete. Ranking a plan where some operators state a
+ * cost and the rest state NaN would point at whichever happened to be known,
+ * so the numbers stay on the node and nothing is ranked by them.
+ */
+
+const CHILDREN_KEY = "children";
+const ROOT_FRAGMENT = "0";
+
+/** Keys the model promotes to typed fields, so the property list drops them. */
+const PROMOTED_KEYS = new Set([
+ "id",
+ "name",
+ "descriptor",
+ "estimates",
+ CHILDREN_KEY,
+]);
+
+/** The operator whose children are the fragments it names, not its own. */
+const REMOTE_SOURCE = "RemoteSource";
+
+/** Trino writes a table as `catalog:schema:table`. */
+const QUALIFIED_TABLE = /^([^:]+):([^:]+):([^:]+)$/;
+
+export const TRINO_PLAN_EMPTY_MESSAGE =
+ "Trino returned no query plan for this statement.";
+export const TRINO_PLAN_INVALID_JSON_MESSAGE =
+ "The query plan is not valid JSON. Trino's EXPLAIN (FORMAT JSON) output is expected.";
+export const TRINO_PLAN_NO_PLAN_MESSAGE =
+ "The query plan JSON contains no plan fragment to start from.";
+
+function optionalNumber(value: unknown): number | undefined {
+ // Trino writes an estimate it could not make as the string "NaN".
+ if (typeof value === "number" && Number.isFinite(value)) return value;
+ if (typeof value === "string" && value.trim()) {
+ const parsed = Number(value);
+ if (Number.isFinite(parsed)) return parsed;
+ }
+ return undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+ return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function formatValue(value: unknown): string {
+ if (value === null || value === undefined) return "";
+ if (typeof value === "string") return value;
+ if (typeof value === "number" || typeof value === "boolean") {
+ return String(value);
+ }
+ if (Array.isArray(value)) {
+ return value.map((entry) => formatValue(entry)).join(", ");
+ }
+ return JSON.stringify(value);
+}
+
+function descriptorOf(raw: JsonRecord): JsonRecord {
+ return isJsonRecord(raw.descriptor) ? raw.descriptor : {};
+}
+
+/** The estimates Trino made, one per step of an operator it fused. */
+function estimatesOf(raw: JsonRecord): JsonRecord[] {
+ return Array.isArray(raw.estimates) ? raw.estimates.filter(isJsonRecord) : [];
+}
+
+/**
+ * The fragment numbers a `RemoteSource` reads, which Trino writes as a string
+ * holding a bracketed list: `[1]`, or `[1, 2]` where it unions them.
+ */
+function sourceFragments(raw: JsonRecord): string[] {
+ const ids = stringValue(descriptorOf(raw).sourceFragmentIds);
+ if (!ids) return [];
+ return ids
+ .replace(/^\[|\]$/g, "")
+ .split(",")
+ .map((id) => id.trim())
+ .filter(Boolean);
+}
+
+function toRelation(raw: JsonRecord): PlanRelation | undefined {
+ const table = stringValue(descriptorOf(raw).table);
+ const qualified = table ? QUALIFIED_TABLE.exec(table) : null;
+ if (!qualified) return undefined;
+ // Trino's catalog is the database Bytebase connects to; its schema is the
+ // schema, so a node answers a lookup without guessing either.
+ return { database: qualified[1], schema: qualified[2], table: qualified[3] };
+}
+
+/**
+ * What the operator does, for the node's card: the table it reads, or else the
+ * descriptor Trino prints beside the operator in its own text plan.
+ */
+function toSubject(raw: JsonRecord): string | undefined {
+ const descriptor = descriptorOf(raw);
+ const table = stringValue(descriptor.table);
+ if (table) return table;
+ const described = Object.entries(descriptor)
+ .map(([key, value]) => [key, formatValue(value)] as const)
+ .filter(([, value]) => value)
+ .map(([key, value]) => `${key}: ${value}`);
+ return described.length ? described.join(", ") : undefined;
+}
+
+function toProperties(raw: JsonRecord): PlanProperty[] {
+ const properties: PlanProperty[] = [];
+ for (const [key, value] of Object.entries(descriptorOf(raw))) {
+ addPlanProperty(properties, planLabel(key), formatValue(value));
+ }
+ const details = Array.isArray(raw.details) ? raw.details : [];
+ for (const detail of details) {
+ addPlanProperty(properties, "Details", formatValue(detail));
+ }
+ // Every estimate, in the engine's own words, since none of them is ranked.
+ for (const estimate of estimatesOf(raw)) {
+ const described = Object.entries(estimate)
+ .map(([key, value]) => `${planLabel(key)}: ${formatValue(value)}`)
+ .join(", ");
+ addPlanProperty(properties, "Estimate", described);
+ }
+ for (const [key, value] of Object.entries(raw)) {
+ if (PROMOTED_KEYS.has(key) || key === "details") continue;
+ addPlanProperty(properties, planLabel(key), formatValue(value));
+ }
+ return properties;
+}
+
+/**
+ * The rows the operator produces. An operator Trino fused reports one estimate
+ * per fused step, and the last of them is what leaves the operator.
+ */
+function toRows(raw: JsonRecord): number | undefined {
+ const estimates = estimatesOf(raw);
+ const last = estimates[estimates.length - 1];
+ return last ? optionalNumber(last.outputRowCount) : undefined;
+}
+
+/**
+ * @param seen - The fragments on the path to this node. A fragment that reads
+ * itself, directly or through another, would never finish; the rest of the
+ * plan still draws.
+ * @param count - The size budget, since a fragment two remote sources read is
+ * drawn under each of them.
+ */
+function toPlanNode(
+ raw: JsonRecord,
+ fragments: Map<string, JsonRecord>,
+ id: string,
+ seen: Set<string>,
+ depth: number,
+ count: () => void
+): PlanNode {
+ checkPlanDepth(depth);
+ count();
+ const name = stringValue(raw.name) ?? "Unknown";
+ const children: PlanNode[] = [];
+ const add = (child: JsonRecord) =>
+ children.push(
+ toPlanNode(
+ child,
+ fragments,
+ `${id}.${children.length}`,
+ seen,
+ depth + 1,
+ count
+ )
+ );
+
+ const own = Array.isArray(raw[CHILDREN_KEY]) ? raw[CHILDREN_KEY] : [];
+ for (const child of own.filter(isJsonRecord)) add(child);
+
+ if (name === REMOTE_SOURCE) {
+ for (const fragment of sourceFragments(raw)) {
+ const source = fragments.get(fragment);
+ if (!source || seen.has(fragment)) continue;
+ seen.add(fragment);
+ add(source);
+ seen.delete(fragment);
+ }
+ }
+
+ return {
+ id,
+ nodeType: name,
+ subject: toSubject(raw),
+ relation: toRelation(raw),
+ rows: toRows(raw),
+ properties: toProperties(raw),
+ warnings: [],
+ children,
+ };
+}
+
+export function parseTrinoPlan(source: string): PlanParseResult {
+ const trimmed = source.trim();
+ if (!trimmed) {
+ return { ok: false, message: TRINO_PLAN_EMPTY_MESSAGE };
+ }
+
+ let parsed: unknown;
+ try {
+ parsed = JSON.parse(trimmed);
+ } catch {
+ return { ok: false, message: TRINO_PLAN_INVALID_JSON_MESSAGE };
+ }
+ if (!isJsonRecord(parsed)) {
+ return { ok: false, message: TRINO_PLAN_INVALID_JSON_MESSAGE };
+ }
+
+ const fragments = new Map<string, JsonRecord>();
+ for (const [id, fragment] of Object.entries(parsed)) {
+ if (isJsonRecord(fragment)) fragments.set(id, fragment);
+ }
+ // Fragment 0 is the one that returns the query's rows; the rest feed it.
+ const root = fragments.get(ROOT_FRAGMENT) ?? [...fragments.values()][0];
+ if (!root) {
+ return { ok: false, message: TRINO_PLAN_NO_PLAN_MESSAGE };
+ }
+
+ const count = planSizeBudget();
+ return parseWithDepthLimit(() =>
+ toPlanNode(root, fragments, "0", new Set([ROOT_FRAGMENT]), 0, count)
+ );
+}
diff --git a/frontend/src/locales/en-US.json b/frontend/src/locales/en-US.json
index b6339a5c33..d122543002 100644
--- a/frontend/src/locales/en-US.json
+++ b/frontend/src/locales/en-US.json
@@ -3521,18 +3521,46 @@
"zoom-out": "Zoom out"
},
"error": {
+ "clickhouse-empty": "ClickHouse returned no query plan for this statement.",
+ "clickhouse-invalid": "The query plan is not valid JSON. EXPLAIN json = 1 output is expected.",
+ "clickhouse-no-plan": "The ClickHouse query plan JSON does not contain a \"Plan\" object.",
+ "cockroachdb-empty": "CockroachDB returned no query plan for this statement.",
+ "cockroachdb-invalid": "The query plan is not valid JSON. The diagram EXPLAIN (DISTSQL) encodes is expected.",
+ "cockroachdb-no-plan": "The query plan JSON contains no \"processors\" to draw.",
+ "mongodb-empty": "MongoDB returned no query plan for this statement.",
+ "mongodb-invalid": "The query plan is not valid JSON. MongoDB's explain() output is expected.",
+ "mongodb-no-plan": "The query plan JSON has neither a \"queryPlanner\" nor a \"stages\" pipeline to draw.",
"mssql-empty": "SQL Server returned no query plan for this statement.",
"mssql-invalid": "The query plan is not valid XML. SHOWPLAN_XML output is expected.",
"mssql-no-plan": "The query plan XML is not a SQL Server showplan with at least one statement.",
+ "mysql-empty": "No query plan came back for this statement.",
+ "mysql-invalid": "The query plan is not valid JSON. EXPLAIN FORMAT=JSON output is expected.",
+ "mysql-no-plan": "The query plan JSON does not contain a \"query_block\" object.",
+ "oceanbase-empty": "OceanBase returned no query plan for this statement.",
+ "oceanbase-invalid": "The query plan is not valid JSON. OceanBase's EXPLAIN FORMAT=JSON output is expected.",
+ "oceanbase-no-plan": "The query plan JSON names no operator, so there is nothing to draw.",
+ "oracle-empty": "Oracle returned no query plan for this statement.",
+ "oracle-invalid": "The query plan is not valid JSON. Oracle's plan table is expected, as the server renders it.",
+ "oracle-no-plan": "The query plan has no step without a parent, so it has no operator to start from.",
"postgres-empty": "PostgreSQL returned no query plan for this statement.",
"postgres-invalid": "The query plan is not valid JSON. EXPLAIN (FORMAT JSON) output is expected.",
"postgres-no-plan": "The query plan JSON does not contain a \"Plan\" object.",
+ "redshift-empty": "Redshift returned no query plan for this statement.",
+ "redshift-no-plan": "The query plan has no operator in it: a Redshift plan states a cost for every one.",
"spanner-empty": "Spanner returned no query plan for this statement.",
"spanner-emulator": "Spanner returned no query plan for this statement. The Spanner emulator returns none for any statement, so explain it on a Spanner instance to see one.",
"spanner-invalid": "The query plan is not valid JSON. A Spanner query plan is expected.",
"spanner-no-plan": "The query plan JSON does not contain a \"planNodes\" list with an operator at its root.",
+ "starrocks-empty": "The statement produced no query plan to draw.",
+ "starrocks-no-plan": "The query plan has no numbered operator in any of its fragments.",
+ "tidb-empty": "TiDB returned no query plan for this statement.",
+ "tidb-invalid": "The query plan is not valid JSON. EXPLAIN FORMAT=tidb_json output is expected.",
+ "tidb-no-plan": "The query plan JSON does not contain an operator at its root.",
"too-deep": "The query plan is nested too deeply for this visualizer to draw.",
"too-many-nodes": "The query plan has more operators than this visualizer draws, so it is shown as text.",
+ "trino-empty": "Trino returned no query plan for this statement.",
+ "trino-invalid": "The query plan is not valid JSON. Trino's EXPLAIN (FORMAT JSON) output is expected.",
+ "trino-no-plan": "The query plan JSON contains no plan fragment to start from.",
"unreadable": "This query plan could not be read"
},
"grid": {
@@ -3607,6 +3635,20 @@
"estimated-cost": "estimated cost {{cost}}",
"measured-time": "measured time {{time}} ms",
"nodes": "{{count}} nodes"
+ },
+ "warning": {
+ "data-redistribution": {
+ "detail": "This join moves rows between slices before it can match them. Distributing both tables on their join column, or making the smaller one ALL, lets the join run where the rows already are.",
+ "title": "Data redistribution"
+ },
+ "full-index-scan": {
+ "detail": "Reads every entry of this index. If the query needs only a few of them, a condition on the index's leading columns could avoid the full read.",
+ "title": "Full index scan"
+ },
+ "full-table-scan": {
+ "detail": "Reads every row of this table. If the query needs only a few of them, an index on the filtered columns could avoid the full read.",
+ "title": "Full table scan"
+ }
}
},
"query-time": "Query time",
diff --git a/frontend/src/locales/es-ES.json b/frontend/src/locales/es-ES.json
index bad068405f..d1e27f2929 100644
--- a/frontend/src/locales/es-ES.json
+++ b/frontend/src/locales/es-ES.json
@@ -3521,18 +3521,46 @@
"zoom-out": "Alejar"
},
"error": {
+ "clickhouse-empty": "ClickHouse no devolvió ningún plan de consulta para esta sentencia.",
+ "clickhouse-invalid": "El plan de consulta no es JSON válido. Se espera la salida de EXPLAIN json = 1.",
+ "clickhouse-no-plan": "El JSON del plan de consulta de ClickHouse no contiene un objeto \"Plan\".",
+ "cockroachdb-empty": "CockroachDB no devolvió ningún plan de consulta para esta sentencia.",
+ "cockroachdb-invalid": "El plan de consulta no es JSON válido. Se espera el diagrama que codifica EXPLAIN (DISTSQL).",
+ "cockroachdb-no-plan": "El JSON del plan de consulta no contiene \"processors\" que dibujar.",
+ "mongodb-empty": "MongoDB no devolvió ningún plan de consulta para esta sentencia.",
+ "mongodb-invalid": "El plan de consulta no es JSON válido. Se espera la salida de explain() de MongoDB.",
+ "mongodb-no-plan": "El JSON del plan de consulta no tiene ni \"queryPlanner\" ni una tubería \"stages\" que dibujar.",
"mssql-empty": "SQL Server no devolvió ningún plan de consulta para esta sentencia.",
"mssql-invalid": "El plan de consulta no es XML válido. Se espera la salida de SHOWPLAN_XML.",
"mssql-no-plan": "El XML del plan de consulta no es un showplan de SQL Server con al menos una sentencia.",
+ "mysql-empty": "No se devolvió ningún plan de consulta para esta sentencia.",
+ "mysql-invalid": "El plan de consulta no es JSON válido. Se espera la salida de EXPLAIN FORMAT=JSON.",
+ "mysql-no-plan": "El JSON del plan de consulta no contiene un objeto \"query_block\".",
+ "oceanbase-empty": "OceanBase no devolvió ningún plan de consulta para esta sentencia.",
+ "oceanbase-invalid": "El plan de consulta no es JSON válido. Se espera la salida de EXPLAIN FORMAT=JSON de OceanBase.",
+ "oceanbase-no-plan": "El JSON del plan de consulta no nombra ningún operador, así que no hay nada que dibujar.",
+ "oracle-empty": "Oracle no devolvió ningún plan de consulta para esta sentencia.",
+ "oracle-invalid": "El plan de consulta no es JSON válido. Se espera la tabla de planes de Oracle, tal como la representa el servidor.",
+ "oracle-no-plan": "El plan de consulta no tiene ningún paso sin padre, así que no hay un operador por el que empezar.",
"postgres-empty": "PostgreSQL no devolvió ningún plan de consulta para esta sentencia.",
"postgres-invalid": "El plan de consulta no es JSON válido. Se espera la salida de EXPLAIN (FORMAT JSON).",
"postgres-no-plan": "El JSON del plan de consulta no contiene un objeto \"Plan\".",
+ "redshift-empty": "Redshift no devolvió ningún plan de consulta para esta sentencia.",
+ "redshift-no-plan": "El plan de consulta no contiene ningún operador: un plan de Redshift indica un coste para cada uno.",
"spanner-empty": "Spanner no devolvió ningún plan de consulta para esta sentencia.",
"spanner-emulator": "Spanner no devolvió ningún plan de consulta para esta sentencia. El emulador de Spanner no devuelve ninguno para ninguna sentencia; explíquela en una instancia de Spanner para ver uno.",
"spanner-invalid": "El plan de consulta no es JSON válido. Se espera un plan de consulta de Spanner.",
"spanner-no-plan": "El JSON del plan de consulta no contiene una lista \"planNodes\" con un operador en la raíz.",
+ "starrocks-empty": "La sentencia no produjo ningún plan de consulta que dibujar.",
+ "starrocks-no-plan": "El plan de consulta no tiene ningún operador numerado en ninguno de sus fragmentos.",
+ "tidb-empty": "TiDB no devolvió ningún plan de consulta para esta sentencia.",
+ "tidb-invalid": "El plan de consulta no es JSON válido. Se espera la salida de EXPLAIN FORMAT=tidb_json.",
+ "tidb-no-plan": "El JSON del plan de consulta no contiene un operador en la raíz.",
"too-deep": "El plan de consulta está demasiado anidado para que este visualizador pueda dibujarlo.",
"too-many-nodes": "El plan de consulta tiene más operadores de los que este visualizador dibuja, así que se muestra como texto.",
+ "trino-empty": "Trino no devolvió ningún plan de consulta para esta sentencia.",
+ "trino-invalid": "El plan de consulta no es JSON válido. Se espera la salida de EXPLAIN (FORMAT JSON) de Trino.",
+ "trino-no-plan": "El JSON del plan de consulta no contiene ningún fragmento por el que empezar.",
"unreadable": "No se pudo leer este plan de consulta"
},
"grid": {
@@ -3607,6 +3635,20 @@
"estimated-cost": "coste estimado {{cost}}",
"measured-time": "tiempo medido {{time}} ms",
"nodes": "{{count}} nodos"
+ },
+ "warning": {
+ "data-redistribution": {
+ "detail": "Esta unión mueve filas entre segmentos antes de poder emparejarlas. Distribuir ambas tablas por su columna de unión, o hacer ALL la más pequeña, permite que la unión se ejecute donde ya están las filas.",
+ "title": "Redistribución de datos"
+ },
+ "full-index-scan": {
+ "detail": "Lee todas las entradas de este índice. Si la consulta solo necesita unas pocas, una condición sobre las columnas iniciales del índice evitaría la lectura completa.",
+ "title": "Exploración completa del índice"
+ },
+ "full-table-scan": {
+ "detail": "Lee todas las filas de esta tabla. Si la consulta solo necesita unas pocas, un índice sobre las columnas filtradas evitaría la lectura completa.",
+ "title": "Exploración completa de la tabla"
+ }
}
},
"query-time": "Tiempo de consulta",
diff --git a/frontend/src/locales/ja-JP.json b/frontend/src/locales/ja-JP.json
index 25d39a4aa3..840179d2c0 100644
--- a/frontend/src/locales/ja-JP.json
+++ b/frontend/src/locales/ja-JP.json
@@ -3521,18 +3521,46 @@
"zoom-out": "縮小"
},
"error": {
+ "clickhouse-empty": "ClickHouse はこのステートメントのクエリプランを返しませんでした。",
+ "clickhouse-invalid": "クエリプランが有効な JSON ではありません。EXPLAIN json = 1 の出力が必要です。",
+ "clickhouse-no-plan": "ClickHouse のクエリプラン JSON に \"Plan\" オブジェクトがありません。",
+ "cockroachdb-empty": "CockroachDB はこのステートメントのクエリプランを返しませんでした。",
+ "cockroachdb-invalid": "クエリプランが有効な JSON ではありません。EXPLAIN (DISTSQL) が埋め込む図が必要です。",
+ "cockroachdb-no-plan": "クエリプラン JSON に描画できる \"processors\" がありません。",
+ "mongodb-empty": "MongoDB はこのステートメントのクエリプランを返しませんでした。",
+ "mongodb-invalid": "クエリプランが有効な JSON ではありません。MongoDB の explain() の出力が必要です。",
+ "mongodb-no-plan": "クエリプラン JSON に \"queryPlanner\" も、描画できる \"stages\" パイプラインもありません。",
"mssql-empty": "SQL Server はこのステートメントのクエリプランを返しませんでした。",
"mssql-invalid": "クエリプランが有効な XML ではありません。SHOWPLAN_XML の出力が必要です。",
"mssql-no-plan": "クエリプラン XML は、1つ以上のステートメントを含む SQL Server showplan ではありません。",
+ "mysql-empty": "このステートメントのクエリプランは返されませんでした。",
+ "mysql-invalid": "クエリプランが有効な JSON ではありません。EXPLAIN FORMAT=JSON の出力が必要です。",
+ "mysql-no-plan": "クエリプラン JSON に \"query_block\" オブジェクトがありません。",
+ "oceanbase-empty": "OceanBase はこのステートメントのクエリプランを返しませんでした。",
+ "oceanbase-invalid": "クエリプランが有効な JSON ではありません。OceanBase の EXPLAIN FORMAT=JSON の出力が必要です。",
+ "oceanbase-no-plan": "クエリプラン JSON にオペレーターの記載がないため、描画できません。",
+ "oracle-empty": "Oracle はこのステートメントのクエリプランを返しませんでした。",
+ "oracle-invalid": "クエリプランが有効な JSON ではありません。サーバーが描画した Oracle のプランテーブルが必要です。",
+ "oracle-no-plan": "クエリプランに親を持たないステップがないため、起点となるオペレーターがありません。",
"postgres-empty": "PostgreSQL はこのステートメントのクエリプランを返しませんでした。",
"postgres-invalid": "クエリプランが有効な JSON ではありません。EXPLAIN (FORMAT JSON) の出力が必要です。",
"postgres-no-plan": "クエリプラン JSON に \"Plan\" オブジェクトがありません。",
+ "redshift-empty": "Redshift はこのステートメントのクエリプランを返しませんでした。",
+ "redshift-no-plan": "クエリプランにオペレーターがありません。Redshift のプランは各オペレーターにコストを示します。",
"spanner-empty": "Spanner はこのステートメントのクエリプランを返しませんでした。",
"spanner-emulator": "Spanner はこのステートメントのクエリプランを返しませんでした。Spanner エミュレーターはいずれのステートメントにもプランを返さないため、Spanner インスタンスで説明を実行してください。",
"spanner-invalid": "クエリプランが有効な JSON ではありません。Spanner クエリプランが必要です。",
"spanner-no-plan": "クエリプラン JSON に、ルートがオペレーターである \"planNodes\" リストがありません。",
+ "starrocks-empty": "このステートメントから描画できるクエリプランは得られませんでした。",
+ "starrocks-no-plan": "クエリプランのどのフラグメントにも番号付きのオペレーターがありません。",
+ "tidb-empty": "TiDB はこのステートメントのクエリプランを返しませんでした。",
+ "tidb-invalid": "クエリプランが有効な JSON ではありません。EXPLAIN FORMAT=tidb_json の出力が必要です。",
+ "tidb-no-plan": "クエリプラン JSON のルートにオペレーターがありません。",
"too-deep": "クエリプランの入れ子が深すぎるため、このビジュアライザーでは描画できません。",
"too-many-nodes": "クエリプランの演算子数がこのビジュアライザーで描画できる数を超えているため、テキストで表示します。",
+ "trino-empty": "Trino はこのステートメントのクエリプランを返しませんでした。",
+ "trino-invalid": "クエリプランが有効な JSON ではありません。Trino の EXPLAIN (FORMAT JSON) の出力が必要です。",
+ "trino-no-plan": "クエリプラン JSON に、起点となるプランフラグメントがありません。",
"unreadable": "このクエリプランを読み取れませんでした"
},
"grid": {
@@ -3607,6 +3635,20 @@
"estimated-cost": "推定コスト {{cost}}",
"measured-time": "実測時間 {{time}} ms",
"nodes": "{{count}} ノード"
+ },
+ "warning": {
+ "data-redistribution": {
+ "detail": "この結合は、照合の前に行をスライス間で移動します。両方のテーブルを結合列で分散するか、小さいほうを ALL にすると、行がある場所のまま結合できます。",
+ "title": "データの再分配"
+ },
+ "full-index-scan": {
+ "detail": "このインデックスの全エントリを読み取ります。クエリが必要とするエントリがわずかであれば、インデックスの先頭列に条件を付けることで全件読み取りを避けられます。",
+ "title": "フルインデックススキャン"
+ },
+ "full-table-scan": {
+ "detail": "このテーブルの全行を読み取ります。クエリが必要とする行がわずかであれば、絞り込みに使う列へのインデックスで全件読み取りを避けられます。",
+ "title": "フルテーブルスキャン"
+ }
}
},
"query-time": "クエリ時間",
diff --git a/frontend/src/locales/vi-VN.json b/frontend/src/locales/vi-VN.json
index 95b63ba584..cb7dcfa25c 100644
--- a/frontend/src/locales/vi-VN.json
+++ b/frontend/src/locales/vi-VN.json
@@ -3521,18 +3521,46 @@
"zoom-out": "Thu nhỏ"
},
"error": {
+ "clickhouse-empty": "ClickHouse không trả về kế hoạch truy vấn cho câu lệnh này.",
+ "clickhouse-invalid": "Kế hoạch truy vấn không phải JSON hợp lệ. Cần đầu ra EXPLAIN json = 1.",
+ "clickhouse-no-plan": "JSON của kế hoạch truy vấn ClickHouse không chứa đối tượng \"Plan\".",
+ "cockroachdb-empty": "CockroachDB không trả về kế hoạch truy vấn cho câu lệnh này.",
+ "cockroachdb-invalid": "Kế hoạch truy vấn không phải JSON hợp lệ. Cần sơ đồ mà EXPLAIN (DISTSQL) mã hoá.",
+ "cockroachdb-no-plan": "JSON của kế hoạch truy vấn không chứa \"processors\" nào để vẽ.",
+ "mongodb-empty": "MongoDB không trả về kế hoạch truy vấn cho câu lệnh này.",
+ "mongodb-invalid": "Kế hoạch truy vấn không phải JSON hợp lệ. Cần đầu ra explain() của MongoDB.",
+ "mongodb-no-plan": "JSON của kế hoạch truy vấn không có \"queryPlanner\" lẫn tuyến \"stages\" để vẽ.",
"mssql-empty": "SQL Server không trả về kế hoạch truy vấn cho câu lệnh này.",
"mssql-invalid": "Kế hoạch truy vấn không phải XML hợp lệ. Cần đầu ra SHOWPLAN_XML.",
"mssql-no-plan": "XML của kế hoạch truy vấn không phải showplan SQL Server có ít nhất một câu lệnh.",
+ "mysql-empty": "Không có kế hoạch truy vấn nào được trả về cho câu lệnh này.",
+ "mysql-invalid": "Kế hoạch truy vấn không phải JSON hợp lệ. Cần đầu ra EXPLAIN FORMAT=JSON.",
+ "mysql-no-plan": "JSON của kế hoạch truy vấn không chứa đối tượng \"query_block\".",
+ "oceanbase-empty": "OceanBase không trả về kế hoạch truy vấn cho câu lệnh này.",
+ "oceanbase-invalid": "Kế hoạch truy vấn không phải JSON hợp lệ. Cần đầu ra EXPLAIN FORMAT=JSON của OceanBase.",
+ "oceanbase-no-plan": "JSON của kế hoạch truy vấn không nêu toán tử nào, nên không có gì để vẽ.",
+ "oracle-empty": "Oracle không trả về kế hoạch truy vấn cho câu lệnh này.",
+ "oracle-invalid": "Kế hoạch truy vấn không phải JSON hợp lệ. Cần bảng kế hoạch của Oracle, theo cách máy chủ kết xuất nó.",
+ "oracle-no-plan": "Kế hoạch truy vấn không có bước nào không có cha, nên không có toán tử để bắt đầu.",
"postgres-empty": "PostgreSQL không trả về kế hoạch truy vấn cho câu lệnh này.",
"postgres-invalid": "Kế hoạch truy vấn không phải JSON hợp lệ. Cần đầu ra EXPLAIN (FORMAT JSON).",
"postgres-no-plan": "JSON của kế hoạch truy vấn không chứa đối tượng \"Plan\".",
+ "redshift-empty": "Redshift không trả về kế hoạch truy vấn cho câu lệnh này.",
+ "redshift-no-plan": "Kế hoạch truy vấn không có toán tử nào: kế hoạch của Redshift nêu chi phí cho từng toán tử.",
"spanner-empty": "Spanner không trả về kế hoạch truy vấn cho câu lệnh này.",
"spanner-emulator": "Spanner không trả về kế hoạch truy vấn cho câu lệnh này. Trình giả lập Spanner không trả về kế hoạch cho bất kỳ câu lệnh nào; hãy giải thích câu lệnh trên một phiên bản Spanner để xem kế hoạch.",
"spanner-invalid": "Kế hoạch truy vấn không phải JSON hợp lệ. Cần một kế hoạch truy vấn Spanner.",
"spanner-no-plan": "JSON của kế hoạch truy vấn không chứa danh sách \"planNodes\" có toán tử ở gốc.",
+ "starrocks-empty": "Câu lệnh không tạo ra kế hoạch truy vấn nào để vẽ.",
+ "starrocks-no-plan": "Kế hoạch truy vấn không có toán tử được đánh số trong bất kỳ phân đoạn nào.",
+ "tidb-empty": "TiDB không trả về kế hoạch truy vấn cho câu lệnh này.",
+ "tidb-invalid": "Kế hoạch truy vấn không phải JSON hợp lệ. Cần đầu ra EXPLAIN FORMAT=tidb_json.",
+ "tidb-no-plan": "JSON của kế hoạch truy vấn không chứa toán tử ở gốc.",
"too-deep": "Kế hoạch truy vấn lồng quá sâu để trình trực quan hóa này có thể vẽ.",
"too-many-nodes": "Kế hoạch truy vấn có nhiều toán tử hơn mức trình trực quan hóa này vẽ được, nên được hiển thị dưới dạng văn bản.",
+ "trino-empty": "Trino không trả về kế hoạch truy vấn cho câu lệnh này.",
+ "trino-invalid": "Kế hoạch truy vấn không phải JSON hợp lệ. Cần đầu ra EXPLAIN (FORMAT JSON) của Trino.",
+ "trino-no-plan": "JSON của kế hoạch truy vấn không chứa phân đoạn nào để bắt đầu.",
"unreadable": "Không thể đọc kế hoạch truy vấn này"
},
"grid": {
@@ -3607,6 +3635,20 @@
"estimated-cost": "chi phí ước tính {{cost}}",
"measured-time": "thời gian đo được {{time}} ms",
"nodes": "{{count}} nút"
+ },
+ "warning": {
+ "data-redistribution": {
+ "detail": "Phép nối này phải chuyển các hàng giữa các phân mảnh trước khi khớp được chúng. Phân phối cả hai bảng theo cột nối, hoặc đặt bảng nhỏ hơn thành ALL, để phép nối chạy ngay tại nơi đã có dữ liệu.",
+ "title": "Tái phân phối dữ liệu"
+ },
+ "full-index-scan": {
+ "detail": "Đọc mọi mục của chỉ mục này. Nếu truy vấn chỉ cần một vài mục, một điều kiện trên các cột dẫn đầu của chỉ mục có thể tránh được việc đọc toàn bộ.",
+ "title": "Quét toàn bộ chỉ mục"
+ },
+ "full-table-scan": {
+ "detail": "Đọc mọi hàng của bảng này. Nếu truy vấn chỉ cần một vài hàng, một chỉ mục trên các cột lọc có thể tránh được việc đọc toàn bộ.",
+ "title": "Quét toàn bộ bảng"
+ }
}
},
"query-time": "Thời gian truy vấn",
diff --git a/frontend/src/locales/zh-CN.json b/frontend/src/locales/zh-CN.json
index 179cb539f1..c3ea7dfe40 100644
--- a/frontend/src/locales/zh-CN.json
+++ b/frontend/src/locales/zh-CN.json
@@ -3521,18 +3521,46 @@
"zoom-out": "缩小"
},
"error": {
+ "clickhouse-empty": "ClickHouse 未返回此语句的查询计划。",
+ "clickhouse-invalid": "查询计划不是有效的 JSON。需要 EXPLAIN json = 1 输出。",
+ "clickhouse-no-plan": "ClickHouse 查询计划 JSON 不包含 \"Plan\" 对象。",
+ "cockroachdb-empty": "CockroachDB 未返回此语句的查询计划。",
+ "cockroachdb-invalid": "查询计划不是有效的 JSON。需要 EXPLAIN (DISTSQL) 编码的图示。",
+ "cockroachdb-no-plan": "查询计划 JSON 不包含可绘制的 \"processors\"。",
+ "mongodb-empty": "MongoDB 未返回此语句的查询计划。",
+ "mongodb-invalid": "查询计划不是有效的 JSON。需要 MongoDB 的 explain() 输出。",
+ "mongodb-no-plan": "查询计划 JSON 既不包含 \"queryPlanner\",也不包含可绘制的 \"stages\" 管道。",
"mssql-empty": "SQL Server 未返回此语句的查询计划。",
"mssql-invalid": "查询计划不是有效的 XML。需要 SHOWPLAN_XML 输出。",
"mssql-no-plan": "查询计划 XML 不是至少包含一条语句的 SQL Server showplan。",
+ "mysql-empty": "未返回此语句的查询计划。",
+ "mysql-invalid": "查询计划不是有效的 JSON。需要 EXPLAIN FORMAT=JSON 输出。",
+ "mysql-no-plan": "查询计划 JSON 不包含 \"query_block\" 对象。",
+ "oceanbase-empty": "OceanBase 未返回此语句的查询计划。",
+ "oceanbase-invalid": "查询计划不是有效的 JSON。需要 OceanBase 的 EXPLAIN FORMAT=JSON 输出。",
+ "oceanbase-no-plan": "查询计划 JSON 未指明任何操作符,无法绘制。",
+ "oracle-empty": "Oracle 未返回此语句的查询计划。",
+ "oracle-invalid": "查询计划不是有效的 JSON。需要服务器渲染的 Oracle 计划表。",
+ "oracle-no-plan": "查询计划中没有不带父节点的步骤,因此没有可作为起点的操作符。",
"postgres-empty": "PostgreSQL 未返回此语句的查询计划。",
"postgres-invalid": "查询计划不是有效的 JSON。需要 EXPLAIN (FORMAT JSON) 输出。",
"postgres-no-plan": "查询计划 JSON 不包含 \"Plan\" 对象。",
+ "redshift-empty": "Redshift 未返回此语句的查询计划。",
+ "redshift-no-plan": "查询计划中没有操作符:Redshift 的计划会为每个操作符给出成本。",
"spanner-empty": "Spanner 未返回此语句的查询计划。",
"spanner-emulator": "Spanner 未返回此语句的查询计划。Spanner 模拟器不会为任何语句返回计划,请在 Spanner 实例上执行解释以查看计划。",
"spanner-invalid": "查询计划不是有效的 JSON。需要 Spanner 查询计划。",
"spanner-no-plan": "查询计划 JSON 不包含根节点为操作符的 \"planNodes\" 列表。",
+ "starrocks-empty": "该语句未产生可绘制的查询计划。",
+ "starrocks-no-plan": "查询计划的各个片段中都没有编号的操作符。",
+ "tidb-empty": "TiDB 未返回此语句的查询计划。",
+ "tidb-invalid": "查询计划不是有效的 JSON。需要 EXPLAIN FORMAT=tidb_json 输出。",
+ "tidb-no-plan": "查询计划 JSON 的根节点不是操作符。",
"too-deep": "查询计划嵌套过深,此可视化工具无法绘制。",
"too-many-nodes": "查询计划的算子数量超过此可视化工具可绘制的上限,已改为文本展示。",
+ "trino-empty": "Trino 未返回此语句的查询计划。",
+ "trino-invalid": "查询计划不是有效的 JSON。需要 Trino 的 EXPLAIN (FORMAT JSON) 输出。",
+ "trino-no-plan": "查询计划 JSON 中没有可作为起点的计划片段。",
"unreadable": "无法读取此查询计划"
},
"grid": {
@@ -3607,6 +3635,20 @@
"estimated-cost": "预计成本 {{cost}}",
"measured-time": "实测耗时 {{time}} ms",
"nodes": "{{count}} 个节点"
+ },
+ "warning": {
+ "data-redistribution": {
+ "detail": "该连接在匹配之前需要在计算分片之间搬运数据。将两张表都按连接列分布,或把较小的表设为 ALL,可以让连接在数据所在之处完成。",
+ "title": "数据重分布"
+ },
+ "full-index-scan": {
+ "detail": "读取该索引的每一条记录。如果查询只需要其中少数几条,为索引的前导列加上条件就可以避免整体读取。",
+ "title": "全索引扫描"
+ },
+ "full-table-scan": {
+ "detail": "读取该表的每一行。如果查询只需要其中少数几行,在过滤列上建立索引就可以避免整表读取。",
+ "title": "全表扫描"
+ }
}
},
"query-time": "查询时间",
diff --git a/frontend/src/modules/sql-editor/components/ResultView/SingleResultView.test.tsx b/frontend/src/modules/sql-editor/components/ResultView/SingleResultView.test.tsx
index 62db6d300d..27a3be117a 100644
--- a/frontend/src/modules/sql-editor/components/ResultView/SingleResultView.test.tsx
+++ b/frontend/src/modules/sql-editor/components/ResultView/SingleResultView.test.tsx
@@ -1073,19 +1073,17 @@ describe("SingleResultView explain visualizer", () => {
expect(runQuery).not.toHaveBeenCalled();
});
- test("keeps multi-column explain output in the result table", () => {
+ const tabularPlan = (engine: Engine, format: QueryOption_ExplainFormat) =>
render(
<SingleResultView
disallowCopyingData={false}
- params={{ ...params, engine: Engine.MYSQL, explain: true }}
- database={databaseForEngine(Engine.MYSQL)}
+ params={{ ...params, engine, explain: true }}
+ database={databaseForEngine(engine)}
result={create(QueryResultSchema, {
columnNames: ["table", "type"],
columnTypeNames: ["TEXT", "TEXT"],
statement: "EXPLAIN SELECT * FROM t",
- queryPlan: create(QueryResult_QueryPlanSchema, {
- format: QueryOption_ExplainFormat.TEXT,
- }),
+ queryPlan: create(QueryResult_QueryPlanSchema, { format }),
rows: [
create(QueryRowSchema, {
values: [
@@ -1103,12 +1101,31 @@ describe("SingleResultView explain visualizer", () => {
/>
);
+ test("keeps multi-column explain output in the result table", () => {
+ // Snowflake has no parser, so there is no drawable plan to fetch and the
+ // grid is all there is to show.
+ tabularPlan(Engine.SNOWFLAKE, QueryOption_ExplainFormat.TEXT);
+
expect(screen.queryByTestId("query-plan-result")).toBeNull();
expect(screen.getByTestId("result-table")).toHaveTextContent(
"table,typet,ALL"
);
});
+ test("offers a MySQL tabular plan the visualizer, in whatever format it came back", () => {
+ // A tabular EXPLAIN can be re-explained as FORMAT=JSON, so it opens the
+ // viewer with Visualize rather than staying a grid. An omitted FORMAT is
+ // unknown rather than text, and is worth the same offer.
+ for (const format of [
+ QueryOption_ExplainFormat.TEXT,
+ QueryOption_ExplainFormat.EXPLAIN_FORMAT_UNSPECIFIED,
+ ]) {
+ const { unmount } = tabularPlan(Engine.MYSQL, format);
+ expect(screen.getByTestId("query-plan-result")).toBeInTheDocument();
+ unmount();
+ }
+ });
+
test("SQL Server multi-column SHOWPLAN_ALL still opens the visualizer", () => {
render(
<SingleResultView
diff --git a/frontend/src/modules/sql-editor/components/ResultView/SingleResultView.tsx b/frontend/src/modules/sql-editor/components/ResultView/SingleResultView.tsx
index 5421a2f485..02e3d2098d 100644
--- a/frontend/src/modules/sql-editor/components/ResultView/SingleResultView.tsx
+++ b/frontend/src/modules/sql-editor/components/ResultView/SingleResultView.tsx
@@ -80,7 +80,11 @@ import { DetailPanel } from "./DetailPanel";
import { DocumentJSONView } from "./DocumentJSONView";
import { EmptyView } from "./EmptyView";
import { ErrorView } from "./ErrorView";
-import { canReplayStatement, planAvailability } from "./planAvailability";
+import {
+ canReplayStatement,
+ isTextPlanFormat,
+ planAvailability,
+} from "./planAvailability";
import { tableFactsLookup } from "./planTableFacts";
import {
type InlineQueryPlan,
@@ -532,7 +536,11 @@ function SingleResultViewInner({
const planInResult = useMemo(() => inlineQueryPlan(result), [result]);
const canReplay =
isVisualizerEngine(engine) &&
- plan?.format === QueryOption_ExplainFormat.TEXT &&
+ !!plan &&
+ // Redshift's text plan is the one the viewer draws, so there is no other
+ // format to ask the server for.
+ !planInRows &&
+ isTextPlanFormat(plan.format) &&
!plan.executed &&
canReplayStatement(results, resultIndex);
// Multi-column plans (SQL Server SHOWPLAN_ALL) keep their table unless the
diff --git a/frontend/src/modules/sql-editor/components/ResultView/planAvailability.test.ts b/frontend/src/modules/sql-editor/components/ResultView/planAvailability.test.ts
index 125903d95b..4d86b9f158 100644
--- a/frontend/src/modules/sql-editor/components/ResultView/planAvailability.test.ts
+++ b/frontend/src/modules/sql-editor/components/ResultView/planAvailability.test.ts
@@ -1,10 +1,11 @@
import { create } from "@bufbuild/protobuf";
import { describe, expect, test } from "vitest";
import {
+ QueryOption_ExplainFormat,
QueryResult_QueryPlanSchema,
QueryResultSchema,
} from "@/types/proto-es/v1/sql_service_pb";
-import { planAvailability } from "./planAvailability";
+import { isTextPlanFormat, planAvailability } from "./planAvailability";
const rows = (statement = "SELECT 1") =>
create(QueryResultSchema, { statement, columnNames: ["a"] });
@@ -78,3 +79,20 @@ describe("planAvailability", () => {
);
});
});
+
+describe("isTextPlanFormat", () => {
+ test("counts an unknown format as text, so its plan can be fetched again", () => {
+ // MySQL's omitted FORMAT follows the session's explain_format, so a plain
+ // EXPLAIN comes back without the result being able to say in what.
+ expect(
+ isTextPlanFormat(QueryOption_ExplainFormat.EXPLAIN_FORMAT_UNSPECIFIED)
+ ).toBe(true);
+ expect(isTextPlanFormat(QueryOption_ExplainFormat.TEXT)).toBe(true);
+ });
+
+ test("leaves out a format the viewer draws, which needs no second call", () => {
+ expect(isTextPlanFormat(QueryOption_ExplainFormat.JSON)).toBe(false);
+ expect(isTextPlanFormat(QueryOption_ExplainFormat.XML)).toBe(false);
+ expect(isTextPlanFormat(undefined)).toBe(false);
+ });
+});
diff --git a/frontend/src/modules/sql-editor/components/ResultView/planAvailability.ts b/frontend/src/modules/sql-editor/components/ResultView/planAvailability.ts
index 13b1d89b02..2f2d87bdcc 100644
--- a/frontend/src/modules/sql-editor/components/ResultView/planAvailability.ts
+++ b/frontend/src/modules/sql-editor/components/ResultView/planAvailability.ts
@@ -1,4 +1,7 @@
-import type { QueryResult } from "@/types/proto-es/v1/sql_service_pb";
+import {
+ QueryOption_ExplainFormat,
+ type QueryResult,
+} from "@/types/proto-es/v1/sql_service_pb";
export type PlanAvailability = "offered" | "needs-permission" | "absent";
@@ -46,3 +49,20 @@ export function planAvailability({
}
return canExplain ? "offered" : "needs-permission";
}
+
+/**
+ * Whether the viewer shows a plan in this format as text, which is what makes
+ * it worth fetching again in a format the viewer draws.
+ *
+ * Unknown counts as text. MySQL's omitted FORMAT follows the session's
+ * explain_format, so a result cannot say what came back, and text is what the
+ * viewer shows for anything it cannot read.
+ */
+export function isTextPlanFormat(
+ format: QueryOption_ExplainFormat | undefined
+): boolean {
+ return (
+ format === QueryOption_ExplainFormat.TEXT ||
+ format === QueryOption_ExplainFormat.EXPLAIN_FORMAT_UNSPECIFIED
+ );
+}
diff --git a/frontend/src/modules/sql-editor/components/ResultView/planTableFacts.test.ts b/frontend/src/modules/sql-editor/components/ResultView/planTableFacts.test.ts
index 993869d434..04a9acefd5 100644
--- a/frontend/src/modules/sql-editor/components/ResultView/planTableFacts.test.ts
+++ b/frontend/src/modules/sql-editor/components/ResultView/planTableFacts.test.ts
@@ -66,6 +66,17 @@ describe("tableFactsLookup", () => {
).toBeUndefined();
});
+ test("says nothing about a name the engine left as the statement wrote it", () => {
+ // `FROM orders AS o` makes MySQL, MariaDB, TiDB and OceanBase print `o`,
+ // and a database can hold a table called `o`. Answering would describe
+ // that unrelated table as facts about the orders scan.
+ const data = metadata([{ name: "public", tables: [table("o", 12n)] }]);
+
+ expect(lookup(data)({ table: "o", unresolved: true })).toBeUndefined();
+ // The same name from an engine that resolved it is answered as before.
+ expect(lookup(data)({ table: "o" })).toMatchObject({ rowCount: 12 });
+ });
+
test("says nothing about a relation it does not have", () => {
expect(lookup()({ table: "orders" })).toBeUndefined();
expect(lookup()({ table: "" })).toBeUndefined();
diff --git a/frontend/src/modules/sql-editor/components/ResultView/planTableFacts.ts b/frontend/src/modules/sql-editor/components/ResultView/planTableFacts.ts
index af5465ecee..e783a21e4d 100644
--- a/frontend/src/modules/sql-editor/components/ResultView/planTableFacts.ts
+++ b/frontend/src/modules/sql-editor/components/ResultView/planTableFacts.ts
@@ -39,13 +39,18 @@ const sameIdentifier = (a: string, b: string) =>
* The same holds within a database: a plan that names no schema and a name two
* schemas both use is left unanswered. The metadata is the last sync's, which
* is what the rest of the editor shows too.
+ *
+ * So is a name the engine left as the statement wrote it, which is the alias
+ * where the statement gave one: MySQL, MariaDB, TiDB and OceanBase all print
+ * that name and none of them resolves it, so nothing in the plan says whether
+ * `o` is a table or an alias for `orders`.
*/
export function tableFactsLookup(
metadata: DatabaseMetadata,
connectedDatabase: string
): PlanTableLookup {
- return ({ table, schema, database }) => {
- if (!table) return undefined;
+ return ({ table, schema, database, unresolved }) => {
+ if (!table || unresolved) return undefined;
if (database && !sameIdentifier(database, connectedDatabase)) {
return undefined;
}
diff --git a/frontend/src/utils/queryPlanEngines.test.ts b/frontend/src/utils/queryPlanEngines.test.ts
index b2eb5d08ef..344819630d 100644
--- a/frontend/src/utils/queryPlanEngines.test.ts
+++ b/frontend/src/utils/queryPlanEngines.test.ts
@@ -6,14 +6,40 @@ import {
isVisualizerEngine,
VISUALIZER_EXPLAIN_FORMATS,
} from "./queryPlanEngines";
+import { instanceV1AllowsExplain } from "./v1/instance";
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()
+ [
+ Engine.POSTGRES,
+ Engine.MSSQL,
+ Engine.SPANNER,
+ Engine.MYSQL,
+ Engine.MARIADB,
+ Engine.TIDB,
+ Engine.ORACLE,
+ Engine.CLICKHOUSE,
+ Engine.TRINO,
+ Engine.OCEANBASE,
+ Engine.MONGODB,
+ Engine.COCKROACHDB,
+ Engine.REDSHIFT,
+ Engine.STARROCKS,
+ Engine.DORIS,
+ ].sort()
);
expect(isVisualizerEngine(Engine.POSTGRES)).toBe(true);
- expect(isVisualizerEngine(Engine.MYSQL)).toBe(false);
+ expect(isVisualizerEngine(Engine.MYSQL)).toBe(true);
+ expect(isVisualizerEngine(Engine.SNOWFLAKE)).toBe(false);
+ });
+
+ test("names only engines the editor offers Explain on", () => {
+ // Explain is how a plan is asked for, so a parser for an engine the editor
+ // does not explain would never be reached.
+ for (const engine of Object.keys(VISUALIZER_EXPLAIN_FORMATS).map(Number)) {
+ expect(instanceV1AllowsExplain(engine), Engine[engine]).toBe(true);
+ }
});
});
@@ -30,13 +56,37 @@ describe("explainQueryOption", () => {
expect(explainQueryOption(Engine.SPANNER).explainFormat).toBe(
QueryOption_ExplainFormat.JSON
);
+ // These plans are text; the viewer draws them because these engines
+ // publish nothing else.
+ for (const engine of [Engine.REDSHIFT, Engine.STARROCKS, Engine.DORIS]) {
+ expect(explainQueryOption(engine).explainFormat).toBe(
+ QueryOption_ExplainFormat.TEXT
+ );
+ }
+ // Each remaining engine has one structured plan, which the server spells
+ // in that engine's own syntax — or, for Oracle, renders itself.
+ for (const engine of [
+ Engine.MYSQL,
+ Engine.MARIADB,
+ Engine.TIDB,
+ Engine.ORACLE,
+ Engine.CLICKHOUSE,
+ Engine.TRINO,
+ Engine.OCEANBASE,
+ Engine.MONGODB,
+ Engine.COCKROACHDB,
+ ]) {
+ expect(explainQueryOption(engine).explainFormat).toBe(
+ QueryOption_ExplainFormat.JSON
+ );
+ }
});
test("leaves an engine the viewer cannot draw on its own default", () => {
- expect(explainQueryOption(Engine.MYSQL).explainFormat).toBe(
+ expect(explainQueryOption(Engine.SNOWFLAKE).explainFormat).toBe(
QueryOption_ExplainFormat.EXPLAIN_FORMAT_UNSPECIFIED
);
- expect(explainQueryOption(Engine.ORACLE).explainFormat).toBe(
+ expect(explainQueryOption(Engine.HIVE).explainFormat).toBe(
QueryOption_ExplainFormat.EXPLAIN_FORMAT_UNSPECIFIED
);
});
diff --git a/frontend/src/utils/queryPlanEngines.ts b/frontend/src/utils/queryPlanEngines.ts
index 91ff08c2de..586b694bf1 100644
--- a/frontend/src/utils/queryPlanEngines.ts
+++ b/frontend/src/utils/queryPlanEngines.ts
@@ -15,6 +15,20 @@ export const VISUALIZER_EXPLAIN_FORMATS = {
[Engine.POSTGRES]: "JSON",
[Engine.MSSQL]: "XML",
[Engine.SPANNER]: "JSON",
+ [Engine.MYSQL]: "JSON",
+ [Engine.MARIADB]: "JSON",
+ [Engine.TIDB]: "JSON",
+ [Engine.ORACLE]: "JSON",
+ [Engine.CLICKHOUSE]: "JSON",
+ [Engine.TRINO]: "JSON",
+ [Engine.OCEANBASE]: "JSON",
+ [Engine.MONGODB]: "JSON",
+ [Engine.COCKROACHDB]: "JSON",
+ // These three publish no plan as a document; their text plan is what there
+ // is.
+ [Engine.REDSHIFT]: "TEXT",
+ [Engine.STARROCKS]: "TEXT",
+ [Engine.DORIS]: "TEXT",
} as const;
export type VisualizerEngine = keyof typeof VISUALIZER_EXPLAIN_FORMATS;
diff --git a/frontend/src/utils/v1/instance.ts b/frontend/src/utils/v1/instance.ts
index c3d48b4be9..847adb2dd1 100644
--- a/frontend/src/utils/v1/instance.ts
+++ b/frontend/src/utils/v1/instance.ts
@@ -236,6 +236,7 @@ export const instanceV1AllowsExplain = (
const engine = engineOfInstanceV1(instanceOrEngine);
return [
Engine.MYSQL,
+ Engine.MARIADB,
Engine.TIDB,
Engine.CLICKHOUSE,
Engine.COCKROACHDB,
@@ -246,7 +247,11 @@ export const instanceV1AllowsExplain = (
Engine.REDSHIFT,
Engine.SNOWFLAKE,
Engine.STARROCKS,
+ Engine.DORIS,
Engine.SPANNER,
+ Engine.TRINO,
+ Engine.OCEANBASE,
+ Engine.MONGODB,
].includes(engine);
};