1/* 2Copyright 2017 Google LLC 3 4Licensed under the Apache License, Version 2.0 (the "License"); 5you may not use this file except in compliance with the License. 6You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10Unless required by applicable law or agreed to in writing, software 11distributed under the License is distributed on an "AS IS" BASIS, 12WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13See the License for the specific language governing permissions and 14limitations under the License. 15*/ 16 17package spanner 18 19import ( 20 "bytes" 21 "fmt" 22 "time" 23 24 "cloud.google.com/go/civil" 25 proto3 "github.com/golang/protobuf/ptypes/struct" 26 sppb "google.golang.org/genproto/googleapis/spanner/v1" 27 "google.golang.org/grpc/codes" 28) 29 30// A Key can be either a Cloud Spanner row's primary key or a secondary index 31// key. It is essentially an interface{} array, which represents a set of Cloud 32// Spanner columns. A Key can be used as: 33// 34// - A primary key which uniquely identifies a Cloud Spanner row. 35// - A secondary index key which maps to a set of Cloud Spanner rows indexed under it. 36// - An endpoint of primary key/secondary index ranges; see the KeyRange type. 37// 38// Rows that are identified by the Key type are outputs of read operation or 39// targets of delete operation in a mutation. Note that for 40// Insert/Update/InsertOrUpdate/Update mutation types, although they don't 41// require a primary key explicitly, the column list provided must contain 42// enough columns that can comprise a primary key. 43// 44// Keys are easy to construct. For example, suppose you have a table with a 45// primary key of username and product ID. To make a key for this table: 46// 47// key := spanner.Key{"john", 16} 48// 49// See the description of Row and Mutation types for how Go types are mapped to 50// Cloud Spanner types. For convenience, Key type supports a wide range of Go 51// types: 52// - int, int8, int16, int32, int64, and NullInt64 are mapped to Cloud Spanner's INT64 type. 53// - uint8, uint16 and uint32 are also mapped to Cloud Spanner's INT64 type. 54// - float32, float64, NullFloat64 are mapped to Cloud Spanner's FLOAT64 type. 55// - bool and NullBool are mapped to Cloud Spanner's BOOL type. 56// - []byte is mapped to Cloud Spanner's BYTES type. 57// - string and NullString are mapped to Cloud Spanner's STRING type. 58// - time.Time and NullTime are mapped to Cloud Spanner's TIMESTAMP type. 59// - civil.Date and NullDate are mapped to Cloud Spanner's DATE type. 60type Key []interface{} 61 62// errInvdKeyPartType returns error for unsupported key part type. 63func errInvdKeyPartType(part interface{}) error { 64 return spannerErrorf(codes.InvalidArgument, "key part has unsupported type %T", part) 65} 66 67// keyPartValue converts a part of the Key (which is a valid Cloud Spanner type) 68// into a proto3.Value. Used for encoding Key type into protobuf. 69func keyPartValue(part interface{}) (pb *proto3.Value, err error) { 70 switch v := part.(type) { 71 case int: 72 pb, _, err = encodeValue(int64(v)) 73 case int8: 74 pb, _, err = encodeValue(int64(v)) 75 case int16: 76 pb, _, err = encodeValue(int64(v)) 77 case int32: 78 pb, _, err = encodeValue(int64(v)) 79 case uint8: 80 pb, _, err = encodeValue(int64(v)) 81 case uint16: 82 pb, _, err = encodeValue(int64(v)) 83 case uint32: 84 pb, _, err = encodeValue(int64(v)) 85 case float32: 86 pb, _, err = encodeValue(float64(v)) 87 case int64, float64, NullInt64, NullFloat64, bool, NullBool, []byte, string, NullString, time.Time, civil.Date, NullTime, NullDate: 88 pb, _, err = encodeValue(v) 89 default: 90 return nil, errInvdKeyPartType(v) 91 } 92 return pb, err 93} 94 95// proto converts a spanner.Key into a proto3.ListValue. 96func (key Key) proto() (*proto3.ListValue, error) { 97 lv := &proto3.ListValue{} 98 lv.Values = make([]*proto3.Value, 0, len(key)) 99 for _, part := range key { 100 v, err := keyPartValue(part) 101 if err != nil { 102 return nil, err 103 } 104 lv.Values = append(lv.Values, v) 105 } 106 return lv, nil 107} 108 109// keySetProto lets a single Key act as a KeySet. 110func (key Key) keySetProto() (*sppb.KeySet, error) { 111 kp, err := key.proto() 112 if err != nil { 113 return nil, err 114 } 115 return &sppb.KeySet{Keys: []*proto3.ListValue{kp}}, nil 116} 117 118// String implements fmt.Stringer for Key. For string, []byte and NullString, it 119// prints the uninterpreted bytes of their contents, leaving caller with the 120// opportunity to escape the output. 121func (key Key) String() string { 122 b := &bytes.Buffer{} 123 fmt.Fprint(b, "(") 124 for i, part := range []interface{}(key) { 125 if i != 0 { 126 fmt.Fprint(b, ",") 127 } 128 switch v := part.(type) { 129 case int, int8, int16, int32, int64, uint, uint8, uint16, uint32, float32, float64, bool: 130 // Use %v to print numeric types and bool. 131 fmt.Fprintf(b, "%v", v) 132 case string: 133 fmt.Fprintf(b, "%q", v) 134 case []byte: 135 if v != nil { 136 fmt.Fprintf(b, "%q", v) 137 } else { 138 fmt.Fprint(b, "<null>") 139 } 140 case NullInt64, NullFloat64, NullBool, NullString, NullTime, NullDate: 141 // The above types implement fmt.Stringer. 142 fmt.Fprintf(b, "%s", v) 143 case civil.Date: 144 fmt.Fprintf(b, "%q", v) 145 case time.Time: 146 fmt.Fprintf(b, "%q", v.Format(time.RFC3339Nano)) 147 default: 148 fmt.Fprintf(b, "%v", v) 149 } 150 } 151 fmt.Fprint(b, ")") 152 return b.String() 153} 154 155// AsPrefix returns a KeyRange for all keys where k is the prefix. 156func (key Key) AsPrefix() KeyRange { 157 return KeyRange{ 158 Start: key, 159 End: key, 160 Kind: ClosedClosed, 161 } 162} 163 164// KeyRangeKind describes the kind of interval represented by a KeyRange: 165// whether it is open or closed on the left and right. 166type KeyRangeKind int 167 168const ( 169 // ClosedOpen is closed on the left and open on the right: the Start 170 // key is included, the End key is excluded. 171 ClosedOpen KeyRangeKind = iota 172 173 // ClosedClosed is closed on the left and the right: both keys are included. 174 ClosedClosed 175 176 // OpenClosed is open on the left and closed on the right: the Start 177 // key is excluded, the End key is included. 178 OpenClosed 179 180 // OpenOpen is open on the left and the right: neither key is included. 181 OpenOpen 182) 183 184// A KeyRange represents a range of rows in a table or index. 185// 186// A range has a Start key and an End key. IncludeStart and IncludeEnd 187// indicate whether the Start and End keys are included in the range. 188// 189// For example, consider the following table definition: 190// 191// CREATE TABLE UserEvents ( 192// UserName STRING(MAX), 193// EventDate STRING(10), 194// ) PRIMARY KEY(UserName, EventDate); 195// 196// The following keys name rows in this table: 197// 198// spanner.Key{"Bob", "2014-09-23"} 199// spanner.Key{"Alfred", "2015-06-12"} 200// 201// Since the UserEvents table's PRIMARY KEY clause names two columns, each 202// UserEvents key has two elements; the first is the UserName, and the second 203// is the EventDate. 204// 205// Key ranges with multiple components are interpreted lexicographically by 206// component using the table or index key's declared sort order. For example, 207// the following range returns all events for user "Bob" that occurred in the 208// year 2015: 209// 210// spanner.KeyRange{ 211// Start: spanner.Key{"Bob", "2015-01-01"}, 212// End: spanner.Key{"Bob", "2015-12-31"}, 213// Kind: ClosedClosed, 214// } 215// 216// Start and end keys can omit trailing key components. This affects the 217// inclusion and exclusion of rows that exactly match the provided key 218// components: if IncludeStart is true, then rows that exactly match the 219// provided components of the Start key are included; if IncludeStart is false 220// then rows that exactly match are not included. IncludeEnd and End key 221// behave in the same fashion. 222// 223// For example, the following range includes all events for "Bob" that occurred 224// during and after the year 2000: 225// 226// spanner.KeyRange{ 227// Start: spanner.Key{"Bob", "2000-01-01"}, 228// End: spanner.Key{"Bob"}, 229// Kind: ClosedClosed, 230// } 231// 232// The next example retrieves all events for "Bob": 233// 234// spanner.Key{"Bob"}.AsPrefix() 235// 236// To retrieve events before the year 2000: 237// 238// spanner.KeyRange{ 239// Start: spanner.Key{"Bob"}, 240// End: spanner.Key{"Bob", "2000-01-01"}, 241// Kind: ClosedOpen, 242// } 243// 244// Although we specified a Kind for this KeyRange, we didn't need to, because 245// the default is ClosedOpen. In later examples we'll omit Kind if it is 246// ClosedOpen. 247// 248// The following range includes all rows in a table or under a 249// index: 250// 251// spanner.AllKeys() 252// 253// This range returns all users whose UserName begins with any 254// character from A to C: 255// 256// spanner.KeyRange{ 257// Start: spanner.Key{"A"}, 258// End: spanner.Key{"D"}, 259// } 260// 261// This range returns all users whose UserName begins with B: 262// 263// spanner.KeyRange{ 264// Start: spanner.Key{"B"}, 265// End: spanner.Key{"C"}, 266// } 267// 268// Key ranges honor column sort order. For example, suppose a table is defined 269// as follows: 270// 271// CREATE TABLE DescendingSortedTable { 272// Key INT64, 273// ... 274// ) PRIMARY KEY(Key DESC); 275// 276// The following range retrieves all rows with key values between 1 and 100 277// inclusive: 278// 279// spanner.KeyRange{ 280// Start: spanner.Key{100}, 281// End: spanner.Key{1}, 282// Kind: ClosedClosed, 283// } 284// 285// Note that 100 is passed as the start, and 1 is passed as the end, because 286// Key is a descending column in the schema. 287type KeyRange struct { 288 // Start specifies the left boundary of the key range; End specifies 289 // the right boundary of the key range. 290 Start, End Key 291 292 // Kind describes whether the boundaries of the key range include 293 // their keys. 294 Kind KeyRangeKind 295} 296 297// String implements fmt.Stringer for KeyRange type. 298func (r KeyRange) String() string { 299 var left, right string 300 switch r.Kind { 301 case ClosedClosed: 302 left, right = "[", "]" 303 case ClosedOpen: 304 left, right = "[", ")" 305 case OpenClosed: 306 left, right = "(", "]" 307 case OpenOpen: 308 left, right = "(", ")" 309 default: 310 left, right = "?", "?" 311 } 312 return fmt.Sprintf("%s%s,%s%s", left, r.Start, r.End, right) 313} 314 315// proto converts KeyRange into sppb.KeyRange. 316func (r KeyRange) proto() (*sppb.KeyRange, error) { 317 var err error 318 var start, end *proto3.ListValue 319 pb := &sppb.KeyRange{} 320 if start, err = r.Start.proto(); err != nil { 321 return nil, err 322 } 323 if end, err = r.End.proto(); err != nil { 324 return nil, err 325 } 326 if r.Kind == ClosedClosed || r.Kind == ClosedOpen { 327 pb.StartKeyType = &sppb.KeyRange_StartClosed{StartClosed: start} 328 } else { 329 pb.StartKeyType = &sppb.KeyRange_StartOpen{StartOpen: start} 330 } 331 if r.Kind == ClosedClosed || r.Kind == OpenClosed { 332 pb.EndKeyType = &sppb.KeyRange_EndClosed{EndClosed: end} 333 } else { 334 pb.EndKeyType = &sppb.KeyRange_EndOpen{EndOpen: end} 335 } 336 return pb, nil 337} 338 339// keySetProto lets a KeyRange act as a KeySet. 340func (r KeyRange) keySetProto() (*sppb.KeySet, error) { 341 rp, err := r.proto() 342 if err != nil { 343 return nil, err 344 } 345 return &sppb.KeySet{Ranges: []*sppb.KeyRange{rp}}, nil 346} 347 348// A KeySet defines a collection of Cloud Spanner keys and/or key ranges. All 349// the keys are expected to be in the same table or index. The keys need not be 350// sorted in any particular way. 351// 352// An individual Key can act as a KeySet, as can a KeyRange. Use the KeySets 353// function to create a KeySet consisting of multiple Keys and KeyRanges. To 354// obtain an empty KeySet, call KeySets with no arguments. 355// 356// If the same key is specified multiple times in the set (for example if two 357// ranges, two keys, or a key and a range overlap), the Cloud Spanner backend 358// behaves as if the key were only specified once. 359type KeySet interface { 360 keySetProto() (*sppb.KeySet, error) 361} 362 363// AllKeys returns a KeySet that represents all Keys of a table or a index. 364func AllKeys() KeySet { 365 return all{} 366} 367 368type all struct{} 369 370func (all) keySetProto() (*sppb.KeySet, error) { 371 return &sppb.KeySet{All: true}, nil 372} 373 374// KeySets returns the union of the KeySets. If any of the KeySets is AllKeys, 375// then the resulting KeySet will be equivalent to AllKeys. 376func KeySets(keySets ...KeySet) KeySet { 377 u := make(union, len(keySets)) 378 copy(u, keySets) 379 return u 380} 381 382type union []KeySet 383 384func (u union) keySetProto() (*sppb.KeySet, error) { 385 upb := &sppb.KeySet{} 386 for _, ks := range u { 387 pb, err := ks.keySetProto() 388 if err != nil { 389 return nil, err 390 } 391 if pb.All { 392 return pb, nil 393 } 394 upb.Keys = append(upb.Keys, pb.Keys...) 395 upb.Ranges = append(upb.Ranges, pb.Ranges...) 396 } 397 return upb, nil 398} 399