Cloud BigQuery C++ Client Library

Table of Contents

• Quickstart
• Setting up your repo
• Main classes
• Next Steps

The Cloud BigQuery C++ Client library offers types and functions to use Cloud BigQuery from C++11 applications.

This library requires a C++14 compiler. It is supported (and tested) on multiple Linux distributions, macOS, and Windows.

Quickstart

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

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 as you will need to use it later.
2. Make sure that billing is enabled for your project.
3. Learn about key terms and concepts for Cloud BigQuery.
4. Setup the authentication for the examples:
   • [Configure a service account][gcloud-authorizing],
   • or [login with your personal account][gcloud-authorizing]

Setting up your repo

In order to use the Cloud BigQuery C++ client library from your own code, you'll need to configure your build system to fetch and compile the Cloud C++ client library. The Cloud BigQuery C++ client library natively supports the Bazel and CMake build systems. We've created a minimal, "Hello world", quickstart repo that includes detailed instructions on how to compile the library for use in your application. You can fetch the source from GitHub as normal:

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

Example: Hello World

The following shows the code that you'll run in the google/cloud/bigquery/quickstart/ directory, which should give you a taste of the Cloud BigQuery C++ client library API.

#include "google/cloud/bigquery/storage/v1/bigquery_read_client.h"
#include <iostream>
 
namespace {
void ProcessRowsInAvroFormat(
    ::google::cloud::bigquery::storage::v1::AvroSchema const&,
    ::google::cloud::bigquery::storage::v1::AvroRows const&) {
  // Code to deserialize avro rows should be added here.
}
}  // namespace
 
int main(int argc, char* argv[]) try {
  if (argc != 3) {
    std::cerr << "Usage: " << argv[0] << " <project-id> <table-name>\n";
    return 1;
  }
 
  // project_name should be in the format "projects/<your-gcp-project>"
  std::string const project_name = "projects/" + std::string(argv[1]);
  // table_name should be in the format:
  // "projects/<project-table-resides-in>/datasets/<dataset-table_resides-in>/tables/<table
  // name>" The project values in project_name and table_name do not have to be
  // identical.
  std::string const table_name = argv[2];
 
  // Create a namespace alias to make the code easier to read.
  namespace bigquery_storage = ::google::cloud::bigquery_storage_v1;
  constexpr int kMaxReadStreams = 1;
  // Create the ReadSession.
  auto client = bigquery_storage::BigQueryReadClient(
      bigquery_storage::MakeBigQueryReadConnection());
  ::google::cloud::bigquery::storage::v1::ReadSession read_session;
  read_session.set_data_format(
      google::cloud::bigquery::storage::v1::DataFormat::AVRO);
  read_session.set_table(table_name);
  auto session =
      client.CreateReadSession(project_name, read_session, kMaxReadStreams);
  if (!session) throw std::move(session).status();
 
  // Read rows from the ReadSession.
  constexpr int kRowOffset = 0;
  auto read_rows = client.ReadRows(session->streams(0).name(), kRowOffset);
 
  std::int64_t num_rows = 0;
  for (auto const& row : read_rows) {
    if (row.ok()) {
      num_rows += row->row_count();
      ProcessRowsInAvroFormat(session->avro_schema(), row->avro_rows());
    }
  }
 
  std::cout << num_rows << " rows read from table: " << table_name << "\n";
  return 0;
} catch (google::cloud::Status const& status) {
  std::cerr << "google::cloud::Status thrown: " << status << "\n";
  return 1;
}

Main classes

This library offers multiple *Client classes, which are listed below. Each one of these classes exposes all the RPCs for a gRPC service as member functions of the class. This library groups multiple gRPC services because they are part of the same product or are often used together. A typical example may be the administrative and data plane operations for a single product.

The library also has other classes that provide helpers, configuration parameters, and infrastructure to mock the *Client classes when testing your application.

• bigquery_analyticshub_v1::AnalyticsHubServiceClient
• bigquery_connection_v1::ConnectionServiceClient
• bigquery_datapolicies_v1::DataPolicyServiceClient
• bigquery_datatransfer_v1::DataTransferServiceClient
• bigquery_migration_v2::MigrationServiceClient
• bigquery_reservation_v1::ReservationServiceClient
• bigquery_storage_v1::BigQueryReadClient
• bigquery_storage_v1::BigQueryWriteClient

Next Steps

• Error Handling - describes how the library reports errors.
• How to Override the Default Endpoint - describes how to override the default endpoint.
• How to Override the Authentication Credentials - describes how to change the authentication credentials used by the library.
• Environment Variables - describes environment variables that can configure the behavior of the library.
• Testing your Cloud BigQueryRead application with googlemock