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, nullString) 139 } 140 case NullInt64, NullFloat64, NullBool: 141 // The above types implement fmt.Stringer. 142 fmt.Fprintf(b, "%s", v) 143 case NullString, NullDate, NullTime: 144 // Quote the returned string if it is not null. 145 if v.(NullableValue).IsNull() { 146 fmt.Fprintf(b, "%s", nullString) 147 } else { 148 fmt.Fprintf(b, "%q", v) 149 } 150 case civil.Date: 151 fmt.Fprintf(b, "%q", v) 152 case time.Time: 153 fmt.Fprintf(b, "%q", v.Format(time.RFC3339Nano)) 154 default: 155 fmt.Fprintf(b, "%v", v) 156 } 157 } 158 fmt.Fprint(b, ")") 159 return b.String() 160} 161 162// AsPrefix returns a KeyRange for all keys where k is the prefix. 163func (key Key) AsPrefix() KeyRange { 164 return KeyRange{ 165 Start: key, 166 End: key, 167 Kind: ClosedClosed, 168 } 169} 170 171// KeyRangeKind describes the kind of interval represented by a KeyRange: 172// whether it is open or closed on the left and right. 173type KeyRangeKind int 174 175const ( 176 // ClosedOpen is closed on the left and open on the right: the Start 177 // key is included, the End key is excluded. 178 ClosedOpen KeyRangeKind = iota 179 180 // ClosedClosed is closed on the left and the right: both keys are included. 181 ClosedClosed 182 183 // OpenClosed is open on the left and closed on the right: the Start 184 // key is excluded, the End key is included. 185 OpenClosed 186 187 // OpenOpen is open on the left and the right: neither key is included. 188 OpenOpen 189) 190 191// A KeyRange represents a range of rows in a table or index. 192// 193// A range has a Start key and an End key. IncludeStart and IncludeEnd 194// indicate whether the Start and End keys are included in the range. 195// 196// For example, consider the following table definition: 197// 198// CREATE TABLE UserEvents ( 199// UserName STRING(MAX), 200// EventDate STRING(10), 201// ) PRIMARY KEY(UserName, EventDate); 202// 203// The following keys name rows in this table: 204// 205// spanner.Key{"Bob", "2014-09-23"} 206// spanner.Key{"Alfred", "2015-06-12"} 207// 208// Since the UserEvents table's PRIMARY KEY clause names two columns, each 209// UserEvents key has two elements; the first is the UserName, and the second 210// is the EventDate. 211// 212// Key ranges with multiple components are interpreted lexicographically by 213// component using the table or index key's declared sort order. For example, 214// the following range returns all events for user "Bob" that occurred in the 215// year 2015: 216// 217// spanner.KeyRange{ 218// Start: spanner.Key{"Bob", "2015-01-01"}, 219// End: spanner.Key{"Bob", "2015-12-31"}, 220// Kind: ClosedClosed, 221// } 222// 223// Start and end keys can omit trailing key components. This affects the 224// inclusion and exclusion of rows that exactly match the provided key 225// components: if IncludeStart is true, then rows that exactly match the 226// provided components of the Start key are included; if IncludeStart is false 227// then rows that exactly match are not included. IncludeEnd and End key 228// behave in the same fashion. 229// 230// For example, the following range includes all events for "Bob" that occurred 231// during and after the year 2000: 232// 233// spanner.KeyRange{ 234// Start: spanner.Key{"Bob", "2000-01-01"}, 235// End: spanner.Key{"Bob"}, 236// Kind: ClosedClosed, 237// } 238// 239// The next example retrieves all events for "Bob": 240// 241// spanner.Key{"Bob"}.AsPrefix() 242// 243// To retrieve events before the year 2000: 244// 245// spanner.KeyRange{ 246// Start: spanner.Key{"Bob"}, 247// End: spanner.Key{"Bob", "2000-01-01"}, 248// Kind: ClosedOpen, 249// } 250// 251// Although we specified a Kind for this KeyRange, we didn't need to, because 252// the default is ClosedOpen. In later examples we'll omit Kind if it is 253// ClosedOpen. 254// 255// The following range includes all rows in a table or under a 256// index: 257// 258// spanner.AllKeys() 259// 260// This range returns all users whose UserName begins with any 261// character from A to C: 262// 263// spanner.KeyRange{ 264// Start: spanner.Key{"A"}, 265// End: spanner.Key{"D"}, 266// } 267// 268// This range returns all users whose UserName begins with B: 269// 270// spanner.KeyRange{ 271// Start: spanner.Key{"B"}, 272// End: spanner.Key{"C"}, 273// } 274// 275// Key ranges honor column sort order. For example, suppose a table is defined 276// as follows: 277// 278// CREATE TABLE DescendingSortedTable { 279// Key INT64, 280// ... 281// ) PRIMARY KEY(Key DESC); 282// 283// The following range retrieves all rows with key values between 1 and 100 284// inclusive: 285// 286// spanner.KeyRange{ 287// Start: spanner.Key{100}, 288// End: spanner.Key{1}, 289// Kind: ClosedClosed, 290// } 291// 292// Note that 100 is passed as the start, and 1 is passed as the end, because 293// Key is a descending column in the schema. 294type KeyRange struct { 295 // Start specifies the left boundary of the key range; End specifies 296 // the right boundary of the key range. 297 Start, End Key 298 299 // Kind describes whether the boundaries of the key range include 300 // their keys. 301 Kind KeyRangeKind 302} 303 304// String implements fmt.Stringer for KeyRange type. 305func (r KeyRange) String() string { 306 var left, right string 307 switch r.Kind { 308 case ClosedClosed: 309 left, right = "[", "]" 310 case ClosedOpen: 311 left, right = "[", ")" 312 case OpenClosed: 313 left, right = "(", "]" 314 case OpenOpen: 315 left, right = "(", ")" 316 default: 317 left, right = "?", "?" 318 } 319 return fmt.Sprintf("%s%s,%s%s", left, r.Start, r.End, right) 320} 321 322// proto converts KeyRange into sppb.KeyRange. 323func (r KeyRange) proto() (*sppb.KeyRange, error) { 324 var err error 325 var start, end *proto3.ListValue 326 pb := &sppb.KeyRange{} 327 if start, err = r.Start.proto(); err != nil { 328 return nil, err 329 } 330 if end, err = r.End.proto(); err != nil { 331 return nil, err 332 } 333 if r.Kind == ClosedClosed || r.Kind == ClosedOpen { 334 pb.StartKeyType = &sppb.KeyRange_StartClosed{StartClosed: start} 335 } else { 336 pb.StartKeyType = &sppb.KeyRange_StartOpen{StartOpen: start} 337 } 338 if r.Kind == ClosedClosed || r.Kind == OpenClosed { 339 pb.EndKeyType = &sppb.KeyRange_EndClosed{EndClosed: end} 340 } else { 341 pb.EndKeyType = &sppb.KeyRange_EndOpen{EndOpen: end} 342 } 343 return pb, nil 344} 345 346// keySetProto lets a KeyRange act as a KeySet. 347func (r KeyRange) keySetProto() (*sppb.KeySet, error) { 348 rp, err := r.proto() 349 if err != nil { 350 return nil, err 351 } 352 return &sppb.KeySet{Ranges: []*sppb.KeyRange{rp}}, nil 353} 354 355// A KeySet defines a collection of Cloud Spanner keys and/or key ranges. All 356// the keys are expected to be in the same table or index. The keys need not be 357// sorted in any particular way. 358// 359// An individual Key can act as a KeySet, as can a KeyRange. Use the KeySets 360// function to create a KeySet consisting of multiple Keys and KeyRanges. To 361// obtain an empty KeySet, call KeySets with no arguments. 362// 363// If the same key is specified multiple times in the set (for example if two 364// ranges, two keys, or a key and a range overlap), the Cloud Spanner backend 365// behaves as if the key were only specified once. 366type KeySet interface { 367 keySetProto() (*sppb.KeySet, error) 368} 369 370// AllKeys returns a KeySet that represents all Keys of a table or a index. 371func AllKeys() KeySet { 372 return all{} 373} 374 375type all struct{} 376 377func (all) keySetProto() (*sppb.KeySet, error) { 378 return &sppb.KeySet{All: true}, nil 379} 380 381// KeySets returns the union of the KeySets. If any of the KeySets is AllKeys, 382// then the resulting KeySet will be equivalent to AllKeys. 383func KeySets(keySets ...KeySet) KeySet { 384 u := make(union, len(keySets)) 385 copy(u, keySets) 386 return u 387} 388 389type union []KeySet 390 391func (u union) keySetProto() (*sppb.KeySet, error) { 392 upb := &sppb.KeySet{} 393 for _, ks := range u { 394 pb, err := ks.keySetProto() 395 if err != nil { 396 return nil, err 397 } 398 if pb.All { 399 return pb, nil 400 } 401 upb.Keys = append(upb.Keys, pb.Keys...) 402 upb.Ranges = append(upb.Ranges, pb.Ranges...) 403 } 404 return upb, nil 405} 406