Example: Ruby "hello world" application

This code sample is a "hello world" application that runs on Ruby. The sample illustrates how to complete the following tasks:

  • Connect to a Cloud Bigtable instance.
  • Create a new table.
  • Write data to the table.
  • Read the data back.
  • Delete the table.

Running the sample

This code sample uses the Ruby Client for Cloud Bigtable package of the Google Cloud Client Library for Ruby to communicate with Cloud Bigtable.

To run this sample program, follow the instructions for the sample on GitHub.

Using the Cloud Client Library with Cloud Bigtable

The sample application connects to Cloud Bigtable and demonstrates some simple operations.

Requiring the client library

The sample requires google/cloud/bigtable, which provides the Bigtable module.

bigtable/hello_world.rb 
require "google/cloud/bigtable"

Connecting to Cloud Bigtable

Establish the variables you will use in your application, replacing "YOUR_PROJECT_ID" with the ID of a valid Google Cloud project. Then create a new Bigtable object that you will use to connect to Cloud Bigtable.

bigtable/hello_world.rb 
# instance_id      = "my-instance"
# table_id         = "my-table"
# column_family    = "cf"
# column_qualifier = "greeting"

bigtable = Google::Cloud::Bigtable.new

Creating a table

Check to see if your table already exists. If it doesn't, call the create_table() method to create a Table object. The table has a single column family that retains one version of each value.

bigtable/hello_world.rb 
if bigtable.table(instance_id, table_id).exists?
  puts "#{table_id} is already exists."
  exit 0
else
  table = bigtable.create_table instance_id, table_id do |column_families|
    column_families.add(
      column_family,
      Google::Cloud::Bigtable::GcRule.max_versions(1)
    )
  end

  puts "Table #{table_id} created."
end

Writing rows to a table

Next, use a string array of greetings to create some new rows for the table. For each greeting, create an entry using the table's new_mutation_entry() method. Next, use the entry's set_cell() method to assign the column family, column qualifier, the greeting, and a timestamp to the entry. Finally, write that entry to the table using the table's mutate_row() method.

bigtable/hello_world.rb 
puts "Write some greetings to the table #{table_id}"
greetings = ["Hello World!", "Hello Bigtable!", "Hello Ruby!"]

# Insert rows one by one
# Note: To perform multiple mutation on multiple rows use `mutate_rows`.
greetings.each_with_index do |value, i|
  puts " Writing,  Row key: greeting#{i}, Value: #{value}"

  entry = table.new_mutation_entry "greeting#{i}"
  entry.set_cell(
    column_family,
    column_qualifier,
    value,
    timestamp: (Time.now.to_f * 1_000_000).round(-3)
  )

  table.mutate_row entry
end

Creating a filter

Before you read the data that you wrote, create a filter to limit the data that Cloud Bigtable returns. This filter tells Cloud Bigtable to return only the most recent version of each value, even if the table contains older versions that haven't been garbage-collected.

bigtable/hello_world.rb 
# Only retrieve the most recent version of the cell.
filter = Google::Cloud::Bigtable::RowFilter.cells_per_column 1

Reading a row by its row key

Create a row object, then call the read_row() method, passing in the filter, to get one version of each value in that row.

bigtable/hello_world.rb 
puts "Reading a single row by row key"
row = table.read_row "greeting0", filter: filter
puts "Row key: #{row.key}, Value: #{row.cells[column_family].first.value}"

Scanning all table rows

Call the read_rows() method, passing in the filter, to get all of the rows in the table. Because you passed in the filter, Cloud Bigtable returns only one version of each value.

bigtable/hello_world.rb 
puts "Reading the entire table"
table.read_rows.each do |row|
  puts "Row key: #{row.key}, Value: #{row.cells[column_family].first.value}"
end

Deleting a table

Delete the table with the table's delete() method.

bigtable/hello_world.rb 
puts "Deleting the table #{table_id}"
table.delete

Putting it all together

Here is the full code sample without comments.

bigtable/hello_world.rb 
# Copyright 2020 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

def hello_world instance_id, table_id, column_family, column_qualifier
  require "google/cloud/bigtable"

  # instance_id      = "my-instance"
  # table_id         = "my-table"
  # column_family    = "cf"
  # column_qualifier = "greeting"

  bigtable = Google::Cloud::Bigtable.new

  if bigtable.table(instance_id, table_id).exists?
    puts "#{table_id} is already exists."
    exit 0
  else
    table = bigtable.create_table instance_id, table_id do |column_families|
      column_families.add(
        column_family,
        Google::Cloud::Bigtable::GcRule.max_versions(1)
      )
    end

    puts "Table #{table_id} created."
  end

  puts "Write some greetings to the table #{table_id}"
  greetings = ["Hello World!", "Hello Bigtable!", "Hello Ruby!"]

  # Insert rows one by one
  # Note: To perform multiple mutation on multiple rows use `mutate_rows`.
  greetings.each_with_index do |value, i|
    puts " Writing,  Row key: greeting#{i}, Value: #{value}"

    entry = table.new_mutation_entry "greeting#{i}"
    entry.set_cell(
      column_family,
      column_qualifier,
      value,
      timestamp: (Time.now.to_f * 1_000_000).round(-3)
    )

    table.mutate_row entry
  end

  # Only retrieve the most recent version of the cell.
  filter = Google::Cloud::Bigtable::RowFilter.cells_per_column 1

  puts "Reading a single row by row key"
  row = table.read_row "greeting0", filter: filter
  puts "Row key: #{row.key}, Value: #{row.cells[column_family].first.value}"

  puts "Reading the entire table"
  table.read_rows.each do |row|
    puts "Row key: #{row.key}, Value: #{row.cells[column_family].first.value}"
  end

  puts "Deleting the table #{table_id}"
  table.delete
end