impl(bigtable): add snippet demonstrating query execution (#15753)

Author: scotthart

google/cloud/bigtable/client.h

@@ -49,36 +49,7 @@ GOOGLE_CLOUD_CPP_INLINE_NAMESPACE_BEGIN
  * For this reason, it is recommended to reuse `Client` objects when possible.
  *
  * @par Example
- * @code
- * #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
- * }
- * @endcode
+ * @snippet data_snippets.cc prepare-and-execute-query
  */
 class Client {
  public:

google/cloud/bigtable/examples/bigtable_examples_common.cc

@@ -129,6 +129,24 @@ Commands::value_type MakeCommandEntry(std::string const& name,
   return Commands::value_type{name, std::move(adapter)};
 }
 
+Commands::value_type MakeCommandEntry(std::string const& name,
+                                      std::vector<std::string> const& args,
+                                      ClientCommandType const& function) {
+  auto command = [=](std::vector<std::string> argv) {
+    auto constexpr kFixedArguments = 0;
+    if ((argv.size() == 1 && argv[0] == "--help") ||
+        argv.size() != args.size() + kFixedArguments) {
+      std::ostringstream os;
+      os << name;
+      if (!args.empty()) os << " " << absl::StrJoin(args, " ");
+      throw Usage{std::move(os).str()};
+    }
+    auto client = bigtable::Client(bigtable::MakeDataConnection());
+    function(client, argv);
+  };
+  return {name, command};
+}
+
 }  // namespace examples
 }  // namespace bigtable
 }  // namespace cloud

google/cloud/bigtable/examples/bigtable_examples_common.h

@@ -17,6 +17,7 @@
 
 #include "google/cloud/bigtable/admin/bigtable_instance_admin_client.h"
 #include "google/cloud/bigtable/admin/bigtable_table_admin_client.h"
+#include "google/cloud/bigtable/client.h"
 #include "google/cloud/bigtable/table.h"
 #include "google/cloud/internal/random.h"
 #include "google/cloud/testing_util/example_driver.h"
@@ -85,6 +86,13 @@ Commands::value_type MakeCommandEntry(std::string const& name,
                                       std::vector<std::string> const& args,
                                       TableAsyncCommandType const& command);
 
+using ClientCommandType = std::function<void(google::cloud::bigtable::Client,
+                                             std::vector<std::string>)>;
+
+Commands::value_type MakeCommandEntry(std::string const& name,
+                                      std::vector<std::string> const& args,
+                                      ClientCommandType const& function);
+
 }  // namespace examples
 }  // namespace bigtable
 }  // namespace cloud

google/cloud/bigtable/examples/data_snippets.cc

@@ -18,6 +18,7 @@
 #include "google/cloud/bigtable/testing/cleanup_stale_resources.h"
 #include "google/cloud/bigtable/testing/random_names.h"
 //! [bigtable includes]
+#include "google/cloud/bigtable/client.h"
 #include "google/cloud/bigtable/table.h"
 //! [bigtable includes]
 #include "google/cloud/internal/getenv.h"
@@ -778,6 +779,38 @@ void RunWriteExamples(
   admin.DeleteTable(schema->name());
 }
 
+void PrepareAndExecuteQuery(google::cloud::bigtable::Client client,
+                            std::vector<std::string> const& args) {
+  // [prepare-and-execute-query] [START bigtable_api_execute_query]
+  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;
+    }
+  }
+  // [prepare-and-execute-query] [END bigtable_api_execute_query]
+  (std::move(client), args.at(0), args.at(1), args.at(2));
+}
+
 void RunDataExamples(
     google::cloud::bigtable_admin::BigtableTableAdminClient admin,
     google::cloud::internal::DefaultPRNG& generator,
@@ -879,6 +912,11 @@ void RunDataExamples(
   std::cout << "Running ReadModifyWrite() example [3]" << std::endl;
   ReadModifyWrite(table, {"read-modify-write"});
 
+  if (!google::cloud::bigtable::examples::UsingEmulator()) {
+    auto client = cbt::Client(cbt::MakeDataConnection());
+    std::cout << "Running PrepareAndExecuteQuery() example" << std::endl;
+    PrepareAndExecuteQuery(client, {project_id, instance_id, table_id});
+  }
   admin.DeleteTable(schema->name());
 }
 
@@ -946,6 +984,9 @@ int main(int argc, char* argv[]) try {
       MakeCommandEntry("write-batch", {}, WriteBatch),
       MakeCommandEntry("write-increment", {}, WriteIncrement),
       MakeCommandEntry("write-conditional", {}, WriteConditionally),
+      MakeCommandEntry("prepare-and-execute-query",
+                       {"<project_id>", "<instance_id>", "<table_id>"},
+                       PrepareAndExecuteQuery),
       {"auto", RunAll},
   };