google-cloud-bigtable 1.3.0

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

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Bigtable
+      module RowFilter
+        ##
+        #
+        # # SimpleFilter
+        #
+        class SimpleFilter
+          # @private
+          # Creates a simple filter instance.
+          #
+          def initialize
+            @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]
+          #
+          def sink
+            @grpc.sink = true
+            self
+          end
+
+          ##
+          # Matches all cells, regardless of input. Functionally equivalent to
+          # leaving `filter` unset, but included for completeness.
+          #
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def pass
+            @grpc.pass_all_filter = true
+            self
+          end
+
+          ##
+          # Does not match any cells, regardless of input. Useful for temporarily
+          # disabling just part of a filter.
+          #
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def block
+            @grpc.block_all_filter = true
+            self
+          end
+
+          ##
+          # Replaces each cell's value with an empty string.
+          #
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def strip_value
+            @grpc.strip_value_transformer = true
+            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.
+          # Note that, since row keys can contain arbitrary bytes, the `\C` escape
+          # sequence must be used if a true wildcard is desired. The `.` character
+          # will not match the new line character `\n`, which may be present in a
+          # binary key.
+          #
+          # For Regex syntax:
+          # @see https://github.com/google/re2/wiki/Syntax
+          #
+          # @param regex [String] Regex to match row keys.
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def key regex
+            @grpc.row_key_regex_filter = regex
+            self
+          end
+
+          ##
+          # Matches all cells from a row with probability p, and matches no cells
+          # from the row with probability 1-p.
+          #
+          # @param probability [Float]
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def sample probability
+            if probability >= 1 || probability <= 0
+              raise RowFilterError, "Probability must be greater than 0 and less than 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.
+          # Note that, since column families cannot contain the new line character
+          # `\n`, it is sufficient to use `.` as a full wildcard when matching
+          # column family names.
+          #
+          # @param regex [String] Regex to match family name.
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def family regex
+            @grpc.family_name_regex_filter = regex
+            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`
+          # escape sequence must be used if a true wildcard is desired. The `.`
+          # character will not match the new line character `\n`, which may be
+          # present in a binary qualifier.
+          #
+          # @param regex [String] Regex to match column qualifier name.
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def qualifier regex
+            @grpc.column_qualifier_regex_filter = regex
+            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
+          # will not match the new line character `\n`, which may be present in a
+          # binary value.
+          #
+          # @param regex [String] Regex to match cell value.
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def value regex
+            @grpc.value_regex_filter = regex
+            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.
+          #
+          # Values must be at most 15 characters in length, and match the RE2
+          # 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
+          # one sub-filter that contains an `apply_label_transformer`. It is okay for
+          # an interleave to contain multiple `apply_label_transformers`, as they
+          # will be applied to separate copies of the input.
+          #
+          # @param value [String] Label name
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def label value
+            @grpc.apply_label_transformer = value
+            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.
+          #
+          # @param offset [Integer] Offset value.
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def cells_per_row_offset offset
+            @grpc.cells_per_row_offset_filter = offset
+            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.
+          #
+          # @param limit [String] Max cell match per row limit
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def cells_per_row limit
+            @grpc.cells_per_row_limit_filter = limit
+            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
+          # column `foo:bar2`.
+          # 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
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def cells_per_column limit
+            @grpc.cells_per_column_limit_filter = limit
+            self
+          end
+
+          ##
+          # Creates a timestamp-range filter.
+          #
+          # Matches only cells with timestamps within the given range.
+          # Specifies a contiguous range of timestamps.
+          #
+          # @param from [Integer] Inclusive lower bound. If left empty, interpreted as 0.
+          # @param to [Integer] Exclusive upper bound. If left empty, interpreted as infinity.
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def timestamp_range from, to
+            range_grpc = Google::Bigtable::V2::TimestampRange.new
+            range_grpc.start_timestamp_micros = from if from
+            range_grpc.end_timestamp_micros = to if to
+            @grpc.timestamp_range_filter = range_grpc
+            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.
+          #
+          # @param range [Google::Cloud::Bigtable::ValueRange]
+          # @return [Google::Cloud::Bigtable::RowFilter::SimpleFilter]
+          #
+          def value_range range
+            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
+              raise RowFilterError, "Range type mustbe ColumnRange"
+            end
+            @grpc.column_range_filter = range.to_grpc
+            self
+          end
+
+          # @private
+          #
+          # Converts to a gRPC row filter instance.
+          #
+          # @return [Google::Bigtable::V2::RowFilter]
+          def to_grpc
+            @grpc
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,179 @@
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+module Google
+  module Cloud
+    module Bigtable
+      ##
+      # # RowRange
+      #
+      # Specifies a contiguous range of rows.
+      #
+      # * From key bound : The row key at which to begin the range.
+      #   If neither field is set, interpreted as an empty string, inclusive.
+      # * End key bound: The row key at which to end the range.
+      #   If neither field is set, interpreted as the infinite row key, exclusive.
+      #
+      # @example
+      #   require "google/cloud/bigtable"
+      #
+      #   bigtable = Google::Cloud::Bigtable.new
+      #   table = bigtable.table("my-instance", "my-table")
+      #
+      #   # Range that includes all row keys including "user-001" to "user-005"
+      #   table.new_row_range.from("user-001").to("user-005", inclusive: true)
+      #
+      #   # Range that includes all row keys including "user-001" up to exclusive "user-010".
+      #   table.new_row_range.from("user-001").to("user-010")
+      #
+      #   # Range that includes all row keys including "user-001" up until end of the row keys.
+      #   table.new_row_range.from("user-001")
+      #
+      #   # Range that includes all row keys exclusive "user-001" up until end of the row keys.
+      #   table.new_row_range.from("user-001", inclusive: false)
+      #
+      #   # Range with unbounded from and the exclusive end "user-010"
+      #   table.new_row_range.to("user-010")
+      #
+      #   # Range that includes all row keys including from and end row keys "user-001", "user-010"
+      #   table.new_row_range.between("user-001", "user-010")
+      #
+      #   # Range that includes all row keys including "user-001" up until "user-010"
+      #   table.new_row_range.of("user-001", "user-010")
+      #
+      class RowRange
+        # @private
+        # Creates a row range instance.
+        def initialize
+          @grpc = Google::Bigtable::V2::RowRange.new
+        end
+
+        ##
+        # Sets a row range with a lower bound.
+        #
+        # @param key [String] Row key. Required.
+        # @param inclusive [String] Inclusive/exclusive lower bound.
+        #   Default is an inclusive lower bound.
+        # @return [Google::Cloud::Bigtable::RowRange]
+        #
+        # @example Inclusive lower bound.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   range = table.new_row_range.from("key-001")
+        #
+        # @example Exclusive lower bound.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   range = table.new_row_range.from("key-001", inclusive: false)
+        #
+        def from key, inclusive: true
+          if inclusive
+            @grpc.start_key_closed = key
+          else
+            @grpc.start_key_open = key
+          end
+          self
+        end
+
+        ##
+        # Sets a row range with an upper bound.
+        #
+        # @param key [String] Row key. Required.
+        # @param inclusive [String] Inclusive/Exclusive upper bound.
+        #   Default it is an exclusive upper bound.
+        # @return [Google::Cloud::Bigtable::RowRange]
+        #
+        # @example Inclusive upper bound.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   range = table.new_row_range.to("key-001", inclusive: true)
+        #
+        # @example Exclusive upper bound.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   range = table.new_row_range.to("key-001")
+        #
+        def to key, inclusive: false
+          if inclusive
+            @grpc.end_key_closed = key
+          else
+            @grpc.end_key_open = key
+          end
+          self
+        end
+
+        ##
+        # Sets a row range with inclusive upper and lower bounds.
+        #
+        # @param from_key [String] Inclusive from row key. Required.
+        # @param to_key [String] Inclusive end row key. Required.
+        # @return [Google::Cloud::Bigtable::RowRange]
+        #   Range with inclusive from and end row keys.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   range = table.new_row_range.between("key-001", "key-010")
+        #
+        def between from_key, to_key
+          from(from_key).to(to_key, inclusive: true)
+        end
+
+        ##
+        # Sets a row range with an inclusive lower bound and an exclusive upper bound.
+        #
+        # @param from_key [String] Inclusive from row key.
+        # @param to_key [String] Exclusive end row key.
+        # @return [Google::Cloud::Bigtable::RowRange]
+        #   Range with inclusive from and exclusive end row key.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   range = table.new_row_range.of("key-001", "key-010")
+        #
+        def of from_key, to_key
+          from(from_key).to(to_key)
+        end
+
+        # @private
+        #
+        # @return [Google::Bigtable::V2::RowRange]
+        #
+        def to_grpc
+          @grpc
+        end
+      end
+    end
+  end
+end