The bigtable package

import "cloud.google.com/go/bigtable"

Introduction

Package bigtable is an API to Google Cloud Bigtable.

See https://cloud.google.com/bigtable/docs/ for general product documentation.

Setup and Credentials

Use NewClient or NewAdminClient to create a client that can be used to access the data or admin APIs respectively. Both require credentials that have permission to access the Cloud Bigtable API.

If your program is run on Google App Engine or Google Compute Engine, using the Application Default Credentials (https://developers.google.com/accounts/docs/application-default-credentials) is the simplest option. Those credentials will be used by default when NewClient or NewAdminClient are called.

To use alternate credentials, pass them to NewClient or NewAdminClient using option.WithTokenSource. For instance, you can use service account credentials by visiting https://cloud.google.com/console/project/MYPROJECT/apiui/credential, creating a new OAuth "Client ID", storing the JSON key somewhere accessible, and writing

jsonKey, err := ioutil.ReadFile(pathToKeyFile)
...
config, err := google.JWTConfigFromJSON(jsonKey, bigtable.Scope) // or bigtable.AdminScope, etc.
...
client, err := bigtable.NewClient(ctx, project, instance, option.WithTokenSource(config.TokenSource(ctx)))
...

Here, `google` means the golang.org/x/oauth2/google package and `option` means the google.golang.org/api/option package.

Reading

The principal way to read from a Bigtable is to use the ReadRows method on *Table. A RowRange specifies a contiguous portion of a table. A Filter may be provided through RowFilter to limit or transform the data that is returned.

tbl := client.Open("mytable")
...
// Read all the rows starting with "com.google.",
// but only fetch the columns in the "links" family.
rr := bigtable.PrefixRange("com.google.")
err := tbl.ReadRows(ctx, rr, func(r Row) bool {
    // do something with r
    return true // keep going
}, bigtable.RowFilter(bigtable.FamilyFilter("links")))
...

To read a single row, use the ReadRow helper method.

r, err := tbl.ReadRow(ctx, "com.google.cloud") // "com.google.cloud" is the entire row key
...

Writing

This API exposes two distinct forms of writing to a Bigtable: a Mutation and a ReadModifyWrite. The former expresses idempotent operations. The latter expresses non-idempotent operations and returns the new values of updated cells. These operations are performed by creating a Mutation or ReadModifyWrite (with NewMutation or NewReadModifyWrite), building up one or more operations on that, and then using the Apply or ApplyReadModifyWrite methods on a Table.

For instance, to set a couple of cells in a table,

tbl := client.Open("mytable")
mut := bigtable.NewMutation()
mut.Set("links", "maps.google.com", bigtable.Now(), []byte("1"))
mut.Set("links", "golang.org", bigtable.Now(), []byte("1"))
err := tbl.Apply(ctx, "com.google.cloud", mut)
...

To increment an encoded value in one cell,

tbl := client.Open("mytable")
rmw := bigtable.NewReadModifyWrite()
rmw.Increment("links", "golang.org", 12) // add 12 to the cell in column "links:golang.org"
r, err := tbl.ApplyReadModifyWrite(ctx, "com.google.cloud", rmw)
...

Retries

If a read or write operation encounters a transient error it will be retried until a successful response, an unretryable error or the context deadline is reached. Non-idempotent writes (where the timestamp is set to ServerTime) will not be retried. In the case of ReadRows, retried calls will not re-scan rows that have already been processed.

Index

Constants
type AdminClient
    func NewAdminClient(ctx context.Context, project, instance string, opts ...option.ClientOption) (*AdminClient, error)
    func (ac *AdminClient) Close() error
    func (ac *AdminClient) CreateColumnFamily(ctx context.Context, table, family string) error
    func (ac *AdminClient) CreateTable(ctx context.Context, table string) error
    func (ac *AdminClient) DeleteColumnFamily(ctx context.Context, table, family string) error
    func (ac *AdminClient) DeleteTable(ctx context.Context, table string) error
    func (ac *AdminClient) SetGCPolicy(ctx context.Context, table, family string, policy GCPolicy) error
    func (ac *AdminClient) TableInfo(ctx context.Context, table string) (*TableInfo, error)
    func (ac *AdminClient) Tables(ctx context.Context) ([]string, error)
type ApplyOption
    func GetCondMutationResult(matched *bool) ApplyOption
type Client
    func NewClient(ctx context.Context, project, instance string, opts ...option.ClientOption) (*Client, error)
    func (c *Client) Close() error
    func (c *Client) Open(table string) *Table
type Filter
    func ChainFilters(sub ...Filter) Filter
    func ColumnFilter(pattern string) Filter
    func FamilyFilter(pattern string) Filter
    func InterleaveFilters(sub ...Filter) Filter
    func LatestNFilter(n int) Filter
    func RowKeyFilter(pattern string) Filter
    func StripValueFilter() Filter
    func TimestampRangeFilter(startTime time.Time, endTime time.Time) Filter
    func ValueFilter(pattern string) Filter
type GCPolicy
    func IntersectionPolicy(sub ...GCPolicy) GCPolicy
    func MaxAgePolicy(d time.Duration) GCPolicy
    func MaxVersionsPolicy(n int) GCPolicy
    func UnionPolicy(sub ...GCPolicy) GCPolicy
type Mutation
    func NewCondMutation(cond Filter, mtrue, mfalse *Mutation) *Mutation
    func NewMutation() *Mutation
    func (m *Mutation) DeleteCellsInColumn(family, column string)
    func (m *Mutation) DeleteCellsInFamily(family string)
    func (m *Mutation) DeleteRow()
    func (m *Mutation) DeleteTimestampRange(family, column string, start, end Timestamp)
    func (m *Mutation) Set(family, column string, ts Timestamp, value []byte)
type ReadItem
type ReadModifyWrite
    func NewReadModifyWrite() *ReadModifyWrite
    func (m *ReadModifyWrite) AppendValue(family, column string, v []byte)
    func (m *ReadModifyWrite) Increment(family, column string, delta int64)
type ReadOption
    func LimitRows(limit int64) ReadOption
    func RowFilter(f Filter) ReadOption
type Row
    func (r Row) Key() string
type RowList
type RowRange
    func InfiniteRange(start string) RowRange
    func NewRange(begin, end string) RowRange
    func PrefixRange(prefix string) RowRange
    func SingleRow(row string) RowRange
    func (r RowRange) Contains(row string) bool
    func (r RowRange) String() string
    func (r RowRange) Unbounded() bool
type RowSet
type Table
    func (t *Table) Apply(ctx context.Context, row string, m *Mutation, opts ...ApplyOption) error
    func (t *Table) ApplyBulk(ctx context.Context, rowKeys []string, muts []*Mutation, opts ...ApplyOption) ([]error, error)
    func (t *Table) ApplyReadModifyWrite(ctx context.Context, row string, m *ReadModifyWrite) (Row, error)
    func (t *Table) ReadRow(ctx context.Context, row string, opts ...ReadOption) (Row, error)
    func (t *Table) ReadRows(ctx context.Context, arg RowSet, f func(Row) bool, opts ...ReadOption) error
type TableInfo
type Timestamp
    func Now() Timestamp
    func Time(t time.Time) Timestamp
    func (ts Timestamp) Time() time.Time

Constants

const (
    // Scope is the OAuth scope for Cloud Bigtable data operations.
    Scope = "https://www.googleapis.com/auth/bigtable.data"
    // ReadonlyScope is the OAuth scope for Cloud Bigtable read-only data operations.
    ReadonlyScope = "https://www.googleapis.com/auth/bigtable.readonly"

    // AdminScope is the OAuth scope for Cloud Bigtable table admin operations.
    AdminScope = "https://www.googleapis.com/auth/bigtable.admin.table"
)

Scope constants for authentication credentials. These should be used when using credential creation functions such as oauth.NewServiceAccountFromFile.

type AdminClient

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

AdminClient is a client type for performing admin operations within a specific instance.

func NewAdminClient

func NewAdminClient(ctx context.Context, project, instance string, opts ...option.ClientOption) (*AdminClient, error)

NewAdminClient creates a new AdminClient for a given project and instance.

func (*AdminClient) Close

func (ac *AdminClient) Close() error

Close closes the AdminClient.

func (*AdminClient) CreateColumnFamily

func (ac *AdminClient) CreateColumnFamily(ctx context.Context, table, family string) error

CreateColumnFamily creates a new column family in a table.

func (*AdminClient) CreateTable

func (ac *AdminClient) CreateTable(ctx context.Context, table string) error

CreateTable creates a new table in the instance. This method may return before the table's creation is complete.

func (*AdminClient) DeleteColumnFamily

func (ac *AdminClient) DeleteColumnFamily(ctx context.Context, table, family string) error

DeleteColumnFamily deletes a column family in a table and all of its data.

func (*AdminClient) DeleteTable

func (ac *AdminClient) DeleteTable(ctx context.Context, table string) error

DeleteTable deletes a table and all of its data.

func (*AdminClient) SetGCPolicy

func (ac *AdminClient) SetGCPolicy(ctx context.Context, table, family string, policy GCPolicy) error

SetGCPolicy specifies which cells in a column family should be garbage collected. GC executes opportunistically in the background; table reads may return data matching the GC policy.

func (*AdminClient) TableInfo

func (ac *AdminClient) TableInfo(ctx context.Context, table string) (*TableInfo, error)

TableInfo retrieves information about a table.

func (*AdminClient) Tables

func (ac *AdminClient) Tables(ctx context.Context) ([]string, error)

Tables returns a list of the tables in the instance.

type ApplyOption

type ApplyOption interface {
    // contains filtered or unexported methods
}

An ApplyOption is an optional argument to Apply.

func GetCondMutationResult

func GetCondMutationResult(matched *bool) ApplyOption

GetCondMutationResult returns an ApplyOption that reports whether the conditional mutation's condition matched.

type Client

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

Client is a client for reading and writing data to tables in an instance.

A Client is safe to use concurrently, except for its Close method.

func NewClient

func NewClient(ctx context.Context, project, instance string, opts ...option.ClientOption) (*Client, error)

NewClient creates a new Client for a given project and instance.

func (*Client) Close

func (c *Client) Close() error

Close closes the Client.

func (*Client) Open

func (c *Client) Open(table string) *Table

Open opens a table.

type Filter

type Filter interface {
    String() string
    // contains filtered or unexported methods
}

A Filter represents a row filter.

func ChainFilters

func ChainFilters(sub ...Filter) Filter

ChainFilters returns a filter that applies a sequence of filters.

func ColumnFilter

func ColumnFilter(pattern string) Filter

ColumnFilter returns a filter that matches cells whose column name matches the provided RE2 pattern. See https://github.com/google/re2/wiki/Syntax for the accepted syntax.

func FamilyFilter

func FamilyFilter(pattern string) Filter

FamilyFilter returns a filter that matches cells whose family name matches the provided RE2 pattern. See https://github.com/google/re2/wiki/Syntax for the accepted syntax.

func InterleaveFilters

func InterleaveFilters(sub ...Filter) Filter

InterleaveFilters returns a filter that applies a set of filters in parallel and interleaves the results.

func LatestNFilter

func LatestNFilter(n int) Filter

LatestNFilter returns a filter that matches the most recent N cells in each column.

func RowKeyFilter

func RowKeyFilter(pattern string) Filter

RowKeyFilter returns a filter that matches cells from rows whose key matches the provided RE2 pattern. See https://github.com/google/re2/wiki/Syntax for the accepted syntax.

func StripValueFilter

func StripValueFilter() Filter

StripValueFilter returns a filter that replaces each value with the empty string.

func TimestampRangeFilter

func TimestampRangeFilter(startTime time.Time, endTime time.Time) Filter

TimestampRangeFilter returns a filter that matches any rows whose timestamp is within the given time bounds. A zero time means no bound.

func ValueFilter

func ValueFilter(pattern string) Filter

ValueFilter returns a filter that matches cells whose value matches the provided RE2 pattern. See https://github.com/google/re2/wiki/Syntax for the accepted syntax.

type GCPolicy

type GCPolicy interface {
    String() string
    // contains filtered or unexported methods
}

A GCPolicy represents a rule that determines which cells are eligible for garbage collection.

func IntersectionPolicy

func IntersectionPolicy(sub ...GCPolicy) GCPolicy

IntersectionPolicy returns a GC policy that only applies when all its sub-policies apply.

func MaxAgePolicy

func MaxAgePolicy(d time.Duration) GCPolicy

MaxAgePolicy returns a GC policy that applies to all cells older than the given age.

func MaxVersionsPolicy

func MaxVersionsPolicy(n int) GCPolicy

MaxVersionsPolicy returns a GC policy that applies to all versions of a cell except for the most recent n.

func UnionPolicy

func UnionPolicy(sub ...GCPolicy) GCPolicy

UnionPolicy returns a GC policy that applies when any of its sub-policies apply.

type Mutation

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

Mutation represents a set of changes for a single row of a table.

func NewCondMutation

func NewCondMutation(cond Filter, mtrue, mfalse *Mutation) *Mutation

NewCondMutation returns a conditional mutation. The given row filter determines which mutation is applied: If the filter matches any cell in the row, mtrue is applied; otherwise, mfalse is applied. Either given mutation may be nil.

func NewMutation

func NewMutation() *Mutation

NewMutation returns a new mutation.

func (*Mutation) DeleteCellsInColumn

func (m *Mutation) DeleteCellsInColumn(family, column string)

DeleteCellsInColumn will delete all the cells whose columns are family:column.

func (*Mutation) DeleteCellsInFamily

func (m *Mutation) DeleteCellsInFamily(family string)

DeleteCellsInFamily will delete all the cells whose columns are family:*.

func (*Mutation) DeleteRow

func (m *Mutation) DeleteRow()

DeleteRow deletes the entire row.

func (*Mutation) DeleteTimestampRange

func (m *Mutation) DeleteTimestampRange(family, column string, start, end Timestamp)

DeleteTimestampRange deletes all cells whose columns are family:column and whose timestamps are in the half-open interval [start, end). If end is zero, it will be interpreted as infinity.

func (*Mutation) Set

func (m *Mutation) Set(family, column string, ts Timestamp, value []byte)

Set sets a value in a specified column, with the given timestamp. The timestamp will be truncated to millisecond resolution. A timestamp of ServerTime means to use the server timestamp.

type ReadItem

type ReadItem struct {
    Row, Column string
    Timestamp   Timestamp
    Value       []byte
}

A ReadItem is returned by Read. A ReadItem contains data from a specific row and column.

type ReadModifyWrite

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

ReadModifyWrite represents a set of operations on a single row of a table. It is like Mutation but for non-idempotent changes. When applied, these operations operate on the latest values of the row's cells, and result in a new value being written to the relevant cell with a timestamp that is max(existing timestamp, current server time).

The application of a ReadModifyWrite is atomic; concurrent ReadModifyWrites will be executed serially by the server.

func NewReadModifyWrite

func NewReadModifyWrite() *ReadModifyWrite

NewReadModifyWrite returns a new ReadModifyWrite.

func (*ReadModifyWrite) AppendValue

func (m *ReadModifyWrite) AppendValue(family, column string, v []byte)

AppendValue appends a value to a specific cell's value. If the cell is unset, it will be treated as an empty value.

func (*ReadModifyWrite) Increment

func (m *ReadModifyWrite) Increment(family, column string, delta int64)

Increment interprets the value in a specific cell as a 64-bit big-endian signed integer, and adds a value to it. If the cell is unset, it will be treated as zero. If the cell is set and is not an 8-byte value, the entire ApplyReadModifyWrite operation will fail.

type ReadOption

type ReadOption interface {
    // contains filtered or unexported methods
}

A ReadOption is an optional argument to ReadRows.

func LimitRows

func LimitRows(limit int64) ReadOption

LimitRows returns a ReadOption that will limit the number of rows to be read.

func RowFilter

func RowFilter(f Filter) ReadOption

RowFilter returns a ReadOption that applies f to the contents of read rows.

type Row

type Row map[string][]ReadItem

A Row is returned by ReadRows. The map is keyed by column family (the prefix of the column name before the colon). The values are the returned ReadItems for that column family in the order returned by Read.

func (Row) Key

func (r Row) Key() string

Key returns the row's key, or "" if the row is empty.

type RowList

type RowList []string

RowList is a sequence of row keys.

type RowRange

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

A RowRange is a half-open interval [Start, Limit) encompassing all the rows with keys at least as large as Start, and less than Limit. (Bigtable string comparison is the same as Go's.) A RowRange can be unbounded, encompassing all keys at least as large as Start.

func InfiniteRange

func InfiniteRange(start string) RowRange

InfiniteRange returns the RowRange consisting of all keys at least as large as start.

func NewRange

func NewRange(begin, end string) RowRange

NewRange returns the new RowRange [begin, end).

func PrefixRange

func PrefixRange(prefix string) RowRange

PrefixRange returns a RowRange consisting of all keys starting with the prefix.

func SingleRow

func SingleRow(row string) RowRange

SingleRow returns a RowRange for reading a single row.

func (RowRange) Contains

func (r RowRange) Contains(row string) bool

Contains says whether the RowRange contains the key.

func (RowRange) String

func (r RowRange) String() string

String provides a printable description of a RowRange.

func (RowRange) Unbounded

func (r RowRange) Unbounded() bool

Unbounded tests whether a RowRange is unbounded.

type RowSet

type RowSet interface {
    // contains filtered or unexported methods
}

RowSet is a set of rows to be read. It is satisfied by RowList and RowRange.

type Table

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

A Table refers to a table.

A Table is safe to use concurrently.

func (*Table) Apply

func (t *Table) Apply(ctx context.Context, row string, m *Mutation, opts ...ApplyOption) error

Apply applies a Mutation to a specific row.

func (*Table) ApplyBulk

func (t *Table) ApplyBulk(ctx context.Context, rowKeys []string, muts []*Mutation, opts ...ApplyOption) ([]error, error)

ApplyBulk applies multiple Mutations. Each mutation is individually applied atomically, but the set of mutations may be applied in any order.

Two types of failures may occur. If the entire process fails, (nil, err) will be returned. If specific mutations fail to apply, ([]err, nil) will be returned, and the errors will correspond to the relevant rowKeys/muts arguments.

Conditional mutations cannot be applied in bulk and providing one will result in an error.

func (*Table) ApplyReadModifyWrite

func (t *Table) ApplyReadModifyWrite(ctx context.Context, row string, m *ReadModifyWrite) (Row, error)

ApplyReadModifyWrite applies a ReadModifyWrite to a specific row. It returns the newly written cells.

func (*Table) ReadRow

func (t *Table) ReadRow(ctx context.Context, row string, opts ...ReadOption) (Row, error)

ReadRow is a convenience implementation of a single-row reader. A missing row will return a zero-length map and a nil error.

func (*Table) ReadRows

func (t *Table) ReadRows(ctx context.Context, arg RowSet, f func(Row) bool, opts ...ReadOption) error

ReadRows reads rows from a table. f is called for each row. If f returns false, the stream is shut down and ReadRows returns. f owns its argument, and f is called serially in order by row key.

By default, the yielded rows will contain all values in all cells. Use RowFilter to limit the cells returned.

type TableInfo

type TableInfo struct {
    Families []string
}

TableInfo represents information about a table.

type Timestamp

type Timestamp int64

Timestamp is in units of microseconds since 1 January 1970.

const ServerTime Timestamp = -1

ServerTime is a specific Timestamp that may be passed to (*Mutation).Set. It indicates that the server's timestamp should be used.

func Now

func Now() Timestamp

Now returns the Timestamp representation of the current time on the client.

func Time

func Time(t time.Time) Timestamp

Time converts a time.Time into a Timestamp.

func (Timestamp) Time

func (ts Timestamp) Time() time.Time

Time converts a Timestamp into a time.Time.

Send feedback about...

Cloud Bigtable Documentation