google-cloud-bigtable 0.6.1 → 1.0.1

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

@@ -18,6 +18,7 @@
 module Google
   module Cloud
     module Bigtable
+      ##
       # # ColumnRange
       #
       # Specifies a contiguous range of column qualifiers.
@@ -49,15 +50,17 @@ module Google
       #   table.new_column_range("cf").between("user-001", "user-100")
       #
       class ColumnRange
+        ##
         # Create qualifier range instance.
         #
         # @param family [String] Column family name.
         #
         def initialize family
-          @grpc = Google::Bigtable::V2::ColumnRange.new(family_name: family)
+          @grpc = Google::Bigtable::V2::ColumnRange.new family_name: family
         end
 
-        # Get column family name
+        ##
+        # Gets the column family name.
         #
         # @return [String]
         #
@@ -65,7 +68,8 @@ module Google
           @grpc.family_name
         end
 
-        # Set column family name
+        ##
+        # Sets the column family name.
         #
         # @param name [String] Column family name
         #
@@ -73,7 +77,8 @@ module Google
           @grpc.family_name = name
         end
 
-        # Set column range with the lower bound.
+        ##
+        # Sets the column range with the lower bound.
         #
         # @param qualifier [String] Column qualifier name. Required
         # @param inclusive [String] Lower bound flag. Inclusive/Exclusive.
@@ -105,7 +110,8 @@ module Google
           self
         end
 
-        # Set column range with the upper bound.
+        ##
+        # Sets the column range with the upper bound.
         #
         # @param qualifier [String] Column qualifier name. Required.
         # @param inclusive [String] Upper bound flag. Inclusive/Exclusive.
@@ -137,7 +143,8 @@ module Google
           self
         end
 
-        # Set column range with the inclusive upper and lower bound.
+        ##
+        # Sets the column range with the inclusive upper and lower bound.
         #
         # @param from_qualifier [String] Inclusive from qualifier. Required.
         # @param to_qualifier [String] Inclusive to qualifier. Required.
@@ -155,7 +162,8 @@ module Google
           from(from_qualifier).to(to_qualifier, inclusive: true)
         end
 
-        # Set column range with the inclusive upper and the exclusive lower bound.
+        ##
+        # Sets the column range with the inclusive upper and the exclusive lower bound.
         #
         # @param from_qualifier [String] Inclusive from qualifier
         # @param to_qualifier [String] Exclusive to qualifier

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

@@ -26,48 +26,56 @@ module Google
       module Convert
         module_function
 
+        ##
         # Convert number to protobuf duration.
         #
         # @param number [Float] Seconds with nano seconds
         # @return [Google::Protobuf::Duration, nil]
+        #
         def number_to_duration number
           return unless number
 
           Google::Protobuf::Duration.new(
             seconds: number.to_i,
-            nanos: (number.remainder(1) * 1000000000).round
+            nanos:   (number.remainder(1) * 1_000_000_000).round
           )
         end
 
+        ##
         # Convert protobuf durations to float.
         #
         # @param duration [Google::Protobuf::Duration, nil]
         # @return [Float, Integer, nil] Seconds with nano seconds
+        #
         def duration_to_number duration
           return unless duration
           return duration.seconds if duration.nanos.zero?
 
-          duration.seconds + (duration.nanos / 1000000000.0)
+          duration.seconds + (duration.nanos / 1_000_000_000.0)
         end
 
+        ##
         # Convert protobuf timestamp to Time object.
         #
         # @param timestamp [Google::Protobuf::Timestamp]
         # @return [Time, nil]
+        #
         def timestamp_to_time timestamp
           return unless timestamp
 
-          Time.at(timestamp.seconds, timestamp.nanos / 1000.0)
+          Time.at timestamp.seconds, timestamp.nanos / 1000.0
         end
 
+        ##
         # Convert time to timestamp protobuf object.
         #
         # @param time [Time]
         # @return [Google::Protobuf::Timestamp, nil]
+        #
         def time_to_timestamp time
           return unless time
 
-          Google::Protobuf::Timestamp.new(seconds: time.to_i, nanos: time.nsec)
+          Google::Protobuf::Timestamp.new seconds: time.to_i, nanos: time.nsec
         end
       end
     end

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

@@ -16,17 +16,20 @@
 module Google
   module Cloud
     module Bigtable
+      ##
       # Invalid read row state error
       class InvalidRowStateError < Google::Cloud::Error
+        ##
         # Invalid row chunk data
         attr_reader :data
 
         def initialize message, data = nil
-          super(message)
+          super message
           @data = data if data
         end
       end
 
+      ##
       # Row filter error.
       class RowFilterError < Google::Cloud::Error
       end

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

@@ -18,51 +18,49 @@
 module Google
   module Cloud
     module Bigtable
+      ##
       # # GcRule
       #
-      # Rule for determining which cells to delete during garbage collection.
+      # A rule or rules for determining which cells to delete during garbage
+      # collection.
+      #
       # Garbage collection (GC) executes opportunistically in the background,
-      # so it's possible for reads to return a cell even if it matches the active
-      # GC expression for its family.
+      # so it is possible for reads to return a cell even if it matches the
+      # active GC expression for its column family.
       #
-      # NOTE: GC Rule can hold only one type at a time.
       # GC Rule types:
-      #   * `max_num_versions` - Delete all cells in a column except the most recent N
-      #   * `max_age` - Delete cells in a column older than the given age.
-      #   * `union` - Delete cells that would be deleted by every nested rule.
-      #       It can have mutiple chainable GC Rules.
-      #   * `intersection` - Delete cells that would be deleted by any nested rule.
-      #       It can have multiple chainable GC Rules.
-      #
-      # @example Create GC rule instance with max version.
-      #
-      #  gc_rule = Google::Cloud::Bigtable::GcRule.max_versions(3)
-      #
-      #  # Change max verions
-      #  gc_rule.max_versions = 5
-      #
-      # @example Create GC rule instance with max age.
-      #
-      #  gc_rule = Google::Cloud::Bigtable::GcRule.max_age(3)
+      #   * `max_num_versions` - A garbage-collection rule that explicitly
+      #     states the maximum number of cells to keep for all columns in a
+      #     column family.
+      #   * `max_age` - A garbage-collection rule based on the timestamp for
+      #     each cell. With this type of garbage-collection rule, you set the
+      #     time to live (TTL) for data. Cloud Bigtable looks at each column
+      #     family during garbage collection and removes any cells that have
+      #     expired.
+      #   * `union` - A union garbage-collection policy will remove all data
+      #     matching *any* of a set of given rules.
+      #   * `intersection` - An intersection garbage-collection policy will
+      #     remove all data matching *all* of a set of given rules.
       #
-      #  # Change max age
-      #  gc_rule.max_age = 600 # 10 minutes
+      # @example Create a table with column families.
+      #   require "google/cloud/bigtable"
       #
-      # @example Create GC rule instance with union.
+      #   bigtable = Google::Cloud::Bigtable.new
       #
-      #  max_age_gc_rule = Google::Cloud::Bigtable::GcRule.max_age(180)
-      #  union_gc_rule = Google::Cloud::Bigtable::GcRule.union(max_age_gc_rule)
+      #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+      #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5))
+      #     cfm.add("cf2", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600))
       #
-      #  # Change union GC rule
-      #  gc_rule.union = Google::Cloud::Bigtable::GcRule.max_age(600)
+      #     gc_rule = Google::Cloud::Bigtable::GcRule.union(
+      #       Google::Cloud::Bigtable::GcRule.max_age(1800),
+      #       Google::Cloud::Bigtable::GcRule.max_versions(3)
+      #     )
+      #     cfm.add("cf3", gc_rule: gc_rule)
+      #   end
       #
-      # @example Create GC rule instance with intersection.
-      #
-      #  max_versions_gc_rule = Google::Cloud::Bigtable::GcRule.max_versions(3)
-      #  gc_rule = Google::Cloud::Bigtable::GcRule.intersection(max_versions_gc_rule)
-      #
-      #  # Change intersection GC rule
-      #  gc_rule.intersection = Google::Cloud::Bigtable::GcRule.max_age(600)
+      #   puts table.column_families["cf1"].gc_rule.max_versions
+      #   puts table.column_families["cf2"].gc_rule.max_age
+      #   puts table.column_families["cf3"].gc_rule.union
       #
       class GcRule
         # @private
@@ -74,7 +72,9 @@ module Google
           @grpc = grpc || Google::Bigtable::Admin::V2::GcRule.new
         end
 
-        # Delete all cells in a column except the most recent N.
+        ##
+        # Sets a garbage-collection rule that explicitly states the maximum
+        # number of cells to keep for all columns in a column family.
         #
         # @param versions [Integer]
         #
@@ -82,75 +82,156 @@ module Google
           @grpc.max_num_versions = versions
         end
 
-        # Get max versions.
+        ##
+        # Gets the garbage-collection rule that explicitly states the maximum
+        # number of cells to keep for all columns in a column family.
         #
         # @return [Integer, nil]
         #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5))
+        #   end
+        #
+        #   puts table.column_families["cf1"].gc_rule.max_versions
+        #
         def max_versions
           @grpc.max_num_versions
         end
 
-        # Delete cells in a column older than the given age.
-        # Values must be at least one millisecond, and will be truncated to
-        # microsecond granularity.
+        ##
+        # Sets a garbage-collection rule based on the timestamp for each cell.
+        # With this type of garbage-collection rule, you set the time to live
+        # (TTL) for data. Cloud Bigtable looks at each column family during
+        # garbage collection and removes any cells that have expired.
         #
-        # @param age [Integer] age in seconds
+        # @param age [Numeric] Max age in seconds. Values must be at least one
+        #   millisecond, and will be truncated to microsecond granularity.
         #
         def max_age= age
-          @grpc.max_age = Convert.number_to_duration(age)
+          @grpc.max_age = Convert.number_to_duration age
         end
 
-        # Max age in seconds, if max age is set.
+        ##
+        # Gets the garbage-collection rule based on the timestamp for each cell.
+        # With this type of garbage-collection rule, you set the time to live
+        # (TTL) for data. Cloud Bigtable looks at each column family during
+        # garbage collection and removes any cells that have expired.
         #
-        # @return [Integer, nil] Max age in seconds.
+        # @return [Numeric, nil] Max age in seconds.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600))
+        #   end
+        #
+        #   puts table.column_families["cf1"].gc_rule.max_age
         #
         def max_age
-          @grpc.max_age.seconds if @grpc.max_age
+          Convert.duration_to_number @grpc.max_age
         end
 
-        # Delete cells that would be deleted by every nested rule.
+        ##
+        # Sets the intersection rules collection for this GcRule.
         #
         # @param rules [Array<Google::Cloud::Bigtable::GcRule>]
         #   List of GcRule with nested rules.
         #
         def intersection= rules
-          @grpc.intersection = \
-            Google::Bigtable::Admin::V2::GcRule::Intersection.new(
-              rules: rules.map(&:to_grpc)
-            )
+          @grpc.intersection = Google::Bigtable::Admin::V2::GcRule::Intersection.new rules: rules.map(&:to_grpc)
         end
 
-        # Get intersection GC rules
+        ##
+        #
+        # Gets the intersection rules collection for this GcRule.
+        #
+        # @return [Array<Google::Cloud::Bigtable::GcRule>, nil]
         #
-        # @return [Google::Bigtable::Admin::V2::GcRule::Intersection, nil]
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     gc_rule = Google::Cloud::Bigtable::GcRule.intersection(
+        #       Google::Cloud::Bigtable::GcRule.max_age(1800),
+        #       Google::Cloud::Bigtable::GcRule.max_versions(3)
+        #     )
+        #     cfm.add("cf1", gc_rule: gc_rule)
+        #   end
+        #
+        #   puts table.column_families["cf1"].gc_rule.intersection
         #
         def intersection
-          @grpc.intersection
+          return nil unless @grpc.intersection
+          @grpc.intersection.rules.map do |gc_rule_grpc|
+            self.class.from_grpc gc_rule_grpc
+          end
         end
 
-        # Delete cells that would be deleted by any nested rule.
+        ##
+        # Sets the union rules collection for this GcRule. A union
+        # garbage-collection policy will remove all data matching *any* of its
+        # set of given rules.
         #
         # @param rules [Array<Google::Cloud::Bigtable::GcRule>]
         #   List of GcRule with nested rules.
         #
         def union= rules
-          @grpc.union = Google::Bigtable::Admin::V2::GcRule::Union.new(
-            rules: rules.map(&:to_grpc)
-          )
+          @grpc.union = Google::Bigtable::Admin::V2::GcRule::Union.new rules: rules.map(&:to_grpc)
         end
 
-        # Get union GC rules
+        ##
+        # Gets the union rules collection for this GcRule. A union
+        # garbage-collection policy will remove all data matching *any* of its
+        # set of given rules.
+        #
+        # @return [Array<Google::Cloud::Bigtable::GcRule>, nil]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
         #
-        # @return [Google::Bigtable::Admin::V2::GcRule::Union, nil]
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     gc_rule = Google::Cloud::Bigtable::GcRule.union(
+        #       Google::Cloud::Bigtable::GcRule.max_age(1800),
+        #       Google::Cloud::Bigtable::GcRule.max_versions(3)
+        #     )
+        #     cfm.add("cf1", gc_rule: gc_rule)
+        #   end
+        #
+        #   puts table.column_families["cf1"].gc_rule.union
         #
         def union
-          @grpc.union
+          return nil unless @grpc.union
+          @grpc.union.rules.map do |gc_rule_grpc|
+            self.class.from_grpc gc_rule_grpc
+          end
         end
 
-        # Create GcRule instance with max number of versions.
+        ##
+        # Creates a GcRule instance with max number of versions.
         #
         # @param versions [Integer] Max number of versions
-        # @return [Google::Bigtable::Admin::V2::GcRule]
+        # @return [Google::Cloud::Bigtable::GcRule]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5))
+        #   end
         #
         def self.max_versions versions
           new.tap do |gc_rule|
@@ -158,10 +239,20 @@ module Google
           end
         end
 
-        # Create GcRule instance with max age.
+        ##
+        # Creates a GcRule instance with max age.
         #
         # @param age [Integer] Max age in seconds.
-        # @return [Google::Bigtable::Admin::V2::GcRule]
+        # @return [Google::Cloud::Bigtable::GcRule]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600))
+        #   end
         #
         def self.max_age age
           new.tap do |gc_rule|
@@ -169,11 +260,25 @@ module Google
           end
         end
 
-        # Create union GcRule instance.
+        ##
+        # Creates a union GcRule instance.
         #
         # @param rules [Google::Cloud::Bigtable::GcRule, Array<Google::Cloud::Bigtable::GcRule>]
         #   List of GcRule with nested rules.
-        # @return [Google::Bigtable::Admin::V2::GcRule]
+        # @return [Google::Cloud::Bigtable::GcRule]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     gc_rule = Google::Cloud::Bigtable::GcRule.union(
+        #       Google::Cloud::Bigtable::GcRule.max_age(1800),
+        #       Google::Cloud::Bigtable::GcRule.max_versions(3)
+        #     )
+        #     cfm.add("cf1", gc_rule: gc_rule)
+        #   end
         #
         def self.union *rules
           new.tap do |gc_rule|
@@ -181,11 +286,25 @@ module Google
           end
         end
 
-        # Create intersection GCRule instance.
+        ##
+        # Creates a intersection GCRule instance.
         #
         # @param rules [Google::Cloud::Bigtable::GcRule, Array<Google::Cloud::Bigtable::GcRule>]
         #   List of GcRule with nested rules.
-        # @return [Google::Bigtable::Admin::V2::GcRule]
+        # @return [Google::Cloud::Bigtable::GcRule]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     gc_rule = Google::Cloud::Bigtable::GcRule.intersection(
+        #       Google::Cloud::Bigtable::GcRule.max_age(1800),
+        #       Google::Cloud::Bigtable::GcRule.max_versions(3)
+        #     )
+        #     cfm.add("cf1", gc_rule: gc_rule)
+        #   end
         #
         def self.intersection *rules
           new.tap do |gc_rule|
@@ -207,7 +326,7 @@ module Google
         # @param grpc [Google::Bigtable::Admin::V2::GcRule]
         # @return [Google::Cloud::Bigtable::GcRule]
         def self.from_grpc grpc
-          new(grpc)
+          new grpc
         end
       end
     end