google-cloud-bigtable 0.6.2 → 1.0.2

data/lib/google/cloud/bigtable/instance/cluster_map.rb

@@ -19,16 +19,18 @@ module Google
   module Cloud
     module Bigtable
       class Instance
-        # Instance::ClusterMap is a hash with cluster name and gRPC object.
-        # It is used to create an instance.
-        # @example Create
+        ##
+        # Instance::ClusterMap is a hash with cluster ID keys and cluster configuration values.
+        # It is used to create a cluster.
+        #
+        # @example
         #
         #  clusters = Google::Cloud::Bigtable::Instance::ClusterMap.new
         #
-        #  clusters.add("cluster-1", 3, location: "us-east1-b", storage_type: :SSD)
+        #  clusters.add("cluster-1", "us-east1-b", nodes: 3, storage_type: :SSD)
         #
         #  # Or
-        #  cluster.add("cluster-2", 1)
+        #  clusters.add("cluster-2", "us-east1-b")
         #
         class ClusterMap < DelegateClass(::Hash)
           # @private
@@ -36,32 +38,34 @@ module Google
           # Creates a new Instance::ClusterMap with an hash of Cluster name and
           # cluster grpc instances.
           def initialize value = {}
-            super(value)
+            super value
           end
 
-          # Adds a cluster to a map
+          ##
+          # Adds a cluster to the cluster map.
           #
-          # @param name [String] Cluster name
+          # @param name [String] The unique identifier for the cluster.
           # @param 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. Currently only zones are supported.
-          # @param nodes [Integer] Number of nodes
+          # @param nodes [Integer] Number of nodes for the cluster. When creating
+          #   an instance of type `:DEVELOPMENT`, `nodes` must not be set.
           # @param storage_type [Symbol]
           #   Valid values are:
           #   * `:SSD`(Flash (SSD) storage should be used),
           #   *`:HDD`(Magnetic drive (HDD) storage should be used)
           #
           #   If not set then default will set to `:STORAGE_TYPE_UNSPECIFIED`
-
+          #
           def add name, location, nodes: nil, storage_type: nil
             attrs = {
-              serve_nodes: nodes,
-              location: location,
+              serve_nodes:          nodes,
+              location:             location,
               default_storage_type: storage_type
             }.delete_if { |_, v| v.nil? }
 
-            self[name] = Google::Bigtable::Admin::V2::Cluster.new(attrs)
+            self[name] = Google::Bigtable::Admin::V2::Cluster.new attrs
           end
         end
       end

data/lib/google/cloud/bigtable/instance/job.rb

@@ -17,6 +17,7 @@ module Google
   module Cloud
     module Bigtable
       class Instance
+        ##
         # # Job
         #
         # A resource representing the long-running, asynchronous processing of
@@ -39,7 +40,7 @@ module Google
         #     type: :DEVELOPMENT,
         #     labels: { "env" => "dev"}
         #   ) do |clusters|
-        #     clusters.add("test-cluster", "us-east1-b", nodes: 1)
+        #     clusters.add("test-cluster", "us-east1-b") # nodes not allowed
         #   end
         #
         #   # Check and reload.
@@ -57,8 +58,8 @@ module Google
         #     instance = job.instance
         #   end
         #
-        #
         class Job < LongrunningJob
+          ##
           # Get the instance object from operation results.
           #
           # @return [Google::Cloud::Bigtable::Instance, nil] The Instance instance, or
@@ -71,11 +72,11 @@ module Google
           #
           #   job = bigtable.create_instance(
           #     "my-instance",
-          #     "Instance for user data",
+          #     display_name: "Instance for user data",
           #     type: :DEVELOPMENT,
           #     labels: { "env" => "dev"}
           #   ) do |clusters|
-          #     clusters.add("test-cluster", "us-east1-b", nodes: 1)
+          #     clusters.add("test-cluster", "us-east1-b") # nodes not allowed
           #   end
           #
           #   job.done? #=> false
@@ -88,7 +89,7 @@ module Google
           #   instance = job.instance
           #
           def instance
-            Instance.from_grpc(results, service) if results
+            Instance.from_grpc results, service if results
           end
         end
       end

data/lib/google/cloud/bigtable/instance/list.rb

@@ -21,6 +21,7 @@ module Google
   module Cloud
     module Bigtable
       class Instance
+        ##
         # Instance::List is a special-case array with additional
         # values and failed_locations.
         class List < DelegateClass(::Array)
@@ -28,24 +29,27 @@ module Google
           # The gRPC Service object.
           attr_accessor :service
 
+          ##
           # If not empty, indicates that more records match
           # the request and this value should be passed to continue.
           attr_accessor :token
 
-          # Locations from which Instance information could not be retrieved,
+          ##
+          # Locations from which instance information could not be retrieved,
           # due to an outage or some other transient condition.
-          # Instances whose Clusters are all in one of the failed locations
-          # may be missing from `instances`, and Instances with at least one
-          # Cluster in a failed location may only have partial information returned.
+          # Instances whose clusters are all in one of the failed locations
+          # may be missing from `instances`, and instances with at least one
+          # cluster in a failed location may only have partial information returned.
           attr_accessor :failed_locations
 
           # @private
           # Creates a new Instance::List with an array of
           # Instance instances.
           def initialize arr = []
-            super(arr)
+            super arr
           end
 
+          ##
           # Whether there is a next page of instances.
           #
           # @return [Boolean]
@@ -59,10 +63,12 @@ module Google
           #   if instances.next?
           #     next_instances = instances.next
           #   end
+          #
           def next?
             !token.nil?
           end
 
+          ##
           # Retrieves the next page of instances.
           #
           # @return [Instance::List] The list of instances.
@@ -80,14 +86,13 @@ module Google
           def next
             return nil unless next?
             ensure_service!
-            grpc = service.list_instances(token: token)
-            next_list = self.class.from_grpc(grpc, service)
-            if failed_locations
-              next_list.failed_locations.concat(failed_locations.map(&:to_s))
-            end
+            grpc = service.list_instances token: token
+            next_list = self.class.from_grpc grpc, service
+            next_list.failed_locations.concat(failed_locations.map(&:to_s)) if failed_locations
             next_list
           end
 
+          ##
           # Retrieves remaining results by repeatedly invoking {#next} until
           # {#next?} returns `false`. Calls the given block once for each
           # result, which is passed as the argument to the block.
@@ -122,7 +127,7 @@ module Google
           #   end
           #
           def all
-            return enum_for(:all) unless block_given?
+            return enum_for :all unless block_given?
 
             results = self
             loop do
@@ -136,10 +141,10 @@ module Google
           # New Instance::List from a Google::Bigtable::Admin::V2::Instance object.
           def self.from_grpc grpc, service
             instances = List.new(Array(grpc.instances).map do |instance|
-              Instance.from_grpc(instance, service)
+              Instance.from_grpc instance, service
             end)
             token = grpc.next_page_token
-            token = nil if token == "".freeze
+            token = nil if token == ""
             instances.token = token
             instances.service = service
             instances.failed_locations = grpc.failed_locations.map(&:to_s)

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

@@ -18,6 +18,7 @@
 module Google
   module Cloud
     module Bigtable
+      ##
       # # LongrunningJob
       #
       # A resource representing the long-running, asynchronous processing operation.
@@ -35,7 +36,8 @@ module Google
         # The gRPC Service object.
         attr_accessor :service
 
-        # Get result object of the operation.
+        ##
+        # Gets the result object of the operation.
         #
         # @return [Object, nil]
         #   `nil` if the operation is not complete.
@@ -46,6 +48,7 @@ module Google
           @grpc.results
         end
 
+        ##
         # Checks if the processing of the instance operation is complete.
         #
         # @return [boolean] `true` when complete, `false` otherwise.
@@ -54,6 +57,7 @@ module Google
           @grpc.done?
         end
 
+        ##
         # Checks if the processing of the instance operation has errored.
         #
         # @return [boolean] `true` when errored, `false` otherwise.
@@ -74,6 +78,7 @@ module Google
           @grpc.error
         end
 
+        ##
         # Reloads the job with current data from the long-running,
         # asynchronous processing of an operation.
         #
@@ -84,6 +89,7 @@ module Google
           self
         end
 
+        ##
         # Reloads the job until the operation is complete. The delay between
         # reloads will incrementally increase.
         #

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

@@ -18,6 +18,7 @@
 module Google
   module Cloud
     module Bigtable
+      ##
       # # MutationEntry
       #
       # MutationEntry is a chainable structure that holds data for different
@@ -41,7 +42,7 @@ module Google
       #     timestamp_to: timestamp_micros
       #   ).delete_from_family("cf3").delete_from_row
       #
-      # @example Using table
+      # @example Create using a table.
       #   require "google/cloud/bigtable"
       #
       #   bigtable = Google::Cloud::Bigtable.new
@@ -56,22 +57,26 @@ module Google
       class MutationEntry
         attr_accessor :row_key
 
+        # @private
         # mutations gRPC list
         # @return [Array<Google::Bigtable::V2::Mutation>]
         attr_accessor :mutations
 
+        ##
         # Creates a mutation entry instance.
         #
         # @param row_key [String]
+        #
         def initialize row_key = nil
           @row_key = row_key
           @mutations = []
           @retryable = true
         end
 
-        # Add SetCell mutation to list of mutations.
+        ##
+        # Adds a SetCell to the list of mutations.
         #
-        # A mutation that sets the value of the specified cell.
+        # A SetCell is a mutation that sets the value of the specified cell.
         #
         # @param family [String] Table column family name.
         #   The name of the family into which new data should be written.
@@ -96,7 +101,7 @@ module Google
         #   entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
         #   entry.set_cell("cf1", "field01", "XYZ")
         #
-        # @example With timestamp
+        # @example With timestamp.
         #   entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
         #   entry.set_cell(
         #     "cf-1",
@@ -107,11 +112,11 @@ module Google
         #
         def set_cell family, qualifier, value, timestamp: nil
           # If value is integer, covert it to a 64-bit signed big-endian integer.
-          value = [value].pack("q>") if value.is_a?(Integer)
+          value = [value].pack "q>" if value.is_a? Integer
           options = {
-            family_name: family,
+            family_name:      family,
             column_qualifier: qualifier,
-            value: value
+            value:            value
           }
 
           if timestamp
@@ -122,10 +127,12 @@ module Google
           self
         end
 
-        # Add DeleteFromColumn entry to list of mutations.
+        ##
+        # Adds a DeleteFromColumn to the list of mutations.
         #
-        # A mutation that deletes cells from the specified column, optionally
-        # restricting the deletions to a given timestamp range.
+        # A DeleteFromColumn is a mutation that deletes cells from the
+        # specified column, optionally restricting the deletions to a given
+        # timestamp range.
         #
         # @param family [String] Table column family name.
         #   The name of the column family from which cells should be deleted.
@@ -147,11 +154,11 @@ module Google
         #   (millisecond granularity). For example: `1564257960168000`.
         # @return [MutationEntry] `self` object of entry for chaining.
         #
-        # @example Without timestamp range
+        # @example Without timestamp range.
         #   entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
         #   entry.delete_cells("cf-1", "field-1")
         #
-        # @example With timestamp range
+        # @example With timestamp range.
         #   entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
         #   timestamp_micros = (Time.now.to_f * 1000000).round(-3)
         #   entry.delete_cells(
@@ -160,7 +167,7 @@ module Google
         #     timestamp_from: timestamp_micros - 5000000,
         #     timestamp_to: timestamp_micros
         #   )
-        # @example With timestamp range with lower boundary only
+        # @example With timestamp range with lower boundary only.
         #   entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
         #   timestamp_micros = (Time.now.to_f * 1000000).round(-3)
         #   entry.delete_cells(
@@ -169,30 +176,22 @@ module Google
         #     timestamp_from: timestamp_micros - 5000000
         #   )
         #
-        def delete_cells \
-            family,
-            qualifier,
-            timestamp_from: nil,
-            timestamp_to: nil
-          grpc = Google::Bigtable::V2::Mutation::DeleteFromColumn.new(
-            family_name: family,
-            column_qualifier: qualifier
-          )
+        def delete_cells family, qualifier, timestamp_from: nil, timestamp_to: nil
+          grpc = Google::Bigtable::V2::Mutation::DeleteFromColumn.new family_name: family, column_qualifier: qualifier
           if timestamp_from || timestamp_to
             time_range = Google::Bigtable::V2::TimestampRange.new
             time_range.start_timestamp_micros = timestamp_from if timestamp_from
             time_range.end_timestamp_micros = timestamp_to if timestamp_to
             grpc.time_range = time_range
           end
-          @mutations << Google::Bigtable::V2::Mutation.new(
-            delete_from_column: grpc
-          )
+          @mutations << Google::Bigtable::V2::Mutation.new(delete_from_column: grpc)
           self
         end
 
-        # Add DeleteFromFamily to list of mutations.
+        ##
+        # Adds a DeleteFromFamily to the list of mutations.
         #
-        # A mutation that deletes all cells from the specified column family.
+        # A DeleteFromFamily is a mutation that deletes all cells from the specified column family.
         #
         # @param family [String] Table column family name.
         #   The name of the column family from which cells should be deleted.
@@ -204,15 +203,14 @@ module Google
         #   entry.delete_from_family("cf-1")
         #
         def delete_from_family family
-          @mutations << Google::Bigtable::V2::Mutation.new(
-            delete_from_family: { family_name: family }
-          )
+          @mutations << Google::Bigtable::V2::Mutation.new(delete_from_family: { family_name: family })
           self
         end
 
-        # Add DeleteFromRow entry to list of mutations
+        ##
+        # Adds a DeleteFromRow to the list of mutations.
         #
-        # A Mutation which deletes all cells from the containing row.
+        # A DeleteFromRow is a mutation which deletes all cells from the containing row.
         #
         # @return [MutationEntry] `self` object of entry for chaining.
         #
@@ -225,7 +223,8 @@ module Google
           self
         end
 
-        # Mutation entry is retryable or not based on set_cell value.
+        ##
+        # If the mutation entry is retryable or not based on set_cell value.
         #
         # @return [Boolean]
         #
@@ -233,10 +232,11 @@ module Google
           @retryable
         end
 
-        # Number of mutations
+        ##
+        # The number of mutations.
         #
         # @return [Integer]
-
+        #
         def length
           @mutations.length
         end
@@ -248,10 +248,7 @@ module Google
         # @return [Google::Bigtable::V2::MutateRowsRequest::Entry]
         #
         def to_grpc
-          Google::Bigtable::V2::MutateRowsRequest::Entry.new(
-            row_key: @row_key,
-            mutations: @mutations
-          )
+          Google::Bigtable::V2::MutateRowsRequest::Entry.new row_key: @row_key, mutations: @mutations
         end
       end
     end