spanenc

func ArrayValueFromSlice ¶

func ArrayValueFromSlice[T any](vs []T) (spanner.GenericColumnValue, error)

ArrayValueFromSlice converts a homogeneous slice into an ARRAY spanner.GenericColumnValue with the element type inferred statically from T (see ValuesFromSlice for the homogeneity rules). Following the client library's slice handling, a nil slice becomes a typed NULL ARRAY and an empty slice an empty ARRAY.

func MutationColumnsAndValues ¶

func MutationColumnsAndValues(v any) ([]string, []any, error)

MutationColumnsAndValues extracts column names and plain Go field values from a struct (or non-nil pointer to struct), mirroring the client's structToMutationParams: read-only fields (`spanner:"->"` or `spanner:"Name;readonly"`, since spanner v1.86.0) are excluded from the results. The results fit the cols/vals form of mutation constructors such as spanner.Insert, spanner.Update, and spanner.Replace, so callers can mask columns by name before building the mutation — something the *Struct constructors cannot do.

Values are returned as-is (no GCV conversion); the client library encodes them when the mutation is applied, so this helper accepts whatever InsertStruct accepts. A nil pointer returns ErrNilStructPointer where the client would silently produce an empty mutation.

package main

import (
	"fmt"
	"slices"

	"cloud.google.com/go/spanner"

	"github.com/apstndb/spanenc"
)

func main() {
	type Singer struct {
		SingerID  int64 `spanner:"SingerId"`
		FirstName string
		LastName  string
	}

	cols, vals, err := spanenc.MutationColumnsAndValues(Singer{SingerID: 1, FirstName: "Marc", LastName: "Richards"})
	if err != nil {
		fmt.Println(err)
		return
	}
	// Update only SingerId and LastName, masking FirstName.
	var mcols []string
	var mvals []any
	for i, c := range cols {
		if !slices.Contains([]string{"SingerId", "LastName"}, c) {
			continue
		}
		mcols = append(mcols, c)
		mvals = append(mvals, vals[i])
	}
	_ = spanner.Update("Singers", mcols, mvals)
	fmt.Println(mcols)
	fmt.Println(mvals)
}

Output:
[SingerId LastName]
[1 Richards]

func MutationMap ¶

func MutationMap(v any) (map[string]any, error)

MutationMap extracts a column-name-to-Go-value map from a struct (or non-nil pointer to struct) for the *Map mutation constructors (spanner.InsertMap, spanner.UpdateMap, spanner.ReplaceMap, spanner.InsertOrUpdateMap). Read-only fields are excluded like MutationColumnsAndValues. Masking a column is a map delete away.

Duplicate column names (possible with explicit duplicate `spanner` tags) return an error rather than silently dropping a value.

func RowTypeFor ¶

func RowTypeFor[T any]() (*sppb.StructType, error)

RowTypeFor returns the sppb.StructType describing a row of T, pairing StructColumns names (read-only fields included) with statically inferred field types (see TypeFromGoType). It suits writer metadata such as github.com/apstndb/spanvalue/writer's WithRowType, or the row_type of a ResultSetMetadata.

Note that this row-shaped view flattens embedded struct fields, while a STRUCT-typed value of T (TypeFor, ValueOf) rejects them; the client library has the same split between mutations/ToStruct and STRUCT parameters.

func RowTypeFromGoType ¶

func RowTypeFromGoType(t reflect.Type) (*sppb.StructType, error)

RowTypeFromGoType is RowTypeFor for a reflect.Type.

func StructColumns ¶

func StructColumns[T any]() ([]string, error)

StructColumns returns the column names derived from T's fields and `spanner` tags, in declaration order, with the same field listing the client library uses for cloud.google.com/go/spanner.Row.ToStruct: exported fields only, embedded struct fields flattened, `spanner:"-"` skipped. Read-only fields (`spanner:"->"` or `spanner:"Name;readonly"`) are included, because they are readable; the write-shaped MutationColumnsAndValues and MutationMap exclude them like the client's mutation constructors do.

It is the spanvalue-side answer to the StructColumns helper requested in https://github.com/googleapis/google-cloud-go/issues/13800, typically used to build the columns argument of Read calls from the same struct passed to ToStruct. T may be a struct or pointer-to-struct type.

package main

import (
	"fmt"

	"github.com/apstndb/spanenc"
)

func main() {
	type Singer struct {
		SingerID  int64 `spanner:"SingerId"`
		FirstName string
		LastName  string
		Internal  string `spanner:"-"`
	}

	columns, err := spanenc.StructColumns[Singer]()
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(columns)
	// client.Single().Read(ctx, "Singers", spanner.AllKeys(), columns) ...
	

Output:

func StructColumnsAndValues ¶

func StructColumnsAndValues(v any) ([]string, []spanner.GenericColumnValue, error)

StructColumnsAndValues converts a struct (or non-nil pointer to struct) into parallel column-name and spanner.GenericColumnValue slices using the ToStruct-shaped field listing (see StructColumns; read-only fields included) and ValueOf for each field. The result feeds GCV-level consumers such as github.com/apstndb/spanvalue/writer's WriteValues, and stays aligned with RowTypeFor.

For the client library's own mutation constructors, use MutationColumnsAndValues or MutationMap instead, which keep plain Go values, exclude read-only fields, and let the client encode the values.

package main

import (
	"fmt"
	"os"

	"github.com/apstndb/spanvalue/writer"

	"github.com/apstndb/spanenc"
)

func main() {
	type Singer struct {
		SingerID  int64 `spanner:"SingerId"`
		FirstName string
	}

	names, values, err := spanenc.StructColumnsAndValues(Singer{SingerID: 1, FirstName: "Marc"})
	if err != nil {
		fmt.Println(err)
		return
	}
	w, err := writer.NewCSVWriter(os.Stdout, writer.WithColumnNames(names))
	if err != nil {
		fmt.Println(err)
		return
	}
	if err := w.WriteValues(names, values); err != nil {
		fmt.Println(err)
		return
	}
	if err := w.Flush(); err != nil {
		fmt.Println(err)
		return
	}
}

Output:
SingerId,FirstName
1,Marc

func StructColumnsFromGoType ¶

func StructColumnsFromGoType(t reflect.Type) ([]string, error)

StructColumnsFromGoType is StructColumns for a reflect.Type.

func TypeFor ¶

func TypeFor[T any]() (*sppb.Type, error)

TypeFor returns the sppb.Type that ValueOf would produce for a non-NULL value of Go type T, following the Cloud Spanner client library encoding semantics. See TypeFromGoType.

func TypeFromGoType ¶

func TypeFromGoType(t reflect.Type) (*sppb.Type, error)

TypeFromGoType returns the sppb.Type that ValueOf produces for values of the given Go type, following the Cloud Spanner client library encoding semantics (encodeValue in cloud.google.com/go/spanner).

It returns ErrTypeNotInferable for Go types whose Spanner type depends on the value rather than the type: interface types, cloud.google.com/go/spanner.Encoder implementations, cloud.google.com/go/spanner.GenericColumnValue, cloud.google.com/go/spanner.NullProtoMessage, and cloud.google.com/go/spanner.NullProtoEnum. It returns ErrUnsupportedType for Go types the client library cannot encode.

func ValueOf ¶

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

ValueOf converts a Go value into a spanner.GenericColumnValue, following the Cloud Spanner client library encoding semantics (encodeValue in cloud.google.com/go/spanner): the Go types accepted for statement parameters and mutation values, including the typed NULL rules (nil pointers and nil slices become typed NULLs), spanner.Null* wrappers, spanner.Encoder implementations, protobuf messages and enums, named variants of base types, Go structs as STRUCT values, and spanner.CommitTimestamp.

Deliberate divergences from the client library are listed in the package documentation; most notably an untyped nil returns ErrUntypedNil instead of a NULL without type information.

package main

import (
	"fmt"

	"github.com/apstndb/spanvalue"

	"github.com/apstndb/spanenc"
)

func main() {
	for _, v := range []any{
		"foo",
		(*int64)(nil),
		[]string{"a", "b"},
	} {
		gcv, err := spanenc.ValueOf(v)
		if err != nil {
			fmt.Println(err)
			return
		}
		s, err := spanvalue.FormatColumnLiteral(gcv)
		if err != nil {
			fmt.Println(err)
			return
		}
		fmt.Println(s)
	}
}

Output:
"foo"
NULL
["a", "b"]

func ValuesFromSlice ¶

func ValuesFromSlice[T any](vs []T) (*sppb.Type, []*structpb.Value, error)

ValuesFromSlice converts a homogeneous slice into the shared element sppb.Type and one wire structpb.Value per element. Homogeneity is enforced through the static element type: T must have a type-inferable Spanner type (see TypeFromGoType), so interface element types — which could hold heterogeneous values — are rejected with ErrTypeNotInferable before any element is examined. Each encoded element is additionally verified against the inferred type.

A nil slice returns the element type with a nil values slice. To express a typed NULL ARRAY versus an empty ARRAY at the GCV level, use ArrayValueFromSlice.