README
¶
spanstats
Typed access to Cloud Spanner query statistics
(ResultSetStats.query_stats), which the API exposes as an untyped protobuf
Struct with undocumented keys that every tool ends up re-parsing by hand.
stats := spanstats.FromResultSetStats(rss) // or FromStruct / FromMap
if stats != nil {
fmt.Println(stats.ElapsedTime, stats.RowsScanned)
}
- Values stay the wire strings Spanner sends (for example
"1.23 msecs"); no unit or number parsing (deliberately out of MVP scope). - Keys not yet modeled — and known keys with unexpectedly non-string
values — are preserved in
Unknown, so nothing is dropped when Spanner adds keys. - JSON marshaling/unmarshaling preserves those unknown keys too, which keeps stored query profile payloads forward-compatible.
- Entry points for all three shapes tools encounter:
FromResultSetStats(*sppb.ResultSetStats),FromStruct(*structpb.Struct), andFromMap(map[string]any)(thespanner.RowIterator.QueryStatsshape). - Nil-safe: PLAN-mode and DML responses often carry no
query_stats; all entry points return nil for absent input.
Extracted from the duplicated parsing in spanner-mycli and spannersh.
Status: experimental. The key set tracks what Cloud Spanner is observed
to send; additions are non-breaking (new fields, with Unknown as the
forward-compatibility net).
License
MIT
Documentation
¶
Overview ¶
Package spanstats provides typed access to Cloud Spanner query statistics (ResultSetStats.query_stats), which the API exposes as an untyped protobuf Struct with undocumented keys.
All values are kept as the wire strings Spanner sends (for example "1.23 msecs"); this package does not parse units or numbers. Keys not yet modeled are preserved in QueryStats.Unknown, and known keys whose value is not a string are routed there too, so no information is dropped.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type QueryStats ¶
type QueryStats struct {
ElapsedTime string `json:"elapsed_time,omitempty"`
CPUTime string `json:"cpu_time,omitempty"`
RowsReturned string `json:"rows_returned,omitempty"`
RowsScanned string `json:"rows_scanned,omitempty"`
DeletedRowsScanned string `json:"deleted_rows_scanned,omitempty"`
OptimizerVersion string `json:"optimizer_version,omitempty"`
OptimizerStatisticsPackage string `json:"optimizer_statistics_package,omitempty"`
RemoteServerCalls string `json:"remote_server_calls,omitempty"`
MemoryPeakUsageBytes string `json:"memory_peak_usage_bytes,omitempty"`
TotalMemoryPeakUsageByte string `json:"total_memory_peak_usage_byte,omitempty"`
QueryText string `json:"query_text,omitempty"`
BytesReturned string `json:"bytes_returned,omitempty"`
RuntimeCreationTime string `json:"runtime_creation_time,omitempty"`
StatisticsLoadTime string `json:"statistics_load_time,omitempty"`
MemoryUsagePercentage string `json:"memory_usage_percentage,omitempty"`
FilesystemDelaySeconds string `json:"filesystem_delay_seconds,omitempty"`
LockingDelay string `json:"locking_delay,omitempty"`
QueryPlanCreationTime string `json:"query_plan_creation_time,omitempty"`
ServerQueueDelay string `json:"server_queue_delay,omitempty"`
DataBytesRead string `json:"data_bytes_read,omitempty"`
IsGraphQuery string `json:"is_graph_query,omitempty"`
RuntimeCached string `json:"runtime_cached,omitempty"`
QueryPlanCached string `json:"query_plan_cached,omitempty"`
// Unknown preserves keys this package does not model (and known keys
// whose value was not a string). A nil map means none were present.
Unknown map[string]any `json:"-"`
}
QueryStats is the typed view of query_stats. Field coverage follows the keys observed from Cloud Spanner; absent keys are zero values.
func FromMap ¶
func FromMap(m map[string]any) *QueryStats
FromMap builds a QueryStats from a decoded query_stats map, the shape of cloud.google.com/go/spanner.RowIterator QueryStats. A nil map returns nil.
func FromResultSetStats ¶
func FromResultSetStats(stats *sppb.ResultSetStats) *QueryStats
FromResultSetStats builds a QueryStats from a cloud.google.com/go/spanner/apiv1/spannerpb.ResultSetStats. A nil stats message or absent query_stats returns nil (PLAN-mode and DML responses often carry no query_stats).
func FromStruct ¶
func FromStruct(s *structpb.Struct) *QueryStats
FromStruct builds a QueryStats from the raw query_stats protobuf Struct. A nil Struct returns nil.
func (QueryStats) MarshalJSON ¶
func (s QueryStats) MarshalJSON() ([]byte, error)
MarshalJSON encodes modeled fields and QueryStats.Unknown as one JSON object, so unknown query_stats keys survive JSON round-trips.
func (*QueryStats) UnmarshalJSON ¶
func (s *QueryStats) UnmarshalJSON(data []byte) error
UnmarshalJSON decodes query_stats JSON with the same preservation semantics as FromMap.
Source Files