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:



295
296
297
298
299
 
# File 'lib/google/cloud/bigtable/project.rb', line 295

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:



539
540
541
542
543
544
545
546
547
548
549
550
551
 
# File 'lib/google/cloud/bigtable/project.rb', line 539

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:



261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/google/cloud/bigtable/project.rb', line 261

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:



459
460
461
462
463
464
465
466
467
468
469
470
 
# File 'lib/google/cloud/bigtable/project.rb', line 459

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.



487
488
489
490
 
# File 'lib/google/cloud/bigtable/project.rb', line 487

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:



161
162
163
164
165
166
167
 
# File 'lib/google/cloud/bigtable/project.rb', line 161

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

#instance_admin_client ⇒ Google::Cloud::Bigtable::Admin::V2::BigtableInstanceAdmin::Client

Retrieve a client for instance administration. This client should be used for instance administration operations such as managing clusters, instances, and app profiles. See https://cloud.google.com/ruby/docs/reference/google-cloud-bigtable-admin-v2/latest/Google-Cloud-Bigtable-Admin-V2-BigtableInstanceAdmin-Client for documentation on this class.

Returns:

  • (Google::Cloud::Bigtable::Admin::V2::BigtableInstanceAdmin::Client) 


73
74
75
 
# File 'lib/google/cloud/bigtable/project.rb', line 73

def instance_admin_client
  service.instances
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:



138
139
140
141
142
 
# File 'lib/google/cloud/bigtable/project.rb', line 138

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.



114
115
116
117
 
# File 'lib/google/cloud/bigtable/project.rb', line 114

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:



377
378
379
380
381
382
383
384
385
386
387
388
389
 
# File 'lib/google/cloud/bigtable/project.rb', line 377

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

#table_admin_client ⇒ Google::Cloud::Bigtable::Admin::V2::BigtableTableAdmin::Client

Retrieve a client for table administration. This client should be used for table administration operations such as managing tables, backups, snapshots, and authorized views. See https://cloud.google.com/ruby/docs/reference/google-cloud-bigtable-admin-v2/latest/Google-Cloud-Bigtable-Admin-V2-BigtableTableAdmin-Client for documentation on this class.

Returns:

  • (Google::Cloud::Bigtable::Admin::V2::BigtableTableAdmin::Client) 


86
87
88
 
# File 'lib/google/cloud/bigtable/project.rb', line 86

def table_admin_client
  service.tables
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:



318
319
320
321
322
 
# File 'lib/google/cloud/bigtable/project.rb', line 318

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

#universe_domain ⇒ String

The universe domain the client is connected to

Returns:

  • (String) 


94
95
96
97
 
# File 'lib/google/cloud/bigtable/project.rb', line 94

def universe_domain
  ensure_service!
  service.universe_domain
end