google-cloud-bigtable 0.6.2 → 0.7.0

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

@@ -19,16 +19,17 @@ 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
         #
         #  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,9 +37,10 @@ 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
           #
           # @param name [String] Cluster name
@@ -53,15 +55,15 @@ module Google
           #   *`: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
@@ -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,7 +72,7 @@ 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|
@@ -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,10 +29,12 @@ 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,
           # due to an outage or some other transient condition.
           # Instances whose Clusters are all in one of the failed locations
@@ -43,9 +46,10 @@ module Google
           # 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,6 +36,7 @@ module Google
         # The gRPC Service object.
         attr_accessor :service
 
+        ##
         # Get result object of the operation.
         #
         # @return [Object, nil]
@@ -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
@@ -56,19 +57,23 @@ 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.
         #
         # A mutation that sets the value of the specified cell.
@@ -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,6 +127,7 @@ module Google
           self
         end
 
+        ##
         # Add DeleteFromColumn entry to list of mutations.
         #
         # A mutation that deletes cells from the specified column, optionally
@@ -169,27 +175,19 @@ 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.
         #
         # A mutation that deletes all cells from the specified column family.
@@ -204,12 +202,11 @@ 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
         #
         # A Mutation which deletes all cells from the containing row.
@@ -225,6 +222,7 @@ module Google
           self
         end
 
+        ##
         # Mutation entry is retryable or not based on set_cell value.
         #
         # @return [Boolean]
@@ -233,10 +231,11 @@ module Google
           @retryable
         end
 
+        ##
         # Number of mutations
         #
         # @return [Integer]
-
+        #
         def length
           @mutations.length
         end
@@ -248,10 +247,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

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

@@ -19,10 +19,12 @@ require "google/cloud/bigtable/mutation_entry"
 require "google/cloud/bigtable/row"
 require "google/cloud/bigtable/rows_mutator"
 require "google/cloud/bigtable/read_modify_write_rule"
+require "google/cloud/bigtable/status"
 
 module Google
   module Cloud
     module Bigtable
+      ##
       # # MutationOperations
       #
       # Collection of mutations APIs.
@@ -33,6 +35,7 @@ module Google
       #   * Check and mutate row
       #
       module MutationOperations
+        ##
         # Mutate row.
         #
         # Mutates a row atomically. Cells in the row are left
@@ -45,18 +48,18 @@ module Google
         #   Mutation entry with row key and list of mutations.
         # @return [Boolean]
         # @example Single mutation on row.
-        #   require "google/cloud"
+        #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
         #   table = bigtable.table("my-instance", "my-table")
         #
-        #   entry = table.new_mutation_entry.new("user-1")
+        #   entry = table.new_mutation_entry("user-1")
         #   entry.set_cell("cf1", "field1", "XYZ")
         #   table.mutate_row(entry)
         #
         # @example Multiple mutations on row.
-        #   require "google/cloud"
+        #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
@@ -73,15 +76,11 @@ module Google
         #   table.mutate_row(entry)
         #
         def mutate_row entry
-          client.mutate_row(
-            path,
-            entry.row_key,
-            entry.mutations,
-            app_profile_id: @app_profile_id
-          )
+          client.mutate_row path, entry.row_key, entry.mutations, app_profile_id: @app_profile_id
           true
         end
 
+        ##
         # Mutates multiple rows in a batch. Each individual row is mutated
         # atomically as in MutateRow, but the entire batch is not executed
         # atomically.
@@ -95,7 +94,7 @@ module Google
         # @return [Array<Google::Bigtable::V2::MutateRowsResponse::Entry>]
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #
@@ -104,12 +103,18 @@ module Google
         #   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")
-        #   table.mutate_row(entries)
+        #   responses = table.mutate_rows(entries)
+        #
+        #   responses.each do |response|
+        #     puts response.status.description
+        #   end
         #
         def mutate_rows entries
-          RowsMutator.new(self, entries).apply_mutations
+          statuses = RowsMutator.new(self, entries).apply_mutations
+          statuses.map { |s| Response.from_grpc s }
         end
 
+        ##
         # Modifies a row atomically on the server. The method reads the latest
         # existing timestamp and value from the specified columns and writes a new
         # entry based on pre-defined read/modify/write rules. The new value for the
@@ -118,7 +123,8 @@ module Google
         #
         # @param key [String]
         #   The row key of the row to which the read/modify/write rules should be applied.
-        # @param rules [Google::Cloud::Bigtable::ReadModifyWriteRule, Array<Google::Cloud::Bigtable::ReadModifyWriteRule>]
+        # @param rules [Google::Cloud::Bigtable::ReadModifyWriteRule,
+        #   Array<Google::Cloud::Bigtable::ReadModifyWriteRule>]
         #   Rules specifying how the specified row's contents are to be transformed
         #   into writes. Entries are applied in order, meaning that earlier rules will
         #   affect the results of later ones.
@@ -158,7 +164,7 @@ module Google
             Array(rules).map(&:to_grpc),
             app_profile_id: @app_profile_id
           ).row
-          row = Row.new(res_row.key)
+          row = Row.new res_row.key
 
           res_row.families.each do |family|
             family.columns.each do |column|
@@ -177,6 +183,7 @@ module Google
           row
         end
 
+        ##
         # Mutates a row atomically based on the output of a predicate reader filter.
         #
         # NOTE: Condition predicate filter is not supported.
@@ -222,35 +229,32 @@ module Google
         #   otherwise_mutations = Google::Cloud::Bigtable::MutationEntry.new
         #   otherwise_mutations.delete_from_family("cf3")
         #
-        #   response = table.check_and_mutate_row(
+        #   predicate_matched = table.check_and_mutate_row(
         #     "user01",
         #     predicate_filter,
         #     on_match: on_match_mutations,
         #     otherwise: otherwise_mutations
         #   )
         #
-        #   if response
+        #   if predicate_matched
         #     puts "All predicates matched"
         #   end
         #
-        def check_and_mutate_row \
-            key,
-            predicate,
-            on_match: nil,
-            otherwise: nil
+        def check_and_mutate_row key, predicate, on_match: nil, otherwise: nil
           true_mutations = on_match.mutations if on_match
           false_mutations = otherwise.mutations if otherwise
           response = client.check_and_mutate_row(
             path,
             key,
             predicate_filter: predicate.to_grpc,
-            true_mutations: true_mutations,
-            false_mutations: false_mutations,
-            app_profile_id: @app_profile_id
+            true_mutations:   true_mutations,
+            false_mutations:  false_mutations,
+            app_profile_id:   @app_profile_id
           )
           response.predicate_matched
         end
 
+        ##
         # Read sample row keys.
         #
         # Returns a sample of row keys in the table. The returned row keys will
@@ -263,7 +267,7 @@ module Google
         #   Yield block for each processed SampleRowKey.
         #
         # @example
-        #   require "google/cloud"
+        #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
         #   table = bigtable.table("my-instance", "my-table")
@@ -274,17 +278,18 @@ module Google
         #   end
         #
         def sample_row_keys
-          return enum_for(:sample_row_keys) unless block_given?
+          return enum_for :sample_row_keys unless block_given?
 
           response = client.sample_row_keys(
             path,
             app_profile_id: @app_profile_id
           )
           response.each do |grpc|
-            yield SampleRowKey.from_grpc(grpc)
+            yield SampleRowKey.from_grpc grpc
           end
         end
 
+        ##
         # Create an instance of mutation_entry
         #
         # @param row_key [String] Row key. Optional
@@ -303,9 +308,10 @@ module Google
         #   entry = table.new_mutation_entry
         #
         def new_mutation_entry row_key = nil
-          Google::Cloud::Bigtable::MutationEntry.new(row_key)
+          Google::Cloud::Bigtable::MutationEntry.new row_key
         end
 
+        ##
         # Create an instance of ReadModifyWriteRule to append or increment the value
         # of the cell qualifier.
         #
@@ -332,7 +338,54 @@ module Google
         #   rule.increment(100)
         #
         def new_read_modify_write_rule family, qualifier
-          Google::Cloud::Bigtable::ReadModifyWriteRule.new(family, qualifier)
+          Google::Cloud::Bigtable::ReadModifyWriteRule.new family, qualifier
+        end
+
+        ##
+        # # MutationEntry::Response
+        #
+        # Represents a response message from BigtableService.MutateRows.
+        #
+        # @attr [Integer] index The index into the original request's `entries`
+        #   list of the Entry for which a result is being reported.
+        # @attr [Google::Cloud::Bigtable::Status] The result of the request
+        #   Entry identified by `index`. Depending on how requests are batched
+        #   during execution, it is possible for one Entry to fail due to an
+        #   error with another Entry. In the event that this occurs, the same
+        #   error will be reported for both entries.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   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.each do |response|
+        #     puts response.status.description
+        #   end
+        #
+        class Response
+          attr_reader :index, :status
+
+          ##
+          # @private Creates a MutationEntry::Response object.
+          def initialize index, status
+            @index = index
+            @status = status
+          end
+
+          ##
+          # @private New MutationEntry::Response from a
+          # Google::Bigtable::V2::MutateRowsResponse::Entry object.
+          def self.from_grpc grpc
+            new grpc.index, Status.from_grpc(grpc.status)
+          end
         end
       end
     end