rpc

package
v0.0.0-...-3903214 Latest Latest
Warning

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

 Go to latest Published: Apr 6, 2021 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// CommitTimestamp is a special value used to tell Cloud Spanner to insert
	// the commit timestamp of the transaction into a column. It can be used in
	// a Mutation, or directly used in InsertStruct or InsertMap. See
	// ExampleCommitTimestamp. This is just a placeholder and the actual value
	// stored in this variable has no meaning.
	CommitTimestamp = commitTimestamp
)

Functions

func BoolProto 

func BoolProto(b bool) *tspb.Value

func BoolType 

func BoolType() *tspb.Type

func BuildCommitResponse 

func BuildCommitResponse(r Response) *tspb.CommitResponse

func BuildMutationResponse 

func BuildMutationResponse(r Response) *tspb.MutationResponse

func BytesProto 

func BytesProto(b []byte) *tspb.Value

func BytesType 

func BytesType() *tspb.Type

func DateKind 

func DateKind(d civil.Date) *tspb.Value_TimestampValue

func DateProto 

func DateProto(d civil.Date) *tspb.Value

func DateType 

func DateType() *tspb.Type

func DecodeValue 

func DecodeValue(v *tspb.Value, t *tspb.Type, ptr interface{}) error

func ErrInvdMutationOp 

func ErrInvdMutationOp(op OP) error

ErrInvdMutationOp returns error for unrecognized mutation operation.

func FloatProto 

func FloatProto(n float64) *tspb.Value

func FloatType 

func FloatType() *tspb.Type

func IntProto 

func IntProto(n int64) *tspb.Value

func IntType 

func IntType() *tspb.Type

func KeyPartValue 

func KeyPartValue(part interface{}) (pb *tspb.Value, err error)

KeyPartValue converts a part of the Key (which is a valid Cloud Spanner type) into a tspb.Value. Used for encoding Key type into protobuf.

func ListType 

func ListType(t *tspb.Type) *tspb.Type

func NullProto 

func NullProto() *tspb.Value

func ReadRequestFromProto 

func ReadRequestFromProto(r *tspb.ReadRequest) *readRequest

func StringProto 

func StringProto(s string) *tspb.Value

Helpers to generate protobuf values and Cloud Spanner types.

func StringType 

func StringType() *tspb.Type

func TimeProto 

func TimeProto(t time.Time) *tspb.Value

func TimeType 

func TimeType() *tspb.Type

func TimestampProto 

func TimestampProto(t time.Time) *structpb.Timestamp

Types

type CommitTimeResp 

type CommitTimeResp struct {
	CommitTs time.Time
}

func (CommitTimeResp) CommitTimestamp 

func (r CommitTimeResp) CommitTimestamp() time.Time

type Error 

type Error struct {
	// Code is the canonical error code for describing the nature of a
	// particular error.
	Code codes.Code
	// Desc explains more details of the error.
	Desc string
}

Error is the structured error returned by Cloud Spanner client.

func (*Error) Error 

func (e *Error) Error() string

Error implements error.Error.

func (*Error) GRPCStatus 

func (e *Error) GRPCStatus() *status.Status

GRPCStatus returns the corresponding gRPC Status of this Spanner error. This allows the error to be converted to a gRPC status using `status.Convert(error)`.

type GenericColumnValue 

type GenericColumnValue struct {
	Type  *tspb.Type
	Value *tspb.Value
}

GenericColumnValue represents the generic encoded value and type of the column. See google.spanner.v1.ResultSet proto for details. This can be useful for proxying query results when the result types are not known in advance.

If you populate a GenericColumnValue from a row using Row.Column or related methods, do not modify the contents of Type and Value.

func (GenericColumnValue) Decode 

func (v GenericColumnValue) Decode(ptr interface{}) error

Decode decodes a GenericColumnValue. The ptr argument should be a pointer to a Go value that can accept v.

type Key 

type Key []interface{}

A Key can be either a Cloud Spanner row's primary key or a secondary index key. It is essentially an interface{} array, which represents a set of Cloud Spanner columns. A Key can be used as:

  • A primary key which uniquely identifies a Cloud Spanner row.
  • A secondary index key which maps to a set of Cloud Spanner rows indexed under it.
  • An endpoint of primary key/secondary index ranges; see the KeyRange type.

Rows that are identified by the Key type are outputs of read operation or targets of delete operation in a mutation. Note that for Insert/Update/InsertOrUpdate/Update mutation types, although they don't require a primary key explicitly, the column list provided must contain enough columns that can comprise a primary key.

Keys are easy to construct. For example, suppose you have a table with a primary key of username and product ID. To make a key for this table: 

key := spanner.Key{"john", 16}

See the description of Row and Mutation types for how Go types are mapped to Cloud Spanner types. For convenience, Key type supports a wide range of Go types:

  • int, int8, int16, int32, int64, and NullInt64 are mapped to Cloud Spanner's INT64 type.
  • uint8, uint16 and uint32 are also mapped to Cloud Spanner's INT64 type.
  • float32, float64, NullFloat64 are mapped to Cloud Spanner's FLOAT64 type.
  • bool and NullBool are mapped to Cloud Spanner's BOOL type.
  • []byte is mapped to Cloud Spanner's BYTES type.
  • string and NullString are mapped to Cloud Spanner's STRING type.
  • time.Time and NullTime are mapped to Cloud Spanner's TIMESTAMP type.
  • civil.Date and NullDate are mapped to Cloud Spanner's DATE type.

func (Key) AsPrefix 

func (key Key) AsPrefix() KeyRange

AsPrefix returns a KeyRange for all keys where k is the prefix.

func (Key) KeySetProto 

func (key Key) KeySetProto() (*tspb.KeySet, error)

KeySetProto lets a single Key act as a KeySet.

func (Key) Proto 

func (key Key) Proto() (*tspb.ListValue, error)

Proto converts a spanner.Key into a tspb.ListValue.

func (Key) String 

func (key Key) String() string

String implements fmt.Stringer for Key. For string, []byte and NullString, it prints the uninterpreted bytes of their contents, leaving caller with the opportunity to escape the output.

type KeyRange 

type KeyRange struct {
	// Start specifies the left boundary of the key range; End specifies
	// the right boundary of the key range.
	Start, End Key

	// Kind describes whether the boundaries of the key range include
	// their keys.
	Kind KeyRangeKind
}

A KeyRange represents a range of rows in a table or index.

A range has a Start key and an End key. IncludeStart and IncludeEnd indicate whether the Start and End keys are included in the range.

For example, consider the following table definition: 

CREATE TABLE UserEvents (
  UserName STRING(MAX),
  EventDate STRING(10),
) PRIMARY KEY(UserName, EventDate);

The following keys name rows in this table: 

spanner.Key{"Bob", "2014-09-23"}
spanner.Key{"Alfred", "2015-06-12"}

Since the UserEvents table's PRIMARY KEY clause names two columns, each UserEvents key has two elements; the first is the UserName, and the second is the EventDate.

Key ranges with multiple components are interpreted lexicographically by component using the table or index key's declared sort order. For example, the following range returns all events for user "Bob" that occurred in the year 2015: 

spanner.KeyRange{
	Start: spanner.Key{"Bob", "2015-01-01"},
	End:   spanner.Key{"Bob", "2015-12-31"},
	Kind:  ClosedClosed,
}

Start and end keys can omit trailing key components. This affects the inclusion and exclusion of rows that exactly match the provided key components: if IncludeStart is true, then rows that exactly match the provided components of the Start key are included; if IncludeStart is false then rows that exactly match are not included. IncludeEnd and End key behave in the same fashion.

For example, the following range includes all events for "Bob" that occurred during and after the year 2000: 

spanner.KeyRange{
	Start: spanner.Key{"Bob", "2000-01-01"},
	End:   spanner.Key{"Bob"},
	Kind:  ClosedClosed,
}

The next example retrieves all events for "Bob": 

spanner.Key{"Bob"}.AsPrefix()

To retrieve events before the year 2000: 

spanner.KeyRange{
	Start: spanner.Key{"Bob"},
	End:   spanner.Key{"Bob", "2000-01-01"},
	Kind:  ClosedOpen,
}

Although we specified a Kind for this KeyRange, we didn't need to, because the default is ClosedOpen. In later examples we'll omit Kind if it is ClosedOpen.

The following range includes all rows in a table or under a index: 

spanner.AllKeys()

This range returns all users whose UserName begins with any character from A to C: 

spanner.KeyRange{
	Start: spanner.Key{"A"},
	End:   spanner.Key{"D"},
}

This range returns all users whose UserName begins with B: 

spanner.KeyRange{
	Start: spanner.Key{"B"},
	End:   spanner.Key{"C"},
}

Key ranges honor column sort order. For example, suppose a table is defined as follows: 

CREATE TABLE DescendingSortedTable {
  Key INT64,
  ...
) PRIMARY KEY(Key DESC);

The following range retrieves all rows with key values between 1 and 100 inclusive: 

spanner.KeyRange{
	Start: spanner.Key{100},
	End:   spanner.Key{1},
	Kind:  ClosedClosed,
}

Note that 100 is passed as the start, and 1 is passed as the end, because Key is a descending column in the schema.

func (KeyRange) KeySetProto 

func (r KeyRange) KeySetProto() (*tspb.KeySet, error)

KeySetProto lets a KeyRange act as a KeySet.

func (KeyRange) Proto 

func (r KeyRange) Proto() (*tspb.KeyRange, error)

Proto converts KeyRange into tspb.KeyRange.

func (KeyRange) String 

func (r KeyRange) String() string

String implements fmt.Stringer for KeyRange type.

type KeyRangeKind 

type KeyRangeKind int

KeyRangeKind describes the kind of interval represented by a KeyRange: whether it is open or closed on the left and right. 

const (
	// ClosedOpen is closed on the left and open on the right: the Start
	// key is included, the End key is excluded.
	ClosedOpen KeyRangeKind = iota

	// ClosedClosed is closed on the left and the right: both keys are included.
	ClosedClosed

	// OpenClosed is open on the left and closed on the right: the Start
	// key is excluded, the End key is included.
	OpenClosed

	// OpenOpen is open on the left and the right: neither key is included.
	OpenOpen
)

type KeySet 

type KeySet interface {
	KeySetProto() (*tspb.KeySet, error)
}

A KeySet defines a collection of Cloud Spanner keys and/or key ranges. All the keys are expected to be in the same table or index. The keys need not be sorted in any particular way.

An individual Key can act as a KeySet, as can a KeyRange. Use the KeySets function to create a KeySet consisting of multiple Keys and KeyRanges. To obtain an empty KeySet, call KeySets with no arguments.

If the same key is specified multiple times in the set (for example if two ranges, two keys, or a key and a range overlap), the Cloud Spanner backend behaves as if the key were only specified once.

func AllKeys 

func AllKeys() KeySet

AllKeys returns a KeySet that represents all Keys of a table or a index.

func KeySets 

func KeySets(keySets ...KeySet) KeySet

KeySets returns the union of the KeySets. If any of the KeySets is AllKeys, then the resulting KeySet will be equivalent to AllKeys.

type Mutation 

type Mutation struct {
	// op is the operation type of the mutation.
	// See documentation for spanner.op for more details.
	Op OP
	// Table is the name of the target table to be modified.
	Table string
	// keySet is a set of primary keys that names the rows
	// in a delete operation.
	KeySet *tspb.KeySet
	// columns names the set of columns that are going to be
	// modified by Insert, InsertOrUpdate, Replace or Update
	// operations.
	Columns []string
	// values specifies the new values for the target columns
	// named by Columns.
	Values     []interface{}
	ListValues []*tspb.ListValue
}

A Mutation describes a modification to one or more Cloud Spanner rows. The mutation represents an insert, update, delete, etc on a table.

func (*Mutation) FromProto 

func (m *Mutation) FromProto(mutation *tspb.Mutation) error

type MutationRequest 

type MutationRequest interface {
	GetSession() string
	GetMutations() []*tspb.Mutation
	GetTable() string
}

type NullBool 

type NullBool struct {
	Bool  bool
	Valid bool // Valid is true if Bool is not NULL.
}

NullBool represents a Cloud Spanner BOOL that may be NULL.

func (NullBool) IsNull 

func (n NullBool) IsNull() bool

IsNull implements NullableValue.IsNull for NullBool.

func (NullBool) String 

func (n NullBool) String() string

String implements Stringer.String for NullBool

type NullDate 

type NullDate struct {
	Date  civil.Date
	Valid bool // Valid is true if Date is not NULL.
}

NullDate represents a Cloud Spanner DATE that may be null.

func (NullDate) IsNull 

func (n NullDate) IsNull() bool

IsNull implements NullableValue.IsNull for NullDate.

func (NullDate) String 

func (n NullDate) String() string

String implements Stringer.String for NullDate

type NullFloat64 

type NullFloat64 struct {
	Float64 float64
	Valid   bool // Valid is true if Float64 is not NULL.
}

NullFloat64 represents a Cloud Spanner FLOAT64 that may be NULL.

func (NullFloat64) IsNull 

func (n NullFloat64) IsNull() bool

IsNull implements NullableValue.IsNull for NullFloat64.

func (NullFloat64) String 

func (n NullFloat64) String() string

String implements Stringer.String for NullFloat64

type NullInt64 

type NullInt64 struct {
	Int64 int64
	Valid bool // Valid is true if Int64 is not NULL.
}

NullInt64 represents a Cloud Spanner INT64 that may be NULL.

func (NullInt64) IsNull 

func (n NullInt64) IsNull() bool

IsNull implements NullableValue.IsNull for NullInt64.

func (NullInt64) String 

func (n NullInt64) String() string

String implements Stringer.String for NullInt64

type NullRow 

type NullRow struct {
	Row   Row
	Valid bool // Valid is true if Row is not NULL.
}

NullRow represents a Cloud Spanner STRUCT that may be NULL. See also the document for Row. Note that NullRow is not a valid Cloud Spanner column Type.

type NullString 

type NullString struct {
	StringVal string
	Valid     bool // Valid is true if StringVal is not NULL.
}

NullString represents a Cloud Spanner STRING that may be NULL.

func (NullString) IsNull 

func (n NullString) IsNull() bool

IsNull implements NullableValue.IsNull for NullString.

func (NullString) String 

func (n NullString) String() string

String implements Stringer.String for NullString

type NullTime 

type NullTime struct {
	Time  time.Time
	Valid bool // Valid is true if Time is not NULL.
}

NullTime represents a Cloud Spanner TIMESTAMP that may be null.

func (NullTime) IsNull 

func (n NullTime) IsNull() bool

IsNull implements NullableValue.IsNull for NullTime.

func (NullTime) String 

func (n NullTime) String() string

String implements Stringer.String for NullTime

type NullableValue 

type NullableValue interface {
	// IsNull returns true if the underlying database value is null.
	IsNull() bool
}

NullableValue is the interface implemented by all null value wrapper types.

type OP 

type OP int

Op is the mutation operation. 

const (
	// OpUnknown indicate unknown operation
	OpUnknown OP = iota
	// OpDelete removes a row from a table.  Succeeds whether or not the
	// key was present.
	OpDelete
	// OpInsert inserts a row into a table.  If the row already exists, the
	// write or transaction fails.
	OpInsert
	// OpInsertOrUpdate inserts a row into a table. If the row already
	// exists, it updates it instead.  Any column values not explicitly
	// written are preserved.
	OpInsertOrUpdate
	// OpReplace inserts a row into a table, deleting any existing row.
	// Unlike InsertOrUpdate, this means any values not explicitly written
	// become NULL.
	OpReplace
	// OpUpdate updates a row in a table.  If the row does not already
	// exist, the write or transaction fails.
	OpUpdate
)

type ReadRequest 

type ReadRequest interface {
	GetSession() string
	GetTable() string
}

type Response 

type Response interface {
	CommitTimestamp() time.Time
}

type Row 

type Row struct {
	// contains filtered or unexported fields
}

A Row is a view of a row of data returned by a Cloud Spanner read. It consists of a number of columns; the number depends on the columns used to construct the read.

The column values can be accessed by index. For instance, if the read specified []string{"photo_id", "caption"}, then each row will contain two columns: "photo_id" with index 0, and "caption" with index 1.

Column values are decoded by using one of the Column, ColumnByName, or Columns methods. The valid values passed to these methods depend on the column type. For example: 

var photoID int64
err := row.Column(0, &photoID) // Decode column 0 as an integer.

var caption string
err := row.Column(1, &caption) // Decode column 1 as a string.

// Decode all the columns.
err := row.Columns(&photoID, &caption)

Supported types and their corresponding Cloud Spanner column type(s) are: 

*string(not NULL), *NullString - STRING
*[]string, *[]NullString - STRING ARRAY
*[]byte - BYTES
*[][]byte - BYTES ARRAY
*int64(not NULL), *NullInt64 - INT64
*[]int64, *[]NullInt64 - INT64 ARRAY
*bool(not NULL), *NullBool - BOOL
*[]bool, *[]NullBool - BOOL ARRAY
*float64(not NULL), *NullFloat64 - FLOAT64
*[]float64, *[]NullFloat64 - FLOAT64 ARRAY
*time.Time(not NULL), *NullTime - TIMESTAMP
*[]time.Time, *[]NullTime - TIMESTAMP ARRAY
*Date(not NULL), *NullDate - DATE
*[]civil.Date, *[]NullDate - DATE ARRAY
*[]*some_go_struct, *[]NullRow - STRUCT ARRAY
*GenericColumnValue - any Cloud Spanner type

For TIMESTAMP columns, the returned time.Time object will be in UTC.

To fetch an array of BYTES, pass a *[][]byte. To fetch an array of (sub)rows, pass a *[]spanner.NullRow or a *[]*some_go_struct where some_go_struct holds all information of the subrow, see spanner.Row.ToStruct for the mapping between a Cloud Spanner row and a Go struct. To fetch an array of other types, pass a *[]spanner.NullXXX type of the appropriate type. Use GenericColumnValue when you don't know in advance what column type to expect.

Row decodes the row contents lazily; as a result, each call to a getter has a chance of returning an error.

A column value may be NULL if the corresponding value is not present in Cloud Spanner. The spanner.NullXXX types (spanner.NullInt64 et al.) allow fetching values that may be null. A NULL BYTES can be fetched into a *[]byte as nil. It is an error to fetch a NULL value into any other type.

func NewRow 

func NewRow(columnNames []string, columnValues []interface{}) (*Row, error)

NewRow returns a Row containing the supplied data. This can be useful for mocking Cloud Spanner Read and Query responses for unit testing.

func (*Row) Column 

func (r *Row) Column(i int, ptr interface{}) error

Column fetches the value from the ith column, decoding it into ptr. See the Row documentation for the list of acceptable argument types. see Client.ReadWriteTransaction for an example.

func (*Row) ColumnByName 

func (r *Row) ColumnByName(name string, ptr interface{}) error

ColumnByName fetches the value from the named column, decoding it into ptr. See the Row documentation for the list of acceptable argument types.

func (*Row) ColumnIndex 

func (r *Row) ColumnIndex(name string) (int, error)

ColumnIndex returns the index of the column with the given name. The comparison is case-sensitive.

func (*Row) ColumnName 

func (r *Row) ColumnName(i int) string

ColumnName returns the name of column i, or empty string for invalid column.

func (*Row) ColumnNames 

func (r *Row) ColumnNames() []string

ColumnNames returns all column names of the row.

func (*Row) Columns 

func (r *Row) Columns(ptrs ...interface{}) error

Columns fetches all the columns in the row at once.

The value of the kth column will be decoded into the kth argument to Columns. See Row for the list of acceptable argument types. The number of arguments must be equal to the number of columns. Pass nil to specify that a column should be ignored.

func (*Row) Size 

func (r *Row) Size() int

Size is the number of columns in the row.

func (*Row) ToStruct 

func (r *Row) ToStruct(p interface{}) error

ToStruct fetches the columns in a row into the fields of a struct. The rules for mapping a row's columns into a struct's exported fields are:

  1. If a field has a `spanner: "column_name"` tag, then decode column 'column_name' into the field. A special case is the `spanner: "-"` tag, which instructs ToStruct to ignore the field during decoding.

  2. Otherwise, if the name of a field matches the name of a column (ignoring case), decode the column into the field.

The fields of the destination struct can be of any type that is acceptable to spanner.Row.Column.

Slice and pointer fields will be set to nil if the source column is NULL, and a non-nil value if the column is not NULL. To decode NULL values of other types, use one of the spanner.NullXXX types as the type of the destination field.

If ToStruct returns an error, the contents of p are undefined. Some fields may have been successfully populated, while others were not; you should not use any of the fields.

type SparseReadRequest 

type SparseReadRequest struct {
	*tspb.SparseReadRequest
}

Source Files

View all Source files

Directories

Path Synopsis
Package fields provides a view of the fields of a struct that follows the Go rules, amended to consider tags and case insensitivity.
 Package fields provides a view of the fields of a struct that follows the Go rules, amended to consider tags and case insensitivity.

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.