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, Instance objects are created, accessed, and managed by Google::Cloud::Bigtable::Project.

See new and Google::Cloud#bigtable.

Examples:

Obtaining an instance and the clusters from a project.

require "google/cloud"

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>

List all clusters in 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) —

    The token value returned by the last call to clusters; indicates that this is a continuation of a call, and that the system should return the next page of data.

Returns:



270
271
272
273
274
 
# File 'lib/google/cloud/bigtable/project.rb', line 270

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

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

Create a Bigtable instance.

Examples:

Create 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: 1)
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 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 in length. Required.

  • display_name (String) —

    The descriptive name for this instance as it appears in UIs. Must be unique per project and between 4 and 30 characters in length.

  • type (Symbol) —

    The type of the instance. Valid values are :DEVELOPMENT or :PRODUCTION. Default :PRODUCTION instance will created if left blank.

  • labels (Hash{String=>String}) —

    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. And they can be used as arguments to policy management rules (e.g. route, firewall, load balancing, etc.).

    • Label keys must be between 1 and 63 characters long 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 long 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}) —

    (See Instance::ClusterMap) If passed as an empty use code block to add clusters. Minimum one cluster must be specified.

Yields:

  • (clusters) —

    A block for adding clusters.

Yield Parameters:

Returns:

See Also:



222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/google/cloud/bigtable/project.rb', line 222

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

  instance_attrs = {
    display_name: display_name,
    type: type,
    labels: labels
  }.delete_if { |_, v| v.nil? }
  instance = Google::Bigtable::Admin::V2::Instance.new(instance_attrs)
  clusters ||= Instance::ClusterMap.new
  yield clusters if block_given?

  clusters.each_value do |cluster|
    unless cluster.location == "".freeze
      cluster.location = service.location_path(cluster.location)
    end
  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.

(See Instance::ColumnFamilyMap) GC Rules for column family see GcRule)

Examples:

Create table without column family

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

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

Create table with column families and initial splits.

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 |column_families|
  column_families.add('cf1', Google::Cloud::Bigtable::GcRule.max_versions(5))
  column_families.add('cf2', 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)
  )
  column_families.add('cf3', gc_rule)
end

p table

Parameters:

  • instance_id (String) —

    The unique Id of the instance in which to create the table.

  • table_id (String) —

    The name by which the new table should be referred to within the parent instance, e.g., +foobar+

  • column_families (Hash{String => Google::Cloud::Bigtable::ColumnFamily}) —

    (See Table::ColumnFamilyMap) If passed as an empty use code block to add column families.

  • granularity (Symbol) —

    The granularity at which timestamps are stored in this table. Timestamps not matching the granularity will be rejected. Valid values are :MILLIS. If unspecified, the value will be set to :MILLIS

  • initial_splits (Array<String>) —

    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) => "custom".+
      • Tablet 3 : +[customer_1, customer_2) => "customer_1".+
      • Tablet 4 : +[customer_2, other) => "customer_2".+
      • Tablet 5 : +[other, ) => "zz".+ A hash of the same form as Google::Bigtable::Admin::V2::CreateTableRequest::Split can also be provided.

Yields:

  • (column_families) —

    A block for adding column_families.

Yield Parameters:

Returns:



472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
 
# File 'lib/google/cloud/bigtable/project.rb', line 472

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 a specified table and all of its data.

Examples:

Create table with column families and initial splits.

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 in which table is exists.

  • table_id (String) —

    The unique name of the table to be deleted. e.g., +foobar+



506
507
508
509
 
# File 'lib/google/cloud/bigtable/project.rb', line 506

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

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

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



123
124
125
126
127
128
129
 
# File 'lib/google/cloud/bigtable/project.rb', line 123

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) —

    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:



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

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

#modify_column_families(instance_id, table_id, modifications) ⇒ Google::Cloud::Bigtable::Table

Performs a series of column family modifications on the specified table. Either all or none of the modifications will occur before this method returns, but data requests received prior to that point may see a table where only some modifications have taken effect.

Examples:

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

modifications = []
modifications << Google::Cloud::Bigtable::ColumnFamily.create_modification(
  "cf1", Google::Cloud::Bigtable::GcRule.max_age(600))
)

modifications << Google::Cloud::Bigtable::ColumnFamily.update_modification(
  "cf2", Google::Cloud::Bigtable::GcRule.max_versions(5)
)

gc_rule_1 = Google::Cloud::Bigtable::GcRule.max_versions(3)
gc_rule_2 = Google::Cloud::Bigtable::GcRule.max_age(600)
modifications << Google::Cloud::Bigtable::ColumnFamily.update_modification(
  "cf3", Google::Cloud::Bigtable::GcRule.union(gc_rule_1, gc_rule_2)
)

max_age_gc_rule = Google::Cloud::Bigtable::GcRule.max_age(300)
modifications << Google::Cloud::Bigtable::ColumnFamily.update_modification(
  "cf4", Google::Cloud::Bigtable::GcRule.union(max_version_gc_rule)
)

modifications << Google::Cloud::Bigtable::ColumnFamily.drop_modification("cf5")

table = bigtable.modify_column_families("my-instance", "my-table", modifications)

p table.column_families

Parameters:

Returns:



558
559
560
561
562
563
564
565
566
 
# File 'lib/google/cloud/bigtable/project.rb', line 558

def modify_column_families instance_id, table_id, modifications
  ensure_service!
  Table.modify_column_families(
    service,
    instance_id,
    table_id,
    modifications
  )
end

#project_id ⇒ String

The identifier for the Cloud Bigtable project.

Examples:

require "google/cloud"

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

bigtable.project_id #=> "my-project"

Returns:

  • (String) —

    Project id.



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

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?

Get table information.

Examples:

Get table with schema only view

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table("my-instance", "my-table", perform_lookup: true, view: :SCHEMA_VIEW)
if table
  p table.name
  p table.column_families
end

Get table object without calling get table admin api.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

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

Get table with all fields. Clusters states, column families

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table("my-instance", "my-table", view: :FULL, perform_lookup: true)
iftruee
  puts table.name
  p table.column_families
  p table.cluster_states
end

Mutate rows

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

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

entry = table.new_mutation_entry("user-1")
entry.set_cell(
  "cf-1",
  "field-1",
  "XYZ"
  timestamp: Time.now.to_i * 1000 # Time stamp in milli seconds.
).delete_from_column("cf2", "field02")

table.mutate_row(entry)

Read rows using app profile routing

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table("my-instance", "my-table", app_profile_id: "my-app-profile")

table.read_rows(limit: 5).each do |row|
  row
end

Parameters:

  • instance_id (String) —

    Existing instance Id.

  • table_id (String) —

    Existing table Id.

  • view (Symbol) —

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

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

    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. It helps to reduce admin apis calls.

  • app_profile_id (String) —

    The unique identifier for the app profile. Optional. It is 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
390
391
392
393
394
395
396
397
398
399
 
# 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!

  table = if perform_lookup
            grpc = service.get_table(instance_id, table_id, view: view)
            Table.from_grpc(grpc, service, view: view)
          else
            Table.from_path(
              service.table_path(instance_id, table_id),
              service
            )
          end

  table.app_profile_id = app_profile_id
  table
rescue Google::Cloud::NotFoundError
  nil
end

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

List all tables for given instance.

Examples:

Get tables

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:



292
293
294
295
296
 
# File 'lib/google/cloud/bigtable/project.rb', line 292

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