Add an opt-in concise query-plan metadata mode via spannerplan

[apstndb]

Goal and maintainer decision (2026-09-15)

Offer an opt-in concise metadata mode for EXPLAIN / EXPLAIN ANALYZE. Do not generally suppress seekable_key_size: 0 or the reported automatic scan_method: these values can carry useful information, and whether they should be omitted by default is unresolved. Preserve the existing default display of these fields.

The implementation belongs in apstndb/spannerplan first. spanner-mycli may expose the upstream mode once it exists; it should not fork or postprocess upstream notation emitters to hide fields.

This decision supersedes the earlier proposal to make a new concise form the default and rely on CLI_SPANNER_CLI_COMPATIBLE_PLAN=true to recover the old form.

Motivation

Verbose per-node metadata can widen plans in constrained terminals and documentation. Users who prefer a shorter display should be able to choose it without removing information from the normal display for everyone.

Examples in existing plan fixtures include:

• seekable_key_size: 0
• scan_method: Automatic

The user's concern applies to the automatic scan-method notation generally; preserve exact metadata values rather than assuming an undocumented value spelling.

Bounded implementation direction

1. Add an explicit optional mode to spannerplan's metadata rendering. Define and test its exact omissions/abbreviations against representative plan fixtures before adoption.
2. Preserve current default output. A zero seekable key size and an automatic scan method must remain visible by default where they are visible today.
3. In the opt-in mode, consider omitting zero seekable-key size and automatic scan-method annotations; preserve nonzero, nondefault and unknown values. Do not mutate the underlying plan or exported raw metadata.
4. After an upstream release contains the mode, wire a deliberate spanner-mycli setting and document the tradeoff and interaction with existing plan compatibility/format controls. Select the setting name and enum/boolean shape in that implementation design.
5. Keep full and concise rendering tests together, including default preservation and unknown metadata. Use one PR per independent upstream/downstream change.

Already implemented / exclusions

Current concise boolean notation already suppresses false values such as split_ranges_aligned: false and displays true as split_ranges_aligned; this is documented in docs/query_plan.md. Historical wide examples do not prove that behavior is missing. Do not reimplement it or use this task to change its default.

No blanket metadata suppression, new concise default, raw-plan data loss, or local mycli renderer fork. This remains a backlog item; it is not part of the current #292 operation-eligibility implementation.

Origin

Extracted from the EXPLAIN umbrella #182 (remaining metadata notation work). Foundation notation work shipped in #185. Rendering largely lives in apstndb/spannerplan (and spannerplanviz).

[apstndb]

Concrete downstream contract (2026-09-17)

The upstream prerequisite is now proposed in apstndb/spannerplan#66, independently reviewed before release. Do not implement a local metadata filter while that PR/release is pending.

After an accepted upstream release provides spannerplan.WithConciseMetadata(bool), implement this Issue in one downstream PR:

• Register session boolean CLI_EXPLAIN_CONCISE_METADATA, default FALSE, using the existing display-variable registry and normal SET/SHOW/RESET behavior. Add ExplainConciseMetadata to DisplayVars. No new CLI flag or metadata enum is needed for the two-mode contract.
• Feed the option through the shared processPlanNodes rendering path. Cover EXPLAIN / EXPLAIN ANALYZE, applicable last-plan rendering, and the plan appendix for CLI_QUERY_MODE='WITH_PLAN_AND_STATS'. Inspect both statements_explain_describe.go and explain_print_sections.go; do not wire only the first call site.
• FALSE preserves existing output byte-for-byte. TRUE omits only the exact metadata strings seekable_key_size: 0, scan_method: Auto, and scan_method: Automatic. Preserve nonzero, nondefault, unknown, differently cased and other metadata values.
• Concision is independent of the CURRENT/TRADITIONAL/COMPACT layout selection and applies only when explicitly enabled. Preserve wrapping, indentation, labels, inline statistics and appendix selection. Do not mutate plan protos, last-query caches, raw plan files, or machine-readable exports.
• Use the upstream option through plantree.WithQueryPlanOptions. Prefer extending the existing option flow over a parallel renderer or a generic configuration framework. Limit the dependency update to the required released version.

Acceptance evidence: registry SET/SHOW/RESET and default checks; representative visible default-vs-concise output through both the EXPLAIN and query-appendix paths; nondefault/unknown values remain visible; the input proto remains equal; existing output fixtures remain unchanged by default. Keep these tests compact and reuse existing fixtures. Run make check before push and all applicable hosted checks, preserving the 80% CI coverage floor. Document the deliberate display-information omission in docs/query_plan.md and the system-variable reference.

This contract preserves the maintainer's decision that the two metadata values are useful in ordinary output. It does not make concise rendering the default.