Cloud Bigtable API - Class Google::Cloud::Bigtable::Instance (v2.7.1)

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

Instance

Represents a Bigtable instance. Instances are dedicated Bigtable storage resources that contain Bigtable tables.

See Project#instances, Project#instance, and Project#create_instance.

Inherits

  • Object

Example

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

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

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

Methods

#app_profile

def app_profile(app_profile_id) -> Google::Cloud::Bigtable::AppProfile, nil

Gets an app profile in the instance.

See AppProfile#delete and AppProfile#save.

Parameter
  • app_profile_id (String) — The unique name of the requested app profile.
Returns
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

app_profile = instance.app_profile "my-app-profile"

if app_profile
  puts app_profile.name
end

#app_profiles

def app_profiles() -> Array<Google::Cloud::Bigtable::AppProfile>

Lists all app profiles in the instance.

See AppProfile#delete and AppProfile#save.

Returns
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

instance.app_profiles.all do |app_profile|
  puts app_profile.name
end

#cluster

def cluster(cluster_id) -> Google::Cloud::Bigtable::Cluster, nil

Gets a cluster in the instance.

See Cluster#delete and Cluster#save.

Parameter
  • cluster_id (String) — The unique ID of the requested cluster.
Returns
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

cluster = instance.cluster "my-cluster"
puts cluster.cluster_id

#clusters

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

Lists the clusters in the instance.

See Cluster#delete and Cluster#save.

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 that the system should return the next page of data.
Returns
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

instance.clusters.all do |cluster|
  puts cluster.cluster_id
end

#create_app_profile

def create_app_profile(name, routing_policy, description: nil, etag: nil, ignore_warnings: false) -> Google::Cloud::Bigtable::AppProfile

Creates an app profile for the instance with a routing policy. Only one routing policy can applied to the app profile. The policy can be multi-cluster routing or single cluster routing.

Parameters
  • name (String) — Unique ID of the app profile.
  • routing_policy (Google::Cloud::Bigtable::RoutingPolicy) —

    The routing policy for all read/write requests that use this app profile. A value must be explicitly set.

    Routing Policies:

    • MultiClusterRoutingUseAny - Read/write requests may be routed to any cluster in the instance and will fail over to another cluster in the event of transient errors or delays. Choosing this option sacrifices read-your-writes consistency to improve availability.
    • SingleClusterRouting - Unconditionally routes all read/write requests to a specific cluster. This option preserves read-your-writes consistency but does not improve availability. Value contains cluster_id and optional field allow_transactional_writes.
  • description (String) (defaults to: nil) — Description of the use case for this app profile.
  • etag (String) (defaults to: nil) — Strongly validated etag for optimistic concurrency control. Preserve the value returned from GetAppProfile when calling UpdateAppProfile to fail the request if there has been a modification in the meantime. The update_mask of the request need not include etag for this protection to apply. See Wikipedia and RFC 7232 for more details.
  • ignore_warnings (Boolean) (defaults to: false) — If true, ignore safety checks when creating the app profile. Default value is false.
Returns
Examples

Create an app profile with a single cluster routing policy.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

routing_policy = Google::Cloud::Bigtable::AppProfile.single_cluster_routing(
  "my-cluster",
  allow_transactional_writes: true
)

app_profile = instance.create_app_profile(
  "my-app-profile",
  routing_policy,
  description: "App profile for user data instance"
)
puts app_profile.name

Create an app profile with multi-cluster routing policy.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

routing_policy = Google::Cloud::Bigtable::AppProfile.multi_cluster_routing

app_profile = instance.create_app_profile(
  "my-app-profile",
  routing_policy,
  description: "App profile for user data instance"
)
puts app_profile.name

Create app profile and ignore warnings.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

routing_policy = Google::Cloud::Bigtable::AppProfile.multi_cluster_routing

app_profile = instance.create_app_profile(
  "my-app-profile",
  routing_policy,
  description: "App profile for user data instance",
  ignore_warnings: true
)
puts app_profile.name

#create_cluster

def create_cluster(cluster_id, location, nodes: nil, storage_type: nil) -> Google::Cloud::Bigtable::Cluster::Job

Creates a cluster in the instance.

Parameters
  • cluster_id (String) — The ID to be used when referring to the new cluster within its instance.
  • location (String) — The location where this cluster's nodes and storage reside. For best performance, clients should be located as close as possible to this cluster. Example: "us-east-1b"
  • nodes (Integer) (defaults to: nil) — The number of nodes allocated to this cluster. More nodes enable higher throughput and more consistent performance.
  • storage_type (Symbol) (defaults to: nil) —

    Storage type. The type of storage used by this cluster to serve its parent instance's tables. Valid types are:

    • :SSD - Flash (SSD) storage.
    • :HDD - Magnetic drive (HDD).
Returns
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"
job = instance.create_cluster(
  "my-new-cluster",
  "us-east-1b",
  nodes: 3,
  storage_type: :SSD
)

job.done? #=> false

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

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

#create_table

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

Creates a new table in the instance.

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

Parameters
  • name (String) — The name by which the new table should be referred to within the parent instance.
  • 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::Cloud::Bigtable::Admin::V2::CreateTableRequest::Split can also be provided.
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

instance = bigtable.instance "my-instance"

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

Create a table with initial splits and column families.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

initial_splits = ["user-00001", "user-100000", "others"]
table = instance.create_table "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

#creating?

def creating?() -> Boolean

The instance is currently being created and may be destroyed if the creation process encounters an error.

Returns
  • (Boolean)

#delete

def delete() -> Boolean

Permanently deletes the instance from the project.

Returns
  • (Boolean) — Returns true if the instance was deleted.
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"
instance.delete

#development?

def development?() -> Boolean

The instance is meant for development and testing purposes only; it has no performance or uptime guarantees and is not covered by SLA. After a development instance is created, it can be upgraded by updating the instance to type :PRODUCTION. An instance created as a production instance cannot be changed to a development instance. When creating a development instance, nodes on the cluster must not be set. (See #create_cluster.)

Returns
  • (Boolean)

#display_name

def display_name() -> String

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

Returns
  • (String)

#display_name=

def display_name=(value)

Updates the descriptive name for the instance as it appears in UIs. Can be changed at any time, but should be kept globally unique to avoid confusion.

Parameter
  • value (String) — The descriptive name for the instance.

#instance_id

def instance_id() -> String

The unique identifier for the instance.

Returns
  • (String)

#labels

def labels() -> Hash{String=>String}

Gets the Cloud Labels for the instance.

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, to control how resource metrics are aggregated, and 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?.
  • Label values must be between 0 and 63 characters long and must conform to the regular expression (a-z?)?.
  • No more than 64 labels can be associated with a given resource.
Returns
  • (Hash{String=>String}) — The label keys and values in a hash.

#labels=

def labels=(labels)

Sets the Cloud Labels for the instance.

Parameter
  • labels (Hash{String=>String}) — The Cloud Labels.

#path

def path() -> String

The full path for the instance resource. Values are of the form projects/<project_id>/instances/<instance_id>.

Returns
  • (String)

#policy

def policy() { |policy| ... } -> Policy

Gets the Cloud IAM access control policy for the instance.

Yields
  • (policy) — A block for updating the policy. The latest policy will be read from the Bigtable service and passed to the block. After the block completes, the modified policy will be written to the service.
Yield Parameter
  • policy (Policy) — the current Cloud IAM Policy for this instance.
Returns
  • (Policy) — The current Cloud IAM Policy for the instance.
Examples 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"
policy = instance.policy

Update the policy by passing a block.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new
instance = bigtable.instance "my-instance"

instance.policy do |p|
  p.add "roles/owner", "user:owner@example.com"
end # 2 API calls

#policy=

def policy=(new_policy) -> Policy
Alias Of: #update_policy

Updates the Cloud IAM access control policy for the instance. The policy should be read from #policy. See Policy for an explanation of the policy etag property and how to modify policies.

You can also update the policy by passing a block to #policy, which will call this method internally after the block completes.

Parameter
  • new_policy (Policy) — a new or modified Cloud IAM Policy for this instance
Returns
  • (Policy) — The policy returned by the API update operation.
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

policy = instance.policy
policy.add "roles/owner", "user:owner@example.com"
updated_policy = instance.update_policy policy

puts updated_policy.roles

#production?

def production?() -> Boolean

An instance meant for production use. Requires that nodes must be set on the cluster. (See #create_cluster.)

Returns
  • (Boolean)

#project_id

def project_id() -> String

The unique identifier for the project to which the instance belongs.

Returns
  • (String)

#ready?

def ready?() -> Boolean

The instance has been successfully created and can serve requests to its tables.

Returns
  • (Boolean)

#reload!

def reload!() -> Google::Cloud::Bigtable::Instance

Reloads instance data.

Returns

#save

def save() -> Google::Cloud::Bigtable::Instance::Job
Aliases

Updates the instance.

Updatable attributes are:

  • display_name - The descriptive name for the instance.
  • type - :DEVELOPMENT type instance can be upgraded to :PRODUCTION instance. An instance created as a production instance cannot be changed to a development instance.
  • labels - Cloud Labels are a flexible and lightweight mechanism for organizing cloud resources.
Returns
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"
instance.display_name = "My app dev instance"  # Set display name
instance.labels = { env: "dev", data: "users" }
job = instance.save

job.done? #=> false

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

if job.error?
  puts job.error
else
  instance = job.instance
  puts instance.name
  puts instance.labels
end

#state

def state() -> Symbol

The current instance state. Possible values are :CREATING, :READY, :STATE_NOT_KNOWN.

Returns
  • (Symbol)

#table

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

Gets metadata information of a table in the instance.

Parameters
  • view (Symbol) (defaults to: nil) —

    The view to be applied to the returned tables' fields. Defaults to SCHEMA_VIEW if unspecified. 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) (defaults to: nil) — Creates 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 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

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

# Name-only view
table = instance.table "my-table", view: :NAME_ONLY, perform_lookup: true
puts table.name

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(
  "cf1",
  "field1",
  "XYZ",
  timestamp: (Time.now.to_f * 1_000_000).round(-3) # microseconds
).delete_cells "cf2", "field02"

table.mutate_row entry

#tables

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

Lists all tables in the instance.

See Table#delete and Table#save.

Returns
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

# Default name-only view
instance.tables.all do |table|
  puts table.name
end

#test_iam_permissions

def test_iam_permissions(*permissions) -> Array<String>

Tests the specified permissions against the Cloud IAM access control policy.

Parameter
  • permissions (String, Array<String>) —

    permissions The set of permissions to check access for. Permissions with wildcards (such as * or bigtable.*) are not allowed. See Access Control.

    Some of the permissions that can be checked on a instance are:

    • bigtable.instances.create
    • bigtable.instances.list
    • bigtable.instances.get
    • bigtable.tables.create
    • bigtable.tables.delete
    • bigtable.tables.get
    • bigtable.tables.list
Returns
  • (Array<String>) — The permissions that are configured for the policy.
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

permissions = instance.test_iam_permissions(
  "bigtable.instances.get",
  "bigtable.instances.update"
)
permissions.include? "bigtable.instances.get" #=> true
permissions.include? "bigtable.instances.update" #=> false

#type

def type() -> Symbol

Instance type. Possible values include :DEVELOPMENT and :PRODUCTION.

Returns
  • (Symbol)

#type=

def type=(instance_type)

Sets the instance type.

Valid values are :DEVELOPMENT and :PRODUCTION. After a development instance is created, it can be upgraded by updating the instance to type :PRODUCTION. An instance created as a production instance cannot be changed to a development instance.

Parameter
  • instance_type (Symbol)
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

instance.development? # true
instance.type = :PRODUCTION
instance.development? # false
instance.production? # true

#update

def update() -> Google::Cloud::Bigtable::Instance::Job
Alias Of: #save

Updates the instance.

Updatable attributes are:

  • display_name - The descriptive name for the instance.
  • type - :DEVELOPMENT type instance can be upgraded to :PRODUCTION instance. An instance created as a production instance cannot be changed to a development instance.
  • labels - Cloud Labels are a flexible and lightweight mechanism for organizing cloud resources.
Returns
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"
instance.display_name = "My app dev instance"  # Set display name
instance.labels = { env: "dev", data: "users" }
job = instance.save

job.done? #=> false

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

if job.error?
  puts job.error
else
  instance = job.instance
  puts instance.name
  puts instance.labels
end

#update_policy

def update_policy(new_policy) -> Policy
Aliases

Updates the Cloud IAM access control policy for the instance. The policy should be read from #policy. See Policy for an explanation of the policy etag property and how to modify policies.

You can also update the policy by passing a block to #policy, which will call this method internally after the block completes.

Parameter
  • new_policy (Policy) — a new or modified Cloud IAM Policy for this instance
Returns
  • (Policy) — The policy returned by the API update operation.
Example 
require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"

policy = instance.policy
policy.add "roles/owner", "user:owner@example.com"
updated_policy = instance.update_policy policy

puts updated_policy.roles