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:

Preparing a query: The service creates and caches a query execution plan.
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

#include "google/cloud/bigtable/client.h"
#include "google/cloud/project.h"
#include <iostream>

int main() {
  namespace cbt = google::cloud::bigtable;
  cbt::Client client(cbt::MakeDataConnection());
  cbt::InstanceResource instance(google::cloud::Project("my-project"),
"my-instance");

  // Declare a parameter with a type, but no value.
  cbt::SqlStatement statement(
      "SELECT _key, CAST(family['qual'] AS STRING) AS value "
      "FROM my-table WHERE _key = @key",
      {{"key", cbt::Value(cbt::Bytes())}});

  google::cloud::StatusOr<cbt::PreparedQuery> prepared_query =
      client.PrepareQuery(instance, statement);
  if (!prepared_query) throw std::move(prepared_query).status();

  auto bound_query = prepared_query->BindParameters(
      {{"key", cbt::Value("row-key-2")}});

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

  ... // process rows
}

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.