google-cloud-bigtable 0.6.2 → 0.7.0

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

@@ -18,6 +18,7 @@
 module Google
   module Cloud
     module Bigtable
+      ##
       # # ReadModifyWriteRule
       #
       # Specifies an atomic read/modify/write operation on the latest value of the
@@ -48,6 +49,7 @@ module Google
           @grpc.column_qualifier = qualifier
         end
 
+        ##
         # Create an instance of an append-value rule.
         #
         # @param family [String]
@@ -65,11 +67,12 @@ module Google
         #   )
         #
         def self.append family, qualifier, value
-          rule = new(family, qualifier)
-          rule.append(value)
+          rule = new family, qualifier
+          rule.append value
           rule
         end
 
+        ##
         # Create an instance of an increment-amount rule.
         #
         # @param family [String]
@@ -89,11 +92,12 @@ module Google
         #   )
         #
         def self.increment family, qualifier, amount
-          rule = new(family, qualifier)
-          rule.increment(amount)
+          rule = new family, qualifier
+          rule.increment amount
           rule
         end
 
+        ##
         # Set append value.
         #
         # @param value [String]
@@ -104,6 +108,7 @@ module Google
           self
         end
 
+        ##
         # Set increment amount.
         #
         # @param amount [Integer]

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

@@ -24,6 +24,7 @@ require "google/cloud/bigtable/sample_row_key"
 module Google
   module Cloud
     module Bigtable
+      ##
       # # ReadOperations
       #
       # Collection of read-rows APIs.
@@ -33,6 +34,7 @@ module Google
       #   * Read rows
       #
       module ReadOperations
+        ##
         # Reads sample row keys.
         #
         # Returns a sample of row keys in the table. The returned row keys will
@@ -45,7 +47,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")
@@ -56,17 +58,15 @@ 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 = 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
 
+        ##
         # Reads rows.
         #
         # Streams back the contents of all requested rows in key order, optionally
@@ -112,7 +112,7 @@ module Google
         #   bigtable = Google::Cloud::Bigtable.new
         #   table = bigtable.table("my-instance", "my-table")
         #
-        #   range =  table.row_range.between("user-1", "user-100")
+        #   range = table.new_row_range.between("user-1", "user-100")
         #
         #   table.read_rows(ranges: range).each do |row|
         #     puts row
@@ -148,43 +148,25 @@ module Google
         #     puts row
         #   end
         #
-        def read_rows \
-            keys: nil,
-            ranges: nil,
-            filter: nil,
-            limit: nil,
-            &block
-          unless block_given?
-            return enum_for(
-              :read_rows,
-              keys: keys,
-              ranges: ranges,
-              filter: filter,
-              limit: limit
-            )
-          end
-          row_set = build_row_set(keys, ranges)
+        def read_rows keys: nil, ranges: nil, filter: nil, limit: nil, &block
+          return enum_for :read_rows, keys: keys, ranges: ranges, filter: filter, limit: limit unless block_given?
+
+          row_set = build_row_set keys, ranges
           rows_limit = limit
           rows_filter = filter.to_grpc if filter
-          rows_reader = RowsReader.new(self)
+          rows_reader = RowsReader.new self
 
           begin
-            rows_reader.read(
-              rows: row_set,
-              filter: rows_filter,
-              rows_limit: rows_limit,
-              &block
-            )
+            rows_reader.read rows: row_set, filter: rows_filter, rows_limit: rows_limit, &block
           rescue *RowsReader::RETRYABLE_ERRORS => e
             rows_reader.retry_count += 1
-            unless rows_reader.retryable?
-              raise Google::Cloud::Error.from_error(e)
-            end
-            rows_limit, row_set = rows_reader.retry_options(limit, row_set)
+            raise Google::Cloud::Error.from_error(e) unless rows_reader.retryable?
+            rows_limit, row_set = rows_reader.retry_options limit, row_set
             retry
           end
         end
 
+        ##
         # Reads a single row by row key.
         #
         # @param key [String] Row key. Required
@@ -216,6 +198,7 @@ module Google
           read_rows(keys: [key], filter: filter).first
         end
 
+        ##
         # Creates a new instance of ValueRange.
         #
         # @return [Google::Cloud::Bigtable::ValueRange]
@@ -226,7 +209,7 @@ module Google
         #   bigtable = Google::Cloud::Bigtable.new
         #   table = bigtable.table("my-instance", "my-table")
         #
-        #   range = table.value_range
+        #   range = table.new_value_range
         #   range.from("abc")
         #   range.to("xyz")
         #
@@ -245,6 +228,7 @@ module Google
           Google::Cloud::Bigtable::ValueRange.new
         end
 
+        ##
         # Get a new instance of ColumnRange.
         #
         # @param family [String] Column family name
@@ -256,7 +240,7 @@ module Google
         #   bigtable = Google::Cloud::Bigtable.new
         #   table = bigtable.table("my-instance", "my-table")
         #
-        #   range = table.column_range("test-family")
+        #   range = table.new_column_range("test-family")
         #   range.from("abc")
         #   range.to("xyz")
         #
@@ -272,9 +256,10 @@ module Google
         #   range = table.new_column_range("test-family").from("key-1", inclusive: false).to("key-5")
         #
         def new_column_range family
-          Google::Cloud::Bigtable::ColumnRange.new(family)
+          Google::Cloud::Bigtable::ColumnRange.new family
         end
 
+        ##
         # Get a new instance of RowRange.
         #
         # @return [Google::Cloud::Bigtable::RowRange]
@@ -285,7 +270,7 @@ module Google
         #   bigtable = Google::Cloud::Bigtable.new
         #   table = bigtable.table("my-instance", "my-table")
         #
-        #   range = table.row_range
+        #   range = table.new_row_range
         #   range.from("abc")
         #   range.to("xyz")
         #
@@ -304,6 +289,7 @@ module Google
           Google::Cloud::Bigtable::RowRange.new
         end
 
+        ##
         # Gets a row filter.
         #
         # @return [Google::Cloud::Bigtable::RowRange]
@@ -322,6 +308,7 @@ module Google
 
         private
 
+        ##
         # Builds a RowSet object from row keys and row ranges.
         #
         # @param row_keys [Array<String>]
@@ -333,11 +320,11 @@ module Google
           row_set[:row_keys] = row_keys if row_keys
 
           if row_ranges
-            row_ranges = [row_ranges] unless row_ranges.instance_of?(Array)
+            row_ranges = [row_ranges] unless row_ranges.instance_of? Array
             row_set[:row_ranges] = row_ranges.map(&:to_grpc)
           end
 
-          Google::Bigtable::V2::RowSet.new(row_set)
+          Google::Bigtable::V2::RowSet.new row_set
         end
       end
     end

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

@@ -0,0 +1,171 @@
+# Copyright 2019 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Bigtable
+      ##
+      # # RoutingPolicy
+      #
+      # An abstract routing policy.
+      #
+      # See subclasses for concrete implementations:
+      # * {Google::Cloud::Bigtable::MultiClusterRoutingUseAny} - Read/write
+      #   requests may be routed to any cluster in the instance and will
+      #   fail over to another cluster in the event of transient errors or
+      #   delays. Choosing this option sacrifices read-your-writes
+      #   consistency to improve availability.
+      # * {Google::Cloud::Bigtable::SingleClusterRouting} - Unconditionally
+      #   routes all read/write requests to a specific cluster. This option
+      #   preserves read-your-writes consistency but does not improve
+      #   availability. Value contains `cluster_id` and optional field
+      #   `allow_transactional_writes`.
+      #
+      # @example Create an app profile with a single cluster routing policy
+      #   require "google/cloud/bigtable"
+      #
+      #   bigtable = Google::Cloud::Bigtable.new
+      #
+      #   instance = bigtable.instance("my-instance")
+      #
+      #   routing_policy = Google::Cloud::Bigtable::AppProfile.single_cluster_routing(
+      #     "my-instance-cluster-1",
+      #     allow_transactional_writes: true
+      #   )
+      #
+      #   app_profile = instance.create_app_profile(
+      #     "my-app-profile",
+      #     routing_policy,
+      #     description: "App profile for user data instance"
+      #   )
+      #   puts app_profile.routing_policy
+      #
+      # @example Create an app profile with multi-cluster routing policy
+      #   require "google/cloud/bigtable"
+      #
+      #   bigtable = Google::Cloud::Bigtable.new
+      #
+      #   instance = bigtable.instance("my-instance")
+      #
+      #   routing_policy = Google::Cloud::Bigtable::AppProfile.multi_cluster_routing
+      #
+      #   app_profile = instance.create_app_profile(
+      #     "my-app-profile",
+      #     routing_policy,
+      #     description: "App profile for user data instance"
+      #   )
+      #   puts app_profile.routing_policy
+      #
+      class RoutingPolicy
+      end
+
+      ##
+      # A multi-cluster routing policy for all read/write requests that use the
+      # associated app profile.
+      #
+      # Read/write requests may be routed to any cluster in the instance, and will
+      # fail over to another cluster in the event of transient errors or delays.
+      # Choosing this option sacrifices read-your-writes consistency to improve
+      # availability.
+      #
+      # @example
+      #   require "google/cloud/bigtable"
+      #
+      #   bigtable = Google::Cloud::Bigtable.new
+      #
+      #   instance = bigtable.instance("my-instance")
+      #
+      #   routing_policy = Google::Cloud::Bigtable::AppProfile.multi_cluster_routing
+      #
+      #   app_profile = instance.create_app_profile(
+      #     "my-app-profile",
+      #     routing_policy,
+      #     description: "App profile for user data instance"
+      #   )
+      #   puts app_profile.routing_policy
+      #
+      class MultiClusterRoutingUseAny < RoutingPolicy
+        # @private
+        def to_grpc
+          Google::Bigtable::Admin::V2::AppProfile::MultiClusterRoutingUseAny.new
+        end
+      end
+
+      ##
+      # A single-cluster routing policy for all read/write requests that use the
+      # associated app profile.
+      #
+      # Unconditionally routes all read/write requests to a specific cluster.
+      # This option preserves read-your-writes consistency, but does not improve
+      # availability.
+      #
+      # @example
+      #   require "google/cloud/bigtable"
+      #
+      #   bigtable = Google::Cloud::Bigtable.new
+      #
+      #   instance = bigtable.instance("my-instance")
+      #
+      #   routing_policy = Google::Cloud::Bigtable::AppProfile.single_cluster_routing(
+      #     "my-instance-cluster-1",
+      #     allow_transactional_writes: true
+      #   )
+      #
+      #   app_profile = instance.create_app_profile(
+      #     "my-app-profile",
+      #     routing_policy,
+      #     description: "App profile for user data instance"
+      #   )
+      #   puts app_profile.routing_policy
+      #
+      # @!attribute [rw] cluster_id
+      #   @return [String]
+      #     The cluster to which read/write requests should be routed.
+      # @!attribute [rw] allow_transactional_writes
+      #   @return [true, false]
+      #     If true, `CheckAndMutateRow` and `ReadModifyWriteRow` requests are
+      #     allowed by this app profile. It is unsafe to send these requests to
+      #     the same table/row/column in multiple clusters.
+      #     Default value is false.
+      class SingleClusterRouting < RoutingPolicy
+        attr_reader :cluster_id, :allow_transactional_writes
+
+        ##
+        # Creates a new single-cluster routing policy.
+        #
+        # @param cluster_id [String] The cluster to which read/write requests
+        #   should be routed.
+        # @param allow_transactional_writes [Boolean]
+        #   If true, `CheckAndMutateRow` and `ReadModifyWriteRow` requests are
+        #   allowed by this app profile. It is unsafe to send these requests to
+        #   the same table/row/column in multiple clusters.
+        #   Default value is false.
+        #
+        def initialize cluster_id, allow_transactional_writes
+          @cluster_id = cluster_id
+          @allow_transactional_writes = allow_transactional_writes
+        end
+
+        # @private
+        def to_grpc
+          Google::Bigtable::Admin::V2::AppProfile::SingleClusterRouting.new(
+            cluster_id:                 cluster_id,
+            allow_transactional_writes: allow_transactional_writes
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -18,16 +18,21 @@
 module Google
   module Cloud
     module Bigtable
+      ##
       # # Row
       #
       # Row structure based on merged cells using read row state.
+      #
       class Row
+        ##
         # Cell
         #
         # Row cell built from data chunks.
+        #
         class Cell
           attr_reader :family, :qualifier, :value, :labels, :timestamp
 
+          ##
           # Creates a row cell instance.
           #
           # @param family [String] Column family name
@@ -35,7 +40,7 @@ module Google
           # @param timestamp [Integer] Timestamp in microseconds
           # @param value [String] Cell value
           # @param labels [Array<String>] List of label array
-
+          #
           def initialize family, qualifier, timestamp, value, labels = []
             @family = family
             @qualifier = qualifier
@@ -44,6 +49,7 @@ module Google
             @labels = labels
           end
 
+          ##
           # Converts timestamp to Time instance.
           #
           # @param granularity [Symbol] Optional
@@ -53,16 +59,17 @@ module Google
           #
           def to_time granularity = nil
             return nil if @timestamp.zero?
-            return Time.at(@timestamp / 100_0000.0) if granularity == :micros
-            Time.at(@timestamp / 1000.0)
+            return Time.at @timestamp / 1_000_000.0 if granularity == :micros
+            Time.at @timestamp / 1000.0
           end
 
+          ##
           # Converts a value to an integer.
           #
           # @return [Integer]
           #
           def to_i
-            @value.unpack("q>").first
+            @value.unpack1 "q>"
           end
 
           # @private
@@ -80,12 +87,17 @@ module Google
           end
         end
 
+        ##
         # @return [String] Row key
+        #
         attr_accessor :key
 
+        ##
         # @return [Hash{String => Array<Google::Cloud::Bigtable::Row::Cell>}] Row cells
+        #
         attr_accessor :cells
 
+        ##
         # Creates a flat row object.
         #
         # @param key [String] Row key name
@@ -95,6 +107,7 @@ module Google
           @cells = Hash.new { |h, k| h[k] = [] }
         end
 
+        ##
         # List of column families names
         #
         # @return [Array<String>]
@@ -111,9 +124,7 @@ module Google
         #
         def == other
           return false unless self.class == other.class
-          if key != other.key || column_families != other.column_families
-            return false
-          end
+          return false if key != other.key || column_families != other.column_families
 
           cells.all? do |family, list|
             list == other.cells[family]