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 an instance, use new or Google::Cloud#bigtable.

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>

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) (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:



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

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. 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. Valid values are :DEVELOPMENT or :PRODUCTION. Default :PRODUCTION instance will created if left blank.

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



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

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|
    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"} A hash in the form of Google::Bigtable::Admin::V2::CreateTableRequest::Split can also be provided.

Yields:

  • (column_families) —

    A block for adding column families.

Yield Parameters:

Returns:



456
457
458
459
460
461
462
463
464
465
466
467
 
# File 'lib/google/cloud/bigtable/project.rb', line 456

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

  • table_id (String) —

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



485
486
487
488
 
# File 'lib/google/cloud/bigtable/project.rb', line 485

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

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

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



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

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:



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

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.



81
82
83
84
 
# File 'lib/google/cloud/bigtable/project.rb', line 81

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
  puts table.name
  puts 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, 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

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_f * 1000000).round(-3) # microseconds
).delete_cells("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|
  p row
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:



370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
 
# File 'lib/google/cloud/bigtable/project.rb', line 370

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:



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

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