Class Client (2.44.0-rc)

Connects to Cloud Bigtable's query preparation and execution APIs.

A Bigtable query's lifecycle consists of two phases:

  1. Preparing a query: The service creates and caches a query execution plan.
  2. Executing a query: The client sends the plan ID and concrete parameters to the service, which then executes the query.

This class provides methods for both preparing and executing SQL queries.

Cost

Creating a Client object is a relatively low-cost operation. It does not require connecting to the Bigtable servers. However, each Client object holds a std::shared_ptr<DataConnection>, and the first RPC made on this connection may incur a higher latency as the connection is established. For this reason, it is recommended to reuse Client objects when possible.

Example
  namespace cbt = ::google::cloud::bigtable;
  [](cbt::Client client, std::string const& project_id,
     std::string const& instance_id, std::string const& table_id) {
    cbt::InstanceResource instance(google::cloud::Project(project_id),
                                   instance_id);
    cbt::SqlStatement statement(
        "SELECT _key, CAST(fam['column0'] AS STRING) as value0 FROM `" +
            table_id + "` WHERE _key=@key",
        {{"key", cbt::Parameter(cbt::Bytes())}});

    auto prepared_query = client.PrepareQuery(instance, statement);
    if (!prepared_query) throw std::move(prepared_query).status();

    auto bound_query = prepared_query->BindParameters(
        {{"key", cbt::Value(cbt::Bytes("test-key-for-apply"))}});

    auto results = client.ExecuteQuery(std::move(bound_query));

    using RowType = std::tuple<cbt::Bytes, absl::optional<std::string>>;
    for (auto& row : cbt::StreamOf<RowType>(results)) {
      if (!row.ok()) throw std::move(row.status());
      auto v = std::get<1>(*row);
      std::cout << std::get<0>(*row) << "; " << (v ? *v : "null") << std::endl;
    }
  }

Constructors

Client(std::shared_ptr< DataConnection >, Options)

Creates a new Client object.

Parameters
Name Description
conn std::shared_ptr< DataConnection >

The connection object to use for all RPCs. This is typically created by MakeDataConnection().

opts Options

Unused for now

Functions

PrepareQuery(InstanceResource const &, SqlStatement const &, Options)

Prepares a query for future execution.

This sends the SQL statement to the service, which validates it and creates an execution plan, returning a handle to this plan.

Parameters
Name Description
instance InstanceResource const &

The instance to prepare the query against.

statement SqlStatement const &

The SQL statement to prepare.

opts Options

Unused for now

Returns
Type Description
StatusOr< PreparedQuery >

A StatusOr containing the prepared query on success. On failure, the Status contains error details.

AsyncPrepareQuery(InstanceResource const &, SqlStatement const &, Options)

Asynchronously prepares a query for future execution.

This sends the SQL statement to the service, which validates it and creates an execution plan, returning a handle to this plan.

Parameters
Name Description
instance InstanceResource const &

The instance to prepare the query against.

statement SqlStatement const &

The SQL statement to prepare.

opts Options

Unused for now

Returns
Type Description
future< StatusOr< PreparedQuery > >

A future that will be satisfied with a StatusOr containing the prepared query on success. On failure, the Status will contain error details.

ExecuteQuery(BoundQuery &&, Options)

Executes a bound query with concrete parameters.

This returns a RowStream, which is a range of StatusOr<QueryRow>. The BoundQuery is passed by rvalue-reference to promote thread safety, as it is not safe to use a BoundQuery concurrently.

Parameters
Name Description
bound_query BoundQuery &&

The bound query to execute.

opts Options

Overrides the client-level options for this call.

Returns
Type Description
RowStream

A RowStream that can be used to iterate over the result rows.