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
@return [String] App profile ID for request routing.
@private The current gRPC resource, for testing only.
@private The current loaded_views
, for testing only. See check_view_and_load
, below.
@private The gRPC Service
object.
Public Class Methods
@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
@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
@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
@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
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
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
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
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
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
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
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
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
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
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
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
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
The unique identifier for the table.
@return [String]
# File lib/google/cloud/bigtable/table.rb, line 105 def name @grpc.name.split("/")[5] end
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
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
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
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
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
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
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
@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
@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