spantype

package module
v0.3.13 Latest Latest
Warning

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

 Go to latest Published: Jun 27, 2026 License: MIT Imports: 4 Imported by: 2

README

spantype

github.com/apstndb/spantype provides two related packages for working with Cloud Spanner types:

  • spantype: format google.spanner.v1.Type values for logs, errors, and debugging.
  • typector: construct *spannerpb.Type and *spannerpb.StructType_Field values for tests and helpers.

Go Reference

Packages

spantype

The root package formats Spanner types with configurable verbosity. For a type like STRUCT<arr ARRAY<STRUCT<n INT64>>, proto PROTO<examples.Book>>, the helpers differ like this:

Function Intended use Example output
FormatTypeSimplest Very compact summaries such as schema overviews STRUCT
FormatTypeSimple Compact logs; top-level STRUCTs are still collapsed to STRUCT STRUCT
FormatTypeNormal Default structured output without field names STRUCT<ARRAY<STRUCT<INT64>>, Book>
FormatTypeVerbose Human-facing diagnostics with struct field names STRUCT<arr ARRAY<STRUCT<n INT64>>, proto examples.Book>
FormatTypeMoreVerbose Errors and debugging where PROTO / ENUM kind should stay explicit STRUCT<arr ARRAY<STRUCT<n INT64>>, proto PROTO<examples.Book>>

If you need custom behavior, call FormatType with FormatOption.

Type.TypeAnnotation (PostgreSQL dialect markers)
FormatOption.TypeAnnotation selects how non-unspecified TypeAnnotationCode values are shown:

TypeAnnotationMode Example (NUMERIC + PG_NUMERIC)
TypeAnnotationModeSuffix (default, zero value) NUMERIC(PG_NUMERIC)
TypeAnnotationModeOmit NUMERIC
TypeAnnotationModePrimary PG_NUMERIC

The same mode applies recursively inside ARRAY<> and STRUCT<> fields.

typector

typector is a constructor helper package for building Spanner type values.

  • Use CodeToSimpleType when you already have a spannerpb.TypeCode.
  • Use shorthand constructors such as Int64(), String(), and UUID() for common scalar types.
  • Use ElemCodeToArrayType / ElemTypeToArrayType for arrays.
  • Use FQNToProtoType / FQNToEnumType for PROTO and ENUM, which require a fully-qualified name.
  • Use SimpleTypeWithAnnotation, PGNumeric, PGJSONB, or PGOID when you need PostgreSQL TypeAnnotation markers on scalars.
  • Prefer ...Code... forms when your input is a type code, and ...Type... forms when you already have *spannerpb.Type.

CLI Example

./cmd/spantype is a small example program that reads protobuf JSON from stdin:

echo '{"fields":[{"name":"n","type":{"code":"INT64"}}]}' | go run ./cmd/spantype --mode=verbose

Supported modes are simplest, simple, normal, verbose, and more.
Use --type-annotation=suffix|omit|primary to control TypeAnnotation rendering (default suffix).
Unknown flags and invalid --mode / --type-annotation values are reported on stderr with a non-zero exit.

Development

go test ./...
go build ./...
go vet ./...

Documentation

Overview

Package spantype formats Cloud Spanner google.spanner.v1.Type values with multiple verbosity levels for logs, errors, and debugging output. Dialect sppb.Type.TypeAnnotation values (for example PostgreSQL PG_NUMERIC) are controlled by TypeAnnotationMode inside FormatOption.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// FormatOptionSimplest is a FormatOption for FormatTypeSimplest.
	FormatOptionSimplest = FormatOption{
		Struct:  StructModeBase,
		Proto:   ProtoEnumModeBase,
		Enum:    ProtoEnumModeBase,
		Array:   ArrayModeBase,
		Unknown: UnknownModeTypeCode,
	}
	// FormatOptionSimple is a FormatOption for FormatTypeSimple.
	FormatOptionSimple = FormatOption{
		Struct:  StructModeBase,
		Proto:   ProtoEnumModeLeaf,
		Enum:    ProtoEnumModeLeaf,
		Array:   ArrayModeRecursive,
		Unknown: UnknownModeUnknown,
	}
	// FormatOptionNormal is a FormatOption for FormatTypeNormal.
	FormatOptionNormal = FormatOption{
		Struct:  StructModeRecursive,
		Proto:   ProtoEnumModeLeaf,
		Enum:    ProtoEnumModeLeaf,
		Array:   ArrayModeRecursive,
		Unknown: UnknownModeVerbose,
	}
	// FormatOptionVerbose is a FormatOption for FormatTypeVerbose.
	FormatOptionVerbose = FormatOption{
		Struct:  StructModeRecursiveWithName,
		Proto:   ProtoEnumModeFull,
		Enum:    ProtoEnumModeFull,
		Array:   ArrayModeRecursive,
		Unknown: UnknownModeVerbose,
	}
	// FormatOptionMoreVerbose is a FormatOption for FormatTypeMoreVerbose.
	FormatOptionMoreVerbose = FormatOption{
		Struct:  StructModeRecursiveWithName,
		Proto:   ProtoEnumModeFullWithKind,
		Enum:    ProtoEnumModeFullWithKind,
		Array:   ArrayModeRecursive,
		Unknown: UnknownModeVerbose,
	}
)

Functions

func EquivalentTypes added in v0.3.13 

func EquivalentTypes(a, b *sppb.Type) bool

EquivalentTypes reports whether a and b are Spanner-equivalent cloud.google.com/go/spanner/apiv1/spannerpb.Type metadata for identity retyping: a value of either type can carry the same wire payload when only Type metadata differs in ways that do not affect type identity.

EquivalentTypes is stricter than wire-encoding compatibility: sppb.Type.TypeAnnotation and sppb.Type.ProtoTypeFqn are part of type identity even when serialization is unchanged.

Rules follow [google.spanner.v1.Type] shape (https://github.com/googleapis/googleapis/blob/master/google/spanner/v1/type.proto) and GoogleSQL supertypes for composite types (https://docs.cloud.google.com/spanner/docs/reference/standard-sql/conversion_rules#supertypes):

  • Scalars: same TypeCode, TypeAnnotation, and ProtoTypeFqn; container fields must be absent. Unknown protobuf fields are intentionally ignored.
  • ARRAY: equivalent sppb.Type.ArrayElementType; sppb.Type.StructType must be absent.
  • STRUCT: same number of fields with pairwise equivalent field types by position; field names are not compared. sppb.Type.ArrayElementType must be absent.

This is narrower than the Cast table in the same conversion-rules page: types that can CAST to one another (for example INT64 and FLOAT64) are not necessarily equivalent. Use EquivalentTypes only when semantics require an identity path (no value conversion), such as ARRAY/STRUCT layout checks or gcvctor.WithEquivalentType.

func FormatProtoEnum added in v0.2.0 

func FormatProtoEnum(typ *sppb.Type, mode ProtoEnumMode) string

FormatProtoEnum formats `PROTO` or `ENUM` type using ProtoEnumMode. It panics when the input type is not `PROTO` or `ENUM`.

func FormatStructFields 

func FormatStructFields(fields []*sppb.StructType_Field, opts FormatOption) string

FormatStructFields formats Cloud Spanner struct fields or `metadata.rowType` using the given FormatOption.

func FormatType 

func FormatType(typ *sppb.Type, opts FormatOption) string

FormatType formats Cloud Spanner type using the given FormatOption. FormatOption.TypeAnnotation selects whether sppb.Type.TypeAnnotation is omitted, appended in parentheses after the base type, or used as the primary label (see TypeAnnotationMode).

func FormatTypeCode added in v0.2.0 

func FormatTypeCode(code sppb.TypeCode, mode UnknownMode) string

FormatTypeCode formats sppb.TypeCode, but it formats unknown type code as `UNKNOWN(int32(code))`. e.g. `UNKNOWN(-1)`

func FormatTypeMoreVerbose added in v0.3.0 

func FormatTypeMoreVerbose(typ *sppb.Type) string

FormatTypeMoreVerbose formats Cloud Spanner type as more verbose format. e.g. `INT64`, `ARRAY<INT64>`, `PROTO<examples.ProtoType>`, `ENUM<examples.EnumType>`, `STRUCT<n INT64>`

func FormatTypeNormal 

func FormatTypeNormal(typ *sppb.Type) string

FormatTypeNormal formats Cloud Spanner type as normal format. e.g. `INT64`, `ARRAY<INT64>`, `ProtoType`, `EnumType`, `STRUCT<INT64>`

func FormatTypePostgreSQL added in v0.3.12 

func FormatTypePostgreSQL(typ *sppb.Type) string

FormatTypePostgreSQL renders a sppb.Type using PostgreSQL-dialect spellings from https://docs.cloud.google.com/spanner/docs/reference/postgresql/data-types (supported types: bool, bytea, date, float4, float8, bigint, interval, jsonb, numeric, timestamptz, text, uuid, oid, and `T[]` array declarations). sppb.TypeCode_JSON is rendered "jsonb" only when the type carries sppb.TypeAnnotationCode_PG_JSONB (otherwise "json", a label that preserves the wire distinction even though plain JSON is not a PostgreSQL data type), and sppb.TypeCode_INT64 with sppb.TypeAnnotationCode_PG_OID is rendered "oid". A nil type renders as the empty string.

sppb.TypeCode_PROTO and sppb.TypeCode_ENUM are not PostgreSQL-interface types: they render as "proto" and "enum" — not as "bytea" or "text" — so wire types are never mislabeled if they appear in metadata. sppb.TypeCode_STRUCT does not appear in PostgreSQL-dialect metadata in practice today; the provisional rendering uses GoogleSQL STRUCT<...> declaration syntax with field types spelled using the PostgreSQL names above, and may change once official guidance for composite types exists (no stability guarantee for the STRUCT branch).

This function originated as FormatPostgreSQLType in github.com/apstndb/spanpg, where its spellings are pinned against PostgreSQL-dialect Spanner databases by integration probes.

func FormatTypeSimple 

func FormatTypeSimple(typ *sppb.Type) string

FormatTypeSimple formats Cloud Spanner type as simple format. e.g. `INT64`, `ARRAY<INT64>`, `ProtoType`, `EnumType`, `STRUCT`

func FormatTypeSimplest 

func FormatTypeSimplest(typ *sppb.Type) string

FormatTypeSimplest formats Cloud Spanner type as simplest format. e.g. `INT64`, `ARRAY`, `PROTO`, `ENUM`, `STRUCT`

func FormatTypeVerbose 

func FormatTypeVerbose(typ *sppb.Type) string

FormatTypeVerbose formats Cloud Spanner type as verbose format. e.g. `INT64`, `ARRAY<INT64>`, `examples.ProtoType`, `examples.EnumType`, `STRUCT<n INT64>`

Types

type ArrayMode 

type ArrayMode int

ArrayMode controls how ARRAY types are rendered by selecting either base or recursive element rendering. 

const (
	// ArrayModeBase formats `ARRAY` type as `ARRAY`
	ArrayModeBase ArrayMode = iota
	// ArrayModeRecursive formats `ARRAY` type with element type. e.g. `ARRAY<INT64>`
	ArrayModeRecursive
)

type FormatOption 

type FormatOption struct {
	// Struct controls STRUCT formatting.
	Struct StructMode
	// Proto controls PROTO formatting.
	Proto ProtoEnumMode
	// Enum controls ENUM formatting.
	Enum ProtoEnumMode
	// Array controls ARRAY formatting.
	Array ArrayMode
	// Unknown controls formatting for unknown type codes.
	Unknown UnknownMode
	// TypeAnnotation controls how dialect TypeAnnotation is combined with the base type.
	TypeAnnotation TypeAnnotationMode
}

FormatOption is an option for FormatType, and FormatStructFields.

Callers building their own values should use keyed struct literals (e.g. FormatOption{Struct: ..., Proto: ...}) so that new fields can be added in minor releases without breaking compilation. Positional literals are fragile.

type ProtoEnumMode added in v0.2.0 

type ProtoEnumMode int

ProtoEnumMode controls how PROTO and ENUM types are rendered by selecting base, leaf, full-name, or explicit-kind output. 

const (
	// ProtoEnumModeBase formats `PROTO` and `ENUM` type as `PROTO` and `ENUM`.
	ProtoEnumModeBase ProtoEnumMode = iota
	// ProtoEnumModeLeaf formats `PROTO` and `ENUM` type without package name. e.g. `ProtoType`, `EnumType`
	ProtoEnumModeLeaf
	// ProtoEnumModeFull formats `PROTO` and `ENUM` type as full qualified name. e.g. `examples.ProtoType`, `examples.EnumType`
	ProtoEnumModeFull
	// ProtoEnumModeLeafWithKind formats `PROTO` and `ENUM` type without package name with kind.
	// e.g. `PROTO<ProtoType>`, `ENUM<EnumType>`
	ProtoEnumModeLeafWithKind
	// ProtoEnumModeFullWithKind formats `PROTO` and `ENUM` type as full qualified name with kind.
	// e.g. `PROTO<examples.ProtoType>`, `ENUM<examples.EnumType>`.
	// Note: It should be same format with `INFORMATION_SCHEMA.COLUMNS.SPANNER_TYPE`.
	ProtoEnumModeFullWithKind
)

type StructMode 

type StructMode int

StructMode controls how STRUCT types are rendered by selecting one of StructModeBase, StructModeRecursive, or StructModeRecursiveWithName. 

const (
	// StructModeBase formats `STRUCT` type as `STRUCT`.
	StructModeBase StructMode = iota
	// StructModeRecursive formats `STRUCT` type with field types. e.g. `STRUCT<INT64, STRUCT<INT64>>`
	StructModeRecursive
	// StructModeRecursiveWithName formats `STRUCT` type with field types with field name. e.g. `STRUCT<n INT64, s STRUCT<n INT64>>`
	StructModeRecursiveWithName
)

type TypeAnnotationMode added in v0.3.11 

type TypeAnnotationMode int

TypeAnnotationMode controls how sppb.Type.TypeAnnotation is rendered for simple and container types (recursively for ARRAY and STRUCT fields). 

const (
	// TypeAnnotationModeSuffix is the default (zero value): append a parenthetical
	// annotation when set, e.g. `NUMERIC(PG_NUMERIC)`.
	TypeAnnotationModeSuffix TypeAnnotationMode = iota
	// TypeAnnotationModeOmit ignores TypeAnnotation and formats the base type only, e.g. `NUMERIC`.
	TypeAnnotationModeOmit
	// TypeAnnotationModePrimary uses the annotation as the displayed type label when non-UNSPECIFIED,
	// e.g. `PG_NUMERIC` instead of `NUMERIC` or `NUMERIC(PG_NUMERIC)`.
	TypeAnnotationModePrimary
)

type UnknownMode added in v0.3.0 

type UnknownMode int

UnknownMode controls how unknown type codes are rendered by selecting UNKNOWN, the raw numeric code, a verbose form, or panic behavior. 

const (
	// UnknownModeUnknown formats unknown type code as `UNKNOWN`
	UnknownModeUnknown UnknownMode = iota
	// UnknownModeTypeCode formats unknown type code as e.g. `-1`
	UnknownModeTypeCode
	// UnknownModeVerbose formats unknown type code as `UNKNOWN(int32(code))` as e.g. `UNKNOWN(-1)`
	UnknownModeVerbose
	// UnknownModePanic panics when type code is unknown.
	UnknownModePanic
)

Source Files

View all Source files

Directories

Path Synopsis
cmd
spantype command
Package typector provides small constructor helpers for building Cloud Spanner google.spanner.v1.Type values and struct fields in tests and callers.
 Package typector provides small constructor helpers for building Cloud Spanner google.spanner.v1.Type values and struct fields in tests and callers.

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.