google-cloud-bigtable 0.6.2 → 1.0.2

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

@@ -19,15 +19,19 @@ module Google
   module Cloud
     module Bigtable
       module RowFilter
+        ##
         # # ChainFilter
         #
         # A RowFilter that sends rows through several RowFilters in sequence.
         #
         # The elements of "filters" are chained together to process the input row:
-        # in row -> f(0) -> intermediate row -> f(1) -> ... -> f(N) -> out row
+        #
+        #     in row -> f(0) -> intermediate row -> f(1) -> ... -> f(N) -> out row
+        #
         # The full chain is executed atomically.
         #
         # @example
+        #   require "google/cloud/bigtable"
         #
         #   chain = Google::Cloud::Bigtable::RowFilter.chain
         #   # Add filters to chain filter
@@ -37,15 +41,18 @@ module Google
           # @private
           # Creates an instance of a chain filter.
           def initialize
-            @grpc = Google::Bigtable::V2::RowFilter::Chain.new
+            @filters = []
           end
 
-          # Adds a chain filter instance.
+          ##
+          # Adds a chain filter.
           #
           # A Chain RowFilter that sends rows through several RowFilters in sequence.
           #
           # The elements of "filters" are chained together to process the input row:
-          # in row -> f(0) -> intermediate row -> f(1) -> ... -> f(N) -> out row
+          #
+          #     in row -> f(0) -> intermediate row -> f(1) -> ... -> f(N) -> out row
+          #
           # The full chain is executed atomically.
           #
           # @param filter [SimpleFilter, ChainFilter, InterleaveFilter, ConditionFilter]
@@ -53,6 +60,7 @@ module Google
           #   `self` instance of chain filter.
           #
           # @example Create a chain filter and add a chain filter.
+          #   require "google/cloud/bigtable"
           #
           #   chain_1 = Google::Cloud::Bigtable::RowFilter.chain
           #
@@ -66,13 +74,12 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.chain(chain_1)
           #
           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
 
-          # Add interleave filter.
+          ##
+          # Adds an interleave filter.
           #
           # A RowFilter that sends each row to each of several component
           # RowFilters and interleaves the results.
@@ -109,7 +116,8 @@ module Google
           # @return [Google::Cloud::Bigtable::RowFilter::ChainFilter]
           #   `self` instance of chain filter.
           #
-          # @example Add interleave filter to chain filter
+          # @example Add an interleave filter to the chain filter.
+          #   require "google/cloud/bigtable"
           #
           #   interleave = Google::Cloud::Bigtable::RowFilter.interleave
           #
@@ -119,13 +127,12 @@ module Google
           #   chain = Google::Cloud::Bigtable::RowFilter.chain.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.
@@ -142,24 +149,25 @@ module Google
           #   `self` instance of chain 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.chain.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.
@@ -168,14 +176,16 @@ module Google
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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.
@@ -184,14 +194,16 @@ module Google
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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.
           #
@@ -199,14 +211,16 @@ module Google
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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.
           #
@@ -214,13 +228,15 @@ module Google
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.strip_value
           #
           def strip_value
-            add(RowFilter.strip_value)
+            add RowFilter.strip_value
           end
 
+          ##
           # Adds a key-filter instance to match keys using a regular expression.
           #
           # Matches only cells from rows whose keys satisfy the given RE2 regex. In
@@ -239,31 +255,35 @@ module Google
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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::ChainFilter]
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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
@@ -281,14 +301,16 @@ module Google
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.family("cf-*")
           #
           def family regex
-            add(RowFilter.family(regex))
+            add RowFilter.family(regex)
           end
 
-          # Add a column-qualifier-match filter using a regular expression.
+          ##
+          # Adds a column-qualifier-match filter using a regular expression.
           #
           # Matches only cells from columns whose qualifiers satisfy the given RE2
           # regex.
@@ -305,13 +327,15 @@ module Google
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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.
@@ -328,13 +352,15 @@ module Google
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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
@@ -355,13 +381,15 @@ module Google
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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.
@@ -373,32 +401,36 @@ module Google
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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,
           # each copy of the cell is counted separately.
           #
-          # @param limit [String] Max cell match per row limit
+          # @param limit [String] Max cell match per row limit.
           # @return [Google::Cloud::Bigtable::RowFilter::ChainFilter]
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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,
@@ -407,19 +439,21 @@ module Google
           # If duplicate cells are present, as is possible when using an Interleave,
           # each copy of the cell is counted separately.
           #
-          # @param limit [String] Max cell match per column limit
+          # @param limit [String] Max cell match per column limit.
           # @return [Google::Cloud::Bigtable::RowFilter::ChainFilter]
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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.
@@ -432,6 +466,7 @@ module Google
           #   `self` instance of chain filter.
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
           #   timestamp_micros = (Time.now.to_f * 1000000).round(-3)
           #   from = timestamp_micros - 300000000
@@ -440,38 +475,49 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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.
           #
           # See {Google::Cloud::Bigtable::ValueRange#from} and { Google::Cloud::Bigtable::ValueRange#to} for range
-          # option inclusive/exclusive options
+          # 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 the infinite string, exclusive.
+          # * The value at which to end the range. If neither field is set, interpreted as the infinite string,
+          #   exclusive.
           #
           # @param range [Google::Cloud::Bigtable::ValueRange]
           # @return [Google::Cloud::Bigtable::RowFilter::ChainFilter]
           #   `self` instance of chain 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.chain.value_range(range)
           #
-          # @example Start exlusive to infinite end range
+          # @example Start exclusive 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.chain.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.
           #
@@ -480,34 +526,38 @@ module Google
           #   `self` instance of chain 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.chain.column_range(range)
           #
           def column_range range
-            add(RowFilter.column_range(range))
+            add RowFilter.column_range(range)
           end
 
-          # Gets the number of filters in the chain filter.
+          ##
+          # Gets the number of filters in the chain.
           #
           # @return [Integer]
           #
           # @example
+          #   require "google/cloud/bigtable"
           #
-          #  filter = Google::Cloud::Bigtable::RowFilter.chain.key("user-1*").label("user")
-          #  filter.length # 2
+          #   filter = Google::Cloud::Bigtable::RowFilter.chain.key("user-1*").label("user")
+          #   filter.length # 2
           #
           def length
-            @grpc.filters.length
+            @filters.length
           end
 
-          # Gets the 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
@@ -517,10 +567,11 @@ module Google
           # @return [Google::Bigtable::V2::RowFilter]
           #
           def to_grpc
-            Google::Bigtable::V2::RowFilter.new(chain: @grpc)
+            Google::Bigtable::V2::RowFilter.new(
+              chain: Google::Bigtable::V2::RowFilter::Chain.new(filters: @filters.map(&:to_grpc))
+            )
           end
 
-
           private
 
           # @private
@@ -529,7 +580,7 @@ module Google
           # @param filter [SimpleFilter, ChainFilter, InterleaveFilter, ConditionFilter]
           #
           def add filter
-            @grpc.filters << filter.to_grpc
+            @filters << filter
             self
           end
         end