Google Cloud Bigtable C++ Client  1.1.0
A C++ Client Library for Google Cloud Bigtable
Classes | Public Member Functions | Friends | List of all members
google::cloud::bigtable::v1::Table Class Reference

The main interface to interact with data in a Cloud Bigtable table. More...

#include <google/cloud/bigtable/table.h>

Public Member Functions

 Table (std::shared_ptr< DataClient > client, std::string const &table_id)
 Constructor with default policies. More...
 
 Table (std::shared_ptr< DataClient > client, std::string app_profile_id, std::string const &table_id)
 Constructor with default policies. More...
 
template<typename... Policies, typename std::enable_if< valid_policies< Policies... >::value, int >::type = 0>
 Table (std::shared_ptr< DataClient > client, std::string const &table_id, Policies &&... policies)
 Constructor with explicit policies. More...
 
template<typename... Policies, typename std::enable_if< valid_policies< Policies... >::value, int >::type = 0>
 Table (std::shared_ptr< DataClient > client, std::string app_profile_id, std::string const &table_id, Policies &&... policies)
 Constructor with explicit policies. More...
 
std::string const & table_name () const
 
std::string const & app_profile_id () const
 
std::string const & project_id () const
 
std::string const & instance_id () const
 
std::string const & table_id () const
 
Status Apply (SingleRowMutation mut)
 Attempts to apply the mutation to a row. More...
 
future< Status > AsyncApply (SingleRowMutation mut, CompletionQueue &cq)
 Makes asynchronous attempts to apply the mutation to a row. More...
 
std::vector< FailedMutationBulkApply (BulkMutation mut)
 Attempts to apply mutations to multiple rows. More...
 
future< std::vector< FailedMutation > > AsyncBulkApply (BulkMutation mut, CompletionQueue &cq)
 Makes asynchronous attempts to apply mutations to multiple rows. More...
 
RowReader ReadRows (RowSet row_set, Filter filter)
 Reads a set of rows from the table. More...
 
RowReader ReadRows (RowSet row_set, std::int64_t rows_limit, Filter filter)
 Reads a limited set of rows from the table. More...
 
StatusOr< std::pair< bool, Row > > ReadRow (std::string row_key, Filter filter)
 Read and return a single row from the table. More...
 
StatusOr< MutationBranchCheckAndMutateRow (std::string row_key, Filter filter, std::vector< Mutation > true_mutations, std::vector< Mutation > false_mutations)
 Atomic test-and-set for a row using filter expressions. More...
 
future< StatusOr< MutationBranch > > AsyncCheckAndMutateRow (std::string row_key, Filter filter, std::vector< Mutation > true_mutations, std::vector< Mutation > false_mutations, CompletionQueue &cq)
 Make an asynchronous request to conditionally mutate a row. More...
 
StatusOr< std::vector< bigtable::RowKeySample > > SampleRows ()
 Sample of the row keys in the table, including approximate data sizes. More...
 
template<typename... Args>
StatusOr< RowReadModifyWriteRow (std::string row_key, bigtable::ReadModifyWriteRule rule, Args &&... rules)
 Atomically read and modify the row in the server, returning the resulting row. More...
 
template<typename... Args>
future< StatusOr< Row > > AsyncReadModifyWriteRow (std::string row_key, CompletionQueue &cq, bigtable::ReadModifyWriteRule rule, Args &&... rules)
 Make an asynchronous request to atomically read and modify a row. More...
 
template<typename RowFunctor , typename FinishFunctor >
void AsyncReadRows (CompletionQueue &cq, RowFunctor on_row, FinishFunctor on_finish, RowSet row_set, Filter filter)
 Asynchronously reads a set of rows from the table. More...
 
template<typename RowFunctor , typename FinishFunctor >
void AsyncReadRows (CompletionQueue &cq, RowFunctor on_row, FinishFunctor on_finish, RowSet row_set, std::int64_t rows_limit, Filter filter)
 Asynchronously reads a set of rows from the table. More...
 
future< StatusOr< std::pair< bool, Row > > > AsyncReadRow (CompletionQueue &cq, std::string row_key, Filter filter)
 Asynchronously read and return a single row from the table. More...
 

Friends

class MutationBatcher
 

Detailed Description

The main interface to interact with data in a Cloud Bigtable table.

This class provides member functions to:

The class deals with the most common transient failures, and retries the underlying RPC calls subject to the policies configured by the application. These policies are documented in Table::Table().

Thread-safety
Instances of this class created via copy-construction or copy-assignment share the underlying pool of connections. Access to these copies via multiple threads is guaranteed to work. Two threads operating on the same instance of this class is not guaranteed to work.
Cost
Creating a new object of type Table is comparable to creating a few objects of type std::string or a few objects of type std::shared_ptr<int>. The class represents a shallow handle to a remote object.
Error Handling
This class uses StatusOr<T> to report errors. When an operation fails to perform its work the returned StatusOr<T> contains the error details. If the ok() member function in the StatusOr<T> returns true then it contains the expected result. Operations that do not return a value simply return a google::cloud::Status indicating success or the details of the error Please consult the StatusOr<T> documentation for more details.
cbt::Table = ...;
google::cloud::StatusOr<std::pair<bool, cbt::Row>> row = table.ReadRow(...);
if (!row) {
std::cerr << "Error reading row\n";
return;
}
// Use "row" as a smart pointer here, e.g.:
if (!row->first) {
std::cout << "Contacting the server was successful, but the row does not"
<< " exist\n";
return;
}
std::cout << "The row has " << row->second.cells().size() << " cells\n";

In addition, the main page contains examples using StatusOr<T> to handle errors.

Retry, Backoff, and Idempotency Policies
The library automatically retries requests that fail with transient errors, and uses truncated exponential backoff to backoff between retries. The default policies are to continue retrying for up to 10 minutes. On each transient failure the backoff period is doubled, starting with an initial backoff of 100 milliseconds. The backoff period growth is truncated at 60 seconds. The default idempotency policy is to only retry idempotent operations. Note that most operations that change state are not idempotent.

The application can override these policies when constructing objects of this class. The documentation for the constructors show examples of this in action.

See also
https://cloud.google.com/bigtable/ for an overview of Cloud Bigtable.
https://cloud.google.com/bigtable/docs/overview for an overview of the Cloud Bigtable data model.
https://cloud.google.com/bigtable/docs/instances-clusters-nodes for an introduction of the main APIs into Cloud Bigtable.
https://cloud.google.com/bigtable/docs/reference/service-apis-overview for an overview of the underlying Cloud Bigtable API.
google::cloud::v0::StatusOr for a description of the error reporting class used by this library.
LimitedTimeRetryPolicy and LimitedErrorCountRetryPolicy for alternative retry policies.
ExponentialBackoffPolicy to configure different parameters for the exponential backoff policy.
SafeIdempotentMutationPolicy and AlwaysRetryMutationPolicy for alternative idempotency policies.

Definition at line 165 of file table.h.

Constructor & Destructor Documentation

◆ Table() [1/4]

google::cloud::bigtable::v1::Table::Table ( std::shared_ptr< DataClient client,
std::string const &  table_id 
)
inline

Constructor with default policies.

Parameters
clienthow to communicate with Cloud Bigtable, including credentials, the project id, and the instance id.
table_idthe table id within the instance defined by client. The full table name is `client->instance_name() + '/tables/' + table_id`.

Definition at line 190 of file table.h.

◆ Table() [2/4]

google::cloud::bigtable::v1::Table::Table ( std::shared_ptr< DataClient client,
std::string  app_profile_id,
std::string const &  table_id 
)
inline

Constructor with default policies.

Parameters
clienthow to communicate with Cloud Bigtable, including credentials, the project id, and the instance id.
app_profile_idthe app_profile_id needed for using the replication API.
table_idthe table id within the instance defined by client. The full table name is `client->instance_name() + '/tables/' + table_id`.
Example
Example Using AppProfile
cbt::Table read(data_client, profile_id, table_id);
google::cloud::StatusOr<std::pair<bool, cbt::Row>> result =
read.ReadRow("key-0", cbt::Filter::ColumnRangeClosed("fam", "c0", "c0"));
if (!result) {
throw std::runtime_error(result.status().message());
}
if (!result->first) {
std::cout << "Cannot find row 'key-0' in the table: " << table_id << "\n";
return 1;
}
cbt::Cell const& cell = result->second.cells().front();
std::cout << cell.family_name() << ":" << cell.column_qualifier() << " @ "
<< cell.timestamp().count() << "us\n"
<< '"' << cell.value() << '"' << "\n";

Definition at line 209 of file table.h.

◆ Table() [3/4]

template<typename... Policies, typename std::enable_if< valid_policies< Policies... >::value, int >::type = 0>
google::cloud::bigtable::v1::Table::Table ( std::shared_ptr< DataClient client,
std::string const &  table_id,
Policies &&...  policies 
)
inline

Constructor with explicit policies.

The policies are passed by value, because this makes it easy for applications to create them.

Example
using namespace std::chrono_literals; // assuming C++14.
auto client = bigtable::CreateDefaultClient(...); // details ommitted
bigtable::Table table(client, "my-table",
// Allow up to 20 minutes to retry operations
bigtable::LimitedTimeRetryPolicy(20min),
// Start with 50 milliseconds backoff, grow
// exponentially to 5 minutes.
bigtable::ExponentialBackoffPolicy(50ms, 5min),
// Only retry idempotent mutations.
bigtable::SafeIdempotentMutationPolicy());
Parameters
clienthow to communicate with Cloud Bigtable, including credentials, the project id, and the instance id.
table_idthe table id within the instance defined by client. The full table name is client->instance_name() + "/tables/" + table_id.
policiesthe set of policy overrides for this object.
Template Parameters
Policiesthe types of the policies to override, the types must derive from one of the following types:
See also
SafeIdempotentMutationPolicy, AlwaysRetryMutationPolicy, ExponentialBackoffPolicy, LimitedErrorCountRetryPolicy, LimitedTimeRetryPolicy.
Idempotency Policy Example
[](std::string project_id, std::string instance_id, std::string table_id,
std::string row_key) {
cbt::Table table(cbt::CreateDefaultDataClient(project_id, instance_id,
cbt::ClientOptions()),
table_id, cbt::AlwaysRetryMutationPolicy());
// Normally this is not retried on transient failures, because the operation
// is not idempotent (each retry would set a different timestamp), in this
// case it would, because the table is setup to always retry.
cbt::SingleRowMutation mutation(
row_key, cbt::SetCell("fam", "some-column", "some-value"));
google::cloud::Status status = table.Apply(std::move(mutation));
if (!status.ok()) {
throw std::runtime_error(status.message());
}
}
Modified Retry Policy Example
[](std::string project_id, std::string instance_id, std::string table_id,
std::string row_key) {
cbt::Table table(cbt::CreateDefaultDataClient(project_id, instance_id,
cbt::ClientOptions()),
table_id, cbt::LimitedErrorCountRetryPolicy(7));
cbt::SingleRowMutation mutation(
row_key, cbt::SetCell("fam", "some-column",
std::chrono ::milliseconds(0), "some-value"));
google::cloud::Status status = table.Apply(std::move(mutation));
if (!status.ok()) {
throw std::runtime_error(status.message());
}
}

Definition at line 279 of file table.h.

◆ Table() [4/4]

template<typename... Policies, typename std::enable_if< valid_policies< Policies... >::value, int >::type = 0>
google::cloud::bigtable::v1::Table::Table ( std::shared_ptr< DataClient client,
std::string  app_profile_id,
std::string const &  table_id,
Policies &&...  policies 
)
inline

Constructor with explicit policies.

The policies are passed by value, because this makes it easy for applications to create them.

Example
using namespace std::chrono_literals; // assuming C++14.
auto client = bigtable::CreateDefaultClient(...); // details ommitted
bigtable::Table table(client, "app_id", "my-table",
// Allow up to 20 minutes to retry operations
bigtable::LimitedTimeRetryPolicy(20min),
// Start with 50 milliseconds backoff, grow
// exponentially to 5 minutes.
bigtable::ExponentialBackoffPolicy(50ms, 5min),
// Only retry idempotent mutations.
bigtable::SafeIdempotentMutationPolicy());
Parameters
clienthow to communicate with Cloud Bigtable, including credentials, the project id, and the instance id.
app_profile_idthe app_profile_id needed for using the replication API.
table_idthe table id within the instance defined by client. The full table name is client->instance_name() + "/tables/" + table_id.
policiesthe set of policy overrides for this object.
Template Parameters
Policiesthe types of the policies to override, the types must derive from one of the following types:
See also
SafeIdempotentMutationPolicy, AlwaysRetryMutationPolicy, ExponentialBackoffPolicy, LimitedErrorCountRetryPolicy, LimitedTimeRetryPolicy.
Idempotency Policy Example
[](std::string project_id, std::string instance_id, std::string table_id,
std::string row_key) {
cbt::Table table(cbt::CreateDefaultDataClient(project_id, instance_id,
cbt::ClientOptions()),
table_id, cbt::AlwaysRetryMutationPolicy());
// Normally this is not retried on transient failures, because the operation
// is not idempotent (each retry would set a different timestamp), in this
// case it would, because the table is setup to always retry.
cbt::SingleRowMutation mutation(
row_key, cbt::SetCell("fam", "some-column", "some-value"));
google::cloud::Status status = table.Apply(std::move(mutation));
if (!status.ok()) {
throw std::runtime_error(status.message());
}
}
Modified Retry Policy Example
[](std::string project_id, std::string instance_id, std::string table_id,
std::string row_key) {
cbt::Table table(cbt::CreateDefaultDataClient(project_id, instance_id,
cbt::ClientOptions()),
table_id, cbt::LimitedErrorCountRetryPolicy(7));
cbt::SingleRowMutation mutation(
row_key, cbt::SetCell("fam", "some-column",
std::chrono ::milliseconds(0), "some-value"));
google::cloud::Status status = table.Apply(std::move(mutation));
if (!status.ok()) {
throw std::runtime_error(status.message());
}
}

Definition at line 342 of file table.h.

Member Function Documentation

◆ app_profile_id()

std::string const& google::cloud::bigtable::v1::Table::app_profile_id ( ) const
inline

Definition at line 349 of file table.h.

◆ Apply()

Status google::cloud::bigtable::v1::Table::Apply ( SingleRowMutation  mut)

Attempts to apply the mutation to a row.

Parameters
mutthe mutation. Note that this function takes ownership (and then discards) the data in the mutation. In general, a SingleRowMutation can be used to modify and/or delete multiple cells, across different columns and column families.
Returns
status of the operation.
Idempotency
This operation is idempotent if the provided mutations are idempotent. Note that google::cloud::bigtable::SetCell() without an explicit timestamp is not an idempotent operation.
Example
[](cbt::Table table) {
auto timestamp = std::chrono::duration_cast<std::chrono::milliseconds>(
std::chrono::system_clock::now().time_since_epoch());
cbt::SingleRowMutation mutation("test-key-for-apply");
mutation.emplace_back(cbt::SetCell("fam", "some-column", "some-value"));
mutation.emplace_back(
cbt::SetCell("fam", "another-column", "another-value"));
mutation.emplace_back(cbt::SetCell("fam", "even-more-columns", timestamp,
"with-explicit-timestamp"));
google::cloud::Status status = table.Apply(std::move(mutation));
if (!status.ok()) {
throw std::runtime_error(status.message());
}
}

Definition at line 68 of file table.cc.

◆ AsyncApply()

future< Status > google::cloud::bigtable::v1::Table::AsyncApply ( SingleRowMutation  mut,
CompletionQueue cq 
)

Makes asynchronous attempts to apply the mutation to a row.

Warning
This is an early version of the asynchronous APIs for Cloud Bigtable. These APIs might be changed in backward-incompatible ways. It is not subject to any SLA or deprecation policy.
Parameters
mutthe mutation. Note that this function takes ownership (and then discards) the data in the mutation. In general, a SingleRowMutation can be used to modify and/or delete multiple cells, across different columns and column families.
cqthe completion queue that will execute the asynchronous calls, the application must ensure that one or more threads are blocked on cq.Run().
Idempotency
This operation is idempotent if the provided mutations are idempotent. Note that google::cloud::bigtable::SetCell() without an explicit timestamp is not an idempotent operation.
Example
using google::cloud::future;
using google::cloud::StatusOr;
[](cbt::Table table, cbt::CompletionQueue cq, std::string row_key) {
auto timestamp = std::chrono::duration_cast<std::chrono::milliseconds>(
std::chrono::system_clock::now().time_since_epoch());
cbt::SingleRowMutation mutation(row_key);
mutation.emplace_back(cbt::SetCell("fam", "some-column", "some-value"));
mutation.emplace_back(
cbt::SetCell("fam", "another-column", "another-value"));
mutation.emplace_back(cbt::SetCell("fam", "even-more-columns", timestamp,
"with-explicit-timestamp"));
future<google::cloud::Status> status_future =
table.AsyncApply(std::move(mutation), cq);
auto status = status_future.get();
if (!status.ok()) {
throw std::runtime_error(status.message());
}
std::cout << "Successfully applied mutation\n";
}

Definition at line 112 of file table.cc.

◆ AsyncBulkApply()

future< std::vector< FailedMutation > > google::cloud::bigtable::v1::Table::AsyncBulkApply ( BulkMutation  mut,
CompletionQueue cq 
)

Makes asynchronous attempts to apply mutations to multiple rows.

Warning
This is an early version of the asynchronous APIs for Cloud Bigtable. These APIs might be changed in backward-incompatible ways. It is not subject to any SLA or deprecation policy.
Parameters
mutthe mutations, note that this function takes ownership (and then discards) the data in the mutation. In general, a BulkMutation can modify multiple rows, and the modifications for each row can change (or create) multiple cells, across different columns and column families.
cqthe completion queue that will execute the asynchronous calls, the application must ensure that one or more threads are blocked on cq.Run().
Idempotency
This operation is idempotent if the provided mutations are idempotent. Note that google::cloud::bigtable::SetCell() without an explicit timestamp is not an idempotent operation.
Example
using google::cloud::future;
[](cbt::Table table, cbt::CompletionQueue cq) {
// Write several rows in a single operation, each row has some trivial data.
cbt::BulkMutation bulk;
for (int i = 0; i != 5000; ++i) {
// Note: This example uses sequential numeric IDs for simplicity, but
// this can result in poor performance in a production application.
// Since rows are stored in sorted order by key, sequential keys can
// result in poor distribution of operations across nodes.
//
// For more information about how to design a Bigtable schema for the
// best performance, see the documentation:
//
// https://cloud.google.com/bigtable/docs/schema-design
char buf[32];
snprintf(buf, sizeof(buf), "key-%06d", i);
cbt::SingleRowMutation mutation(buf);
mutation.emplace_back(
cbt::SetCell("fam", "col0", "value0-" + std::to_string(i)));
mutation.emplace_back(
cbt::SetCell("fam", "col1", "value2-" + std::to_string(i)));
mutation.emplace_back(
cbt::SetCell("fam", "col2", "value3-" + std::to_string(i)));
mutation.emplace_back(
cbt::SetCell("fam", "col3", "value4-" + std::to_string(i)));
bulk.emplace_back(std::move(mutation));
}
table.AsyncBulkApply(std::move(bulk), cq)
.then([](future<std::vector<cbt::FailedMutation>> ft) {
auto failures = ft.get();
if (failures.empty()) {
std::cout << "All the mutations were successful\n";
return;
}
std::cerr << "The following mutations failed:\n";
for (auto const& f : failures) {
std::cerr << "index[" << f.original_index() << "]=" << f.status()
<< "\n";
}
throw std::runtime_error(failures.front().status().message());
})
.get(); // block to simplify the example
}

Definition at line 172 of file table.cc.

◆ AsyncCheckAndMutateRow()

future< StatusOr< MutationBranch > > google::cloud::bigtable::v1::Table::AsyncCheckAndMutateRow ( std::string  row_key,
Filter  filter,
std::vector< Mutation true_mutations,
std::vector< Mutation false_mutations,
CompletionQueue cq 
)

Make an asynchronous request to conditionally mutate a row.

Warning
This is an early version of the asynchronous APIs for Cloud Bigtable. These APIs might be changed in backward-incompatible ways. It is not subject to any SLA or deprecation policy.
Parameters
row_keythe row key on which the conditional mutation will be performed
filterthe condition, depending on which the mutation will be performed
true_mutationsthe mutations which will be performed if filter is true
false_mutationsthe mutations which will be performed if filter is false
cqthe completion queue that will execute the asynchronous calls, the application must ensure that one or more threads are blocked on cq.Run().
Idempotency
This operation is always treated as non-idempotent.
Example
using google::cloud::future;
using google::cloud::StatusOr;
[](cbt::Table table, cbt::CompletionQueue cq, std::string row_key) {
// Check if the latest value of the flip-flop column is "on".
cbt::Filter predicate = cbt::Filter::Chain(
cbt::Filter::ColumnRangeClosed("fam", "flip-flop", "flip-flop"),
cbt::Filter::Latest(1), cbt::Filter::ValueRegex("on"));
future<StatusOr<cbt::MutationBranch>> branch_future =
table.AsyncCheckAndMutateRow(row_key, std::move(predicate),
{cbt::SetCell("fam", "flip-flop", "off"),
cbt::SetCell("fam", "flop-flip", "on")},
{cbt::SetCell("fam", "flip-flop", "on"),
cbt::SetCell("fam", "flop-flip", "off")},
cq);
branch_future
.then([](future<StatusOr<cbt::MutationBranch>> f) {
auto response = f.get();
if (!response) {
throw std::runtime_error(response.status().message());
}
if (*response == cbt::MutationBranch::kPredicateMatched) {
std::cout << "The predicate was matched\n";
} else {
std::cout << "The predicate was not matched\n";
}
})
.get(); // block to simplify the example.
}

Definition at line 250 of file table.cc.

◆ AsyncReadModifyWriteRow()

template<typename... Args>
future<StatusOr<Row> > google::cloud::bigtable::v1::Table::AsyncReadModifyWriteRow ( std::string  row_key,
CompletionQueue cq,
bigtable::ReadModifyWriteRule  rule,
Args &&...  rules 
)
inline

Make an asynchronous request to atomically read and modify a row.

Warning
This is an early version of the asynchronous APIs for Cloud Bigtable. These APIs might be changed in backward-incompatible ways. It is not subject to any SLA or deprecation policy.
Parameters
row_keythe row key on which modification will be performed
cqthe completion queue that will execute the asynchronous calls, the application must ensure that one or more threads are blocked on cq.Run().
ruleto modify the row. Two types of rules are applied here AppendValue which will read the existing value and append the text provided to the value. IncrementAmount which will read the existing uint64 big-endian-int and add the value provided. Both rules accept the family and column identifier to modify.
rulesis the zero or more ReadModifyWriteRules to apply on a row.
Returns
A future, that becomes satisfied when the operation completes, at that point the future has the contents of all modified cells.
Idempotency
This operation is always treated as non-idempotent.
Example
using google::cloud::future;
using google::cloud::StatusOr;
[](cbt::Table table, cbt::CompletionQueue cq, std::string row_key) {
future<StatusOr<cbt::Row>> row_future = table.AsyncReadModifyWriteRow(
row_key, cq,
cbt::ReadModifyWriteRule::AppendValue("fam", "list", ";element"));
row_future
.then([](future<StatusOr<cbt::Row>> f) {
auto row = f.get();
if (!row) {
throw std::runtime_error(row.status().message());
}
})
.get(); // block to simplify example.
}

Definition at line 640 of file table.h.

◆ AsyncReadRow()

future< StatusOr< std::pair< bool, Row > > > google::cloud::bigtable::v1::Table::AsyncReadRow ( CompletionQueue cq,
std::string  row_key,
Filter  filter 
)

Asynchronously read and return a single row from the table.

Warning
This is an early version of the asynchronous APIs for Cloud Bigtable. These APIs might be changed in backward-incompatible ways. It is not subject to any SLA or deprecation policy.
Parameters
cqthe completion queue that will execute the asynchronous calls, the application must ensure that one or more threads are blocked on cq.Run().
row_keythe row to read.
filtera filter expression, can be used to select a subset of the column families and columns in the row.
Returns
a future satisfied when the operation completes, failes permanently or keeps failing transiently, but the retry policy has been exhausted. The future will return a tuple. The first element is a boolean, with value false if the row does not exist. If the first element is true the second element has the contents of the Row. Note that the contents may be empty if the filter expression removes all column families and columns.
Idempotency
This is a read-only operation and therefore it is always idempotent.
Example
using google::cloud::future;
using google::cloud::StatusOr;
[](cbt::CompletionQueue cq, google::cloud::bigtable::Table table,
std::string row_key) {
// Filter the results, only include the latest value on each cell.
cbt::Filter filter = cbt::Filter::Latest(1);
table.AsyncReadRow(cq, row_key, std::move(filter))
.then(
[row_key](future<StatusOr<std::pair<bool, cbt::Row>>> row_future) {
// Read a row, this returns a tuple (bool, row)
auto tuple = row_future.get();
if (!tuple) {
throw std::runtime_error(tuple.status().message());
}
if (!tuple->first) {
std::cout << "Row " << row_key << " not found\n";
return;
}
std::cout << "key: " << tuple->second.row_key() << "\n";
for (auto& cell : tuple->second.cells()) {
std::cout << " " << cell.family_name() << ":"
<< cell.column_qualifier() << " = <";
if (cell.column_qualifier() == "counter") {
// This example uses "counter" to store 64-bit numbers in
// big-endian format, extract them as follows:
std::cout
<< cell.decode_big_endian_integer<std::int64_t>().value();
} else {
std::cout << cell.value();
}
std::cout << ">\n";
}
})
.get(); // block to simplify the example
}

Definition at line 383 of file table.cc.

◆ AsyncReadRows() [1/2]

template<typename RowFunctor , typename FinishFunctor >
void google::cloud::bigtable::v1::Table::AsyncReadRows ( CompletionQueue cq,
RowFunctor  on_row,
FinishFunctor  on_finish,
RowSet  row_set,
Filter  filter 
)
inline

Asynchronously reads a set of rows from the table.

Warning
This is an early version of the asynchronous APIs for Cloud Bigtable. These APIs might be changed in backward-incompatible ways. It is not subject to any SLA or deprecation policy.
Parameters
cqthe completion queue that will execute the asynchronous calls, the application must ensure that one or more threads are blocked on cq.Run().
on_rowthe callback to be invoked on each successfully read row; it should be invocable with Row and return a future<bool>; the returned future<bool> should be satisfied with true when the user is ready to receive the next callback and with false when the user doesn't want any more rows; if on_row throws, the results are undefined
on_finishthe callback to be invoked when the stream is closed; it should be invocable with Status and not return anything; it will always be called as the last callback; if on_finish throws, the results are undefined
row_setthe rows to read from.
filteris applied on the server-side to data in the rows.
Template Parameters
RowFunctorthe type of the on_row callback.
FinishFunctorthe type of the on_finish callback.
Example
using google::cloud::make_ready_future;
using google::cloud::promise;
using google::cloud::Status;
[](cbt::CompletionQueue cq, cbt::Table table) {
// Create the range of rows to read.
auto range = cbt::RowRange::Range("key-000010", "key-000020");
// Filter the results, only include values from the "col0" column in the
// "fam" column family, and only get the latest value.
auto filter = cbt::Filter::Chain(
cbt::Filter::ColumnRangeClosed("fam", "col0", "col0"),
cbt::Filter::Latest(1));
promise<Status> stream_status_promise;
// Read and print the rows.
table.AsyncReadRows(cq,
[](cbt::Row row) {
if (row.cells().size() != 1) {
std::cout << "Unexpected number of cells in "
<< row.row_key() << "\n";
return make_ready_future(false);
}
auto const& cell = row.cells().at(0);
std::cout << cell.row_key() << " = [" << cell.value()
<< "]\n";
return make_ready_future(true);
},
[&stream_status_promise](Status stream_status) {
stream_status_promise.set_value(stream_status);
},
range, filter);
Status stream_status = stream_status_promise.get_future().get();
if (!stream_status.ok()) {
throw std::runtime_error(stream_status.message());
}
}

Definition at line 680 of file table.h.

◆ AsyncReadRows() [2/2]

template<typename RowFunctor , typename FinishFunctor >
void google::cloud::bigtable::v1::Table::AsyncReadRows ( CompletionQueue cq,
RowFunctor  on_row,
FinishFunctor  on_finish,
RowSet  row_set,
std::int64_t  rows_limit,
Filter  filter 
)
inline

Asynchronously reads a set of rows from the table.

Warning
This is an early version of the asynchronous APIs for Cloud Bigtable. These APIs might be changed in backward-incompatible ways. It is not subject to any SLA or deprecation policy.
Parameters
cqthe completion queue that will execute the asynchronous calls, the application must ensure that one or more threads are blocked on cq.Run().
on_rowthe callback to be invoked on each successfully read row; it should be invocable with Row and return a future<bool>; the returned future<bool> should be satisfied with true when the user is ready to receive the next callback and with false when the user doesn't want any more rows; if on_row throws, the results are undefined
on_finishthe callback to be invoked when the stream is closed; it should be invocable with Status and not return anything; it will always be called as the last callback; if on_finish throws, the results are undefined
row_setthe rows to read from.
rows_limitthe maximum number of rows to read. Cannot be a negative number or zero. Use AsyncReadRows(CompletionQueue, RowSet, Filter) to read all matching rows.
filteris applied on the server-side to data in the rows.
Template Parameters
RowFunctorthe type of the on_row callback.
FinishFunctorthe type of the on_finish callback.
Example
using google::cloud::make_ready_future;
using google::cloud::promise;
using google::cloud::Status;
[](cbt::CompletionQueue cq, cbt::Table table) {
// Create the range of rows to read.
auto range = cbt::RowRange::Range("key-000010", "key-000020");
// Filter the results, only include values from the "col0" column in the
// "fam" column family, and only get the latest value.
auto filter = cbt::Filter::Chain(
cbt::Filter::ColumnRangeClosed("fam", "col0", "col0"),
cbt::Filter::Latest(1));
promise<Status> stream_status_promise;
// Read and print the rows.
table.AsyncReadRows(cq,
[](cbt::Row row) {
if (row.cells().size() != 1) {
std::cout << "Unexpected number of cells in "
<< row.row_key() << "\n";
return make_ready_future(false);
}
auto const& cell = row.cells().at(0);
std::cout << cell.row_key() << " = [" << cell.value()
<< "]\n";
return make_ready_future(true);
},
[&stream_status_promise](Status stream_status) {
stream_status_promise.set_value(stream_status);
},
range, filter);
Status stream_status = stream_status_promise.get_future().get();
if (!stream_status.ok()) {
throw std::runtime_error(stream_status.message());
}
}

Definition at line 724 of file table.h.

◆ BulkApply()

std::vector< FailedMutation > google::cloud::bigtable::v1::Table::BulkApply ( BulkMutation  mut)

Attempts to apply mutations to multiple rows.

Parameters
mutthe mutations, note that this function takes ownership (and then discards) the data in the mutation. In general, a BulkMutation can modify multiple rows, and the modifications for each row can change (or create) multiple cells, across different columns and column families.
Idempotency
This operation is idempotent if the provided mutations are idempotent. Note that google::cloud::bigtable::SetCell() without an explicit timestamp is not an idempotent operation.
Example
[](cbt::Table table) {
// Write several rows in a single operation, each row has some trivial data.
cbt::BulkMutation bulk;
for (int i = 0; i != 5000; ++i) {
// Note: This example uses sequential numeric IDs for simplicity, but
// this can result in poor performance in a production application.
// Since rows are stored in sorted order by key, sequential keys can
// result in poor distribution of operations across nodes.
//
// For more information about how to design a Bigtable schema for the
// best performance, see the documentation:
//
// https://cloud.google.com/bigtable/docs/schema-design
char buf[32];
snprintf(buf, sizeof(buf), "key-%06d", i);
cbt::SingleRowMutation mutation(buf);
mutation.emplace_back(
cbt::SetCell("fam", "col0", "value0-" + std::to_string(i)));
mutation.emplace_back(
cbt::SetCell("fam", "col1", "value1-" + std::to_string(i)));
bulk.emplace_back(std::move(mutation));
}
std::vector<cbt::FailedMutation> failures =
table.BulkApply(std::move(bulk));
if (failures.empty()) {
std::cout << "All mutations applied successfully\n";
return;
}
std::cerr << "The following mutations failed:\n";
for (auto const& f : failures) {
std::cerr << "index[" << f.original_index() << "]=" << f.status() << "\n";
}
throw std::runtime_error(failures.front().status().message());
}

Definition at line 145 of file table.cc.

◆ CheckAndMutateRow()

StatusOr< MutationBranch > google::cloud::bigtable::v1::Table::CheckAndMutateRow ( std::string  row_key,
Filter  filter,
std::vector< Mutation true_mutations,
std::vector< Mutation false_mutations 
)

Atomic test-and-set for a row using filter expressions.

Atomically check the value of a row using a filter expression. If the expression passes (meaning at least one element is returned by it), one set of mutations is applied. If the filter does not pass, a different set of mutations is applied. The changes are atomically applied in the server.

Parameters
row_keythe row to modify.
filterthe filter expression.
true_mutationsthe mutations for the "filter passed" case.
false_mutationsthe mutations for the "filter did not pass" case.
Returns
true if the filter passed.
Idempotency
This operation is always treated as non-idempotent.
Check for Value Example
using google::cloud::StatusOr;
[](cbt::Table table, std::string row_key) {
// Check if the latest value of the flip-flop column is "on".
cbt::Filter predicate = cbt::Filter::Chain(
cbt::Filter::ColumnRangeClosed("fam", "flip-flop", "flip-flop"),
cbt::Filter::Latest(1), cbt::Filter::ValueRegex("on"));
// If the predicate matches, change the latest value to "off", otherwise,
// change the latest value to "on". Modify the "flop-flip" column at the
// same time.
StatusOr<cbt::MutationBranch> branch =
table.CheckAndMutateRow(row_key, std::move(predicate),
{cbt::SetCell("fam", "flip-flop", "off"),
cbt::SetCell("fam", "flop-flip", "on")},
{cbt::SetCell("fam", "flip-flop", "on"),
cbt::SetCell("fam", "flop-flip", "off")});
if (!branch) {
throw std::runtime_error(branch.status().message());
}
if (*branch == cbt::MutationBranch::kPredicateMatched) {
std::cout << "The predicate was matched\n";
} else {
std::cout << "The predicate was not matched\n";
}
}
Check for Cell Presence Example
using google::cloud::StatusOr;
[](cbt::Table table, std::string row_key) {
// Check if the latest value of the "test-column" column is present,
// regardless of its value.
cbt::Filter predicate = cbt::Filter::Chain(
cbt::Filter::ColumnRangeClosed("fam", "test-column", "test-column"),
cbt::Filter::Latest(1));
// If the predicate matches, do nothing, otherwise set the
// "had-test-column" to "false":
StatusOr<cbt::MutationBranch> branch = table.CheckAndMutateRow(
row_key, std::move(predicate), {},
{cbt::SetCell("fam", "had-test-column", "false")});
if (!branch) {
throw std::runtime_error(branch.status().message());
}
if (*branch == cbt::MutationBranch::kPredicateMatched) {
std::cout << "The predicate was matched\n";
} else {
std::cout << "The predicate was not matched\n";
}
}

Definition at line 221 of file table.cc.

◆ instance_id()

std::string const& google::cloud::bigtable::v1::Table::instance_id ( ) const
inline

Definition at line 351 of file table.h.

◆ project_id()

std::string const& google::cloud::bigtable::v1::Table::project_id ( ) const
inline

Definition at line 350 of file table.h.

◆ ReadModifyWriteRow()

template<typename... Args>
StatusOr<Row> google::cloud::bigtable::v1::Table::ReadModifyWriteRow ( std::string  row_key,
bigtable::ReadModifyWriteRule  rule,
Args &&...  rules 
)
inline

Atomically read and modify the row in the server, returning the resulting row.

Template Parameters
Argsthis is zero or more ReadModifyWriteRules to apply on a row
Parameters
row_keythe row to read
ruleto modify the row. Two types of rules are applied here AppendValue which will read the existing value and append the text provided to the value. IncrementAmount which will read the existing uint64 big-endian-int and add the value provided. Both rules accept the family and column identifier to modify.
rulesis the zero or more ReadModifyWriteRules to apply on a row.
Returns
The new contents of all modified cells.
Idempotency
This operation is always treated as non-idempotent.
Example
using google::cloud::StatusOr;
[](cbt::Table table, std::string row_key) {
StatusOr<cbt::Row> row = table.ReadModifyWriteRow(
row_key, cbt::ReadModifyWriteRule::IncrementAmount("fam", "counter", 1),
cbt::ReadModifyWriteRule::AppendValue("fam", "list", ";element"));
if (!row) {
throw std::runtime_error(row.status().message());
}
std::cout << row->row_key() << "\n";
}

Definition at line 590 of file table.h.

◆ ReadRow()

StatusOr< std::pair< bool, Row > > google::cloud::bigtable::v1::Table::ReadRow ( std::string  row_key,
Filter  filter 
)

Read and return a single row from the table.

Parameters
row_keythe row to read.
filtera filter expression, can be used to select a subset of the column families and columns in the row.
Returns
a tuple, the first element is a boolean, with value false if the row does not exist. If the first element is true the second element has the contents of the Row. Note that the contents may be empty if the filter expression removes all column families and columns.
Idempotency
This is a read-only operation and therefore it is always idempotent.
Example
using google::cloud::StatusOr;
[](google::cloud::bigtable::Table table, std::string row_key) {
// Filter the results, only include the latest value on each cell.
cbt::Filter filter = cbt::Filter::Latest(1);
// Read a row, this returns a tuple (bool, row)
StatusOr<std::pair<bool, cbt::Row>> tuple =
table.ReadRow(row_key, std::move(filter));
if (!tuple) {
throw std::runtime_error(tuple.status().message());
}
if (!tuple->first) {
std::cout << "Row " << row_key << " not found\n";
return;
}
std::cout << "key: " << tuple->second.row_key() << "\n";
for (auto& cell : tuple->second.cells()) {
std::cout << " " << cell.family_name() << ":"
<< cell.column_qualifier() << " = <";
if (cell.column_qualifier() == "counter") {
// This example uses "counter" to store 64-bit numbers in big-endian
// format, extract them as follows:
std::cout << cell.decode_big_endian_integer<std::int64_t>().value();
} else {
std::cout << cell.value();
}
std::cout << ">\n";
}
}

Definition at line 199 of file table.cc.

◆ ReadRows() [1/2]

RowReader google::cloud::bigtable::v1::Table::ReadRows ( RowSet  row_set,
Filter  filter 
)

Reads a set of rows from the table.

Parameters
row_setthe rows to read from.
filteris applied on the server-side to data in the rows.
Idempotency
This is a read-only operation and therefore it is always idempotent.
Example
using google::cloud::StatusOr;
[](cbt::Table table) {
// Create the range of rows to read.
auto range = cbt::RowRange::Range("key-000010", "key-000020");
// Filter the results, only include values from the "col0" column in the
// "fam" column family, and only get the latest value.
cbt::Filter filter = cbt::Filter::Chain(
cbt::Filter::ColumnRangeClosed("fam", "col0", "col0"),
cbt::Filter::Latest(1));
// Read and print the rows.
for (StatusOr<cbt::Row> const& row : table.ReadRows(range, filter)) {
if (!row) {
throw std::runtime_error(row.status().message());
}
if (row->cells().size() != 1) {
std::ostringstream os;
os << "Unexpected number of cells in " << row->row_key();
throw std::runtime_error(os.str());
}
auto const& cell = row->cells().at(0);
std::cout << cell.row_key() << " = [" << cell.value() << "]\n";
}
}

Definition at line 181 of file table.cc.

◆ ReadRows() [2/2]

RowReader google::cloud::bigtable::v1::Table::ReadRows ( RowSet  row_set,
std::int64_t  rows_limit,
Filter  filter 
)

Reads a limited set of rows from the table.

Parameters
row_setthe rows to read from.
rows_limitthe maximum number of rows to read. Cannot be a negative number or zero. Use ReadRows(RowSet, Filter) to read all matching rows.
filteris applied on the server-side to data in the rows.
Idempotency
This is a read-only operation and therefore it is always idempotent.
Example
using google::cloud::StatusOr;
[](cbt::Table table) {
// Create the range of rows to read.
auto range = cbt::RowRange::Range("key-000010", "key-000020");
// Filter the results, only include values from the "col0" column in the
// "fam" column family, and only get the latest value.
cbt::Filter filter = cbt::Filter::Chain(
cbt::Filter::ColumnRangeClosed("fam", "col0", "col0"),
cbt::Filter::Latest(1));
// Read and print the first 5 rows in the range.
for (StatusOr<cbt::Row> const& row : table.ReadRows(range, 5, filter)) {
if (!row) {
throw std::runtime_error(row.status().message());
}
if (row->cells().size() != 1) {
std::ostringstream os;
os << "Unexpected number of cells in " << row->row_key();
throw std::runtime_error(os.str());
}
auto const& cell = row->cells().at(0);
std::cout << cell.row_key() << " = [" << cell.value() << "]\n";
}
}

Definition at line 190 of file table.cc.

◆ SampleRows()

StatusOr< std::vector< bigtable::RowKeySample > > google::cloud::bigtable::v1::Table::SampleRows ( )

Sample of the row keys in the table, including approximate data sizes.

Returns
Note that the sample may only include one element for small tables. In addition, the sample may include row keys that do not exist on the table, and may include the empty row key to indicate "end of table".
Idempotency
This operation is always treated as non-idempotent.
Examples
using google::cloud::StatusOr;
[](cbt::Table table) {
StatusOr<std::vector<cbt::RowKeySample>> samples = table.SampleRows();
if (!samples) {
throw std::runtime_error(samples.status().message());
}
for (auto const& sample : *samples) {
std::cout << "key=" << sample.row_key << " - " << sample.offset_bytes
<< "\n";
}
}

Definition at line 295 of file table.cc.

◆ table_id()

std::string const& google::cloud::bigtable::v1::Table::table_id ( ) const
inline

Definition at line 352 of file table.h.

◆ table_name()

std::string const& google::cloud::bigtable::v1::Table::table_name ( ) const
inline

Definition at line 348 of file table.h.

Friends And Related Function Documentation

◆ MutationBatcher

friend class MutationBatcher
friend

Definition at line 827 of file table.h.