google-cloud-bigtable 2.4.1 → 2.6.2

data/lib/google/cloud/bigtable/row_range.rb

@@ -30,7 +30,7 @@ module Google
       #   require "google/cloud/bigtable"
       #
       #   bigtable = Google::Cloud::Bigtable.new
-      #   table = bigtable.table("my-instance", "my-table")
+      #   table = bigtable.table "my-instance", "my-table"
       #
       #   # Range that includes all row keys including "user-001" to "user-005"
       #   table.new_row_range.from("user-001").to("user-005", inclusive: true)
@@ -39,19 +39,19 @@ module Google
       #   table.new_row_range.from("user-001").to("user-010")
       #
       #   # Range that includes all row keys including "user-001" up until end of the row keys.
-      #   table.new_row_range.from("user-001")
+      #   table.new_row_range.from "user-001"
       #
       #   # Range that includes all row keys exclusive "user-001" up until end of the row keys.
-      #   table.new_row_range.from("user-001", inclusive: false)
+      #   table.new_row_range.from "user-001", inclusive: false
       #
       #   # Range with unbounded from and the exclusive end "user-010"
-      #   table.new_row_range.to("user-010")
+      #   table.new_row_range.to "user-010"
       #
       #   # Range that includes all row keys including from and end row keys "user-001", "user-010"
-      #   table.new_row_range.between("user-001", "user-010")
+      #   table.new_row_range.between "user-001", "user-010"
       #
       #   # Range that includes all row keys including "user-001" up until "user-010"
-      #   table.new_row_range.of("user-001", "user-010")
+      #   table.new_row_range.of "user-001", "user-010"
       #
       class RowRange
         # @private
@@ -72,17 +72,17 @@ module Google
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
-        #   range = table.new_row_range.from("key-001")
+        #   range = table.new_row_range.from "key-001"
         #
         # @example Exclusive lower bound.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
-        #   range = table.new_row_range.from("key-001", inclusive: false)
+        #   range = table.new_row_range.from "key-001", inclusive: false
         #
         def from key, inclusive: true
           if inclusive
@@ -105,17 +105,17 @@ module Google
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
-        #   range = table.new_row_range.to("key-001", inclusive: true)
+        #   range = table.new_row_range.to "key-001", inclusive: true
         #
         # @example Exclusive upper bound.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
-        #   range = table.new_row_range.to("key-001")
+        #   range = table.new_row_range.to "key-001"
         #
         def to key, inclusive: false
           if inclusive
@@ -138,9 +138,9 @@ module Google
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
-        #   range = table.new_row_range.between("key-001", "key-010")
+        #   range = table.new_row_range.between "key-001", "key-010"
         #
         def between from_key, to_key
           from(from_key).to(to_key, inclusive: true)
@@ -158,9 +158,9 @@ module Google
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
-        #   range = table.new_row_range.of("key-001", "key-010")
+        #   range = table.new_row_range.of "key-001", "key-010"
         #
         def of from_key, to_key
           from(from_key).to(to_key)

data/lib/google/cloud/bigtable/sample_row_key.rb

@@ -42,7 +42,7 @@ module Google
       #
       #   bigtable = Google::Cloud::Bigtable.new
       #
-      #   table = bigtable.table("my-instance", "my-table")
+      #   table = bigtable.table "my-instance", "my-table"
       #
       #   table.sample_row_keys.each do |r|
       #     p r

data/lib/google/cloud/bigtable/service.rb

@@ -752,17 +752,20 @@ module Google
         # Create a new table by restoring from a completed backup.
         #
         # @param table_id [String] The table ID for the new table. This table must not yet exist.
-        # @param instance_id [String] The instance ID for the source backup. The table will be created in this instance.
+        # @param instance_id [String] The instance ID for the source backup. The table will be created in this instance
+        #   if table_instance_id is not provided.
         # @param cluster_id [String] The cluster ID for the source backup.
         # @param backup_id [String] The backup ID for the source backup.
+        # @param table_instance_id [String] The instance ID for the table, if different from instance_id. Optional.
         #
         # @return [Gapic::Operation] The {Google::Longrunning::Operation#metadata metadata} field type is
         #   {Google::Cloud::Bigtable::Admin::RestoreTableMetadata RestoreTableMetadata}. The
         #   {Google::Longrunning::Operation#response response} type is
         #   {Google::Cloud::Bigtable::Admin::V2::Table Table}, if successful.
         #
-        def restore_table table_id, instance_id, cluster_id, backup_id
-          tables.restore_table parent:   instance_path(instance_id),
+        def restore_table table_id, instance_id, cluster_id, backup_id, table_instance_id: nil
+          table_instance_id ||= instance_id
+          tables.restore_table parent:   instance_path(table_instance_id),
                                table_id: table_id,
                                backup:   backup_path(instance_id, cluster_id, backup_id)
         end

data/lib/google/cloud/bigtable/status.rb

@@ -35,12 +35,12 @@ module Google
       #
       #   bigtable = Google::Cloud::Bigtable.new
       #
-      #   table = bigtable.table("my-instance", "my-table")
+      #   table = bigtable.table "my-instance", "my-table"
       #
       #   entries = []
       #   entries << table.new_mutation_entry("row-1").set_cell("cf1", "field1", "XYZ")
       #   entries << table.new_mutation_entry("row-2").set_cell("cf1", "field1", "ABC")
-      #   responses = table.mutate_rows(entries)
+      #   responses = table.mutate_rows entries
       #
       #   responses.each do |response|
       #     puts response.status.description

data/lib/google/cloud/bigtable/table.rb

@@ -37,7 +37,7 @@ module Google
       #
       #   bigtable = Google::Cloud::Bigtable.new
       #
-      #   table = bigtable.table("my-instance", "my-table")
+      #   table = bigtable.table "my-instance", "my-table"
       #
       #   if table.exists?
       #     p "Table exists."
@@ -140,19 +140,34 @@ module Google
         end
 
         ##
-        # Map from cluster ID to per-cluster table state.
+        # 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
-        # there will be an entry for the cluster with UNKNOWN `replication_status`.
+        # the cluster state's `replication_state` will be `UNKNOWN`.
         #
-        # Reloads the table if necessary to retrieve the cluster states data,
-        # since it is only available in a table with view type `REPLICATION_VIEW`
-        # or `FULL`. Previously loaded data is retained.
+        # 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
+        #
         def cluster_states
-          check_view_and_load :REPLICATION_VIEW
+          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
@@ -192,7 +207,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #   table = bigtable.table "my-instance", "my-table", perform_lookup: true
         #
         #   table.column_families.each do |name, cf|
         #     puts name
@@ -207,15 +222,15 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #   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)
+        #     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"
@@ -281,7 +296,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #   table = bigtable.table "my-instance", "my-table", perform_lookup: true
         #   policy = table.policy
         #
         # @example Update the policy by passing a block.
@@ -289,10 +304,10 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #   table = bigtable.table "my-instance", "my-table", perform_lookup: true
         #
         #   table.policy do |p|
-        #     p.add("roles/owner", "user:owner@example.com")
+        #     p.add "roles/owner", "user:owner@example.com"
         #   end # 2 API calls
         #
         def policy
@@ -323,11 +338,11 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #   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)
+        #   policy.add "roles/owner", "user:owner@example.com"
+        #   updated_policy = table.update_policy policy
         #
         #   puts updated_policy.roles
         #
@@ -357,7 +372,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #   table = bigtable.table "my-instance", "my-table", perform_lookup: true
         #
         #   permissions = table.test_iam_permissions(
         #     "bigtable.tables.delete",
@@ -382,7 +397,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #   table.delete
         #
         def delete
@@ -401,7 +416,7 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
         #   if table.exists?
         #     p "Table exists."
@@ -414,8 +429,8 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
-        #   table = instance.table("my-table")
+        #   instance = bigtable.instance "my-instance"
+        #   table = instance.table "my-table"
         #
         #   if table.exists?
         #     p "Table exists."
@@ -474,8 +489,8 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
-        #   table = instance.table("my-table")
+        #   instance = bigtable.instance "my-instance"
+        #   table = instance.table "my-table"
         #
         #   table.generate_consistency_token # "l947XelENinaxJQP0nnrZJjHnAF7YrwW8HCJLotwrF"
         #
@@ -497,12 +512,12 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
-        #   table = instance.table("my-table")
+        #   instance = bigtable.instance "my-instance"
+        #   table = instance.table "my-table"
         #
         #   token = "l947XelENinaxJQP0nnrZJjHnAF7YrwW8HCJLotwrF"
         #
-        #   if table.check_consistency(token)
+        #   if table.check_consistency token
         #     puts "Replication is consistent"
         #   end
         #
@@ -531,14 +546,14 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table", perform_lookup: true)
+        #   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)
+        #   if table.wait_for_replication timeout: 300, check_interval: 10
         #     puts "Replication done"
         #   end
         #
@@ -570,12 +585,12 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   instance = bigtable.instance("my-instance")
-        #   table = instance.table("my-table")
+        #   instance = bigtable.instance "my-instance"
+        #   table = instance.table "my-table"
         #   table.delete_all_rows
         #
         #   # With timeout
-        #   table.delete_all_rows(timeout: 120) # 120 seconds.
+        #   table.delete_all_rows timeout: 120 # 120 seconds.
         #
         def delete_all_rows timeout: nil
           drop_row_range delete_all_data: true, timeout: timeout
@@ -592,12 +607,12 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
-        #   table.delete_rows_by_prefix("user-100")
+        #   table.delete_rows_by_prefix "user-100"
         #
         #   # With timeout
-        #   table.delete_rows_by_prefix("user-1", timeout: 120) # 120 seconds.
+        #   table.delete_rows_by_prefix "user-1", timeout: 120 # 120 seconds.
         #
         def delete_rows_by_prefix prefix, timeout: nil
           drop_row_range row_key_prefix: prefix, timeout: timeout
@@ -616,13 +631,13 @@ module Google
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
-        #   table = bigtable.table("my-instance", "my-table")
+        #   table = bigtable.table "my-instance", "my-table"
         #
         #   # Delete rows using row key prefix.
-        #   table.drop_row_range(row_key_prefix: "user-100")
+        #   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.
+        #   table.drop_row_range delete_all_data: true, timeout: 120 # 120 seconds.
         #
         def drop_row_range row_key_prefix: nil, delete_all_data: nil, timeout: nil
           ensure_service!
@@ -674,19 +689,24 @@ module Google
 
         FIELDS_BY_VIEW = {
           SCHEMA_VIEW:      ["granularity", "column_families"],
+          ENCRYPTION_VIEW:  ["cluster_states"],
           REPLICATION_VIEW: ["cluster_states"],
           FULL:             ["granularity", "column_families", "cluster_states"]
         }.freeze
 
         # @private
         #
-        # Checks and reloads table with expected view and sets fields.
-        # @param view [Symbol] Expected view type.
+        # 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.
         #
-        def check_view_and_load view
+        def check_view_and_load view, skip_if: nil
           ensure_service!
 
-          return if @loaded_views.include?(view) || @loaded_views.include?(:FULL)
+          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
@@ -694,6 +714,9 @@ module Google
           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

data/lib/google/cloud/bigtable/table/cluster_state.rb

@@ -15,6 +15,8 @@
 # limitations under the License.
 
 
+require "google/cloud/bigtable/encryption_info"
+
 module Google
   module Cloud
     module Bigtable
@@ -23,6 +25,20 @@ module Google
         # Table::ClusterState is the state of a table's data in a particular cluster.
         #
         # @attr [String] cluster_name The name of the cluster.
+        #
+        # @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
+        #
         class ClusterState
           attr_reader :cluster_name
 
@@ -36,7 +52,7 @@ module Google
 
           ##
           # The state of replication for the table in this cluster.
-          #   Valid values are:
+          #   Valid values include:
           #   * `:INITIALIZING` - The cluster was recently created.
           #   * `:PLANNED_MAINTENANCE` - The table is temporarily unable to serve.
           #   * `:UNPLANNED_MAINTENANCE` - The table is temporarily unable to serve.
@@ -45,6 +61,10 @@ module Google
           #     after a restore, and is being optimized for performance. When
           #     optimizations are complete, the table will transition to `READY`
           #     state.
+          #   * `:STATE_NOT_KNOWN` - If replication state is not present in the object
+          #      because the table view is not `REPLICATION_VIEW` or `FULL`.
+          #   * `:UNKNOWN` - If it could not be determined whether or not the table
+          #     has data in a particular cluster (for example, if its zone is unavailable.)
           #
           # @return [Symbol] The state of replication.
           #
@@ -57,7 +77,8 @@ module Google
           # over pre-existing data from other clusters before it can begin
           # receiving live replication updates and serving.
           #
-          # @return [Boolean] `true` if the table in this cluster is initializing.
+          # @return [Boolean] `true` if the value of {#replication_state} is `INITIALIZING`,
+          #   `false` otherwise.
           #
           def initializing?
             replication_state == :INITIALIZING
@@ -67,8 +88,8 @@ module Google
           # The table is temporarily unable to serve
           # requests from this cluster due to planned internal maintenance.
           #
-          # @return [Boolean] `true` if the table in this cluster is in planned
-          #   maintenance.
+          # @return [Boolean] `true` if the value of {#replication_state} is `PLANNED_MAINTENANCE`,
+          #   `false` otherwise.
           #
           def planned_maintenance?
             replication_state == :PLANNED_MAINTENANCE
@@ -78,8 +99,8 @@ module Google
           # The table is temporarily unable to serve requests from this
           # cluster due to unplanned or emergency maintenance.
           #
-          # @return [Boolean] `true` if the table in this cluster is in unplanned
-          #   maintenance.
+          # @return [Boolean] `true` if the value of {#replication_state} is `UNPLANNED_MAINTENANCE`,
+          #   `false` otherwise.
           #
           def unplanned_maintenance?
             replication_state == :UNPLANNED_MAINTENANCE
@@ -90,7 +111,8 @@ module Google
           # Depending on replication delay, reads may not immediately
           # reflect the state of the table in other clusters.
           #
-          # @return [Boolean] `true` if the table in this cluster is ready.
+          # @return [Boolean] `true` if the value of {#replication_state} is `READY`,
+          #   `false` otherwise.
           #
           def ready?
             replication_state == :READY
@@ -102,13 +124,25 @@ module Google
           # optimizations are complete, the table will transition to `READY`
           # state.
           #
-          # @return [Boolean] `true` if the table in this cluster is being
-          #   optimized.
+          # @return [Boolean] `true` if the value of {#replication_state} is `READY_OPTIMIZING`,
+          #   `false` otherwise.
           #
           def ready_optimizing?
             replication_state == :READY_OPTIMIZING
           end
 
+          ##
+          # The encryption info value objects for the table in this cluster. The encryption info
+          # is only present when the table view is `ENCRYPTION_VIEW` or `FULL`. See also
+          # {Instance::ClusterMap#add}.
+          #
+          # @return [Array<Google::Cloud::Bigtable::EncryptionInfo>] The array of encryption info
+          #   value objects, or an empty array if none are present.
+          #
+          def encryption_infos
+            @grpc.encryption_info.map { |ei_grpc| Google::Cloud::Bigtable::EncryptionInfo.from_grpc ei_grpc }
+          end
+
           # @private
           # New Table::ClusterState from a Google::Cloud::Bigtable::Admin::V2::Table::ClusterState object.
           # @param grpc [Google::Cloud::Bigtable::Admin::V2::Table::ClusterState]