google-cloud-bigtable 0.6.2 → 0.7.0

data/lib/google/cloud/bigtable/row_filter/condition_filter.rb

@@ -19,6 +19,7 @@ module Google
   module Cloud
     module Bigtable
       module RowFilter
+        ##
         # # ConditionFilter
         #
         # A RowFilter that evaluates one of two possible RowFilters, depending on
@@ -51,6 +52,7 @@ module Google
             @grpc.predicate_filter = predicate.to_grpc
           end
 
+          ##
           # Set a true filter on predicate-filter match.
           #
           # The filter to apply to the input row if `predicate_filter` returns any
@@ -72,6 +74,7 @@ module Google
             self
           end
 
+          ##
           # Set otherwise(false) filter.
           #
           # The filter to apply to the input row if `predicate_filter` does not
@@ -99,7 +102,7 @@ module Google
           # @return [Google::Bigtable::V2::RowFilter]
           #
           def to_grpc
-            Google::Bigtable::V2::RowFilter.new(condition: @grpc)
+            Google::Bigtable::V2::RowFilter.new condition: @grpc
           end
         end
       end

data/lib/google/cloud/bigtable/row_filter/interleave_filter.rb

@@ -19,6 +19,7 @@ module Google
   module Cloud
     module Bigtable
       module RowFilter
+        ##
         # # InterleaveFilter
         #
         # A RowFilter that sends each row to each of several component
@@ -59,7 +60,7 @@ module Google
         #   interleave.sink
         #
         #   # OR
-        #   interleave.key("user-*).sink
+        #   interleave.key("user-*").sink
         #
         # @example Create a complex interleave filter.
         #
@@ -69,13 +70,16 @@ module Google
         #  chain_1.label("users").qualifier("name").cells_per_row(5)
         #
         #  # Add to main chain filter
-        #  interleave.chain(chain_1).value("xyz*).key("user-*")
+        #  interleave.chain(chain_1).value("xyz*").key("user-*")
         #
         class InterleaveFilter
+          # @private
+          # Creates an instance of an interleave filter.
           def initialize
-            @grpc = Google::Bigtable::V2::RowFilter::Interleave.new
+            @filters = []
           end
 
+          ##
           # Adds a chain filter instance.
           #
           # A Chain RowFilter that sends rows through several RowFilters in sequence.
@@ -100,12 +104,11 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.chain(chain)
           #
           def chain filter
-            unless filter.instance_of?(ChainFilter)
-              raise RowFilterError, "Filter type must be ChainFilter"
-            end
-            add(filter)
+            raise RowFilterError, "Filter type must be ChainFilter" unless filter.instance_of? ChainFilter
+            add filter
           end
 
+          ##
           # Adds an interleave filter.
           #
           # A RowFilter that sends each row to each of several component
@@ -151,12 +154,11 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.interleave(interleave)
           #
           def interleave filter
-            unless filter.instance_of?(InterleaveFilter)
-              raise RowFilterError, "Filter type must be InterleaveFilter"
-            end
-            add(filter)
+            raise RowFilterError, "Filter type must be InterleaveFilter" unless filter.instance_of? InterleaveFilter
+            add filter
           end
 
+          ##
           # Adds a condition filter instance.
           #
           # A RowFilter that evaluates one of two possible RowFilters, depending on
@@ -180,17 +182,17 @@ module Google
           #   label = Google::Cloud::Bigtable::RowFilter.label("user")
           #   strip_value = Google::Cloud::Bigtable::RowFilter.strip_value
           #
-          #   condition_filter = Google::Cloud::Bigtable::RowFilter.condition(predicate).on_match(label).otherwise(strip_value)
+          #   condition_filter = Google::Cloud::Bigtable::RowFilter.
+          #     condition(predicate).on_match(label).otherwise(strip_value)
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.condition(condition_filter)
           #
           def condition filter
-            unless filter.instance_of?(ConditionFilter)
-              raise RowFilterError, "Filter type must be ConditionFilter"
-            end
-            add(filter)
+            raise RowFilterError, "Filter type must be ConditionFilter" unless filter.instance_of? ConditionFilter
+            add filter
           end
 
+          ##
           # Adds a pass filter instance.
           #
           # Matches all cells, regardless of input. Functionally equivalent to
@@ -204,9 +206,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.pass
           #
           def pass
-            add(RowFilter.pass)
+            add RowFilter.pass
           end
 
+          ##
           # Adds a block-all filter instance.
           #
           # Does not match any cells, regardless of input. Useful for temporarily
@@ -220,9 +223,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.block
           #
           def block
-            add(RowFilter.block)
+            add RowFilter.block
           end
 
+          ##
           # Adds a sink filter instance.
           #
           # Outputs all cells directly to the output of the read rather than to any parent filter.
@@ -235,9 +239,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.sink
           #
           def sink
-            add(RowFilter.sink)
+            add RowFilter.sink
           end
 
+          ##
           # Adds a strip-value filter instance.
           #
           # Replaces each cell's value with an empty string.
@@ -250,9 +255,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.strip_value
           #
           def strip_value
-            add(RowFilter.strip_value)
+            add RowFilter.strip_value
           end
 
+          ##
           # Adds a row-key filter instance to match key using a regular expression.
           #
           # Matches only cells from rows whose keys satisfy the given RE2 regex. In
@@ -275,9 +281,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.key("user-*")
           #
           def key regex
-            add(RowFilter.key(regex))
+            add RowFilter.key(regex)
           end
 
+          ##
           # Adds a sample-probability filter instance.
           #
           # Matches all cells from a row with probability p, and matches no cells
@@ -293,9 +300,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.sample(0.5)
           #
           def sample probability
-            add(RowFilter.sample(probability))
+            add RowFilter.sample(probability)
           end
 
+          ##
           # Adds a family-name-match filter using a regular expression.
           #
           # Matches only cells from columns whose families satisfy the given RE2
@@ -317,9 +325,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.family("cf-*")
           #
           def family regex
-            add(RowFilter.family(regex))
+            add RowFilter.family(regex)
           end
 
+          ##
           # Adds a column-qualifier-match filter using a regular expression.
           #
           # Matches only cells from columns whose qualifiers satisfy the given RE2
@@ -341,9 +350,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.qualifier("user-name*")
           #
           def qualifier regex
-            add(RowFilter.qualifier(regex))
+            add RowFilter.qualifier(regex)
           end
 
+          ##
           # Adds a value-match filter using a regular expression.
           #
           # Matches only cells with values that satisfy the given regular expression.
@@ -364,9 +374,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.value("abc*")
           #
           def value regex
-            add(RowFilter.value(regex))
+            add RowFilter.value(regex)
           end
 
+          ##
           # Adds a label filter instance to apply a label based on the result of read rows.
           #
           # Applies the given label to all cells in the output row. This allows
@@ -391,9 +402,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.label("user-detail")
           #
           def label value
-            add(RowFilter.label(value))
+            add RowFilter.label(value)
           end
 
+          ##
           # Adds a cell-per-row-offset filter instance to skip the first N cells.
           #
           # Skips the first N cells of each row, matching all subsequent cells.
@@ -409,9 +421,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.cells_per_row_offset(3)
           #
           def cells_per_row_offset offset
-            add(RowFilter.cells_per_row_offset(offset))
+            add RowFilter.cells_per_row_offset(offset)
           end
 
+          ##
           # Adds a cells-per-row-limit filter instance.
           #
           # Matches only the first N cells of each row.
@@ -427,9 +440,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.cells_per_row(5)
           #
           def cells_per_row limit
-            add(RowFilter.cells_per_row(limit))
+            add RowFilter.cells_per_row(limit)
           end
 
+          ##
           # Adds a cells-per-column filter instance.
           #
           # Matches only the most recent N cells within each column. For example,
@@ -448,9 +462,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.cells_per_column(5)
           #
           def cells_per_column limit
-            add(RowFilter.cells_per_column(limit))
+            add RowFilter.cells_per_column(limit)
           end
 
+          ##
           # Adds a timestamp-range filter instance.
           #
           # Matches only cells with timestamps within the given range.
@@ -472,9 +487,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.timestamp_range(from: from, to: to)
           #
           def timestamp_range from: nil, to: nil
-            add(RowFilter.timestamp_range(from: from, to: to))
+            add RowFilter.timestamp_range(from: from, to: to)
           end
 
+          ##
           # Adds a value-range filter instance.
           #
           # Matches only cells with values that fall within the given range.
@@ -483,26 +499,36 @@ module Google
           # option inclusive/exclusive options.
           #
           # * The value at which to start the range. If neither field is set, interpreted as an empty string, inclusive.
-          # * The value at which to end the range. If neither field is set, interpreted as an infinite string, exclusive.
+          # * The value at which to end the range. If neither field is set, interpreted as an infinite string,
+          #   exclusive.
           #
           # @param range [Google::Cloud::Bigtable::ValueRange]
           # @return [Google::Cloud::Bigtable::RowFilter::InterleaveFilter]
           #   `self` instance of interleave filter.
           #
           # @example Start to end range
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #   table = bigtable.table("my-instance", "my-table")
           #
-          #   range = Google::Cloud::Bigtable::ValueRange.from("abc").to('xyz')
+          #   range = table.new_value_range.from("value-001").to("value-005")
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.value_range(range)
           #
           # @example Start exlusive to infinite end range
+          #   require "google/cloud/bigtable"
+          #
+          #   bigtable = Google::Cloud::Bigtable.new
+          #   table = bigtable.table("my-instance", "my-table")
           #
-          #   range = Google::Cloud::Bigtable::ValueRange.from("abc", inclusive: false)
+          #   range = table.new_value_range.from("value-001", inclusive: false)
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.value_range(range)
           #
           def value_range range
-            add(RowFilter.value_range(range))
+            add RowFilter.value_range(range)
           end
 
+          ##
           # Adds a column-range filter instance.
           #
           # Matches only cells from columns within the given range.
@@ -512,16 +538,18 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
-          #   range = Google::Cloud::Bigtable::ColumnRange.new(cf).from("field0").to('field5')
+          #   range = Google::Cloud::Bigtable::ColumnRange.new("cf").from("field0").to("field5")
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.column_range(range)
           #
           def column_range range
-            add(RowFilter.column_range(range))
+            add RowFilter.column_range(range)
           end
 
-          # Gets the number of filters in chain filters.
+          ##
+          # Returns the number of filters in the interleave.
           #
           # @return [Integer]
           #
@@ -531,15 +559,16 @@ module Google
           #  filter.length # 2
           #
           def length
-            @grpc.filters.length
+            @filters.length
           end
 
-          # Gets a list of filters.
+          ##
+          # Returns a frozen copy of the filters array.
           #
-          # @return [Array<Google::Bigtable::V2::RowFilter>]
+          # @return [Array<SimpleFilter|ChainFilter|InterleaveFilter|ConditionFilter>]
           #
           def filters
-            @grpc.filters
+            @filters.dup.freeze
           end
 
           # @private
@@ -549,7 +578,9 @@ module Google
           # @return [Google::Bigtable::V2::RowFilter]
           #
           def to_grpc
-            Google::Bigtable::V2::RowFilter.new(interleave: @grpc)
+            Google::Bigtable::V2::RowFilter.new(
+              interleave: Google::Bigtable::V2::RowFilter::Interleave.new(filters: @filters.map(&:to_grpc))
+            )
           end
 
           private
@@ -560,7 +591,7 @@ module Google
           # @param filter [SimpleFilter, ChainFilter, InterleaveFilter, ConditionFilter]
           #
           def add filter
-            @grpc.filters << filter.to_grpc
+            @filters << filter
             self
           end
         end

data/lib/google/cloud/bigtable/row_filter/simple_filter.rb

@@ -19,6 +19,7 @@ module Google
   module Cloud
     module Bigtable
       module RowFilter
+        ##
         #
         # # SimpleFilter
         #
@@ -30,6 +31,7 @@ module Google
             @grpc = Google::Bigtable::V2::RowFilter.new
           end
 
+          ##
           # Outputs all cells directly to the output of the read rather than to any parent filter.
           #
           # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
@@ -39,6 +41,7 @@ module Google
             self
           end
 
+          ##
           # Matches all cells, regardless of input. Functionally equivalent to
           # leaving `filter` unset, but included for completeness.
           #
@@ -49,6 +52,7 @@ module Google
             self
           end
 
+          ##
           # Does not match any cells, regardless of input. Useful for temporarily
           # disabling just part of a filter.
           #
@@ -59,6 +63,7 @@ module Google
             self
           end
 
+          ##
           # Replaces each cell's value with an empty string.
           #
           # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
@@ -68,6 +73,7 @@ module Google
             self
           end
 
+          ##
           # Matches only cells from rows whose keys satisfy the given RE2 regex. In
           # other words, passes through the entire row when the key matches, and
           # otherwise produces an empty row.
@@ -87,6 +93,7 @@ module Google
             self
           end
 
+          ##
           # Matches all cells from a row with probability p, and matches no cells
           # from the row with probability 1-p.
           #
@@ -95,15 +102,13 @@ module Google
           #
           def sample probability
             if probability >= 1 || probability <= 0
-              raise(
-                RowFilterError,
-                "Probability must be greather then 0 and less then 1.0"
-              )
+              raise RowFilterError, "Probability must be greather then 0 and less then 1.0"
             end
             @grpc.row_sample_filter = probability
             self
           end
 
+          ##
           # Matches only cells from columns whose families satisfy the given RE2
           # regex. For technical reasons, the regex must not contain the `:`
           # character, even if it is not being used as a literal.
@@ -119,6 +124,7 @@ module Google
             self
           end
 
+          ##
           # Matches only cells from columns whose qualifiers satisfy the given RE2
           # regex.
           # Note that, since column qualifiers can contain arbitrary bytes, the `\C`
@@ -134,6 +140,7 @@ module Google
             self
           end
 
+          ##
           # Matches only cells with values that satisfy the given regular expression.
           # Note that, since cell values can contain arbitrary bytes, the `\C` escape
           # sequence must be used if a true wildcard is desired. The `.` character
@@ -148,6 +155,7 @@ module Google
             self
           end
 
+          ##
           # Applies the given label to all cells in the output row. This allows
           # the client to determine which results were produced from which part of
           # the filter.
@@ -169,6 +177,7 @@ module Google
             self
           end
 
+          ##
           # Skips the first N cells of each row, matching all subsequent cells.
           # If duplicate cells are present, as is possible when using an interleave,
           # each copy of the cell is counted separately.
@@ -181,6 +190,7 @@ module Google
             self
           end
 
+          ##
           # Matches only the first N cells of each row.
           # If duplicate cells are present, as is possible when using an Interleave,
           # each copy of the cell is counted separately.
@@ -193,6 +203,7 @@ module Google
             self
           end
 
+          ##
           # Matches only the most recent N cells within each column. For example,
           # if N=2, this filter would match column `foo:bar` at timestamps 10 and 9,
           # skip all earlier cells in `foo:bar`, and then begin matching again in
@@ -208,6 +219,7 @@ module Google
             self
           end
 
+          ##
           # Creates a timestamp-range filter instance.
           #
           # Matches only cells with timestamps within the given range.
@@ -225,32 +237,35 @@ module Google
             self
           end
 
+          ##
           # Matches only cells with values that fall within the given range.
           #
           # See {Google::Cloud::Bigtable::ValueRange#from} and { Google::Cloud::Bigtable::ValueRange#to} for range
           # option inclusive/exclusive options
           #
           # * The value at which to start the range. If neither field is set, interpreted as an empty string, inclusive.
-          # * The value at which to end the range. If neither field is set, interpreted as an infinite string, exclusive.
+          # * The value at which to end the range. If neither field is set, interpreted as an infinite string,
+          #   exclusive.
           #
           # @param range [Google::Cloud::Bigtable::ValueRange]
           # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
           #
           def value_range range
-            unless range.instance_of?(Google::Cloud::Bigtable::ValueRange)
+            unless range.instance_of? Google::Cloud::Bigtable::ValueRange
               raise RowFilterError, "Range type mustbe ValueRange"
             end
             @grpc.value_range_filter = range.to_grpc
             self
           end
 
+          ##
           # Matches only cells from columns within the given range.
           #
           # @param range [Google::Cloud::Bigtable::ColumnRange]
           # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
           #
           def column_range range
-            unless range.instance_of?(Google::Cloud::Bigtable::ColumnRange)
+            unless range.instance_of? Google::Cloud::Bigtable::ColumnRange
               raise RowFilterError, "Range type mustbe ColumnRange"
             end
             @grpc.column_range_filter = range.to_grpc