spannerplan

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 6, 2026 License: Apache-2.0 Imports: 9 Imported by: 1

README

spannerplan

Go Reference

Spanner QueryPlan manipulation module.

This is a v0 module, so breaking changes are possible across all packages before v1.

Directory overview

  • asciitable: Generic ASCII table and appendix rendering helpers.
  • cmd/lintplan: CLI for printing heuristic warnings about expensive plan operators.
  • cmd/rendertree: CLI for rendering Spanner query plans and profiles as ASCII tables.
  • examples/pgexplainjson: Example renderer for PostgreSQL EXPLAIN (ANALYZE, FORMAT JSON) output.
  • examples/wasm/render: Minimal WebAssembly wrapper around the reference renderer.
  • internal: Internal subpackages that are not recommended for external use.
  • lab: Small ad hoc scripts and experiments.
  • plantree: Spanner PlanNode tree processing and row-building primitives.
  • plantree/reference: High-level reference renderer API for Go, browser, and WebAssembly callers.
  • protoyaml (project-internal helper): YAML and JSON helpers used by this module for decoding protobuf query plan data. External use is not recommended; it is especially likely to be removed or moved behind unexported/internal helpers because it exists for internal use rather than as a supported public API.
  • stats: Execution statistics types and extraction helpers.
  • treerender: Generic ASCII tree renderer with wrapping support.

Browser and WASM embedding

For browser-facing renderers, use github.com/apstndb/spannerplan/plantree/reference as the recommended high-level entrypoint.

  • Go callers should prefer reference.RenderTreeTableWithOptions(...).
  • Serialized or cross-language callers such as WebAssembly or JavaScript wrappers should prefer reference.RenderTreeTableWithConfig(...) with reference.RenderConfig.

A minimal syscall/js wrapper lives in examples/wasm/render. It accepts a Spanner query plan as JSON text or a JavaScript object containing planNodes, parses mode and format strings with reference.ParseRenderMode(...) and reference.ParseFormat(...), decodes render settings into reference.RenderConfig, and returns either {output: string} or {error: string}.

GOOS=js GOARCH=wasm go build -o ./spannerplan.wasm ./examples/wasm/render

const result = globalThis.spannerplanRenderTreeTable(
  queryPlanJson,
  "AUTO",
  "CURRENT",
  {wrapWidth: 80, hangingIndent: true},
)

if (result.error) {
  throw new Error(result.error)
}

console.log(result.output)

Disclaimer

This module is alpha quality.

Documentation

Overview

Package spannerplan provides helper functions to process PlanNodes (EXPERIMENTAL)

Index

Examples

Constants

View Source 
const (
	// KnownFlagFormatRaw prints known boolean flag metadata as is.
	KnownFlagFormatRaw KnownFlagFormat = iota

	// KnownFlagFormatLabel prints known boolean flag metadata without value if true or omits if false.
	KnownFlagFormatLabel

	// Deprecated: FullScanFormatRaw is an alias of KnownFlagFormatRaw.
	FullScanFormatRaw = KnownFlagFormatRaw

	// Deprecated: FullScanFormatLabel is an alias of KnownFlagFormatLabel.
	FullScanFormatLabel = KnownFlagFormatLabel
)

Variables

View Source 
var (
	ErrEmptyPlanNodes           = errors.New("spannerplan: planNodes cannot be empty")
	ErrNilPlanNode              = errors.New("spannerplan: planNode cannot be nil")
	ErrPlanNodeIndexMismatch    = errors.New("spannerplan: planNode index must match slice position")
	ErrNilChildLink             = errors.New("spannerplan: childLink cannot be nil")
	ErrChildLinkIndexOutOfRange = errors.New("spannerplan: childLink childIndex out of range")
)

Category sentinels identify the specific kind of validation failure. Each is reported through a *ValidationError (see New) whose Kind field is set to one of these values and which also wraps ErrInvalidPlan. Match them with errors.Is; prefer ErrInvalidPlan when any validation failure should be treated the same way.

View Source 
var ErrInvalidPlan = errors.New("spannerplan: invalid plan")

ErrInvalidPlan is the stable sentinel identifying any plan-validation failure returned by New. Every validation error wraps it, so consumers can detect a malformed plan with errors.Is(err, ErrInvalidPlan) regardless of the specific cause or the exact message wording, which is not guaranteed to remain stable.

Functions

func ExtractQueryPlan 

func ExtractQueryPlan(b []byte) (*sppb.ResultSetStats, *sppb.StructType, error)

func HasStats added in v0.1.1 

func HasStats(nodes []*sppb.PlanNode) bool

func NodeTitle 

func NodeTitle(node *sppb.PlanNode, opts ...Option) string

Types

type ExecutionMethodFormat 

type ExecutionMethodFormat int64
const (
	// ExecutionMethodFormatRaw prints execution_method metadata as is.
	ExecutionMethodFormatRaw ExecutionMethodFormat = iota

	// ExecutionMethodFormatAngle prints execution_method metadata after display_name with angle bracket like `Scan <Row>`.
	ExecutionMethodFormatAngle
)

func ParseExecutionMethodFormat added in v0.1.2 

func ParseExecutionMethodFormat(s string) (ExecutionMethodFormat, error)

ParseExecutionMethodFormat parses string representation of ExecutionMethodFormat.

type FullScanFormat 

type FullScanFormat = KnownFlagFormat

type KnownFlagFormat 

type KnownFlagFormat int64

func ParseKnownFlagFormat added in v0.1.2 

func ParseKnownFlagFormat(s string) (KnownFlagFormat, error)

ParseKnownFlagFormat parses string representation of KnownFlagFormat.

type Option 

type Option func(o *option)

func EnableCompact 

func EnableCompact() Option

func HideMetadata added in v0.1.3 

func HideMetadata() Option

HideMetadata hides all metadata and labels even if KnownFlagFormatLabel is set. It is used by spannerplanviz.

func WithExecutionMethodFormat 

func WithExecutionMethodFormat(fmt ExecutionMethodFormat) Option

func WithFullScanFormat deprecated 

func WithFullScanFormat(fmt FullScanFormat) Option

Deprecated: WithFullScanFormat is an alias of WithKnownFlagFormat.

func WithInlineStatsFunc added in v0.1.2 

func WithInlineStatsFunc(f func(*sppb.PlanNode) []string) Option

func WithKnownFlagFormat 

func WithKnownFlagFormat(fmt KnownFlagFormat) Option

func WithTargetMetadataFormat 

func WithTargetMetadataFormat(fmt TargetMetadataFormat) Option

type QueryPlan 

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

func New 

func New(planNodes []*sppb.PlanNode) (*QueryPlan, error)

New constructs a QueryPlan from sppb.QueryPlan.PlanNodes.

The input must be the original PlanNodes slice from Cloud Spanner's sppb.QueryPlan. This function assumes each PlanNode.Index matches its position in the slice, as documented by the Spanner protobuf contract. Arbitrary or reordered PlanNode slices are not supported and will return an error.

On validation failure it returns a *ValidationError that wraps ErrInvalidPlan and a category sentinel; see ValidationError.

Example (InvalidPlan)

ExampleNew_invalidPlan shows how to detect a malformed plan without pinning the error message text: errors.Is against ErrInvalidPlan matches any validation failure, and errors.As exposes the structured *ValidationError. 

package main

import (
	"errors"
	"fmt"

	sppb "cloud.google.com/go/spanner/apiv1/spannerpb"

	"github.com/apstndb/spannerplan"
)

func main() {
	// A child link references a node index that does not exist.
	_, err := spannerplan.New([]*sppb.PlanNode{
		{Index: 0, ChildLinks: []*sppb.PlanNode_ChildLink{{ChildIndex: 99}}},
		{Index: 1},
	})

	fmt.Println("is ErrInvalidPlan:", errors.Is(err, spannerplan.ErrInvalidPlan))
	fmt.Println("is ErrChildLinkIndexOutOfRange:", errors.Is(err, spannerplan.ErrChildLinkIndexOutOfRange))

	var verr *spannerplan.ValidationError
	if errors.As(err, &verr) {
		fmt.Printf("node %d, child link %d\n", verr.NodeIndex, verr.ChildIndex)
	}

}

Output:
is ErrInvalidPlan: true
is ErrChildLinkIndexOutOfRange: true
node 0, child link 0

func (*QueryPlan) GetLinkType added in v0.1.3 

func (qp *QueryPlan) GetLinkType(link *sppb.PlanNode_ChildLink) string
func (qp *QueryPlan) GetNodeByChildLink(link *sppb.PlanNode_ChildLink) *sppb.PlanNode

GetNodeByChildLink returns PlanNode indicated by `link`. If `link` is nil, return the root node.

func (*QueryPlan) GetNodeByIndex 

func (qp *QueryPlan) GetNodeByIndex(id int32) *sppb.PlanNode

func (*QueryPlan) GetParentNodeByChildIndex 

func (qp *QueryPlan) GetParentNodeByChildIndex(index int32) *sppb.PlanNode
func (qp *QueryPlan) GetParentNodeByChildLink(link *sppb.PlanNode_ChildLink) *sppb.PlanNode

func (*QueryPlan) HasStats added in v0.1.1 

func (qp *QueryPlan) HasStats() bool

func (*QueryPlan) IsFunction 

func (qp *QueryPlan) IsFunction(childLink *sppb.PlanNode_ChildLink) bool

func (*QueryPlan) IsPredicate 

func (qp *QueryPlan) IsPredicate(childLink *sppb.PlanNode_ChildLink) bool

func (*QueryPlan) IsVisible 

func (qp *QueryPlan) IsVisible(link *sppb.PlanNode_ChildLink) bool

IsVisible reports whether a child link should be rendered as part of the operator tree. Scalar PlanNodes are hidden unless the child link type is "Scalar", which represents scalar subquery-like operator subtrees. A nil link represents the root node. 

func (qp *QueryPlan) ParentLinks(childIndex int32) []ResolvedParentLink

ParentLinks returns all parent child links that point to childIndex.

Links are returned in plan node traversal order, preserving each parent's ChildLinks order. The returned slice is a copy and can be modified by callers.

func (*QueryPlan) PlanNodes 

func (qp *QueryPlan) PlanNodes() []*sppb.PlanNode
func (qp *QueryPlan) ResolveChildLink(item *sppb.PlanNode_ChildLink) *ResolvedChildLink
func (qp *QueryPlan) VisibleChildLinks(node *sppb.PlanNode) []*sppb.PlanNode_ChildLink
type ResolvedChildLink struct {
	ChildLink *sppb.PlanNode_ChildLink
	Child     *sppb.PlanNode
}
type ResolvedParentLink struct {
	Parent    *sppb.PlanNode
	ChildLink *sppb.PlanNode_ChildLink
}

ResolvedParentLink contains a parent PlanNode and the child link that points from that parent to a child node.

type TargetMetadataFormat 

type TargetMetadataFormat int64

TargetMetadataFormat controls how to render target metadata. target metadata are scan_target, distribution_table, and table. 

const (
	// TargetMetadataFormatRaw prints target metadata as is.
	TargetMetadataFormatRaw TargetMetadataFormat = iota

	// TargetMetadataFormatOn prints target metadata as `on <target>`.
	TargetMetadataFormatOn
)

func ParseTargetMetadataFormat added in v0.1.2 

func ParseTargetMetadataFormat(s string) (TargetMetadataFormat, error)

ParseTargetMetadataFormat parses string representation of TargetMetadataFormat.

type ValidationError added in v0.2.0 

type ValidationError struct {
	// Kind is the category sentinel for this failure, e.g.
	// ErrChildLinkIndexOutOfRange. It is always one of the exported
	// Err* sentinels; the ValidationError itself also wraps ErrInvalidPlan.
	Kind error
	// NodeIndex is the plan-node index (equivalently, slice position, which
	// New requires to match) involved in the failure, or -1 when no single
	// node applies (e.g. an empty slice).
	NodeIndex int
	// ChildIndex is the position within the parent node's ChildLinks slice
	// involved in the failure, or -1 when the failure is not about a specific
	// child link.
	ChildIndex int
	// contains filtered or unexported fields
}

ValidationError is returned by New (and any other constructor that validates its input) when a plan fails validation. It provides a stable, machine- readable identity for the failure so consumers can branch on it without pinning message text.

Both errors.Is and errors.As work:

  • errors.Is(err, spannerplan.ErrInvalidPlan) matches any validation failure.
  • errors.Is(err, spannerplan.ErrChildLinkIndexOutOfRange) (and the other category sentinels) matches a specific failure kind.
  • errors.As(err, &verr) exposes the structured fields below.

The Error string is preserved for humans but is not part of the stable API; use the sentinels or the fields instead.

func (*ValidationError) Error added in v0.2.0 

func (e *ValidationError) Error() string

Error returns the full human-readable message. The exact wording is not part of the stable API and may change; match on ErrInvalidPlan, the category sentinels, or the struct fields instead.

func (*ValidationError) Unwrap added in v0.2.0 

func (e *ValidationError) Unwrap() []error

Unwrap reports both ErrInvalidPlan and the wrapped category error, so that errors.Is matches ErrInvalidPlan and every specific sentinel.

Source Files

View all Source files

Directories

Path Synopsis
Package asciitable renders caller-owned rows as ASCII tables.
 Package asciitable renders caller-owned rows as ASCII tables.
cmd
lintplan command
rendertree command
rendertree/impl
examples
pgexplainjson command
wasm/render command
internal
scalarappendix
Package plantree provides functionality to render PlanNode as ASCII tree (EXPERIMENTAL).
 Package plantree provides functionality to render PlanNode as ASCII tree (EXPERIMENTAL).
reference
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.
reference/tools/genexpected command
Package treerender renders generic ASCII operator trees with optional wrapping.
 Package treerender renders generic ASCII operator trees with optional wrapping.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.