Google Cloud Bigtable C++ Client  1.1.0
A C++ Client Library for Google Cloud Bigtable
Google Cloud Platform Bigtable C++ Client Library

Overview

Cloud Bigtable is Google's NoSQL Big Data database service. It's the same database that powers many core Google services, including Search, Analytics, Maps, and Gmail.

The Cloud Bigtable C++ Client library offers types and functions to access Cloud Bigtable from C++11 applications (Read more about Cloud Bigtable). It offers access to the Cloud Bigtable API, including operations to list, read, write, and delete Instances and Clusters, Tables and Application Profiles.

Quick Start

The following instructions show you how to perform basic tasks in Cloud Bigtable using the C++ client library.

If you have never used Cloud Bigtable we recommend that you first follow one of the language neutral quickstart guides before you follow this guide.

Before you begin

  1. Select or create a Google Cloud Platform (GCP) project using the manage resource page. Make a note of the project id, you will need to use it later.
  2. Make sure that billing is enabled for your project. Costs that you incur in Cloud Bigtable are based on the resources you use.
  3. Learn about key terms and concepts for Cloud Storage.
  4. Setup the authentication for the examples:

Download and Compile C++ Client Library

The source code for the Cloud Bigtable C++ Client Library can be found on GitHub. Download or clone this repository as usual:

git clone https://github.com/googleapis/google-cloud-cpp.git

The top-level README file in this repository includes detailed instructions on how to compile the library. The examples used in this guide should be automatically compiled when you follow said instructions.

Configuring authentication for the C++ Client Library

This library uses the GOOGLE_APPLICATION_CREDENTIALS environment variable to find the credentials file. For example:

Shell Command
Bash/zsh/ksh/etc. export GOOGLE_APPLICATION_CREDENTIALS=[PATH]
sh GOOGLE_APPLICATION_CREDENTIALS=[PATH]; export GOOGLE_APPLICATION_CREDENTIALS
csh/tsch setenv GOOGLE_APPLICATION_CREDENTIALS [PATH]
Windows Powershell $env:GOOGLE_APPLICATION_CREDENTIALS=[PATH]
Windows cmd.exe set GOOGLE_APPLICATION_CREDENTIALS=[PATH]

Setting this environment variable is the recommended way to configure the authentication preferences, though if the environment variable is not set, the library searches for a credentials file in the same location as the Cloud SDK. For more details about authentication and Google Cloud Platform consult the Authentication Overview page.

Read a Row

This is a short example showing how to read a row from Cloud Bigtable: This example assumes you have configured the authentication using GOOGLE_APPLICATION_CREDENTIALS:

int main(int argc, char* argv[]) try {
if (argc != 4) {
std::string const cmd = argv[0];
auto last_slash = std::string(cmd).find_last_of('/');
std::cerr << "Usage: " << cmd.substr(last_slash + 1)
<< " <project_id> <instance_id> <table_id>\n";
return 1;
}
std::string const project_id = argv[1];
std::string const instance_id = argv[2];
std::string const table_id = argv[3];
// Create a namespace alias to make the code easier to read.
cbt::Table table(cbt::CreateDefaultDataClient(project_id, instance_id,
cbt::ClientOptions()),
table_id);
std::string row_key = "r1";
std::string column_family = "cf1";
std::cout << "Getting a single row by row key:" << std::flush;
google::cloud::StatusOr<std::pair<bool, cbt::Row>> result =
table.ReadRow(row_key, cbt::Filter::FamilyRegex(column_family));
if (!result) {
throw std::runtime_error(result.status().message());
}
if (!result->first) {
std::cout << "Cannot find row " << row_key << " in the table: " << table_id
<< "\n";
return 0;
}
cbt::Cell const& cell = result->second.cells().front();
std::cout << cell.family_name() << ":" << cell.column_qualifier() << " @ "
<< cell.timestamp().count() << "us\n"
<< '"' << cell.value() << '"' << "\n";
return 0;
} catch (std::exception const& ex) {
std::cerr << "Standard C++ exception raised: " << ex.what() << "\n";
return 1;
}

This quickstart will always read a single row with key r1 from family cf1. You must provide a project id, instance id, and table id in the command-line when you run the quickstart program. Assuming you followed the build instructions referenced above this would be:

./cmake-out/google/cloud/bigtable/bigtable_quickstart [PROJECT_ID] [INSTANCE ID] [TABLE ID]

Using the library in your own project

Our continuous integration builds compile and test the code using both Bazel, and CMake.

Integrating with Bazel

In your WORKSPACE file add a dependency to download and install the library, for example:

# Change the version and SHA256 hash as needed.
http_archive(
name = "com_github_googleapis_google_cloud_cpp",
url = "http://github.com/googleapis/google-cloud-cpp/archive/v0.9.0.tar.gz",
strip_prefix = "google-cloud-cpp-0.9.0",
sha256 = "a072103546cfa041ad8bfc599fe5a20c58e005a1a0ee18e94b2554dc3d485604",
)

Then load the dependencies of the library:

load("@com_github_googleapis_google_cloud_cpp//bazel:google_cloud_cpp_deps.bzl", "google_cloud_cpp_deps")
google_cloud_cpp_deps()
# Configure @com_google_googleapis to only compile C++ and gRPC:
load("@com_google_googleapis//:repository_rules.bzl", "switched_rules_by_language")
switched_rules_by_language(
name = "com_google_googleapis_imports",
cc = True, # C++ support is only "Partially implemented", roll our own.
grpc = True,
)
# Have to manually call the corresponding function for gRPC:
# https://github.com/bazelbuild/bazel/issues/1550
load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps")
grpc_deps()

You can now use the library as a dependency in your BUILD files, for example:

cc_binary(
name = "my_program",
srcs = [
"my_program.cc",
],
deps = [
"@com_github_googleapis_google_cloud_cpp//google/cloud/bigtable:bigtable_client",
],
)

Integrating with CMake

Follow the instructions on the top-level INSTALL file on GitHub for details on how to compile and install the library for your platform and distribution. Once the library is installed, you can use it in your CMakeLists.txt file like any other package:

cmake_minimum_required(VERSION 3.5)
find_package(bigtable_client REQUIRED)
add_executable(my_program my_program.cc)
target_link_libraries(my_program bigtable_client)

Integrating with Make

The installation instructions on the top-level INSTALL file on GitHub also create pkg-config support files for application developers that prefer to use make as their build system. Once the library is installed, you can use it in your Makefile like any other pkg-config module:

CBT_DEPS := bigtable_client
CBT_CXXFLAGS := $(shell pkg-config $(CBT_DEPS) --cflags)
CBT_CXXLDFLAGS := $(shell pkg-config $(CBT_DEPS) --libs-only-L)
CBT_LIBS := $(shell pkg-config $(CBT_DEPS) --libs-only-l)
# A target using the Cloud Bigtable C++ client library.
bigtable_install_test: bigtable_install_test.cc
$(CXX) $(CXXFLAGS) $(CBT_CXXFLAGS) $(GCS_CXXLDFLAGS) -o $@ $^ $(CBT_LIBS)

Next Steps