gcvctor

package
v0.8.2 Latest Latest
Warning

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

 Go to latest Published: Jun 27, 2026 License: MIT Imports: 18 Imported by: 1

Documentation

Overview

Package gcvctor constructs cloud.google.com/go/spanner.GenericColumnValue values from Go values and explicit cloud.google.com/go/spanner/apiv1/spannerpb.Type metadata, using github.com/apstndb/spantype/typector for type shapes.

ArrayValue infers the element type from the first element (or uses a default empty ARRAY<INT64> when len==0, whether the variadic slice is nil or empty). ArrayValueOf takes the element type explicitly; len==0 yields an empty ARRAY<elemType>. For a SQL NULL ARRAY, use NullOf with github.com/apstndb/spantype/typector.ElemTypeToArrayType or github.com/apstndb/spantype/typector.ElemCodeToArrayType instead of relying on variadic nil. NormalizeArrayElements rewrites SQL NULL elements to NullOf with elemType before a strict ArrayValueOf call when callers already know the final array element type. StructValueOf pairs field names with values; counts must match. StructValueOfFields accepts StructFieldKV pairs; StructFieldKVOf is the usual constructor; keyed composite literals (StructFieldKV{Name: name, Value: value}) are also valid. Empty field names denote unnamed STRUCT fields.

ARRAY-typed cloud.google.com/go/spanner/apiv1/spannerpb.Type values require array_element_type (protobuf: array_element_type; Go field name ArrayElementType); omitting it yields an invalid ARRAY shape and Spanner may reject the request.

Zero-argument ArrayValue returns an empty ARRAY<INT64> with complete type metadata in the Type field of the cloud.google.com/go/spanner.GenericColumnValue. For empty arrays, callers typically must supply explicit SQL type information through these constructors or through the ParamTypes field (protobuf: param_types) on cloud.google.com/go/spanner/apiv1/spannerpb.ExecuteSqlRequest, because an empty list value does not specify an element type by itself.

NullOf returns a typed NULL for any cloud.google.com/go/spanner/apiv1/spannerpb.Type, including STRUCT and ARRAY; the cloud.google.com/go/spanner.GenericColumnValue Value field is always a scalar protobuf null at the top level. NullFromCode does the same for simple scalar type codes only—it cannot express STRUCT field layouts or ARRAY element types. NullOf, NullArrayOf, and EmptyArrayOf normalize a nil Type pointer input to TYPE_CODE_UNSPECIFIED so they never fabricate malformed nil Type pointers. WithType applies the same nil-type normalization when retyping; use WithEquivalentType or WithExactType when the source and destination type metadata must be checked. Those helpers validate Type only; Value is preserved unchanged and not validated or canonicalized. For NULL detection on existing values, see github.com/apstndb/spanvalue.IsNull. Neither encodes a non-null STRUCT whose fields are all null; use StructValueOf with per-field nulls when you need that shape.

Nullable Go inputs are split by shape in the function name:

Use *FromPtr for optional fields modeled as Go pointers. Use *FromNullable when the value already comes from the Spanner client library. For explicit typed NULL without an input value, keep using NullOf or NullFromCode.

JSONFromNullable and PGJSONBFromNullable marshal Value like JSONValue and PGJSONBValue: a Go string becomes a quoted JSON string on the wire, matching the official client's encodeValue. Pass pre-encoded wire JSON as an encoding/json.RawMessage to store it as-is (validated and compacted); see ExampleJSONFromNullable.

NumericValueChecked and PGNumericValueChecked return errors on nil *big.Rat input instead of panicking. The legacy NumericValue and PGNumericValue helpers keep their original signatures and return typed SQL NULL values on nil input.

PGNumericValue, PGJSONBValue, and PGOIDValue build PostgreSQL-dialect annotated NUMERIC/JSON/OID values (cloud.google.com/go/spanner/apiv1/spannerpb.TypeAnnotationCode_PG_NUMERIC, cloud.google.com/go/spanner/apiv1/spannerpb.TypeAnnotationCode_PG_JSONB, cloud.google.com/go/spanner/apiv1/spannerpb.TypeAnnotationCode_PG_OID).

NUMERIC wire strings: NumericValue and PGNumericValue store Spanner-canonical decimals at the GoogleSQL 9-fractional-digit scale (silently rounding); PGNumericValueExact renders the exact decimal for the wider PG-dialect numeric value space, erroring on non-terminating rationals. StringBasedValueFromCode does not normalize; callers that build NUMERIC cells by hand must supply the same wire form Spanner returns (see that helper's doc). The github.com/apstndb/spanvalue formatters treat NUMERIC string payloads as authoritative and do not parse them again.

Formatting these values as strings is provided by the sibling package github.com/apstndb/spanvalue. For converting arbitrary Go values with the official Cloud Spanner Go client's encoding semantics (struct tags, null wrappers, Encoder), see github.com/apstndb/spanenc.

Test fixtures

For nested ARRAY and STRUCT trees in tests, prefer MustArrayValue, MustArrayValueOf, MustStructValueOf, MustStructValueOfFields, and MustNormalizeArrayElements over local panic-on-error helpers. For checked NUMERIC fixtures, MustNumericValueChecked and MustPGNumericValueChecked panic on nil input instead of returning a typed NULL. They wrap the error-returning constructors and are intended for schema-known fixture data, not production paths.

String payloads: StringBasedValueOf and StringBasedValueFromCode store the wire string as-is with no validation (no extra imports beyond typector). Use StringBasedValueOf when the Type carries annotations (for example PG-dialect NUMERIC). When the test cares about canonical wire form, use validated helpers such as DateStringValue, UUIDStringValue, and JSONStringValue, or the corresponding MustDateStringValue, MustTimestampStringValue, MustIntervalStringValue, MustUUIDStringValue, MustJSONStringValue, and MustJSONValue for inline nesting. Typed Go inputs (DateValue with cloud.google.com/go/civil.Date, TimestampValue with time.Time, and so on) avoid parse errors when you already hold the native value.

Literal evaluation (preserve the parsed wire as-is) vs CAST/coercion (validate and canonicalize):

See ExampleStringBasedValueFromCode_validatedDate and ExampleNormalizeArrayElements.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrTypeMismatch is returned by [ArrayValueOf], [ArrayValue], and [NormalizeArrayElements]
	// when an element's type does not match the expected element type.
	ErrTypeMismatch = errors.New("gcvctor: type mismatch")
	// ErrMismatchedCounts is returned by [StructValueOf] when len(names) != len(gcvs).
	ErrMismatchedCounts = errors.New("gcvctor: mismatched name/value count")
	// ErrNilElementType is returned by [ArrayValueOf], [ArrayValue], and [NormalizeArrayElements]
	// when elemType is nil.
	ErrNilElementType = errors.New("gcvctor: nil array element type")
	// ErrNilFieldType is returned by [StructValueOf] when a field's Type is nil.
	ErrNilFieldType = errors.New("gcvctor: nil struct field type")
	// ErrNilNumeric is returned by [NumericValueChecked], [PGNumericValueChecked],
	// and [PGNumericValueExact] when v is nil.
	ErrNilNumeric = errors.New("gcvctor: nil numeric input")
	// ErrInexactNumeric is returned by [PGNumericValueExact] when v has no
	// finite decimal expansion and therefore cannot be rendered exactly.
	ErrInexactNumeric = errors.New("gcvctor: numeric input has no finite decimal expansion")
	// ErrInvalidJSON is returned by [JSONStringValue] when v is not syntactically valid JSON.
	ErrInvalidJSON = errors.New("gcvctor: invalid JSON input")
)
View Source 
var ErrNilDestinationType = errors.New("gcvctor: nil destination type")

ErrNilDestinationType is returned by WithEquivalentType and WithExactType when typ is nil.

Functions

func ArrayValue 

func ArrayValue(vs ...spanner.GenericColumnValue) (spanner.GenericColumnValue, error)

ArrayValue constructs ARRAY GenericColumnValue.

With no elements (including a nil or empty variadic slice), it returns an empty ARRAY<INT64> (SQL length zero, not SQL NULL), using a concrete element type so the Type field is a well-formed cloud.google.com/go/spanner/apiv1/spannerpb.Type (including array_element_type for ARRAY shapes). For a typed NULL ARRAY<INT64>, use NullOf with github.com/apstndb/spantype/typector.ElemCodeToArrayType (or github.com/apstndb/spantype/typector.ElemTypeToArrayType).

For other element types or explicit typing policy, use ArrayValueOf or EmptyArrayOf. At a spread call site (ArrayValue (elems...) where elems is a slice), a nil or empty slice still yields ARRAY<INT64>, not an element type inferred from the slice variable. Prefer ArrayValueOf or EmptyArrayOf when the slice may be empty.

Note: Currently, it doesn't support implicit type conversion a.k.a. coercion so variant typed input is not supported. If the inferred element type from vs[0] is invalid, the error is wrapped in ArrayElementError with Index 0.

func ArrayValueOf added in v0.2.0 

func ArrayValueOf(elemType *sppb.Type, elems ...spanner.GenericColumnValue) (spanner.GenericColumnValue, error)

ArrayValueOf constructs ARRAY GenericColumnValue using elemType as the element type instead of inferring it from the first element. When elems is empty (nil or length zero), it returns an empty ARRAY<elemType> (SQL length zero, not SQL NULL). For a typed NULL ARRAY<elemType>, use NullOf with github.com/apstndb/spantype/typector.ElemTypeToArrayType or github.com/apstndb/spantype/typector.ElemCodeToArrayType.

Each element's Type must match elemType (no coercion). A nil elemType returns ErrNilElementType. Per-element failures are wrapped in ArrayElementError. To accept SQL NULL elements regardless of their current Type metadata, normalize them first with NormalizeArrayElements.

func BoolFromNullable added in v0.4.0 

func BoolFromNullable(n spanner.NullBool) spanner.GenericColumnValue

BoolFromNullable returns a BOOL GenericColumnValue from a Spanner null wrapper.

func BoolFromPtr added in v0.4.0 

func BoolFromPtr(p *bool) spanner.GenericColumnValue

BoolFromPtr returns a BOOL GenericColumnValue. A nil pointer yields typed SQL NULL.

func BoolValue 

func BoolValue(v bool) spanner.GenericColumnValue

BoolValue returns a non-null BOOL GenericColumnValue.

func BytesBasedValueOf added in v0.2.0 

func BytesBasedValueOf(typ *sppb.Type, v []byte) spanner.GenericColumnValue

BytesBasedValueOf constructs a GenericColumnValue with an arbitrary bytes-compatible cloud.google.com/go/spanner/apiv1/spannerpb.Type and base64-encoded payload in Value.

func BytesFromSlice added in v0.4.0 

func BytesFromSlice(v []byte) spanner.GenericColumnValue

BytesFromSlice returns a BYTES GenericColumnValue. A nil slice yields typed SQL NULL. For non-null empty BYTES (wire base64 ""), use BytesValue even with a nil slice.

func BytesValue 

func BytesValue(v []byte) spanner.GenericColumnValue

BytesValue returns a non-null BYTES GenericColumnValue (base64 wire encoding). A nil slice is non-null empty BYTES (wire base64 ""), not typed SQL NULL; for typed NULL use BytesFromSlice with nil.

func DateFromNullable added in v0.4.0 

func DateFromNullable(n spanner.NullDate) spanner.GenericColumnValue

DateFromNullable returns a DATE GenericColumnValue from a Spanner null wrapper.

func DateFromPtr added in v0.4.0 

func DateFromPtr(p *civil.Date) spanner.GenericColumnValue

DateFromPtr returns a DATE GenericColumnValue. A nil pointer yields typed SQL NULL.

func DateStringValue added in v0.3.0 

func DateStringValue(v string) (spanner.GenericColumnValue, error)

DateStringValue validates an RFC3339 full-date string and returns a non-null DATE GenericColumnValue using the canonical DATE wire string.

func DateValue 

func DateValue(v civil.Date) spanner.GenericColumnValue

DateValue returns a non-null DATE GenericColumnValue.

func EmptyArrayFromCode added in v0.2.0 

func EmptyArrayFromCode(code sppb.TypeCode) spanner.GenericColumnValue

EmptyArrayFromCode returns a non-null empty ARRAY<T> for a simple scalar element type code.

func EmptyArrayOf added in v0.2.0 

func EmptyArrayOf(elemType *sppb.Type) spanner.GenericColumnValue

EmptyArrayOf returns a non-null empty ARRAY<elemType> (length zero). A nil elemType is normalized to TYPE_CODE_UNSPECIFIED, so EmptyArrayOf(nil) returns an empty ARRAY<TYPE_CODE_UNSPECIFIED> rather than an invalid ARRAY shape.

Example 
package main

import (
	"fmt"

	sppb "cloud.google.com/go/spanner/apiv1/spannerpb"
	"github.com/apstndb/spantype/typector"

	"github.com/apstndb/spanvalue"
	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	elemType := typector.CodeToSimpleType(sppb.TypeCode_STRING)
	empty := gcvctor.EmptyArrayOf(elemType)
	viaArrayValueOf := gcvctor.MustArrayValueOf(elemType)

	fmt.Println(spanvalue.IsNull(empty), len(empty.Value.GetListValue().GetValues()))
	fmt.Println(empty.Type.ArrayElementType.Code.String())
	fmt.Println(spanvalue.IsNull(viaArrayValueOf), len(viaArrayValueOf.Value.GetListValue().GetValues()))
}

Output:
false 0
STRING
false 0

func EnumValue 

func EnumValue(fqn string, v int64) spanner.GenericColumnValue

EnumValue returns a non-null ENUM GenericColumnValue for the fully qualified enum name fqn. The structpb value is the enum number as a decimal string; delimited export prints that decimal string on the wire.

func Float32FromNullable added in v0.4.0 

func Float32FromNullable(n spanner.NullFloat32) spanner.GenericColumnValue

Float32FromNullable returns a FLOAT32 GenericColumnValue from a Spanner null wrapper.

func Float32FromPtr added in v0.4.0 

func Float32FromPtr(p *float32) spanner.GenericColumnValue

Float32FromPtr returns a FLOAT32 GenericColumnValue. A nil pointer yields typed SQL NULL.

func Float32Value added in v0.1.5 

func Float32Value(v float32) spanner.GenericColumnValue

Float32Value returns a non-null FLOAT32 GenericColumnValue. NaN and ±Inf use string wire values ("NaN", "Infinity", "-Infinity") matching what Spanner returns on the wire. The official client's encodeValue sends finite and non-finite floats as protobuf NumberValue when building params; Spanner accepts both forms.

func Float64FromNullable added in v0.4.0 

func Float64FromNullable(n spanner.NullFloat64) spanner.GenericColumnValue

Float64FromNullable returns a FLOAT64 GenericColumnValue from a Spanner null wrapper.

func Float64FromPtr added in v0.4.0 

func Float64FromPtr(p *float64) spanner.GenericColumnValue

Float64FromPtr returns a FLOAT64 GenericColumnValue. A nil pointer yields typed SQL NULL.

func Float64Value 

func Float64Value(v float64) spanner.GenericColumnValue

Float64Value returns a non-null FLOAT64 GenericColumnValue. NaN and ±Inf use string wire values ("NaN", "Infinity", "-Infinity") matching what Spanner returns on the wire. The official client's encodeValue sends finite and non-finite floats as protobuf NumberValue when building params; Spanner accepts both forms.

func Int64FromNullable added in v0.4.0 

func Int64FromNullable(n spanner.NullInt64) spanner.GenericColumnValue

Int64FromNullable returns an INT64 GenericColumnValue from a Spanner null wrapper.

func Int64FromPtr added in v0.4.0 

func Int64FromPtr(p *int64) spanner.GenericColumnValue

Int64FromPtr returns an INT64 GenericColumnValue. A nil pointer yields typed SQL NULL.

Example (FromNullable) 
package main

import (
	"fmt"

	"cloud.google.com/go/spanner"

	"github.com/apstndb/spanvalue"
	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	var optional *int64
	fromPtr := gcvctor.Int64FromPtr(optional)
	fromNullable := gcvctor.Int64FromNullable(spanner.NullInt64{})

	fmt.Println(spanvalue.IsNull(fromPtr))
	fmt.Println(spanvalue.IsNull(fromNullable))

	v := int64(42)
	fromPtr = gcvctor.Int64FromPtr(&v)
	fromNullable = gcvctor.Int64FromNullable(spanner.NullInt64{Int64: 42, Valid: true})

	fmt.Println(fromPtr.Value.GetStringValue())
	fmt.Println(fromNullable.Value.GetStringValue())
}

Output:
true
true
42
42

func Int64Value 

func Int64Value(v int64) spanner.GenericColumnValue

Int64Value returns a non-null INT64 GenericColumnValue (decimal string wire format).

func IntervalFromNullable added in v0.7.2 

func IntervalFromNullable(n spanner.NullInterval) spanner.GenericColumnValue

IntervalFromNullable returns an INTERVAL GenericColumnValue from a Spanner null wrapper.

func IntervalFromPtr added in v0.7.2 

func IntervalFromPtr(p *spanner.Interval) spanner.GenericColumnValue

IntervalFromPtr returns an INTERVAL GenericColumnValue. A nil pointer yields typed SQL NULL.

func IntervalStringValue added in v0.3.0 

func IntervalStringValue(v string) (spanner.GenericColumnValue, error)

IntervalStringValue validates an ISO8601 duration string and returns a non-null INTERVAL GenericColumnValue using spanner.Interval's canonical wire string.

Example 
package main

import (
	"fmt"

	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	gcv := gcvctor.MustIntervalStringValue("P1Y2M3DT4H5M6S")

	fmt.Println(gcv.Type.Code.String(), gcv.Value.GetStringValue())
}

Output:
INTERVAL P1Y2M3DT4H5M6S

func IntervalValue added in v0.1.6 

func IntervalValue(v spanner.Interval) spanner.GenericColumnValue

IntervalValue returns a non-null INTERVAL GenericColumnValue.

func JSONFromNullable added in v0.7.2 

func JSONFromNullable(n spanner.NullJSON) (spanner.GenericColumnValue, error)

JSONFromNullable returns a JSON GenericColumnValue from a Spanner null wrapper. When Valid, n.Value is marshaled like JSONValue: a Go string becomes a quoted JSON string on the wire, matching the official client's encodeValue. To store pre-encoded wire JSON as-is (validated and compacted), pass it as an encoding/json.RawMessage, the same convention the client follows.

Example

A Go string in NullJSON.Value marshals to a quoted JSON string, matching the official client's encodeValue; pass pre-encoded wire JSON as a json.RawMessage to store it as-is. 

package main

import (
	"encoding/json"
	"fmt"

	"cloud.google.com/go/spanner"

	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	str, _ := gcvctor.JSONFromNullable(spanner.NullJSON{Value: `{"a":1}`, Valid: true})
	raw, _ := gcvctor.JSONFromNullable(spanner.NullJSON{Value: json.RawMessage(`{"a":1}`), Valid: true})

	fmt.Println(str.Value.GetStringValue())
	fmt.Println(raw.Value.GetStringValue())
}

Output:
"{\"a\":1}"
{"a":1}

func JSONStringValue added in v0.7.5 

func JSONStringValue(v string) (spanner.GenericColumnValue, error)

JSONStringValue validates that v is syntactically valid JSON (encoding/json.Valid) and returns a non-null JSON GenericColumnValue with v stored as-is on the wire. It does not normalize, compact, or re-marshal the payload, matching the package's wire-as-is convention for string payloads (see StringBasedValueFromCode); whitespace and key order are preserved exactly as given. Invalid JSON returns ErrInvalidJSON. Use JSONValue to marshal a Go value to a canonical compact wire string instead.

func JSONValue 

func JSONValue(v any) (spanner.GenericColumnValue, error)

JSONValue marshals v to JSON and returns a non-null JSON GenericColumnValue.

func MustArrayValue added in v0.7.5 

func MustArrayValue(vs ...spanner.GenericColumnValue) spanner.GenericColumnValue

MustArrayValue is like ArrayValue but panics on error. Use only in tests and table-driven fixtures where schema and inputs are known good.

func MustArrayValueOf added in v0.6.0 

func MustArrayValueOf(elemType *sppb.Type, elems ...spanner.GenericColumnValue) spanner.GenericColumnValue

MustArrayValueOf is like ArrayValueOf but panics on error. Use only in tests and table-driven fixtures where schema and inputs are known good.

func MustDateStringValue added in v0.6.0 

func MustDateStringValue(v string) spanner.GenericColumnValue

MustDateStringValue is like DateStringValue but panics on error. Use only in tests and table-driven fixtures where inputs are known good.

func MustIntervalStringValue added in v0.6.0 

func MustIntervalStringValue(v string) spanner.GenericColumnValue

MustIntervalStringValue is like IntervalStringValue but panics on error. Use only in tests and table-driven fixtures where inputs are known good.

func MustJSONStringValue added in v0.7.5 

func MustJSONStringValue(v string) spanner.GenericColumnValue

MustJSONStringValue is like JSONStringValue but panics on error. Use only in tests and table-driven fixtures where inputs are known good.

func MustJSONValue added in v0.6.0 

func MustJSONValue(v any) spanner.GenericColumnValue

MustJSONValue is like JSONValue but panics on error. Use only in tests and table-driven fixtures where inputs are known good.

func MustNormalizeArrayElements added in v0.6.0 

func MustNormalizeArrayElements(elemType *sppb.Type, elems ...spanner.GenericColumnValue) []spanner.GenericColumnValue

MustNormalizeArrayElements is like NormalizeArrayElements but panics on error. Use only in tests and table-driven fixtures where schema and inputs are known good.

func MustNumericValueChecked added in v0.7.5 

func MustNumericValueChecked(v *big.Rat) spanner.GenericColumnValue

MustNumericValueChecked is like NumericValueChecked but panics on error. Use only in tests and table-driven fixtures where inputs are known good.

func MustPGJSONBValue added in v0.6.0 

func MustPGJSONBValue(v any) spanner.GenericColumnValue

MustPGJSONBValue is like PGJSONBValue but panics on error. Use only in tests and table-driven fixtures where inputs are known good.

func MustPGNumericValueChecked added in v0.7.5 

func MustPGNumericValueChecked(v *big.Rat) spanner.GenericColumnValue

MustPGNumericValueChecked is like PGNumericValueChecked but panics on error. Use only in tests and table-driven fixtures where inputs are known good.

func MustPGNumericValueExact added in v0.8.1 

func MustPGNumericValueExact(v *big.Rat) spanner.GenericColumnValue

MustPGNumericValueExact is PGNumericValueExact panicking on error, for schema-known fixture data; see the package doc's fixture guidance.

func MustStructValueOf added in v0.6.0 

func MustStructValueOf(names []string, gcvs []spanner.GenericColumnValue) spanner.GenericColumnValue

MustStructValueOf is like StructValueOf but panics on error. Use only in tests and table-driven fixtures where schema and inputs are known good.

func MustStructValueOfFields added in v0.7.0 

func MustStructValueOfFields(fields ...StructFieldKV) spanner.GenericColumnValue

MustStructValueOfFields is like StructValueOfFields but panics on error. It accepts the same StructFieldKV pairs as StructValueOfFields, including from StructFieldKVOf. Use only in tests and table-driven fixtures where schema and inputs are known good.

Example 
package main

import (
	"fmt"

	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	row := gcvctor.MustStructValueOfFields(
		gcvctor.StructFieldKVOf("name", gcvctor.StringValue("alice")),
		gcvctor.StructFieldKVOf("id", gcvctor.Int64Value(1)),
	)

	fmt.Println(row.Type.StructType.Fields[1].Name, row.Value.GetListValue().Values[1].GetStringValue())
}

Output:
id 1

func MustTimestampStringValue added in v0.6.0 

func MustTimestampStringValue(v string) spanner.GenericColumnValue

MustTimestampStringValue is like TimestampStringValue but panics on error. Use only in tests and table-driven fixtures where inputs are known good.

func MustUUIDStringValue added in v0.7.5 

func MustUUIDStringValue(v string) spanner.GenericColumnValue

MustUUIDStringValue is like UUIDStringValue but panics on error. Use only in tests and table-driven fixtures where inputs are known good.

func NormalizeArrayElements added in v0.3.0 

func NormalizeArrayElements(elemType *sppb.Type, elems ...spanner.GenericColumnValue) ([]spanner.GenericColumnValue, error)

NormalizeArrayElements rewrites SQL NULL elements to NullOf with elemType while preserving strict type checks for non-NULL elements. A nil elemType returns ErrNilElementType. Per-element failures are wrapped in ArrayElementError.

Example 
package main

import (
	"fmt"

	"cloud.google.com/go/spanner"
	sppb "cloud.google.com/go/spanner/apiv1/spannerpb"
	"github.com/apstndb/spantype/typector"

	"github.com/apstndb/spanvalue"
	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	elemType := typector.CodeToSimpleType(sppb.TypeCode_DATE)
	elems := []spanner.GenericColumnValue{
		gcvctor.MustDateStringValue("2026-04-01"),
		gcvctor.NullOf(nil),
		gcvctor.MustDateStringValue("2026-04-03"),
	}

	normalized := gcvctor.MustNormalizeArrayElements(elemType, elems...)
	array := gcvctor.MustArrayValueOf(elemType, normalized...)
	values := array.Value.GetListValue().Values

	fmt.Println(array.Type.Code.String(), array.Type.ArrayElementType.Code.String(), len(values))
	fmt.Println(values[0].GetStringValue())
	fmt.Println(spanvalue.IsNull(spanner.GenericColumnValue{Type: elemType, Value: values[1]}))
	fmt.Println(values[2].GetStringValue())
}

Output:
ARRAY DATE 3
2026-04-01
true
2026-04-03

func NullArrayFromCode added in v0.2.0 

func NullArrayFromCode(elemCode sppb.TypeCode) spanner.GenericColumnValue

NullArrayFromCode returns a typed SQL NULL for ARRAY<T> where T is a simple scalar type code.

func NullArrayOf added in v0.2.0 

func NullArrayOf(elemType *sppb.Type) spanner.GenericColumnValue

NullArrayOf returns a typed SQL NULL for ARRAY<elemType>. A nil elemType is normalized to TYPE_CODE_UNSPECIFIED, so NullArrayOf(nil) returns a NULL ARRAY<TYPE_CODE_UNSPECIFIED> rather than an invalid ARRAY shape.

Example 
package main

import (
	"fmt"

	sppb "cloud.google.com/go/spanner/apiv1/spannerpb"
	"github.com/apstndb/spantype/typector"

	"github.com/apstndb/spanvalue"
	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	elemType := typector.CodeToSimpleType(sppb.TypeCode_STRING)
	nullArray := gcvctor.NullArrayOf(elemType)
	nullViaNullOf := gcvctor.NullOf(typector.ElemTypeToArrayType(elemType))

	fmt.Println(spanvalue.IsNull(nullArray), nullArray.Type.ArrayElementType.Code.String())
	fmt.Println(spanvalue.IsNull(nullViaNullOf))
}

Output:
true STRING
true

func NullFromCode added in v0.2.0 

func NullFromCode(code sppb.TypeCode) spanner.GenericColumnValue

NullFromCode returns a typed SQL NULL for a simple scalar type code. The cloud.google.com/go/spanner.GenericColumnValue Value field is always a protobuf NullValue; see NullOf for STRUCT and ARRAY semantics.

func NullOf added in v0.2.0 

func NullOf(typ *sppb.Type) spanner.GenericColumnValue

NullOf returns a typed SQL NULL for typ. The cloud.google.com/go/spanner.GenericColumnValue Value field is always a protobuf NullValue, including when typ is STRUCT or ARRAY. It does not represent a non-null STRUCT whose fields are all null—use StructValueOf with per-field nulls (using NullOf or NullFromCode for each field) when you need that shape. A nil typ is normalized to TYPE_CODE_UNSPECIFIED to avoid a malformed nil Type pointer. Spanner rejects TYPE_CODE_UNSPECIFIED at the server, so a nil-Type bug surfaces there rather than at construction time.

Example 
package main

import (
	"fmt"

	sppb "cloud.google.com/go/spanner/apiv1/spannerpb"
	"github.com/apstndb/spantype/typector"

	"github.com/apstndb/spanvalue"
	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	scalar := gcvctor.NullOf(typector.CodeToSimpleType(sppb.TypeCode_INT64))
	array := gcvctor.NullOf(typector.ElemCodeToArrayType(sppb.TypeCode_DATE))

	fmt.Println(scalar.Type.Code.String(), spanvalue.IsNull(scalar))
	fmt.Println(array.Type.Code.String(), array.Type.ArrayElementType.Code.String(), spanvalue.IsNull(array))
}

Output:
INT64 true
ARRAY DATE true
Example (StructContainer) 
package main

import (
	"fmt"

	"cloud.google.com/go/spanner"
	sppb "cloud.google.com/go/spanner/apiv1/spannerpb"
	"github.com/apstndb/spantype/typector"

	"github.com/apstndb/spanvalue"
	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	structType, err := typector.NameCodeSlicesToStructType(
		[]string{"id", "name"},
		[]sppb.TypeCode{sppb.TypeCode_INT64, sppb.TypeCode_STRING},
	)
	if err != nil {
		panic(err)
	}
	nullStruct := gcvctor.NullOf(structType)
	fieldsAllNull := gcvctor.MustStructValueOf(
		[]string{"id", "name"},
		[]spanner.GenericColumnValue{
			gcvctor.NullOf(typector.CodeToSimpleType(sppb.TypeCode_INT64)),
			gcvctor.NullOf(typector.CodeToSimpleType(sppb.TypeCode_STRING)),
		},
	)

	fmt.Println(spanvalue.IsNull(nullStruct), nullStruct.Type.Code.String())
	fmt.Println(spanvalue.IsNull(fieldsAllNull), fieldsAllNull.Type.Code.String())
}

Output:
true STRUCT
false STRUCT

func NumericFromNullable added in v0.7.2 

func NumericFromNullable(n spanner.NullNumeric) spanner.GenericColumnValue

NumericFromNullable returns a NUMERIC GenericColumnValue from a Spanner null wrapper.

func NumericValue 

func NumericValue(v *big.Rat) spanner.GenericColumnValue

NumericValue returns a NUMERIC GenericColumnValue with a canonical wire string from cloud.google.com/go/spanner.NumericString. A nil v returns a typed SQL NULL NUMERIC for backward compatibility; use NumericValueChecked to reject nil input with ErrNilNumeric.

func NumericValueChecked added in v0.3.0 

func NumericValueChecked(v *big.Rat) (spanner.GenericColumnValue, error)

NumericValueChecked returns a non-null NUMERIC GenericColumnValue. A nil v returns ErrNilNumeric.

func PGJSONBFromNullable added in v0.7.2 

func PGJSONBFromNullable(n spanner.PGJsonB) (spanner.GenericColumnValue, error)

PGJSONBFromNullable returns a PostgreSQL-dialect JSON GenericColumnValue from a cloud.google.com/go/spanner.PGJsonB wrapper. When Valid, n.Value is marshaled like PGJSONBValue: a Go string becomes a quoted JSON string on the wire, matching the official client's encodeValue. To store pre-encoded wire JSON as-is (validated and compacted), pass it as an encoding/json.RawMessage.

func PGJSONBValue added in v0.2.1 

func PGJSONBValue(v any) (spanner.GenericColumnValue, error)

PGJSONBValue marshals v to JSON and returns a non-null PostgreSQL-dialect JSON GenericColumnValue (sppb.TypeAnnotationCode_PG_JSONB).

func PGNumericFromNullable added in v0.7.2 

func PGNumericFromNullable(n spanner.PGNumeric) spanner.GenericColumnValue

PGNumericFromNullable returns a PostgreSQL-dialect NUMERIC GenericColumnValue from a cloud.google.com/go/spanner.PGNumeric wrapper. The wire string is stored as-is when Valid.

func PGNumericValue added in v0.2.1 

func PGNumericValue(v *big.Rat) spanner.GenericColumnValue

PGNumericValue returns a PostgreSQL-dialect NUMERIC GenericColumnValue (sppb.TypeAnnotationCode_PG_NUMERIC) with a canonical wire string from cloud.google.com/go/spanner.NumericString. A nil v returns a typed SQL NULL PG NUMERIC for backward compatibility; use PGNumericValueChecked to reject nil input with ErrNilNumeric.

func PGNumericValueChecked added in v0.3.0 

func PGNumericValueChecked(v *big.Rat) (spanner.GenericColumnValue, error)

PGNumericValueChecked returns a non-null PostgreSQL-dialect NUMERIC GenericColumnValue (sppb.TypeAnnotationCode_PG_NUMERIC). A nil v returns ErrNilNumeric.

func PGNumericValueExact added in v0.8.1 

func PGNumericValueExact(v *big.Rat) (spanner.GenericColumnValue, error)

PGNumericValueExact returns a non-null PostgreSQL-dialect NUMERIC GenericColumnValue (sppb.TypeAnnotationCode_PG_NUMERIC) whose wire string is the exact decimal rendering of v. Unlike PGNumericValue, which formats with the GoogleSQL-scale cloud.google.com/go/spanner.NumericString (9 fractional digits, silently rounding), this constructor refuses to lose precision for the wider PostgreSQL-dialect numeric value space: a rational without a finite decimal expansion (a reduced denominator with prime factors other than 2 and 5, such as 1/3) returns ErrInexactNumeric, and nil returns ErrNilNumeric. Callers holding exact decimal wire text can use StringBasedValueOf or PGNumericFromNullable instead.

func PGOIDValue added in v0.7.5 

func PGOIDValue(v int64) spanner.GenericColumnValue

PGOIDValue returns a non-null PostgreSQL-dialect OID GenericColumnValue (sppb.TypeAnnotationCode_PG_OID) with a decimal string wire payload like Int64Value.

func ProtoValue 

func ProtoValue(fqn string, b []byte) spanner.GenericColumnValue

ProtoValue returns a non-null PROTO GenericColumnValue for the fully qualified message name fqn. The message bytes are stored in the GCV as a base64-encoded string. Delimited export decodes that wire payload for SimpleFormatConfig when possible.

func StringBasedValueFromCode added in v0.2.0 

func StringBasedValueFromCode(code sppb.TypeCode, v string) spanner.GenericColumnValue

StringBasedValueFromCode constructs a GenericColumnValue for a simple scalar type code with a string wire payload.

For sppb.TypeCode_NUMERIC and NUMERIC with sppb.TypeAnnotationCode_PG_NUMERIC, v must already be the canonical wire string Spanner uses (for GoogleSQL NUMERIC, the same form as cloud.google.com/go/spanner.NumericString on a *big.Rat). spanvalue formatters read the wire string as-is and do not re-normalize. Prefer NumericValue, PGNumericValue, or values from the Spanner client (including the emulator and Spanner Omni) over passing arbitrary decimals here.

Accepts simple scalar type codes only. ARRAY and STRUCT codes produce a malformed Type (missing array_element_type or struct_type); use StringBasedValueOf with typector for annotated or composite shapes.

Example (ValidatedDate) 
package main

import (
	"fmt"

	sppb "cloud.google.com/go/spanner/apiv1/spannerpb"

	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	raw := gcvctor.StringBasedValueFromCode(sppb.TypeCode_DATE, "not-a-date")
	_, err := gcvctor.DateStringValue("not-a-date")

	fmt.Println(raw.Type.Code.String(), raw.Value.GetStringValue())
	fmt.Println(err != nil)
}

Output:
DATE not-a-date
true

func StringBasedValueOf added in v0.7.2 

func StringBasedValueOf(typ *sppb.Type, v string) spanner.GenericColumnValue

StringBasedValueOf constructs a GenericColumnValue with an arbitrary string-compatible cloud.google.com/go/spanner/apiv1/spannerpb.Type and wire string stored as-is (no validation). Prefer typed helpers such as NumericValue or PGNumericFromNullable when you hold native Go values; use this when the Type carries annotations (for example PG-dialect NUMERIC) or other metadata beyond a bare type code.

func StringFromNullable added in v0.4.0 

func StringFromNullable(n spanner.NullString) spanner.GenericColumnValue

StringFromNullable returns a STRING GenericColumnValue from a Spanner null wrapper.

func StringFromPtr added in v0.4.0 

func StringFromPtr(p *string) spanner.GenericColumnValue

StringFromPtr returns a STRING GenericColumnValue. A nil pointer yields typed SQL NULL.

func StringValue 

func StringValue(v string) spanner.GenericColumnValue

StringValue returns a non-null STRING GenericColumnValue.

func StructValueOf added in v0.2.0 

func StructValueOf(names []string, gcvs []spanner.GenericColumnValue) (spanner.GenericColumnValue, error)

StructValueOf constructs STRUCT GenericColumnValue. A nil field Type returns ErrNilFieldType wrapped in StructFieldError. Note: Currently, it doesn't support implicit type conversion a.k.a. coercion so variant typed input is not supported.

func StructValueOfFields added in v0.7.0 

func StructValueOfFields(fields ...StructFieldKV) (spanner.GenericColumnValue, error)

StructValueOfFields is like StructValueOf but takes paired fields. Prefer StructFieldKVOf at call sites; keyed composite literals (StructFieldKV{Name: name, Value: value}) are also valid. Empty field names are valid for unnamed STRUCT fields.

Example 
package main

import (
	"fmt"

	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	row, err := gcvctor.StructValueOfFields(
		gcvctor.StructFieldKVOf("name", gcvctor.StringValue("alice")),
		gcvctor.StructFieldKVOf("id", gcvctor.Int64Value(1)),
	)
	if err != nil {
		panic(err)
	}
	unnamed, err := gcvctor.StructValueOfFields(
		gcvctor.StructFieldKVOf("", gcvctor.StringValue("value")),
		gcvctor.StructFieldKVOf("", gcvctor.Int64Value(42)),
	)
	if err != nil {
		panic(err)
	}

	fmt.Println(row.Type.StructType.Fields[0].Name, row.Value.GetListValue().Values[0].GetStringValue())
	fmt.Println(len(unnamed.Type.StructType.Fields), unnamed.Type.StructType.Fields[0].Name == "")
}

Output:
name alice
2 true

func TimestampFromNullable added in v0.4.0 

func TimestampFromNullable(n spanner.NullTime) spanner.GenericColumnValue

TimestampFromNullable returns a TIMESTAMP GenericColumnValue from a Spanner null wrapper.

Callers mirroring the official client's encodeValue must handle cloud.google.com/go/spanner.CommitTimestamp separately; the client checks that sentinel before formatting timestamps.

func TimestampFromPtr added in v0.4.0 

func TimestampFromPtr(p *time.Time) spanner.GenericColumnValue

TimestampFromPtr returns a TIMESTAMP GenericColumnValue. A nil pointer yields typed SQL NULL.

Callers mirroring the official client's encodeValue must handle cloud.google.com/go/spanner.CommitTimestamp separately; the client checks that sentinel before formatting timestamps.

func TimestampStringValue added in v0.3.0 

func TimestampStringValue(v string) (spanner.GenericColumnValue, error)

TimestampStringValue validates an RFC3339Nano timestamp string and returns a non-null TIMESTAMP GenericColumnValue using the canonical UTC wire string.

func TimestampValue 

func TimestampValue(v time.Time) spanner.GenericColumnValue

TimestampValue returns a non-null TIMESTAMP GenericColumnValue (RFC3339Nano string wire format).

func UUIDFromNullable added in v0.4.0 

func UUIDFromNullable(n spanner.NullUUID) spanner.GenericColumnValue

UUIDFromNullable returns a UUID GenericColumnValue from a Spanner null wrapper.

func UUIDFromPtr added in v0.4.0 

func UUIDFromPtr(p *uuid.UUID) spanner.GenericColumnValue

UUIDFromPtr returns a UUID GenericColumnValue. A nil pointer yields typed SQL NULL.

func UUIDStringValue added in v0.7.5 

func UUIDStringValue(v string) (spanner.GenericColumnValue, error)

UUIDStringValue validates a UUID string via github.com/google/uuid.Parse and returns a non-null UUID GenericColumnValue using the canonical lowercase wire string from github.com/google/uuid.UUID.String. Non-canonical forms accepted by uuid.Parse (uppercase hex digits, surrounding braces, a "urn:uuid:" prefix) are normalized to the canonical lowercase 8-4-4-4-12 form on the wire, so the stored payload can differ from v. Use UUIDValue when you already hold a github.com/google/uuid.UUID.

func UUIDValue added in v0.1.8 

func UUIDValue(v uuid.UUID) spanner.GenericColumnValue

UUIDValue returns a non-null UUID GenericColumnValue.

Example 
package main

import (
	"fmt"

	"github.com/google/uuid"

	"github.com/apstndb/spanvalue/gcvctor"
)

func main() {
	gcv := gcvctor.UUIDValue(uuid.MustParse("550e8400-e29b-41d4-a716-446655440000"))

	fmt.Println(gcv.Type.Code.String(), gcv.Value.GetStringValue())
}

Output:
UUID 550e8400-e29b-41d4-a716-446655440000

func WithEquivalentType added in v0.8.2 

func WithEquivalentType(typ *sppb.Type, gcv spanner.GenericColumnValue) (spanner.GenericColumnValue, error)

WithEquivalentType returns gcv retyped to typ when github.com/apstndb/spantype.EquivalentTypes reports the source and destination types are Spanner-equivalent. It only validates Type metadata; Value is preserved unchanged and not validated or canonicalized.

func WithExactType added in v0.8.2 

func WithExactType(typ *sppb.Type, gcv spanner.GenericColumnValue) (spanner.GenericColumnValue, error)

WithExactType returns gcv retyped to typ when proto.Equal(gcv.Type, typ). Use this when expected-type coercion requires identical type metadata, not merely Spanner equivalence. It only validates Type metadata; Value is preserved unchanged and not validated or canonicalized.

func WithType added in v0.8.2 

func WithType(typ *sppb.Type, gcv spanner.GenericColumnValue) spanner.GenericColumnValue

WithType returns a shallow copy of gcv with Type replaced by typ and Value unchanged. A nil typ is normalized to TYPE_CODE_UNSPECIFIED, matching NullOf. For validation, use WithEquivalentType or WithExactType.

Types

type ArrayElementError added in v0.3.0 

type ArrayElementError struct {
	Index int
	Err   error
}

ArrayElementError adds an element index to an ARRAY construction error while preserving the wrapped cause for errors.Is and errors.As.

func (*ArrayElementError) Error added in v0.3.0 

func (e *ArrayElementError) Error() string

func (*ArrayElementError) Unwrap added in v0.3.0 

func (e *ArrayElementError) Unwrap() error

type StructFieldError added in v0.3.0 

type StructFieldError struct {
	Index int
	Name  string
	Err   error
}

StructFieldError adds a field index (and optional field name) to a STRUCT construction error while preserving the wrapped cause for errors.Is and errors.As.

func (*StructFieldError) Error added in v0.3.0 

func (e *StructFieldError) Error() string

func (*StructFieldError) Unwrap added in v0.3.0 

func (e *StructFieldError) Unwrap() error

type StructFieldKV added in v0.7.0 

type StructFieldKV struct {
	Name  string
	Value spanner.GenericColumnValue
}

StructFieldKV pairs one STRUCT field name with its GCV. An empty Name is valid for unnamed STRUCT fields; see StructValueOfFields. Prefer StructFieldKVOf at call sites; keyed composite literals (StructFieldKV{Name: name, Value: value}) are also valid.

func StructFieldKVOf added in v0.7.0 

func StructFieldKVOf(name string, value spanner.GenericColumnValue) StructFieldKV

StructFieldKVOf returns a StructFieldKV with the given name and value. Empty name is valid for unnamed STRUCT fields.

Source Files

View all Source files

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.