cockroach: github.com/cockroachdb/cockroach/pkg/sql/opt/exec/explain Index | Examples | Files

package explain

import "github.com/cockroachdb/cockroach/pkg/sql/opt/exec/explain"

Index

Examples

Package Files

emit.go explain_factory.go flags.go output.go result_columns.go

func Emit Uses

func Emit(plan *Plan, ob *OutputBuilder, spanFormatFn SpanFormatFn) error

Emit produces the EXPLAIN output against the given OutputBuilder. The OutputBuilder flags are taken into account.

type Factory Uses

type Factory struct {
    // contains filtered or unexported fields
}

Factory implements exec.ExplainFactory. It wraps another factory and forwards all factory calls, while also recording the calls and arguments. The product of the factory is the Plan returned by ConstructPlan, which can be used to access the wrapped plan, as well as a parallel Node tree which can be used to produce EXPLAIN information.

func NewFactory Uses

func NewFactory(wrappedFactory exec.Factory) *Factory

NewFactory creates a new explain factory.

func (*Factory) AnnotateNode Uses

func (f *Factory) AnnotateNode(execNode exec.Node, id exec.ExplainAnnotationID, value interface{})

AnnotateNode is part of the exec.ExplainFactory interface.

func (*Factory) ConstructPlan Uses

func (f *Factory) ConstructPlan(
    root exec.Node, subqueries []exec.Subquery, cascades []exec.Cascade, checks []exec.Node,
) (exec.Plan, error)

ConstructPlan is part of the exec.Factory interface.

type Flags Uses

type Flags struct {
    // Verbose indicates that more metadata is shown, and plan columns and
    // ordering are shown.
    Verbose bool
    // ShowTypes indicates that the types of columns are shown.
    // If ShowTypes is true, then Verbose is also true.
    ShowTypes bool
    // If HideValues is true, we hide fields that may contain values from the
    // query (e.g. spans). Used internally for the plan visible in the UI.
    // If HideValues is true, then Verbose must be false.
    HideValues bool
}

Flags are modifiers for EXPLAIN (PLAN).

func MakeFlags Uses

func MakeFlags(options *tree.ExplainOptions) Flags

MakeFlags crates Flags from ExplainOptions.

type Node Uses

type Node struct {
    // contains filtered or unexported fields
}

Node in a plan tree; records the operation and arguments passed to the factory method and provides access to the corresponding exec.Node (produced by the wrapped factory).

func (*Node) Child Uses

func (n *Node) Child(idx int) *Node

Child returns the i-th child.

func (*Node) ChildCount Uses

func (n *Node) ChildCount() int

ChildCount returns the number of children nodes.

func (*Node) Columns Uses

func (n *Node) Columns() colinfo.ResultColumns

Columns returns the ResultColumns for this node.

func (*Node) Ordering Uses

func (n *Node) Ordering() colinfo.ColumnOrdering

Ordering returns the required output ordering for this node; columns correspond to Columns().

func (*Node) WrappedNode Uses

func (n *Node) WrappedNode() exec.Node

WrappedNode returns the corresponding exec.Node produced by the wrapped factory.

type OutputBuilder Uses

type OutputBuilder struct {
    // contains filtered or unexported fields
}

OutputBuilder is used to build the output of an explain tree.

See ExampleOutputBuilder for sample usage.

Code:

example := func(name string, flags explain.Flags) {
    ob := explain.NewOutputBuilder(flags)
    ob.AddField("distributed", "true")
    ob.EnterMetaNode("meta")
    {
        ob.EnterNode(
            "render",
            colinfo.ResultColumns{{Name: "a", Typ: types.Int}, {Name: "b", Typ: types.String}},
            colinfo.ColumnOrdering{
                {ColIdx: 0, Direction: encoding.Ascending},
                {ColIdx: 1, Direction: encoding.Descending},
            },
        )
        ob.AddField("render 0", "foo")
        ob.AddField("render 1", "bar")
        {
            ob.EnterNode("join", colinfo.ResultColumns{{Name: "x", Typ: types.Int}}, nil)
            ob.AddField("type", "outer")
            {
                {
                    ob.EnterNode("scan", colinfo.ResultColumns{{Name: "x", Typ: types.Int}}, nil)
                    ob.AddField("table", "foo")
                    ob.LeaveNode()
                }
                {
                    ob.EnterNode("scan", nil, nil) // Columns should show up as "()".
                    ob.AddField("table", "bar")
                    ob.LeaveNode()
                }
            }
            ob.LeaveNode()
        }
        ob.LeaveNode()
    }
    ob.LeaveNode()

    rows := ob.BuildExplainRows()

    var buf bytes.Buffer
    tw := tabwriter.NewWriter(&buf, 2, 1, 2, ' ', 0)
    for _, r := range rows {
        for j := range r {
            if j > 0 {
                fmt.Fprint(tw, "\t")
            }
            fmt.Fprint(tw, tree.AsStringWithFlags(r[j], tree.FmtExport))
        }
        fmt.Fprint(tw, "\n")
    }
    _ = tw.Flush()

    fmt.Printf("-- %s (datums) --\n", name)
    fmt.Print(util.RemoveTrailingSpaces(buf.String()))

    fmt.Printf("\n-- %s (string) --\n", name)
    fmt.Print(ob.BuildString())

    treeYaml, err := yaml.Marshal(ob.BuildProtoTree())
    if err != nil {
        panic(err)
    }
    fmt.Printf("\n-- %s (tree) --\n%s\n", name, treeYaml)
}

example("basic", explain.Flags{})
example("verbose", explain.Flags{Verbose: true})
example("verbose+types", explain.Flags{Verbose: true, ShowTypes: true})

Output:

-- basic (datums) --
                     distributed  true
meta
 └── render
      │              render 0     foo
      │              render 1     bar
      └── join
           │         type         outer
           ├── scan
           │         table        foo
           └── scan
                     table        bar

-- basic (string) --
                     distributed  true
meta
 └── render
      │              render 0     foo
      │              render 1     bar
      └── join
           │         type         outer
           ├── scan
           │         table        foo
           └── scan
                     table        bar

-- basic (tree) --
name: meta
attrs: []
children:
- name: render
  attrs:
  - key: render 0
    value: foo
  - key: render 1
    value: bar
  children:
  - name: join
    attrs:
    - key: type
      value: outer
    children:
    - name: scan
      attrs:
      - key: table
        value: foo
      children: []
    - name: scan
      attrs:
      - key: table
        value: bar
      children: []

-- verbose (datums) --
                     0          distributed  true
meta                 0  meta
 └── render          1  render                      (a, b)  +a,-b
      │              1          render 0     foo
      │              1          render 1     bar
      └── join       2  join                        (x)
           │         2          type         outer
           ├── scan  3  scan                        (x)
           │         3          table        foo
           └── scan  3  scan                        ()
                     3          table        bar

-- verbose (string) --
                     distributed  true
meta
 └── render                              (a, b)  +a,-b
      │              render 0     foo
      │              render 1     bar
      └── join                           (x)
           │         type         outer
           ├── scan                      (x)
           │         table        foo
           └── scan                      ()
                     table        bar

-- verbose (tree) --
name: meta
attrs: []
children:
- name: render
  attrs:
  - key: render 0
    value: foo
  - key: render 1
    value: bar
  children:
  - name: join
    attrs:
    - key: type
      value: outer
    children:
    - name: scan
      attrs:
      - key: table
        value: foo
      children: []
    - name: scan
      attrs:
      - key: table
        value: bar
      children: []

-- verbose+types (datums) --
                     0          distributed  true
meta                 0  meta
 └── render          1  render                      (a int, b string)  +a,-b
      │              1          render 0     foo
      │              1          render 1     bar
      └── join       2  join                        (x int)
           │         2          type         outer
           ├── scan  3  scan                        (x int)
           │         3          table        foo
           └── scan  3  scan                        ()
                     3          table        bar

-- verbose+types (string) --
                     distributed  true
meta
 └── render                              (a int, b string)  +a,-b
      │              render 0     foo
      │              render 1     bar
      └── join                           (x int)
           │         type         outer
           ├── scan                      (x int)
           │         table        foo
           └── scan                      ()
                     table        bar

-- verbose+types (tree) --
name: meta
attrs: []
children:
- name: render
  attrs:
  - key: render 0
    value: foo
  - key: render 1
    value: bar
  children:
  - name: join
    attrs:
    - key: type
      value: outer
    children:
    - name: scan
      attrs:
      - key: table
        value: foo
      children: []
    - name: scan
      attrs:
      - key: table
        value: bar
      children: []

func NewOutputBuilder Uses

func NewOutputBuilder(flags Flags) *OutputBuilder

NewOutputBuilder creates a new OutputBuilder.

EnterNode / EnterMetaNode and AddField should be used to populate data, after which a Build* method should be used.

func (*OutputBuilder) AddField Uses

func (ob *OutputBuilder) AddField(key, value string)

AddField adds an information field under the current node.

func (*OutputBuilder) Attr Uses

func (ob *OutputBuilder) Attr(key string, value interface{})

Attr adds an information field under the current node.

func (*OutputBuilder) Attrf Uses

func (ob *OutputBuilder) Attrf(key, format string, args ...interface{})

Attrf is a formatter version of Attr.

func (*OutputBuilder) BuildExplainRows Uses

func (ob *OutputBuilder) BuildExplainRows() []tree.Datums

BuildExplainRows builds the output rows for an EXPLAIN (PLAN) statement.

The columns are:

verbose=false:  Tree Field Description
verbose=true:   Tree Level Type Field Description

func (*OutputBuilder) BuildProtoTree Uses

func (ob *OutputBuilder) BuildProtoTree() *roachpb.ExplainTreePlanNode

BuildProtoTree creates a representation of the plan as a tree of roachpb.ExplainTreePlanNodes.

func (*OutputBuilder) BuildString Uses

func (ob *OutputBuilder) BuildString() string

BuildString creates a string representation of the plan information. The output string always ends in a newline.

func (*OutputBuilder) EnterMetaNode Uses

func (ob *OutputBuilder) EnterMetaNode(name string)

EnterMetaNode is like EnterNode, but the output will always have empty strings for the columns and ordering. This is used for "meta nodes" like "fk-cascade".

func (*OutputBuilder) EnterNode Uses

func (ob *OutputBuilder) EnterNode(
    name string, columns colinfo.ResultColumns, ordering colinfo.ColumnOrdering,
)

EnterNode creates a new node as a child of the current node.

func (*OutputBuilder) Expr Uses

func (ob *OutputBuilder) Expr(key string, expr tree.TypedExpr, varColumns colinfo.ResultColumns)

Expr adds an information field with an expression. The expression's IndexedVars refer to the given columns. If the expression is nil, nothing is emitted.

func (*OutputBuilder) LeaveNode Uses

func (ob *OutputBuilder) LeaveNode()

LeaveNode moves the current node back up the tree by one level.

func (*OutputBuilder) VAttr Uses

func (ob *OutputBuilder) VAttr(key string, value interface{})

VAttr adds an information field under the current node, if the Verbose flag is set.

func (*OutputBuilder) VExpr Uses

func (ob *OutputBuilder) VExpr(key string, expr tree.TypedExpr, varColumns colinfo.ResultColumns)

VExpr is a verbose-only variant of Expr.

type Plan Uses

type Plan struct {
    Root        *Node
    Subqueries  []exec.Subquery
    Cascades    []exec.Cascade
    Checks      []*Node
    WrappedPlan exec.Plan
}

Plan is the result of ConstructPlan; provides access to the exec.Plan produced by the wrapped factory.

type SpanFormatFn Uses

type SpanFormatFn func(table cat.Table, index cat.Index, scanParams exec.ScanParams) string

SpanFormatFn is a function used to format spans for EXPLAIN. Only called when there is an index constraint or an inverted constraint.

Package explain imports 17 packages (graph) and is imported by 1 packages. Updated 2020-09-27. Refresh now. Tools for package owners.