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 ¶
- func RenderTreeTable(planNodes []*sppb.PlanNode, mode RenderMode, format Format, wrapWidth int) (string, error)
- func RenderTreeTableWithConfig(planNodes []*sppb.PlanNode, mode RenderMode, format Format, ...) (string, error)
- func RenderTreeTableWithOptions(planNodes []*sppb.PlanNode, mode RenderMode, format Format, opts ...Option) (string, error)
- type Format
- type Option
- type PrintPreset
- type PrintSection
- type PrintSections
- type RenderConfig
- type RenderMode
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 ¶
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
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).