1/* 2Copyright 2015 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 17/* 18Package bigtable is an API to Google Cloud Bigtable. 19 20See https://cloud.google.com/bigtable/docs/ for general product documentation. 21 22See https://godoc.org/cloud.google.com/go for authentication, timeouts, 23connection pooling and similar aspects of this package. 24 25 26Setup and Credentials 27 28Use NewClient or NewAdminClient to create a client that can be used to access 29the data or admin APIs respectively. Both require credentials that have permission 30to access the Cloud Bigtable API. 31 32If your program is run on Google App Engine or Google Compute Engine, using the Application Default Credentials 33(https://developers.google.com/accounts/docs/application-default-credentials) 34is the simplest option. Those credentials will be used by default when NewClient or NewAdminClient are called. 35 36To use alternate credentials, pass them to NewClient or NewAdminClient using option.WithTokenSource. 37For instance, you can use service account credentials by visiting 38https://cloud.google.com/console/project/_/apiui/credential, 39creating a new OAuth "Client ID", storing the JSON key somewhere accessible, and writing 40 jsonKey, err := ioutil.ReadFile(pathToKeyFile) 41 ... 42 config, err := google.JWTConfigFromJSON(jsonKey, bigtable.Scope) // or bigtable.AdminScope, etc. 43 ... 44 client, err := bigtable.NewClient(ctx, project, instance, option.WithTokenSource(config.TokenSource(ctx))) 45 ... 46Here, `google` means the golang.org/x/oauth2/google package 47and `option` means the google.golang.org/api/option package. 48 49Reading 50 51The principal way to read from a Bigtable is to use the ReadRows method on *Table. 52A RowRange specifies a contiguous portion of a table. A Filter may be provided through 53RowFilter to limit or transform the data that is returned. 54 tbl := client.Open("mytable") 55 ... 56 // Read all the rows starting with "com.google.", 57 // but only fetch the columns in the "links" family. 58 rr := bigtable.PrefixRange("com.google.") 59 err := tbl.ReadRows(ctx, rr, func(r Row) bool { 60 // do something with r 61 return true // keep going 62 }, bigtable.RowFilter(bigtable.FamilyFilter("links"))) 63 ... 64 65To read a single row, use the ReadRow helper method. 66 r, err := tbl.ReadRow(ctx, "com.google.cloud") // "com.google.cloud" is the entire row key 67 ... 68 69Writing 70 71This API exposes two distinct forms of writing to a Bigtable: a Mutation and a ReadModifyWrite. 72The former expresses idempotent operations. 73The latter expresses non-idempotent operations and returns the new values of updated cells. 74These operations are performed by creating a Mutation or ReadModifyWrite (with NewMutation or NewReadModifyWrite), 75building up one or more operations on that, and then using the Apply or ApplyReadModifyWrite 76methods on a Table. 77 78For instance, to set a couple of cells in a table, 79 tbl := client.Open("mytable") 80 mut := bigtable.NewMutation() 81 mut.Set("links", "maps.google.com", bigtable.Now(), []byte("1")) 82 mut.Set("links", "golang.org", bigtable.Now(), []byte("1")) 83 err := tbl.Apply(ctx, "com.google.cloud", mut) 84 ... 85 86To increment an encoded value in one cell, 87 tbl := client.Open("mytable") 88 rmw := bigtable.NewReadModifyWrite() 89 rmw.Increment("links", "golang.org", 12) // add 12 to the cell in column "links:golang.org" 90 r, err := tbl.ApplyReadModifyWrite(ctx, "com.google.cloud", rmw) 91 ... 92 93Retries 94 95If a read or write operation encounters a transient error it will be retried until a successful 96response, an unretryable error or the context deadline is reached. Non-idempotent writes (where 97the timestamp is set to ServerTime) will not be retried. In the case of ReadRows, retried calls 98will not re-scan rows that have already been processed. 99*/ 100package bigtable // import "cloud.google.com/go/bigtable" 101 102// Scope constants for authentication credentials. 103// These should be used when using credential creation functions such as oauth.NewServiceAccountFromFile. 104const ( 105 // Scope is the OAuth scope for Cloud Bigtable data operations. 106 Scope = "https://www.googleapis.com/auth/bigtable.data" 107 // ReadonlyScope is the OAuth scope for Cloud Bigtable read-only data operations. 108 ReadonlyScope = "https://www.googleapis.com/auth/bigtable.readonly" 109 110 // AdminScope is the OAuth scope for Cloud Bigtable table admin operations. 111 AdminScope = "https://www.googleapis.com/auth/bigtable.admin.table" 112 113 // InstanceAdminScope is the OAuth scope for Cloud Bigtable instance (and cluster) admin operations. 114 InstanceAdminScope = "https://www.googleapis.com/auth/bigtable.admin.cluster" 115) 116 117// clientUserAgent identifies the version of this package. 118// It should be bumped upon significant changes only. 119const clientUserAgent = "cbt-go/20180601" 120 121// resourcePrefixHeader is the name of the metadata header used to indicate 122// the resource being operated on. 123const resourcePrefixHeader = "google-cloud-resource-prefix" 124