google-cloud-bigtable 0.6.1 → 1.0.1

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,7 +52,8 @@ module Google
             @grpc.predicate_filter = predicate.to_grpc
           end
 
-          # Set a true filter on predicate-filter match.
+          ##
+          # Sets a true filter on predicate-filter match.
           #
           # The filter to apply to the input row if `predicate_filter` returns any
           # results. If not provided, no results will be returned in the true case.
@@ -60,6 +62,7 @@ module Google
           # @return [Google::Cloud::Bigtable::RowFilter::ConditionFilter]
           #
           # @example
+          #   require "google/cloud/bigtable"
           #   predicate = Google::Cloud::Bigtable::RowFilter.key("user-*")
           #
           #   label = Google::Cloud::Bigtable::RowFilter.label("user")
@@ -72,6 +75,7 @@ module Google
             self
           end
 
+          ##
           # Set otherwise(false) filter.
           #
           # The filter to apply to the input row if `predicate_filter` does not
@@ -82,6 +86,8 @@ module Google
           # @return [Google::Cloud::Bigtable::RowFilter::ConditionFilter]
           #
           # @example
+          #   require "google/cloud/bigtable"
+          #
           #   predicate = Google::Cloud::Bigtable::RowFilter.key("user-*")
           #
           #   label = Google::Cloud::Bigtable::RowFilter.label("user")
@@ -99,7 +105,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
@@ -51,6 +52,7 @@ module Google
         # All interleaved filters are executed atomically.
         #
         # @example Create an interleave filter with a simple filter.
+        #   require "google/cloud/bigtable"
         #
         #   interleave = Google::Cloud::Bigtable::RowFilter.interleave
         #
@@ -59,24 +61,28 @@ module Google
         #   interleave.sink
         #
         #   # OR
-        #   interleave.key("user-*).sink
+        #   interleave.key("user-*").sink
         #
         # @example Create a complex interleave filter.
+        #   require "google/cloud/bigtable"
         #
-        #  interleave = Google::Cloud::Bigtable::RowFilter.interleave
+        #   interleave = Google::Cloud::Bigtable::RowFilter.interleave
         #
-        #  chain_1 = Google::Cloud::Bigtable::RowFilter.chain
-        #  chain_1.label("users").qualifier("name").cells_per_row(5)
+        #   chain_1 = Google::Cloud::Bigtable::RowFilter.chain
+        #   chain_1.label("users").qualifier("name").cells_per_row(5)
         #
-        #  # Add to main chain filter
-        #  interleave.chain(chain_1).value("xyz*).key("user-*")
+        #   # Add to main chain filter
+        #   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.
+          ##
+          # Adds a chain filter.
           #
           # A Chain RowFilter that sends rows through several RowFilters in sequence.
           #
@@ -91,6 +97,7 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example Create a chain filter and add an interleave filter.
+          #   require "google/cloud/bigtable"
           #
           #   chain = Google::Cloud::Bigtable::RowFilter.chain
           #
@@ -100,12 +107,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
@@ -142,6 +148,7 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example Add an interleave filter to a chain filter.
+          #   require "google/cloud/bigtable"
           #
           #   interleave = Google::Cloud::Bigtable::RowFilter.interleave
           #
@@ -151,13 +158,12 @@ 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.
+          ##
+          # Adds a condition filter.
           #
           # A RowFilter that evaluates one of two possible RowFilters, depending on
           # whether or not a predicate RowFilter outputs any cells from the input row.
@@ -174,24 +180,25 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   predicate = Google::Cloud::Bigtable::RowFilter.key("user-*")
           #
           #   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.
+          ##
+          # Adds a pass filter.
           #
           # Matches all cells, regardless of input. Functionally equivalent to
           # leaving `filter` unset, but included for completeness.
@@ -200,14 +207,16 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.pass
           #
           def pass
-            add(RowFilter.pass)
+            add RowFilter.pass
           end
 
-          # Adds a block-all filter instance.
+          ##
+          # Adds a block-all filter.
           #
           # Does not match any cells, regardless of input. Useful for temporarily
           # disabling just part of a filter.
@@ -216,14 +225,16 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.block
           #
           def block
-            add(RowFilter.block)
+            add RowFilter.block
           end
 
-          # Adds a sink filter instance.
+          ##
+          # Adds a sink filter.
           #
           # Outputs all cells directly to the output of the read rather than to any parent filter.
           #
@@ -231,14 +242,16 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.interleave.sink
           #
           def sink
-            add(RowFilter.sink)
+            add RowFilter.sink
           end
 
-          # Adds a strip-value filter instance.
+          ##
+          # Adds a strip-value filter.
           #
           # Replaces each cell's value with an empty string.
           #
@@ -246,13 +259,15 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   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
@@ -271,31 +286,35 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   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.
+          ##
+          # Adds a sample-probability filter.
           #
           # Matches all cells from a row with probability p, and matches no cells
           # from the row with probability 1-p.
           #
-          # @param probability [Float] Probability value
-          #   Probability must be greather then 0 and less then 1.0
+          # @param probability [Float] Probability value.
+          #   Probability must be greater than 0 and less than 1.0.
           # @return [Google::Cloud::Bigtable::RowFilter::InterleaveFilter]
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   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
@@ -313,13 +332,15 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   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
@@ -337,13 +358,15 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   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.
@@ -360,13 +383,15 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   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
@@ -374,7 +399,7 @@ module Google
           # the filter.
           #
           # Values must be at most 15 characters in length, and match the RE2
-          # pattern `[a-z0-9\\-]+`
+          # pattern `[a-z0-9\\-]+`.
           #
           # Due to a technical limitation, it is not possible to apply
           # multiple labels to a cell. As a result, a Chain may have no more than
@@ -387,13 +412,15 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   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.
@@ -405,14 +432,16 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   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.
+          ##
+          # Adds a cells-per-row-limit filter.
           #
           # Matches only the first N cells of each row.
           # If duplicate cells are present, as is possible when using an interleave,
@@ -423,14 +452,16 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   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.
+          ##
+          # Adds a cells-per-column filter.
           #
           # 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,
@@ -444,14 +475,16 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   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.
+          ##
+          # Adds a timestamp-range filter.
           #
           # Matches only cells with timestamps within the given range.
           # Specifies a contiguous range of timestamps.
@@ -464,6 +497,7 @@ module Google
           #   `self` instance of interleave filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   timestamp_micros = (Time.now.to_f * 1000000).round(-3)
           #   from = timestamp_micros - 300000000
@@ -472,10 +506,11 @@ 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.
+          ##
+          # Adds a value-range filter.
           #
           # Matches only cells with values that fall within the given range.
           #
@@ -483,27 +518,37 @@ 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
+          # @example Start to end range.
+          #   require "google/cloud/bigtable"
           #
-          #   range = Google::Cloud::Bigtable::ValueRange.from("abc").to('xyz')
+          #   bigtable = Google::Cloud::Bigtable.new
+          #   table = bigtable.table("my-instance", "my-table")
+          #
+          #   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
+          # @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.
+          ##
+          # Adds a column-range filter.
           #
           # Matches only cells from columns within the given range.
           #
@@ -512,34 +557,38 @@ 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]
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
-          #  filter = Google::Cloud::Bigtable::RowFilter.interleave.key("user-1*").label("user")
-          #  filter.length # 2
+          #   filter = Google::Cloud::Bigtable::RowFilter.interleave.key("user-1*").label("user")
+          #   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 +598,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 +611,7 @@ module Google
           # @param filter [SimpleFilter, ChainFilter, InterleaveFilter, ConditionFilter]
           #
           def add filter
-            @grpc.filters << filter.to_grpc
+            @filters << filter
             self
           end
         end