Documentation
¶
Overview ¶
Package plantree provides functionality to render PlanNode as ASCII tree (EXPERIMENTAL).
RowWithPredicates and tree prefix ¶
The tree prefix is exposed without tying callers to a particular struct field shape:
- RowWithPredicates.TreePartString — one string (newline-separated lines), stable with historical encoding
- RowWithPredicates.TreePartLines — one string per line of RowWithPredicates.NodeText
Prefer these methods over reading the TreePart field directly so future internal representations can change with less churn. Typical rendering uses RowWithPredicates.Text, which combines tree prefix and node title.
The TreePart field remains exported for struct literals and cmp.Diff in tests; new code should use the accessors above when not constructing rows by hand. When tests do construct RowWithPredicates values directly, prefer keyed composite literals so future exported fields do not break the call site.
Rows also expose scalar child links in original PlanNode.ChildLinks order via RowWithPredicates.ScalarChildLinks. Callers should group those links at rendering time using the parent row's RowWithPredicates.DisplayName together with each ScalarChildLink.Type, because the same child-link type can have different meanings under different operators. RowWithPredicates.ChildLinks remains available for compatibility with older callers, but new code should prefer RowWithPredicates.ScalarChildLinks because it preserves Spanner's original PlanNode.ChildLinks order after filtering to scalar child links. RowWithPredicates.Keys is also kept for compatibility and contains scalar child descriptions grouped by child-link type; new code should use RowWithPredicates.ScalarChildLinks when it needs variables, child indexes, or stable ordering.
A []string field would avoid one strings.Join in the renderer and one strings.Split in Text, but it is a breaking API change for modules that build RowWithPredicates literals in tests (for example github.com/apstndb/spanner-mycli). Downstream production code reviewed at the time of this change uses ProcessPlan and Text/FormatID only, not TreePart field access.
Breaking changes in this package are called out in the release / PR description when they affect exported options or types.
Stability ¶
This package is still marked EXPERIMENTAL. The shape of exported row types (including how TreePart is represented) may change in a future version if we adopt a different internal representation—callers should prefer RowWithPredicates.Text and stable Option entrypoints where possible, and pin module versions when upgrading.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ContinuationIndent
deprecated
added in
v0.1.5
type ContinuationIndent int
ContinuationIndent controls how wrapped continuation lines are aligned.
Deprecated: use WithHangingIndent to opt into hanging indent, or omit the option to keep the default tree-aligned continuation behavior.
const ( // ContinuationIndentTree preserves the current behavior: continuation lines align only to the tree prefix. // // Deprecated: omit [WithHangingIndent] to keep the default tree-aligned continuation behavior. ContinuationIndentTree ContinuationIndent = iota // ContinuationIndentNodePrefix hangs continuation lines after a node-local prefix such as `[Input] `. // // Deprecated: use [WithHangingIndent]. ContinuationIndentNodePrefix )
type Option ¶
type Option func(*options)
Option configures ProcessPlan.
func DisallowUnknownStats ¶
func DisallowUnknownStats() Option
DisallowUnknownStats makes ProcessPlan fail on unknown execution-stat keys.
func WithContinuationIndent
deprecated
added in
v0.1.5
func WithContinuationIndent(indent ContinuationIndent) Option
WithContinuationIndent selects how wrapped continuation lines are aligned. The default ContinuationIndentTree preserves the current behavior. ContinuationIndentNodePrefix is opt-in and hangs continuation lines after a node-local prefix such as `[Input] ` or `[Map] ` when present.
Deprecated: use WithHangingIndent to opt into hanging indent, or omit the option to keep the default tree-aligned continuation behavior.
func WithHangingIndent ¶ added in v0.1.6
func WithHangingIndent() Option
WithHangingIndent hangs wrapped continuation lines after a node-local prefix such as `[Input] ` or `[Map] ` instead of keeping the default tree-aligned indentation.
func WithQueryPlanOptions ¶
func WithQueryPlanOptions(opts ...spannerplan.Option) Option
WithQueryPlanOptions forwards node-title formatting options to the underlying query plan renderer.
func WithWrapWidth ¶
WithWrapWidth sets the maximum total rendered line width, including the tree prefix. Node title text is wrapped to the remaining width after accounting for the tree prefix. A value of 0 disables wrapping (consistent with the rendertree CLI default of 0). Negative values make ProcessPlan return an error.
type RowWithPredicates ¶
type RowWithPredicates struct {
// ID is the Spanner PlanNode index for this row.
ID int32
// TreePart stores everything rendered before NodeText on each visual line: the ASCII tree prefix
// plus any continuation padding inserted by the renderer for wrapping / hanging indent.
// Prefer [RowWithPredicates.TreePartString] or [RowWithPredicates.TreePartLines] instead of
// reading this field directly, so callers stay decoupled if the storage shape changes.
TreePart string
// NodeText is the rendered operator title, possibly split across visual lines.
NodeText string
// DisplayName is the raw Spanner PlanNode display name, before metadata is folded into NodeText.
DisplayName string
// Predicates contains filter predicate text associated with this row.
Predicates []string
// Keys contains scalar child descriptions grouped by ChildLink type.
//
// Deprecated: this field is kept for source compatibility.
// Use [RowWithPredicates.ScalarChildLinks] and filter by [ScalarChildLink.Type] instead.
Keys map[string][]string
// ExecutionStats contains execution statistics associated with this row.
ExecutionStats stats.ExecutionStats
// ChildLinks contains resolved child-link metadata associated with this row.
//
// Deprecated: use [RowWithPredicates.ScalarChildLinks] for ordered scalar child-link metadata.
ChildLinks map[string][]*spannerplan.ResolvedChildLink
// ScalarChildLinks contains this row's scalar child links in original PlanNode.ChildLinks order.
ScalarChildLinks []ScalarChildLink
}
RowWithPredicates is one rendered plan row plus predicate and execution metadata.
func ProcessPlan ¶
func ProcessPlan(qp *spannerplan.QueryPlan, opts ...Option) (rows []RowWithPredicates, err error)
ProcessPlan converts a query plan into rendered tree rows with predicate and execution metadata.
func (RowWithPredicates) FormatID ¶
func (r RowWithPredicates) FormatID() string
FormatID returns the display ID, prefixed with "*" when the row has predicates.
func (RowWithPredicates) Text ¶
func (r RowWithPredicates) Text() string
Text returns the full rendered row text, with the tree prefix prepended to each node text line.
func (RowWithPredicates) TreePartLines ¶ added in v0.1.5
func (r RowWithPredicates) TreePartLines() []string
TreePartLines splits RowWithPredicates.TreePartString into one prefix per visual line.
func (RowWithPredicates) TreePartString ¶ added in v0.1.5
func (r RowWithPredicates) TreePartString() string
TreePartString returns the full tree-prefix string (newline-separated lines), matching the historical field encoding. Use this when you need a single string; use RowWithPredicates.TreePartLines for per-line access.
type ScalarChildLink ¶ added in v0.1.10
type ScalarChildLink struct {
// Type is the ChildLink type, such as "Condition", "Key", or "Agg".
Type string
// Variable is the ChildLink variable, when Spanner provides one.
Variable string
// Description is the scalar child node's short representation description.
Description string
// DisplayName is the scalar child node's raw PlanNode display name.
DisplayName string
// ChildIndex is the scalar child node's PlanNode index.
ChildIndex int32
}
ScalarChildLink is a scalar child link attached to a rendered plan row.
It keeps raw-ish child-link fields so callers can group links by the parent row's DisplayName and the child-link Type. The same Type can have different semantics under different parent operators, for example Sort Key versus Aggregate Key.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package reference provides a reference implementation for rendering Spanner query plans as ASCII tables with various formatting options.
|
Package reference provides a reference implementation for rendering Spanner query plans as ASCII tables with various formatting options. |
|
tools/genexpected
command
|