reference

package
v0.1.11 Latest Latest
Warning

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

Go to latest
Published: May 17, 2026 License: Apache-2.0 Imports: 8 Imported by: 0

Documentation

Overview

Package reference provides a reference implementation for rendering Spanner query plans as ASCII tables with various formatting options.

Go callers should prefer RenderTreeTableWithOptions with functional options. Cross-language integrations, such as WebAssembly or JavaScript wrappers that start from JSON-like configuration, can use RenderTreeTableWithConfig and RenderConfig.

For browser or WebAssembly embeddings, this package is the recommended high-level renderer entrypoint: decode serialized query plan JSON into spannerpb.QueryPlan with protojson, parse string inputs with ParseRenderMode and ParseFormat, then call RenderTreeTableWithConfig with plan.GetPlanNodes(). The repository's examples/wasm/render example shows a small syscall/js wrapper with that flow.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RenderTreeTable

func RenderTreeTable(planNodes []*sppb.PlanNode, mode RenderMode, format Format, wrapWidth int) (string, error)

RenderTreeTable renders Spanner plan nodes as an ASCII table. It supports different render modes (AUTO, PLAN, PROFILE) and formats (TRADITIONAL, CURRENT, COMPACT). The wrapWidth parameter controls text wrapping (0 disables wrapping).

func RenderTreeTableWithConfig added in v0.1.8

func RenderTreeTableWithConfig(planNodes []*sppb.PlanNode, mode RenderMode, format Format, config RenderConfig) (string, error)

RenderTreeTableWithConfig renders Spanner plan nodes as an ASCII table using serialization-friendly rendering configuration.

func RenderTreeTableWithOptions added in v0.1.5

func RenderTreeTableWithOptions(planNodes []*sppb.PlanNode, mode RenderMode, format Format, opts ...Option) (string, error)

RenderTreeTableWithOptions renders Spanner plan nodes as an ASCII table with optional rendering configuration.

Types

type Format

type Format string

Format specifies the formatting style for the query plan output.

const (
	// FormatTraditional uses raw metadata format in node titles.
	FormatTraditional Format = "TRADITIONAL"
	// FormatCurrent uses modern formatting with labels and angle brackets.
	FormatCurrent Format = "CURRENT"
	// FormatCompact uses compact tree rendering with minimal spacing.
	FormatCompact Format = "COMPACT"
)

func ParseFormat

func ParseFormat(str string) (Format, error)

ParseFormat parses a string into a Format. Valid values are "TRADITIONAL", "CURRENT", and "COMPACT" (case-insensitive).

type Option added in v0.1.5

type Option func(*options)

Option configures optional rendering behavior for RenderTreeTableWithOptions.

func WithHangingIndent added in v0.1.5

func WithHangingIndent() Option

WithHangingIndent hangs wrapped continuation lines after node-local prefixes such as `[Input] ` and `[Map] ` instead of keeping the default tree-aligned indentation.

func WithPrintSections added in v0.1.10

func WithPrintSections(sections ...PrintSection) Option

WithPrintSections selects appendix sections printed after the rendered tree table. If this option is omitted, PrintPredicates is printed for compatibility. Passing no sections suppresses appendices.

func WithResolveScalarVars added in v0.1.10

func WithResolveScalarVars() Option

WithResolveScalarVars replaces direct scalar variable aliases in semantic appendix sections.

func WithResolveScalarVarsRecursive added in v0.1.10

func WithResolveScalarVarsRecursive() Option

WithResolveScalarVarsRecursive recursively resolves scalar variable aliases in semantic appendix sections.

func WithShowScalarVars added in v0.1.10

func WithShowScalarVars() Option

WithShowScalarVars prints scalar assignment variable names in semantic appendix sections.

func WithWrapWidth added in v0.1.5

func WithWrapWidth(width int) Option

WithWrapWidth sets the maximum total rendered line width, including the tree prefix. A value of 0 disables wrapping. Negative values make RenderTreeTableWithOptions return an error.

type PrintPreset added in v0.1.11

type PrintPreset string

PrintPreset selects an intent-based appendix section set.

const (
	// PrintPresetBasic prints predicate-like scalar links.
	PrintPresetBasic PrintPreset = "basic"
	// PrintPresetEnhanced prints predicate, ordering, and aggregate sections.
	PrintPresetEnhanced PrintPreset = "enhanced"
	// PrintPresetFull prints all scalar links, including unnamed links.
	PrintPresetFull PrintPreset = "full"
	// PrintPresetNone suppresses appendix sections.
	PrintPresetNone PrintPreset = "none"
)

func ParsePrintPreset added in v0.1.11

func ParsePrintPreset(s string) (PrintPreset, error)

ParsePrintPreset parses one print preset name. Valid values are "basic", "enhanced", "full", and "none" (case-insensitive).

func (PrintPreset) Sections added in v0.1.11

func (p PrintPreset) Sections() (PrintSections, error)

Sections returns the appendix sections for p.

type PrintSection added in v0.1.10

type PrintSection string

PrintSection selects one appendix section printed after the rendered tree table.

const (
	// PrintPredicates prints predicate-like scalar links.
	PrintPredicates PrintSection = "predicates"
	// PrintOrdering prints ordering scalar links for sort operators.
	PrintOrdering PrintSection = "ordering"
	// PrintAggregate prints grouping and aggregate scalar links for aggregate operators.
	PrintAggregate PrintSection = "aggregate"
	// PrintTyped prints all typed scalar links as a raw debug dump.
	PrintTyped PrintSection = "typed"
	// PrintFull prints all scalar links, including unnamed links, as a raw debug dump.
	PrintFull PrintSection = "full"
)

func ParsePrintSection added in v0.1.10

func ParsePrintSection(s string) (PrintSection, error)

ParsePrintSection parses one print-section name. Valid values are "predicates", "ordering", "aggregate", "typed", and "full" (case-insensitive).

type PrintSections added in v0.1.10

type PrintSections []PrintSection

PrintSections is an ordered list of appendix sections.

func NewPrintSections added in v0.1.11

func NewPrintSections(sections ...PrintSection) *PrintSections

NewPrintSections returns a config-ready print section pointer. Passing no sections returns an explicit empty section list that suppresses appendices. Use nil to keep the default PrintPresetBasic behavior in RenderConfig.

func ParsePrintSections added in v0.1.10

func ParsePrintSections(s string) (PrintSections, error)

ParsePrintSections parses a named preset or a comma-separated print-section list. Empty or blank input returns a non-nil empty list that suppresses appendices when used explicitly.

type RenderConfig added in v0.1.8

type RenderConfig struct {
	// WrapWidth sets the maximum total rendered line width, including the tree prefix.
	// A value of 0 disables wrapping. Negative values make [RenderTreeTableWithConfig] return an error.
	WrapWidth int `json:"wrapWidth,omitempty"`

	// HangingIndent hangs wrapped continuation lines after node-local prefixes such as
	// `[Input] ` and `[Map] ` instead of keeping the default tree-aligned indentation.
	HangingIndent bool `json:"hangingIndent,omitempty"`

	// PrintSections selects appendix sections printed after the rendered tree table.
	// A nil pointer uses the default [PrintPredicates] section.
	// In JSON config, omit this field or set it to null to use the default; set
	// it to [] to print no appendix sections.
	// When converting preset names such as [PrintPresetBasic], [PrintPresetEnhanced],
	// [PrintPresetFull], and [PrintPresetNone] into config values, handle the error
	// from [PrintPreset.Sections] and pass the result to [NewPrintSections] with
	// variadic expansion:
	//
	//	sections, err := preset.Sections()
	//	if err != nil {
	//		return err
	//	}
	//	cfg.PrintSections = NewPrintSections(sections...)
	PrintSections *PrintSections `json:"printSections,omitempty"`

	// ShowScalarVars prints scalar assignment variable names in semantic appendix sections.
	ShowScalarVars bool `json:"showScalarVars,omitempty"`

	// ResolveScalarVars replaces direct scalar variable aliases in semantic appendix sections.
	ResolveScalarVars bool `json:"resolveScalarVars,omitempty"`

	// ResolveScalarVarsRecursive recursively resolves scalar variable aliases in semantic appendix sections.
	ResolveScalarVarsRecursive bool `json:"resolveScalarVarsRecursive,omitempty"`
}

RenderConfig configures optional rendering behavior using serialization-friendly fields.

Use this type for cross-language integrations that start from JSON-like configuration, such as WebAssembly or JavaScript callers. Go callers can continue to use functional Option values with RenderTreeTableWithOptions.

type RenderMode

type RenderMode string

RenderMode specifies how to render the query plan output.

const (
	// RenderModeAuto automatically determines whether to show statistics based on availability.
	RenderModeAuto RenderMode = "AUTO"
	// RenderModePlan shows only the query plan without statistics.
	RenderModePlan RenderMode = "PLAN"
	// RenderModeProfile shows the query plan with execution statistics.
	RenderModeProfile RenderMode = "PROFILE"
)

func ParseRenderMode

func ParseRenderMode(s string) (RenderMode, error)

ParseRenderMode parses a string into a RenderMode. Valid values are "AUTO", "PLAN", and "PROFILE" (case-insensitive).

Directories

Path Synopsis
tools
genexpected command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL