google-cloud-bigtable 0.6.2 → 0.7.0

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

@@ -26,6 +26,7 @@ require "google/cloud/bigtable/row_filter/condition_filter"
 module Google
   module Cloud
     module Bigtable
+      ##
       # # RowFilter
       #
       # Takes a row as input and produces an alternate view of the row based on
@@ -145,6 +146,7 @@ module Google
 
         private_constant :PASS, :BLOCK, :SINK, :STRIP_VALUE
 
+        ##
         # Creates a chain filter instance.
         #
         # A chain RowFilter that sends rows through several RowFilters in sequence.
@@ -166,7 +168,7 @@ module Google
         #   chain.strip_value
         #
         #   # OR
-        #   chain.key("user-*).strip_value
+        #   chain.key("user-*").strip_value
         #
         # @example Create complex chain filter.
         #
@@ -176,12 +178,13 @@ module Google
         #   chain_1.label("users").qualifier("name").cells_per_row(5)
         #
         #   # Add to main chain filter
-        #   chain.chain(chain_1).value("xyz*).key("user-*")
+        #   chain.chain(chain_1).value("xyz*").key("user-*")
         #
         def self.chain
           ChainFilter.new
         end
 
+        ##
         # Creates an interleave filter.
         #
         # A RowFilter that sends each row to each of several component
@@ -224,7 +227,7 @@ module Google
         #   interleave.sink
         #
         #   # OR
-        #   interleave.key("user-*).sink
+        #   interleave.key("user-*").sink
         #
         # @example Create complex interleave filter.
         #
@@ -234,12 +237,13 @@ 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-*")
         #
         def self.interleave
           InterleaveFilter.new
         end
 
+        ##
         # Creates a condition filter instance.
         #
         # A RowFilter that evaluates one of two possible RowFilters, depending on
@@ -267,9 +271,10 @@ module Google
         #   condition.on_match(label).otherwise(strip_value)
         #
         def self.condition predicate
-          ConditionFilter.new(predicate)
+          ConditionFilter.new predicate
         end
 
+        ##
         # Creates a pass filter instance.
         #
         # Matches all cells, regardless of input. Functionally equivalent to
@@ -285,6 +290,7 @@ module Google
           PASS
         end
 
+        ##
         # Creates a block-all filter instance.
         #
         # Does not match any cells, regardless of input. Useful for temporarily
@@ -300,6 +306,7 @@ module Google
           BLOCK
         end
 
+        ##
         # Creates a sink filter instance.
         #
         # Outputs all cells directly to the output of the read rather than to any
@@ -315,6 +322,7 @@ module Google
           SINK
         end
 
+        ##
         # Creates a strip value filter instance.
         #
         # Replaces each cell's value with an empty string.
@@ -329,6 +337,7 @@ module Google
           STRIP_VALUE
         end
 
+        ##
         # Creates a key filter instance to match a row key using a regular expression.
         #
         # Matches only cells from rows whose row keys satisfy the given RE2 regex. In
@@ -350,9 +359,10 @@ module Google
         #   filter = Google::Cloud::Bigtable::RowFilter.key("user-.*")
         #
         def self.key regex
-          SimpleFilter.new.key(regex)
+          SimpleFilter.new.key regex
         end
 
+        ##
         # Creates a sample probability filter instance.
         #
         # Matches all cells from a row with probability p, and matches no cells
@@ -367,9 +377,10 @@ module Google
         #   filter = Google::Cloud::Bigtable::RowFilter.sample(0.5)
         #
         def self.sample probability
-          SimpleFilter.new.sample(probability)
+          SimpleFilter.new.sample probability
         end
 
+        ##
         # Creates a family name match filter using a regular expression.
         #
         # Matches only cells from columns whose families satisfy the given RE2
@@ -390,9 +401,10 @@ module Google
         #   filter = Google::Cloud::Bigtable::RowFilter.family("cf-.*")
         #
         def self.family regex
-          SimpleFilter.new.family(regex)
+          SimpleFilter.new.family regex
         end
 
+        ##
         # Creates a column qualifier match filter using a regular expression.
         #
         # Matches only cells from columns whose qualifiers satisfy the given RE2
@@ -413,9 +425,10 @@ module Google
         #   filter = Google::Cloud::Bigtable::RowFilter.qualifier("user-name.*")
         #
         def self.qualifier regex
-          SimpleFilter.new.qualifier(regex)
+          SimpleFilter.new.qualifier regex
         end
 
+        ##
         # Creates a value match filter using a regular expression.
         #
         # Matches only cells with values that satisfy the given regular expression.
@@ -435,9 +448,10 @@ module Google
         #   filter = Google::Cloud::Bigtable::RowFilter.value("abc.*")
         #
         def self.value regex
-          SimpleFilter.new.value(regex)
+          SimpleFilter.new.value regex
         end
 
+        ##
         # Creates a label filter instance to apply a label based on the result of
         # read rows.
         #
@@ -462,9 +476,10 @@ module Google
         #   filter = Google::Cloud::Bigtable::RowFilter.label("user-detail")
         #
         def self.label value
-          SimpleFilter.new.label(value)
+          SimpleFilter.new.label value
         end
 
+        ##
         # Creates a cell-per-row-offset filter instance to skip first N cells.
         #
         # Skips the first N cells of each row, matching all subsequent cells.
@@ -479,9 +494,10 @@ module Google
         #   filter = Google::Cloud::Bigtable::RowFilter.cells_per_row_offset(3)
         #
         def self.cells_per_row_offset offset
-          SimpleFilter.new.cells_per_row_offset(offset)
+          SimpleFilter.new.cells_per_row_offset offset
         end
 
+        ##
         # Create a cells-per-row limit filter instance.
         #
         # Matches only the first N cells of each row.
@@ -496,9 +512,10 @@ module Google
         #   filter = Google::Cloud::Bigtable::RowFilter.cells_per_row(5)
         #
         def self.cells_per_row limit
-          SimpleFilter.new.cells_per_row(limit)
+          SimpleFilter.new.cells_per_row limit
         end
 
+        ##
         # Creates cells-per-column filter instance.
         #
         # Matches only the most recent N cells within each column.
@@ -513,9 +530,10 @@ module Google
         #   filter = Google::Cloud::Bigtable::RowFilter.cells_per_column(5)
         #
         def self.cells_per_column limit
-          SimpleFilter.new.cells_per_column(limit)
+          SimpleFilter.new.cells_per_column limit
         end
 
+        ##
         # Creates a timestamp-range filter instance.
         #
         # Matches only cells with timestamps within the given range.
@@ -540,9 +558,10 @@ module Google
         #   filter = Google::Cloud::Bigtable::RowFilter.timestamp_range(to: to)
         #
         def self.timestamp_range from: nil, to: nil
-          SimpleFilter.new.timestamp_range(from, to)
+          SimpleFilter.new.timestamp_range from, to
         end
 
+        ##
         # Creates a value-range filter instance.
         #
         # Matches only cells with values that fall within the given range.
@@ -559,19 +578,28 @@ module Google
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @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", inclusive: false)
         #   filter = Google::Cloud::Bigtable::RowFilter.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.value_range(range)
         #
         def self.value_range range
-          SimpleFilter.new.value_range(range)
+          SimpleFilter.new.value_range range
         end
 
+        ##
         # Creates a column-range filter instance.
         #
         # Matches only cells from columns within the given range.
@@ -580,13 +608,14 @@ module Google
         # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
         #
         # @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.column_range(range)
         #
         def self.column_range range
-          SimpleFilter.new.column_range(range)
+          SimpleFilter.new.column_range range
         end
       end
     end

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

@@ -19,6 +19,7 @@ module Google
   module Cloud
     module Bigtable
       module RowFilter
+        ##
         # # ChainFilter
         #
         # A RowFilter that sends rows through several RowFilters in sequence.
@@ -37,9 +38,10 @@ 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.
           #
           # A Chain RowFilter that sends rows through several RowFilters in sequence.
@@ -66,12 +68,11 @@ 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.
           #
           # A RowFilter that sends each row to each of several component
@@ -119,12 +120,11 @@ 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.
           #
           # A RowFilter that evaluates one of two possible RowFilters, depending on
@@ -148,17 +148,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.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.
           #
           # Matches all cells, regardless of input. Functionally equivalent to
@@ -172,9 +172,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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
@@ -188,9 +189,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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.
@@ -203,9 +205,10 @@ module Google
           #   filter = Google::Cloud::Bigtable::RowFilter.chain.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.
@@ -218,9 +221,10 @@ module Google
           #   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
@@ -243,9 +247,10 @@ module Google
           #   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.
           #
           # Matches all cells from a row with probability p, and matches no cells
@@ -261,9 +266,10 @@ module Google
           #   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
@@ -285,9 +291,10 @@ module Google
           #   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.
           #
           # Matches only cells from columns whose qualifiers satisfy the given RE2
@@ -309,9 +316,10 @@ module Google
           #   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.
@@ -332,9 +340,10 @@ module Google
           #   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
@@ -359,9 +368,10 @@ module Google
           #   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.
@@ -377,9 +387,10 @@ module Google
           #   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.
           #
           # Matches only the first N cells of each row.
@@ -395,9 +406,10 @@ module Google
           #   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.
           #
           # Matches only the most recent N cells within each column. For example,
@@ -416,9 +428,10 @@ module Google
           #   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.
           #
           # Matches only cells with timestamps within the given range.
@@ -440,9 +453,10 @@ 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.
           #
           # Matches only cells with values that fall within the given range.
@@ -451,26 +465,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 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
+          #   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.
           #
           # Matches only cells from columns within the given range.
@@ -480,16 +504,18 @@ 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]
           #
@@ -499,15 +525,16 @@ module Google
           #  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 +544,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 +557,7 @@ module Google
           # @param filter [SimpleFilter, ChainFilter, InterleaveFilter, ConditionFilter]
           #
           def add filter
-            @grpc.filters << filter.to_grpc
+            @filters << filter
             self
           end
         end