class Google::Cloud::Bigtable::Table

# Table

A collection of user data indexed by row, column, and timestamp. Each table is served using the resources of its parent cluster.

@example

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

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

if table.exists?
  p "Table exists."
else
  p "Table does not exist"
end

Constants

FIELDS_BY_VIEW

Attributes

app_profile_id[RW]

@return [String] App profile ID for request routing.

grpc[RW]

@private The current gRPC resource, for testing only.

loaded_views[R]

@private The current loaded_views, for testing only. See check_view_and_load, below.

service[RW]

@private The gRPC Service object.

Public Class Methods

create(service, instance_id, table_id, column_families: nil, granularity: nil, initial_splits: nil) { |column_families| ... } click to toggle source

@private Creates a table.

@param service [Google::Cloud::Bigtable::Service] @param instance_id [String] @param table_id [String] @param column_families [ColumnFamilyMap] @param granularity [Symbol] @param initial_splits [Array<String>] @yield [column_families] A block for adding column_families. @yieldparam [ColumnFamilyMap]

@return [Google::Cloud::Bigtable::Table]

# File lib/google/cloud/bigtable/table.rb, line 461
def self.create service, instance_id, table_id, column_families: nil, granularity: nil, initial_splits: nil
  if column_families
    # create an un-frozen and duplicate object
    column_families = ColumnFamilyMap.from_grpc column_families.to_grpc
  end
  column_families ||= ColumnFamilyMap.new

  yield column_families if block_given?

  table = Google::Cloud::Bigtable::Admin::V2::Table.new({
    column_families: column_families.to_grpc_hash,
    granularity:     granularity
  }.delete_if { |_, v| v.nil? })

  grpc = service.create_table instance_id, table_id, table, initial_splits: initial_splits
  from_grpc grpc, service, view: :SCHEMA_VIEW
end
from_grpc(grpc, service, view: new grpc, service, view: view) click to toggle source

@private Creates a new Table instance from a Google::Cloud::Bigtable::Admin::V2::Table.

@param grpc [Google::Cloud::Bigtable::Admin::V2::Table] @param service [Google::Cloud::Bigtable::Service] @param view [Symbol] View type. @return [Google::Cloud::Bigtable::Table]

# File lib/google/cloud/bigtable/table.rb, line 662
def self.from_grpc grpc, service, view:
  new grpc, service, view: view
end
from_path(path, service) click to toggle source

@private Creates a new Table object from table path.

@param path [String] Table path.

Formatted table path
+projects/<project>/instances/<instance>/tables/<table>+

@param service [Google::Cloud::Bigtable::Service] @return [Google::Cloud::Bigtable::Table]

# File lib/google/cloud/bigtable/table.rb, line 675
def self.from_path path, service
  grpc = Google::Cloud::Bigtable::Admin::V2::Table.new name: path
  new grpc, service, view: :NAME_ONLY
end
new(grpc, service, view: @grpc = grpc) click to toggle source

@private

Creates a new Table instance.

# File lib/google/cloud/bigtable/table.rb, line 75
def initialize grpc, service, view:
  @grpc = grpc
  @service = service
  raise ArgumentError, "view must not be nil" if view.nil?
  @loaded_views = Set[view]
end

Public Instance Methods

check_consistency(token) click to toggle source

Checks replication consistency based on a consistency token. Replication is considered consistent if replication has caught up based on the conditions specified in the token and the check request. @param token [String] Consistency token @return [Boolean] `true` if replication is consistent

@example

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"
table = instance.table "my-table"

token = "l947XelENinaxJQP0nnrZJjHnAF7YrwW8HCJLotwrF"

if table.check_consistency token
  puts "Replication is consistent"
end
# File lib/google/cloud/bigtable/table.rb, line 524
def check_consistency token
  ensure_service!
  response = service.check_consistency instance_id, name, token
  response.consistent
end
cluster_states() click to toggle source

Returns an array of {Table::ClusterState} objects that map cluster ID to per-cluster table state.

If it could not be determined whether or not the table has data in a particular cluster (for example, if its zone is unavailable), then the cluster state's `replication_state` will be `UNKNOWN`.

Reloads the table with the `FULL` view type to retrieve the cluster states data, unless the table was previously loaded with view type `ENCRYPTION_VIEW`, `REPLICATION_VIEW` or `FULL`.

@return [Array<Google::Cloud::Bigtable::Table::ClusterState>]

@example Retrieve a table with cluster states.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table "my-instance", "my-table", view: :FULL, perform_lookup: true

table.cluster_states.each do |cs|
  puts cs.cluster_name
  puts cs.replication_state
  puts cs.encryption_infos.first.encryption_type
end
# File lib/google/cloud/bigtable/table.rb, line 169
def cluster_states
  check_view_and_load :FULL, skip_if: [:ENCRYPTION_VIEW, :REPLICATION_VIEW]
  @grpc.cluster_states.map do |name, state_grpc|
    ClusterState.from_grpc state_grpc, name
  end
end
column_families() { |column_families| ... } click to toggle source

Returns a frozen object containing the column families configured for the table, mapped by column family name.

Reloads the table if necessary to retrieve the column families data, since it is only available in a table with view type `SCHEMA_VIEW` or `FULL`. Previously loaded data is retained.

Also accepts a block for making modifications to the table's column families. After the modifications are completed, the table will be updated with the changes, and the updated column families will be returned.

@see cloud.google.com/bigtable/docs/garbage-collection Garbage collection

@yield [column_families] A block for modifying the table's column

families. Applies multiple column modifications. 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.

@yieldparam [ColumnFamilyMap] column_families

A mutable object containing the column families for the table,
mapped by column family name. Any changes made to this object will
be stored in API.

@return [ColumnFamilyMap] A frozen object containing the

column families for the table, mapped by column family name.

@example

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table "my-instance", "my-table", perform_lookup: true

table.column_families.each do |name, cf|
  puts name
  puts cf.gc_rule
end

# Get a column family by name
cf1 = table.column_families["cf1"]

@example Modify the table's column families

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table "my-instance", "my-table", perform_lookup: true

table.column_families do |cfm|
  cfm.add "cf4", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600)
  cfm.add "cf5", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5)

  rule_1 = Google::Cloud::Bigtable::GcRule.max_versions 3
  rule_2 = Google::Cloud::Bigtable::GcRule.max_age 600
  rule_union = Google::Cloud::Bigtable::GcRule.union rule_1, rule_2
  cfm.update "cf2", gc_rule: rule_union

  cfm.delete "cf3"
end

puts table.column_families["cf3"] #=> nil
# File lib/google/cloud/bigtable/table.rb, line 241
def column_families
  check_view_and_load :SCHEMA_VIEW

  if block_given?
    column_families = ColumnFamilyMap.from_grpc @grpc.column_families
    yield column_families
    modifications = column_families.modifications @grpc.column_families
    @grpc = service.modify_column_families instance_id, table_id, modifications if modifications.any?
  end

  ColumnFamilyMap.from_grpc(@grpc.column_families).freeze
end
delete() click to toggle source

Permanently deletes the table from a instance.

@return [Boolean] Returns `true` if the table was deleted.

@example

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table "my-instance", "my-table"
table.delete
# File lib/google/cloud/bigtable/table.rb, line 403
def delete
  ensure_service!
  service.delete_table instance_id, name
  true
end
delete_all_rows(timeout: nil) click to toggle source

Deletes all rows.

@param timeout [Integer] Call timeout in seconds.

Use in case of insufficient deadline for DropRowRange, then
try again with a longer request deadline.

@return [Boolean]

@example

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"
table = instance.table "my-table"
table.delete_all_rows

# With timeout
table.delete_all_rows timeout: 120 # 120 seconds.
# File lib/google/cloud/bigtable/table.rb, line 595
def delete_all_rows timeout: nil
  drop_row_range delete_all_data: true, timeout: timeout
end
delete_rows_by_prefix(prefix, timeout: nil) click to toggle source

Deletes rows using row key prefix.

@param prefix [String] Row key prefix (for example, “user”). @param timeout [Integer] Call timeout in seconds. @return [Boolean] @example

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

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

table.delete_rows_by_prefix "user-100"

# With timeout
table.delete_rows_by_prefix "user-1", timeout: 120 # 120 seconds.
# File lib/google/cloud/bigtable/table.rb, line 617
def delete_rows_by_prefix prefix, timeout: nil
  drop_row_range row_key_prefix: prefix, timeout: timeout
end
drop_row_range(row_key_prefix: nil, delete_all_data: nil, timeout: nil) click to toggle source

Drops row range by row key prefix or deletes all.

@param row_key_prefix [String] Row key prefix (for example, “user”). @param delete_all_data [Boolean] @param timeout [Integer] Call timeout in seconds. @return [Boolean]

@example

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

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

# Delete rows using row key prefix.
table.drop_row_range row_key_prefix: "user-100"

# Delete all data With timeout
table.drop_row_range delete_all_data: true, timeout: 120 # 120 seconds.
# File lib/google/cloud/bigtable/table.rb, line 642
def drop_row_range row_key_prefix: nil, delete_all_data: nil, timeout: nil
  ensure_service!
  service.drop_row_range(
    instance_id,
    name,
    row_key_prefix:             row_key_prefix,
    delete_all_data_from_table: delete_all_data,
    timeout:                    timeout
  )
  true
end
exists?() click to toggle source

Checks to see if the table exists.

@return [Boolean]

@example

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

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

if table.exists?
  p "Table exists."
else
  p "Table does not exist"
end

@example Using Cloud Bigtable instance

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"
table = instance.table "my-table"

if table.exists?
  p "Table exists."
else
  p "Table does not exist"
end
# File lib/google/cloud/bigtable/table.rb, line 441
def exists?
  !service.get_table(instance_id, name, view: :NAME_ONLY).nil?
rescue Google::Cloud::NotFoundError
  false
end
generate_consistency_token() click to toggle source

Generates a consistency token for a table. The token can be used in CheckConsistency to check whether mutations to the table that finished before this call started have been replicated. The tokens will be available for 90 days.

@return [String] The generated consistency token

@example

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

instance = bigtable.instance "my-instance"
table = instance.table "my-table"

table.generate_consistency_token # "l947XelENinaxJQP0nnrZJjHnAF7YrwW8HCJLotwrF"
# File lib/google/cloud/bigtable/table.rb, line 497
def generate_consistency_token
  ensure_service!
  response = service.generate_consistency_token instance_id, name
  response.consistency_token
end
granularity() click to toggle source

The granularity (e.g. `MILLIS`, `MICROS`) at which timestamps are stored in this table. Timestamps not matching the granularity will be rejected. If unspecified at creation time, the value will be set to `MILLIS`.

Reloads the table if necessary to retrieve the column families data, since it is only available in a table with view type `SCHEMA_VIEW` or `FULL`. Previously loaded data is retained.

@return [Symbol]

# File lib/google/cloud/bigtable/table.rb, line 265
def granularity
  check_view_and_load :SCHEMA_VIEW
  @grpc.granularity
end
granularity_millis?() click to toggle source

The table keeps data versioned at a granularity of 1 ms.

@return [Boolean]

# File lib/google/cloud/bigtable/table.rb, line 275
def granularity_millis?
  granularity == :MILLIS
end
instance_id() click to toggle source

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

@return [String]

# File lib/google/cloud/bigtable/table.rb, line 96
def instance_id
  @grpc.name.split("/")[3]
end
name() click to toggle source

The unique identifier for the table.

@return [String]

# File lib/google/cloud/bigtable/table.rb, line 105
def name
  @grpc.name.split("/")[5]
end
Also aliased as: table_id
path() click to toggle source

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

@return [String]

# File lib/google/cloud/bigtable/table.rb, line 116
def path
  @grpc.name
end
policy() { |policy| ... } click to toggle source

Gets the [Cloud IAM](cloud.google.com/iam/) access control policy for the table.

@see cloud.google.com/bigtable/docs/access-control

@yield [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.

@yieldparam [Policy] policy the current Cloud IAM Policy for this

table.

@return [Policy] The current Cloud IAM Policy for the table.

@example

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table "my-instance", "my-table", perform_lookup: true
policy = table.policy

@example Update the policy by passing a block.

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table "my-instance", "my-table", perform_lookup: true

table.policy do |p|
  p.add "roles/owner", "user:owner@example.com"
end # 2 API calls
# File lib/google/cloud/bigtable/table.rb, line 313
def policy
  ensure_service!
  grpc = service.get_table_policy instance_id, name
  policy = Policy.from_grpc grpc
  return policy unless block_given?
  yield policy
  update_policy policy
end
policy=(new_policy)
Alias for: update_policy
project_id() click to toggle source

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

@return [String]

# File lib/google/cloud/bigtable/table.rb, line 87
def project_id
  @grpc.name.split("/")[1]
end
reload!(view: nil) click to toggle source

Reloads table data with the provided `view`, or with `SCHEMA_VIEW` if none is provided. Previously loaded data is not retained.

@param view [Symbol] Table view type.

Default view type is `: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.

@return [Google::Cloud::Bigtable::Table]

# File lib/google/cloud/bigtable/table.rb, line 135
def reload! view: nil
  view ||= :SCHEMA_VIEW
  @grpc = service.get_table instance_id, name, view: view
  @loaded_views = Set[view]
  self
end
table_id()
Alias for: name
test_iam_permissions(*permissions) click to toggle source

Tests the specified permissions against the [Cloud IAM](cloud.google.com/iam/) access control policy.

@see cloud.google.com/iam/docs/managing-policies Managing Policies @see cloud.google.com/bigtable/docs/access-control Access Control

@param 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](https://cloud.google.com/bigtable/docs/access-control).

@return [Array<String>] The permissions that are configured for the policy.

@example

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table "my-instance", "my-table", perform_lookup: true

permissions = table.test_iam_permissions(
  "bigtable.tables.delete",
  "bigtable.tables.get"
)
permissions.include? "bigtable.tables.delete" #=> false
permissions.include? "bigtable.tables.get" #=> true
# File lib/google/cloud/bigtable/table.rb, line 384
def test_iam_permissions *permissions
  ensure_service!
  grpc = service.test_table_permissions instance_id, name, permissions.flatten
  grpc.permissions.to_a
end
update_policy(new_policy) click to toggle source

Updates the [Cloud IAM](cloud.google.com/iam/) access control policy for the table. The policy should be read from {#policy}. See {Google::Cloud::Bigtable::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.

@param new_policy [Policy] a new or modified Cloud IAM Policy for this

table

@return [Policy] The policy returned by the API update operation.

@example

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table "my-instance", "my-table", perform_lookup: true

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

puts updated_policy.roles
# File lib/google/cloud/bigtable/table.rb, line 349
def update_policy new_policy
  ensure_service!
  grpc = service.set_table_policy instance_id, name, new_policy.to_grpc
  Policy.from_grpc grpc
end
Also aliased as: policy=
wait_for_replication(timeout: 600, check_interval: 5) click to toggle source

Wait for replication to check replication consistency. Checks replication consistency by generating a consistency token and making the `check_consistency` API call 5 times (by default). If the response is consistent, returns `true`. Otherwise tries again repeatedly until the timeout. If the check does not succeed by the timeout, returns `false`.

@param timeout [Integer]

Timeout in seconds. Defaults value is 600 seconds.

@param check_interval [Integer]

Consistency check interval in seconds. Default is 5 seconds.

@return [Boolean] `true` if replication is consistent

@example

require "google/cloud/bigtable"

bigtable = Google::Cloud::Bigtable.new

table = bigtable.table "my-instance", "my-table", perform_lookup: true

if table.wait_for_replication
  puts "Replication done"
end

# With custom timeout and interval
if table.wait_for_replication timeout: 300, check_interval: 10
  puts "Replication done"
end
# File lib/google/cloud/bigtable/table.rb, line 560
def wait_for_replication timeout: 600, check_interval: 5
  raise InvalidArgumentError, "'check_interval' cannot be greater than timeout" if check_interval > timeout
  token = generate_consistency_token
  status = false
  start_at = Time.now

  loop do
    status = check_consistency token

    break if status || (Time.now - start_at) >= timeout
    sleep check_interval
  end
  status
end

Protected Instance Methods

check_view_and_load(view, skip_if: nil) click to toggle source

@private

Checks and reloads table with expected view. Performs additive updates to fields specified by the given view. @param view [Symbol] The view type to load. If already loaded, no load is performed. @param skip_if [Symbol] Additional satisfying view types. If already loaded, no load is performed.

# File lib/google/cloud/bigtable/table.rb, line 703
def check_view_and_load view, skip_if: nil
  ensure_service!

  skip = Set.new skip_if
  skip << view
  skip << :FULL
  return if (@loaded_views & skip).any?

  grpc = service.get_table instance_id, table_id, view: view
  @loaded_views << view

  FIELDS_BY_VIEW[view].each do |field|
    case grpc[field]
    when Google::Protobuf::Map
      # Special handling for column_families:
      # Replace contents of existing Map since setting the new Map won't work.
      # See https://github.com/protocolbuffers/protobuf/issues/4969
      @grpc[field].clear
      grpc[field].each { |k, v| @grpc[field][k] = v }
    else
      @grpc[field] = grpc[field]
    end
  end
end
ensure_service!() click to toggle source

@private Raises an error unless an active connection to the service is available.

# File lib/google/cloud/bigtable/table.rb, line 686
def ensure_service!
  raise "Must have active connection to service" unless service
end