planrender

Documentation

Overview

Package planrender renders Cloud Spanner query plans through a thin adapter over github.com/apstndb/spannerplan and github.com/apstndb/spannerplanviz.

The exported API accepts only this package's Format and Options types plus spannerpb messages (metadata.rowType and ResultSetStats). It does not leak those libraries' types. Both libraries are v0 and documented as experimental; this adapter is the CLI boundary while those APIs evolve.

Graphviz SVG/PNG rendering uses github.com/goccy/go-graphviz's WASM runtime (wazero). The v0.11.0 graphviz.Renderer constructs that runtime per Render call and closes it before returning; this package does not retain it.

Index

• Variables
• func Render(ctx context.Context, w io.Writer, format Format, rowType *sppb.StructType, ...) error
• type Format
  • func ParseFormat(s string) (Format, error)
  • func (f Format) IsBinary() bool
  • func (f Format) NeedsGraphviz() bool
• type Options
  • func (o Options) Validate(format Format) error

Variables

var ErrNoQueryPlan = errors.New("no query plan in result; requires --query-mode=PLAN, PROFILE, or WITH_PLAN_AND_STATS")

ErrNoQueryPlan is returned when stats does not contain a usable query plan.

Functions

func Render

func Render(ctx context.Context, w io.Writer, format Format, rowType *sppb.StructType, stats *sppb.ResultSetStats, opts Options) error

Render writes a query plan in format to w.

rowType may be nil. stats must contain a non-empty query plan. Traversal-budget and cycle-detection errors from spannerplan are returned as-is (wrapped). The text renderer has no context parameter; graph renderers receive ctx and honor cancellation where the libraries check it.

Types

type Format

type Format string

Format is a plan-rendering output format.

const (
	FormatText    Format = "text"
	FormatDOT     Format = "dot"
	FormatMermaid Format = "mermaid"
	FormatD2      Format = "d2"
	FormatSVG     Format = "svg"
	FormatPNG     Format = "png"
)

func ParseFormat

func ParseFormat(s string) (Format, error)

ParseFormat parses a plan-rendering format name. Valid values are text, dot, mermaid, d2, svg, and png (case-insensitive).

func (Format) IsBinary

func (f Format) IsBinary() bool

IsBinary reports whether format is a binary image (PNG). SVG is text XML.

func (Format) NeedsGraphviz

func (f Format) NeedsGraphviz() bool

NeedsGraphviz reports whether format requires the embedded Graphviz/WASM runtime.

type Options

type Options struct {
	// TextStyle is current, traditional, or compact. Empty means current.
	TextStyle string
	// WrapWidth is passed to the text renderer. 0 disables wrapping.
	WrapWidth int
	// PrintSections is basic, enhanced, full, none, or an explicit
	// comma-separated section list. Empty means basic.
	PrintSections string
	// Full selects visualize.FullBuildOptions instead of StructureBuildOptions.
	Full bool
	// ShowQuery adds a query-text node to graph output.
	ShowQuery bool
	// ShowQueryStats adds query statistics to that node.
	ShowQueryStats bool
	// Query is injected as query_stats.query_text when ShowQuery is true.
	// It is ignored when empty; a non-empty value without ShowQuery is an error.
	Query string
}

Options configures plan rendering. Zero values select defaults.

TextStyle, WrapWidth, and PrintSections apply only to FormatText. Full, ShowQuery, ShowQueryStats, and Query apply only to graph formats. Render rejects combinations that do not apply to the chosen format rather than silently ignoring them.

func (Options) Validate

func (o Options) Validate(format Format) error

Validate reports whether opts apply to format.