google-cloud-bigtable 0.6.1 → 1.0.1

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
@@ -35,7 +36,7 @@ module Google
       #
       class ReadModifyWriteRule
         # @private
-        # Create an instance of ReadModifyWriteRule
+        # Creates an instance of ReadModifyWriteRule
         #
         # @param family [String]
         #   The name of the family to which the read/modify/write should be applied.
@@ -48,7 +49,8 @@ module Google
           @grpc.column_qualifier = qualifier
         end
 
-        # Create an instance of an append-value rule.
+        ##
+        # Creates an instance of an append-value rule.
         #
         # @param family [String]
         #   The name of the family to which the read/modify/write should be applied.
@@ -65,12 +67,13 @@ 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.
+        ##
+        # Creates an instance of an increment-amount rule.
         #
         # @param family [String]
         #   The name of the family to which the read/modify/write should be applied.
@@ -83,18 +86,19 @@ module Google
         #   as a 64-bit big-endian signed integer), or the entire request will fail.
         # @return [Google::Cloud::Bigtable::ReadModifyWriteRule]
         #
-        # @example increment value rule
+        # @example
         #   rule = Google::Cloud::Bigtable::ReadModifyWriteRule.increment(
         #     "cf", "field01", 1
         #   )
         #
         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.
+        ##
+        # Sets the append value.
         #
         # @param value [String]
         # @return [Google::Cloud::Bigtable::ReadModifyWriteRule]
@@ -104,7 +108,8 @@ module Google
           self
         end
 
-        # Set increment amount.
+        ##
+        # Sets the increment amount.
         #
         # @param amount [Integer]
         # @return [Google::Cloud::Bigtable::ReadModifyWriteRule]

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 = service.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
@@ -86,7 +86,7 @@ module Google
         #   The default (zero) is to return all results.
         # @return [Array<Google::Cloud::Bigtable::Row> | :yields: row]
         #   Array of row or yield block for each processed row.
-        # @example Read with limit
+        # @example Read with limit.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -96,7 +96,7 @@ module Google
         #     puts row
         #   end
         #
-        # @example Read using row keys
+        # @example Read using row keys.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -106,20 +106,19 @@ module Google
         #     puts row
         #   end
         #
-        # @example Read using row ranges
+        # @example Read using row ranges.
         #   require "google/cloud/bigtable"
         #
         #   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
         #   end
         #
-        # @example Read using filter
-        #
+        # @example Read using filter.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -133,8 +132,7 @@ module Google
         #     puts row
         #   end
         #
-        # @example Read using filter with limit
-        #
+        # @example Read using filter with limit.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -148,52 +146,33 @@ 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
+        # @param key [String] Row key. Required.
         # @param filter [Google::Cloud::Bigtable::RowFilter]
         #   The filter to apply to the contents of the specified row. Optional.
         # @return [Google::Cloud::Bigtable::Row]
         #
-        # @example Read row
-        #
+        # @example
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -201,8 +180,7 @@ module Google
         #
         #   row = table.read_row("user-1")
         #
-        # @example Read row
-        #
+        # @example Read row with filter.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -216,6 +194,7 @@ module Google
           read_rows(keys: [key], filter: filter).first
         end
 
+        ##
         # Creates a new instance of ValueRange.
         #
         # @return [Google::Cloud::Bigtable::ValueRange]
@@ -226,14 +205,14 @@ 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")
         #
         #   # OR
         #   range = table.new_value_range.from("abc").to("xyz")
         #
-        # @example With exclusive from range
+        # @example With exclusive from range.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -245,9 +224,10 @@ module Google
           Google::Cloud::Bigtable::ValueRange.new
         end
 
-        # Get a new instance of ColumnRange.
+        ##
+        # Gets a new instance of ColumnRange.
         #
-        # @param family [String] Column family name
+        # @param family [String] Column family name.
         # @return [Google::Cloud::Bigtable::ColumnRange]
         #
         # @example
@@ -256,14 +236,14 @@ 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")
         #
         #   # OR
         #   range = table.new_column_range("test-family").from("key-1").to("key-5")
         #
-        # @example With exclusive from range
+        # @example With exclusive from range.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -272,10 +252,11 @@ 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.
+        ##
+        # Gets a new instance of RowRange.
         #
         # @return [Google::Cloud::Bigtable::RowRange]
         #
@@ -285,14 +266,14 @@ 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")
         #
         #   # OR
         #   range = table.new_row_range.from("key-1").to("key-5")
         #
-        # @example With exclusive from range
+        # @example With exclusive from range.
         #   require "google/cloud/bigtable"
         #
         #   bigtable = Google::Cloud::Bigtable.new
@@ -304,6 +285,7 @@ module Google
           Google::Cloud::Bigtable::RowRange.new
         end
 
+        ##
         # Gets a row filter.
         #
         # @return [Google::Cloud::Bigtable::RowRange]
@@ -322,6 +304,7 @@ module Google
 
         private
 
+        ##
         # Builds a RowSet object from row keys and row ranges.
         #
         # @param row_keys [Array<String>]
@@ -333,11 +316,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,172 @@
+# 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