Class: Google::Cloud::Bigtable::Project

Inherits:
Object
  • Object
show all
Defined in:
lib/google/cloud/bigtable/project.rb

Overview

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.

Examples:

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

Instance Method Summary collapse

Instance Method Details

#clusters(token: nil) ⇒ Array<Google::Cloud::Bigtable::Cluster>

Lists all clusters in the project.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

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

Parameters:

  • 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:



260
261
262
263
264
 
# File 'lib/google/cloud/bigtable/project.rb', line 260

def clusters token: nil
  ensure_service!
  grpc = service.list_clusters "-", token: token
  Cluster::List.from_grpc grpc, service, instance_id: "-"
end

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

Examples:

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

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:



504
505
506
507
508
509
510
511
512
513
514
515
516
 
# File 'lib/google/cloud/bigtable/project.rb', line 504

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:
  ensure_service!
  grpc = service.copy_backup project_id: dest_project_id,
                             instance_id: dest_instance_id,
                             cluster_id: dest_cluster_id,
                             backup_id: new_backup_id,
                             source_backup: service.backup_path(source_instance_id,
                                                                source_cluster_id,
                                                                source_backup_id),
                             expire_time: expire_time
  Backup::Job.from_grpc grpc, service
end

#create_instance(instance_id, display_name: nil, type: nil, labels: nil, clusters: nil) {|clusters| ... } ⇒ Google::Cloud::Bigtable::Instance::Job

Creates a Bigtable instance.

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

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 Parameters:

Returns:

See Also:



226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/google/cloud/bigtable/project.rb', line 226

def create_instance instance_id, display_name: nil, type: nil, labels: nil, clusters: nil
  labels = labels.to_h { |k, v| [String(k), String(v)] } if labels

  instance_attrs = { display_name: display_name, type: type, labels: labels }.compact
  instance = Google::Cloud::Bigtable::Admin::V2::Instance.new instance_attrs
  clusters ||= Instance::ClusterMap.new
  yield clusters if block_given?

  clusters.each_value do |cluster|
    cluster.location = service.location_path cluster.location unless cluster.location == ""
  end

  grpc = service.create_instance instance_id, instance, clusters.to_h
  Instance::Job.from_grpc grpc, service
end

#create_table(instance_id, table_id, column_families: nil, granularity: nil, initial_splits: nil) {|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.

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

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 Parameters:

Returns:



424
425
426
427
428
429
430
431
432
433
434
435
 
# File 'lib/google/cloud/bigtable/project.rb', line 424

def create_table instance_id, table_id, column_families: nil, granularity: nil, initial_splits: nil, &block
  ensure_service!
  Table.create(
    service,
    instance_id,
    table_id,
    column_families: column_families,
    granularity:     granularity,
    initial_splits:  initial_splits,
    &block
  )
end

#delete_table(instance_id, table_id) ⇒ Object

Permanently deletes the specified table and all of its data.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

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

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.



452
453
454
455
 
# File 'lib/google/cloud/bigtable/project.rb', line 452

def delete_table instance_id, table_id
  service.delete_table instance_id, table_id
  true
end

#instance(instance_id) ⇒ Google::Cloud::Bigtable::Instance?

Gets an existing Bigtable instance.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

if instance
  puts instance.instance_id
end

Parameters:

  • instance_id (String) —

    Existing instance ID.

Returns:



126
127
128
129
130
131
132
 
# File 'lib/google/cloud/bigtable/project.rb', line 126

def instance instance_id
  ensure_service!
  grpc = service.get_instance instance_id
  Instance.from_grpc grpc, service
rescue Google::Cloud::NotFoundError
  nil
end

#instances(token: nil) ⇒ Array<Google::Cloud::Bigtable::Instance>

Retrieves the list of Bigtable instances for the project.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

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

Parameters:

  • 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:



103
104
105
106
107
 
# File 'lib/google/cloud/bigtable/project.rb', line 103

def instances token: nil
  ensure_service!
  grpc = service.list_instances token: token
  Instance::List.from_grpc grpc, service
end

#project_id ⇒ String

The identifier for the Cloud Bigtable project.

Examples:

require "google/cloud/bigtable"

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

bigtable.project_id #=> "my-project"

Returns:

  • (String) —

    Project ID.



79
80
81
82
 
# File 'lib/google/cloud/bigtable/project.rb', line 79

def project_id
  ensure_service!
  service.project_id
end

#table(instance_id, table_id, view: nil, perform_lookup: nil, app_profile_id: nil) ⇒ Google::Cloud::Bigtable::Table?

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.

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

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:



342
343
344
345
346
347
348
349
350
351
352
353
354
 
# File 'lib/google/cloud/bigtable/project.rb', line 342

def table instance_id, table_id, view: nil, perform_lookup: nil, app_profile_id: nil
  ensure_service!

  view ||= :SCHEMA_VIEW
  if perform_lookup
    grpc = service.get_table instance_id, table_id, view: view
    Table.from_grpc grpc, service, view: view, app_profile_id: app_profile_id
  else
    Table.from_path service.table_path(instance_id, table_id), service, app_profile_id: app_profile_id
  end
rescue Google::Cloud::NotFoundError
  nil
end

#tables(instance_id) ⇒ Array<Google::Cloud::Bigtable::Table>

Lists all tables for the given instance.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

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

Parameters:

  • instance_id (String) —

    Existing instance Id.

Returns:



283
284
285
286
287
 
# File 'lib/google/cloud/bigtable/project.rb', line 283

def tables instance_id
  ensure_service!
  grpc = service.list_tables instance_id
  Table::List.from_grpc grpc, service
end