Cloud Bigtable API - Class Google::Cloud::Bigtable::Project (v2.11.0)

Reference documentation and code samples for the Cloud Bigtable API class Google::Cloud::Bigtable::Project.

Project

Projects are top-level containers in Google Cloud Platform. They store information about billing and authorized users, and they contain Cloud Bigtable data. Each project has a friendly name and a unique ID.

Google::Cloud::Bigtable::Project is the main object for interacting with Cloud Bigtable.

Cluster and Instance objects are created, accessed, and managed by Google::Cloud::Bigtable::Project.

To create a Project instance, use new.

Inherits

  • Object

Example

Obtaining an instance and the clusters from a project.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"
clusters = bigtable.clusters # All clusters in the project

Methods

#clusters

def clusters(token: nil) -> Array<Google::Cloud::Bigtable::Cluster>

Lists all clusters in the project.

Parameter
  • token (String) (defaults to: nil) — The token value returned by the last call to clusters indicates that this is a continuation of a call and the system should return the next page of data.
Returns
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

bigtable.clusters.all do |cluster|
  puts cluster.cluster_id
  puts cluster.ready?
end

#copy_backup

def copy_backup(dest_project_id:, dest_instance_id:, dest_cluster_id:, new_backup_id:, source_instance_id:, source_cluster_id:, source_backup_id:, expire_time:) -> Google::Cloud::Bigtable::Backup::Job

Creates a copy of the backup at the desired location. Copy of the backup won't be created if the backup is already a copied one.

Parameters
  • dest_project_id (String) — Existing project ID. Copy of the backup will be created in this project. Required.
  • dest_instance_id (Instance, String) — Existing instance ID. Copy of the backup will be created in this instance. Required.
  • dest_cluster_id (String) — Existing cluster ID. Copy of the backup will be created in this cluster. Required.
  • new_backup_id (String) — The id of the copy of the backup to be created. This string must be between 1 and 50 characters in length and match the regex [_a-zA-Z0-9][-_.a-zA-Z0-9]*. Required.
  • source_instance_id (String) — Existing instance ID. Backup will be copied from this instance. Required.
  • source_cluster_id (String) — Existing cluster ID. Backup will be copied from this cluster. Required.
  • source_backup_id (Instance, String) — Existing backup ID. This backup will be copied. Required.
  • expire_time (Time) — The expiration time of the copy of the backup, with microseconds granularity that must be at least 6 hours and at most 30 days from the time the request is received. Once the expire_time has passed, Cloud Bigtable will delete the backup and free the resources used by the backup. Required.
Returns
Example

Create a copy of the specified backup at a specific location

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

job = bigtable.copy_backup dest_project_id:"my-project-2",
                           dest_instance_id:"my-instance-2",
                           dest_cluster_id:"my-cluster-2",
                           new_backup_id:"my-backup-2",
                           source_instance_id:"my-instance",
                           source_cluster_id:"my-cluster",
                           source_backup_id:"my-backup",
                           expire_time: Time.now + 60 * 60 * 7

job.wait_until_done!
job.done? #=> true

if job.error?
  status = job.error
else
  backup = job.backup
end

#create_instance

def create_instance(instance_id, display_name: nil, type: nil, labels: nil, clusters: nil) { |Cluster| ... } -> Google::Cloud::Bigtable::Instance::Job

Creates a Bigtable instance.

Parameters
  • instance_id (String) — The unique identifier for the instance, which cannot be changed after the instance is created. Values are of the form [a-z][-a-z0-9]*[a-z0-9] and must be between 6 and 30 characters. Required.
  • display_name (String) (defaults to: nil) — The descriptive name for this instance as it appears in UIs. Must be unique per project and between 4 and 30 characters.
  • type (Symbol) (defaults to: nil) — The type of the instance. When creating a development instance, nodes on the cluster must not be set. Valid values are :DEVELOPMENT or :PRODUCTION. Default is :PRODUCTION.
  • labels (Hash{String=>String}) (defaults to: nil) —

    labels Cloud Labels are a flexible and lightweight mechanism for organizing cloud resources into groups that reflect a customer's organizational needs and deployment strategies. Cloud Labels can be used to filter collections of resources. They can be used to control how resource metrics are aggregated. Cloud Labels can be used as arguments to policy management rules (e.g., route, firewall, or load balancing).

    • Label keys must be between 1 and 63 characters and must conform to the following regular expression: [a-z]([-a-z0-9]*[a-z0-9])?.
    • Label values must be between 0 and 63 characters and must conform to the regular expression ([a-z]([-a-z0-9]*[a-z0-9])?)?.
    • No more than 64 labels can be associated with a given resource.
  • clusters (Hash{String => Google::Cloud::Bigtable::Cluster}) (defaults to: nil) — (See Instance::ClusterMap) If unspecified, you may use a code block to add clusters. Minimum of one cluster must be specified.
Yields
  • (clusters) — A block for adding clusters.
Yield Parameter
  • Cluster (Hash{String => Google::Cloud::Bigtable::Cluster}) — map of cluster name and cluster object. (See Instance::ClusterMap)
Returns
Examples

Create a development instance.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

job = bigtable.create_instance(
  "my-instance",
  display_name: "Instance for user data",
  type: :DEVELOPMENT,
  labels: { "env" => "dev" }
) do |clusters|
  clusters.add "test-cluster", "us-east1-b" # nodes not allowed
end

job.done? #=> false

# Reload job until completion.
job.wait_until_done!
job.done? #=> true

if job.error?
  status = job.error
else
  instance = job.instance
end

Create a production instance.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

job = bigtable.create_instance(
  "my-instance",
  display_name: "Instance for user data",
  labels: { "env" => "dev" }
) do |clusters|
  clusters.add "test-cluster", "us-east1-b", nodes: 3, storage_type: :SSD
end

job.done? #=> false

# To block until the operation completes.
job.wait_until_done!
job.done? #=> true

if job.error?
  status = job.error
else
  instance = job.instance
end

#create_table

def create_table(instance_id, table_id, column_families: nil, granularity: nil, initial_splits: nil, &block) { |column_families| ... } -> Google::Cloud::Bigtable::Table

Creates a new table in the specified instance. The table can be created with a full set of initial column families, specified in the request.

Parameters
  • instance_id (String) — The unique ID of the instance in which to create the table.
  • table_id (String) — The ID by which the new table should be referred to within the instance, e.g., foobar.
  • column_families (Google::Cloud::Bigtable::ColumnFamilyMap) (defaults to: nil) — An object containing the column families for the table, mapped by column family name.
  • granularity (Symbol) (defaults to: nil) — The granularity at which timestamps are stored in this table. Timestamps not matching the granularity will be rejected. Valid value is :MILLIS. If unspecified, the value will be set to :MILLIS.
  • initial_splits (Array<String>) (defaults to: nil) —

    The optional list of row keys that will be used to initially split the table into several tablets (tablets are similar to HBase regions). Given two split keys, s1 and s2, three tablets will be created, spanning the key ranges: [, s1), [s1, s2), [s2, ).

    Example:

    • Row keys := ["a", "apple", "custom", "customer_1", "customer_2", "other", "zz"]
    • initial_split_keys := ["apple", "customer_1", "customer_2", "other"]
    • Key assignment:
      • Tablet 1 : [, apple) => {"a"}
      • Tablet 2 : [apple, customer_1) => {"apple", "custom"}
      • Tablet 3 : [customer_1, customer_2) => {"customer_1"}
      • Tablet 4 : [customer_2, other) => {"customer_2"}
      • Tablet 5 : [other, ) => {"other", "zz"}
Yields
  • (column_families) — A block for adding column families.
Yield Parameter
Returns
Examples

Create a table without column families.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.create_table "my-instance", "my-table"
puts table.name

Create a table with initial splits and column families.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

initial_splits = ["user-00001", "user-100000", "others"]
table = bigtable.create_table "my-instance", "my-table", initial_splits: initial_splits do |cfm|
  cfm.add "cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5)
  cfm.add "cf2", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600)

  gc_rule = Google::Cloud::Bigtable::GcRule.union(
    Google::Cloud::Bigtable::GcRule.max_age(1800),
    Google::Cloud::Bigtable::GcRule.max_versions(3)
  )
  cfm.add "cf3", gc_rule: gc_rule
end

puts table

#delete_table

def delete_table(instance_id, table_id)

Permanently deletes the specified table and all of its data.

Parameters
  • instance_id (String) — The unique ID of the instance the table is in.
  • table_id (String) — The unique ID of the table to be deleted.
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

bigtable.delete_table "my-instance", "my-table"

#instance

def instance(instance_id) -> Google::Cloud::Bigtable::Instance, nil

Gets an existing Bigtable instance.

Parameter
  • instance_id (String) — Existing instance ID.
Returns
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

if instance
  puts instance.instance_id
end

#instances

def instances(token: nil) -> Array<Google::Cloud::Bigtable::Instance>

Retrieves the list of Bigtable instances for the project.

Parameter
  • token (String) (defaults to: nil) — The token value returned by the last call to instances; indicates that this is a continuation of a call and that the system should return the next page of data.
Returns
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instances = bigtable.instances
instances.all do |instance|
  puts instance.instance_id
end

#project_id

def project_id() -> String

The identifier for the Cloud Bigtable project.

Returns
  • (String) — Project ID.
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new(
  project_id: "my-project",
  credentials: "/path/to/keyfile.json"
)

bigtable.project_id #=> "my-project"

#table

def table(instance_id, table_id, view: nil, perform_lookup: nil, app_profile_id: nil) -> Google::Cloud::Bigtable::Table, nil

Returns a table representation. If perform_lookup is false (the default), a sparse representation will be returned without performing an RPC and without verifying that the table resource exists.

Parameters
  • instance_id (String) — Existing instance Id.
  • table_id (String) — Existing table Id.
  • view (Symbol) (defaults to: nil) —

    Optional. Table view type. Default :SCHEMA_VIEW Valid view types are the following:

    • :NAME_ONLY - Only populates name
    • :SCHEMA_VIEW - Only populates name and fields related to the table's schema
    • :REPLICATION_VIEW - Only populates name and fields related to the table's replication state.
    • :FULL - Populates all fields
  • perform_lookup (Boolean) (defaults to: nil) — Get table object without verifying that the table resource exists. Calls made on this object will raise errors if the table does not exist. Default value is false. Optional. Helps to reduce admin API calls.
  • app_profile_id (String) (defaults to: nil) — The unique identifier for the app profile. Optional. Used only in data operations. This value specifies routing for replication. If not specified, the "default" application profile will be used.
Returns
Examples

Get a sparse table representation without performing an RPC.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table "my-instance", "my-table"

Retrieve a table with a schema-only view.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table "my-instance", "my-table", perform_lookup: true
if table
  puts table.name
  puts table.column_families
end

Retrieve a table with all fields, cluster states, and column families.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table "my-instance", "my-table", view: :FULL, perform_lookup: true
if table
  puts table.name
  puts table.column_families
  puts table.cluster_states
end

#tables

def tables(instance_id) -> Array<Google::Cloud::Bigtable::Table>

Lists all tables for the given instance.

Parameter
  • instance_id (String) — Existing instance Id.
Returns
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

bigtable.tables("my-instance").all do |table|
  puts table.name
  puts table.column_families
end