Ruby hello world

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

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

Set up authentication

To use the Ruby samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  • Install the Google Cloud CLI.

  • If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  • To initialize the gcloud CLI, run the following command:

    gcloud init
  • If you're using a local shell, then create local authentication credentials for your user account:

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

    If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  • For more information, see Set up authentication for a local development environment.

    Running the sample

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

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

    Using the Cloud Client Library with Bigtable

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

    Requiring the client library

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

    require "google/cloud/bigtable"

    Connecting to 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 Bigtable.

    # These variables are used in the sample code below.
    # instance_id      = "my-instance"
    # table_id         = "my-table"
    # column_family    = "cf"
    # column_qualifier = "greeting"
    
    bigtable = Google::Cloud::Bigtable.new
    table_client = bigtable.table_admin_client

    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.

    # This is the full resource name for the table. Use this name to make admin
    # calls for the table, such as reading or deleting the resource.
    table_name = table_client.table_path project: bigtable.project_id,
                                         instance: instance_id,
                                         table: table_id
    begin
      # Attempt to get the table to see if it already exists
      table_client.get_table name: table_name
      puts "#{table_id} is already exists."
      exit 0
    rescue Google::Cloud::NotFoundError
      # The table doesn't exist, so let's create it.
      # The following is the resource name for the table's instance.
      instance_name = table_client.instance_path project: bigtable.project_id,
                                                 instance: instance_id
      # This is the configuration of the table's column families.
      table_config = {
        column_families: {
          column_family => {
            gc_rule: Google::Cloud::Bigtable::Admin::V2::GcRule.max_num_versions(1)
          }
        }
      }
      # Now call the API to create the table.
      table_client.create_table parent: instance_name,
                                table_id: table_id,
                                table: table_config
      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.

    puts "Write some greetings to the table #{table_id}"
    greetings = ["Hello World!", "Hello Bigtable!", "Hello Ruby!"]
    
    # Get a table data object for the new table we created.
    table = bigtable.table instance_id, table_id
    
    # 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 Bigtable returns. This filter tells Bigtable to return only the most recent version of each value, even if the table contains older versions that haven't been garbage-collected.

    # 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.

    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, Bigtable returns only one version of each 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

    Deleting a table

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

    puts "Deleting the table #{table_id}"
    # Call the admin API to delete the table given its full resource path.
    table_client.delete_table name: table_name

    Putting it all together

    Here is the full code sample without comments.

    # Copyright 2021 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"
    
      # These variables are used in the sample code below.
      # instance_id      = "my-instance"
      # table_id         = "my-table"
      # column_family    = "cf"
      # column_qualifier = "greeting"
    
      bigtable = Google::Cloud::Bigtable.new
      table_client = bigtable.table_admin_client
    
      # This is the full resource name for the table. Use this name to make admin
      # calls for the table, such as reading or deleting the resource.
      table_name = table_client.table_path project: bigtable.project_id,
                                           instance: instance_id,
                                           table: table_id
      begin
        # Attempt to get the table to see if it already exists
        table_client.get_table name: table_name
        puts "#{table_id} is already exists."
        exit 0
      rescue Google::Cloud::NotFoundError
        # The table doesn't exist, so let's create it.
        # The following is the resource name for the table's instance.
        instance_name = table_client.instance_path project: bigtable.project_id,
                                                   instance: instance_id
        # This is the configuration of the table's column families.
        table_config = {
          column_families: {
            column_family => {
              gc_rule: Google::Cloud::Bigtable::Admin::V2::GcRule.max_num_versions(1)
            }
          }
        }
        # Now call the API to create the table.
        table_client.create_table parent: instance_name,
                                  table_id: table_id,
                                  table: table_config
        puts "Table #{table_id} created."
      end
    
      puts "Write some greetings to the table #{table_id}"
      greetings = ["Hello World!", "Hello Bigtable!", "Hello Ruby!"]
    
      # Get a table data object for the new table we created.
      table = bigtable.table instance_id, table_id
    
      # 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}"
      # Call the admin API to delete the table given its full resource path.
      table_client.delete_table name: table_name
    end