google-cloud-bigtable 1.3.0

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

@@ -0,0 +1,194 @@
+# 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
+      ##
+      # # ColumnRange
+      #
+      # Specifies a contiguous range of column qualifiers.
+      #
+      # * Start qualifier bound : The qualifier at which to start the range.
+      #   If neither field is set, interpreted as the empty string, inclusive.
+      # * End qualifier bound: The qualifier at which to end the range.
+      #   If neither field is set, interpreted as the infinite string qualifier, exclusive.
+      #
+      # @example
+      #   require "google/cloud/bigtable"
+      #
+      #   bigtable = Google::Cloud::Bigtable.new
+      #   table = bigtable.table("my-instance", "my-table")
+      #
+      #   # Range that includes all qualifiers including "user-001" up until "user-010"
+      #   table.new_column_range("cf").from("user-001").to("user-010")
+      #
+      #   # Range that includes all qualifiers including "user-001" up to and including "user-005"
+      #   table.new_column_range("cf").from("user-001").to("user-005", inclusive: true)
+      #
+      #   # Range that includes all qualifiers until end of the row key "user-001".
+      #   table.new_column_range("cf").to("user-010") # exclusive
+      #
+      #   # Range with unbounded start and the inclusive end "user-100"
+      #   table.new_column_range("cf").to("user-100", inclusive: true)
+      #
+      #   # Range that includes all qualifiers including "user-001" up to and including "user-100"
+      #   table.new_column_range("cf").between("user-001", "user-100")
+      #
+      class ColumnRange
+        ##
+        # Create qualifier range instance.
+        #
+        # @param family [String] Column family name.
+        #
+        def initialize family
+          @grpc = Google::Bigtable::V2::ColumnRange.new family_name: family
+        end
+
+        ##
+        # Gets the column family name.
+        #
+        # @return [String]
+        #
+        def family
+          @grpc.family_name
+        end
+
+        ##
+        # Sets the column family name.
+        #
+        # @param name [String] Column family name
+        #
+        def family= name
+          @grpc.family_name = name
+        end
+
+        ##
+        # Sets the column range with the lower bound.
+        #
+        # @param qualifier [String] Column qualifier name. Required
+        # @param inclusive [String] Lower bound flag. Inclusive/Exclusive.
+        #   Default is an inclusive lower bound.
+        # @return [Google::Cloud::Bigtable::ColumnRange]
+        #
+        # @example Inclusive lower bound.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   table.new_column_range("cf").from("qualifier-1")
+        #
+        # @example Exclusive lower bound.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   table.new_column_range("cf").from("qualifier-1", inclusive: false)
+        #
+        def from qualifier, inclusive: true
+          if inclusive
+            @grpc.start_qualifier_closed = qualifier
+          else
+            @grpc.start_qualifier_open = qualifier
+          end
+          self
+        end
+
+        ##
+        # Sets the column range with the upper bound.
+        #
+        # @param qualifier [String] Column qualifier name. Required.
+        # @param inclusive [String] Upper bound flag. Inclusive/Exclusive.
+        #   Default is an inclusive upper bound.
+        # @return [Google::Cloud::Bigtable::ColumnRange]
+        #
+        # @example Inclusive upper bound.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   table.new_column_range("cf").to("qualifier-10", inclusive: true)
+        #
+        # @example Exclusive upper bound.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   table.new_column_range("cf").to("qualifier-10")
+        #
+        def to qualifier, inclusive: false
+          if inclusive
+            @grpc.end_qualifier_closed = qualifier
+          else
+            @grpc.end_qualifier_open = qualifier
+          end
+          self
+        end
+
+        ##
+        # Sets the column range with the inclusive upper and lower bound.
+        #
+        # @param from_qualifier [String] Inclusive from qualifier. Required.
+        # @param to_qualifier [String] Inclusive to qualifier. Required.
+        # @return [Google::Cloud::Bigtable::ColumnRange]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   table.new_column_range("cf").between("qualifier-1", "qualifier-10")
+        #
+        def between from_qualifier, to_qualifier
+          from(from_qualifier).to(to_qualifier, inclusive: true)
+        end
+
+        ##
+        # Sets the column range with the inclusive upper and the exclusive lower bound.
+        #
+        # @param from_qualifier [String] Inclusive from qualifier
+        # @param to_qualifier [String] Exclusive to qualifier
+        # @return [Google::Cloud::Bigtable::ColumnRange]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   table.new_column_range("cf").of("qualifier-1", "qualifier-10")
+        #
+        def of from_qualifier, to_qualifier
+          from(from_qualifier).to(to_qualifier)
+        end
+
+        # @private
+        #
+        # @return [Google::Bigtable::V2::ColumnRange]
+        #
+        def to_grpc
+          @grpc
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,83 @@
+# 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.
+
+
+require "time"
+require "date"
+
+module Google
+  module Cloud
+    module Bigtable
+      # @private
+      # Helper module for converting Bigtable values.
+      module Convert
+        module_function
+
+        ##
+        # Convert number to protobuf duration.
+        #
+        # @param number [Float] Seconds with nano seconds
+        # @return [Google::Protobuf::Duration, nil]
+        #
+        def number_to_duration number
+          return unless number
+
+          Google::Protobuf::Duration.new(
+            seconds: number.to_i,
+            nanos:   (number.remainder(1) * 1_000_000_000).round
+          )
+        end
+
+        ##
+        # Convert protobuf durations to float.
+        #
+        # @param duration [Google::Protobuf::Duration, nil]
+        # @return [Float, Integer, nil] Seconds with nano seconds
+        #
+        def duration_to_number duration
+          return unless duration
+          return duration.seconds if duration.nanos.zero?
+
+          duration.seconds + (duration.nanos / 1_000_000_000.0)
+        end
+
+        ##
+        # Convert protobuf timestamp to Time object.
+        #
+        # @param timestamp [Google::Protobuf::Timestamp]
+        # @return [Time, nil]
+        #
+        def timestamp_to_time timestamp
+          return unless timestamp
+
+          Time.at timestamp.seconds, timestamp.nanos / 1000.0
+        end
+
+        ##
+        # Convert time to timestamp protobuf object.
+        #
+        # @param time [Time]
+        # @return [Google::Protobuf::Timestamp, nil]
+        #
+        def time_to_timestamp time
+          return unless time
+
+          Google::Protobuf::Timestamp.new seconds: time.to_i, nanos: time.nsec
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# 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.
+
+
+require "google/cloud/bigtable/v2/credentials"
+
+module Google
+  module Cloud
+    module Bigtable
+      class Credentials < Google::Cloud::Bigtable::V2::Credentials
+      end
+    end
+  end
+end

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

@@ -0,0 +1,38 @@
+# 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
+      ##
+      # Invalid read row state error
+      class InvalidRowStateError < Google::Cloud::Error
+        ##
+        # Invalid row chunk data
+        attr_reader :data
+
+        def initialize message, data = nil
+          super message
+          @data = data if data
+        end
+      end
+
+      ##
+      # Row filter error.
+      class RowFilterError < Google::Cloud::Error
+      end
+    end
+  end
+end

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

@@ -0,0 +1,334 @@
+# 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
+      ##
+      # # GcRule
+      #
+      # A rule or rules for determining which cells to delete during garbage
+      # collection.
+      #
+      # Garbage collection (GC) executes opportunistically in the background,
+      # so it is possible for reads to return a cell even if it matches the
+      # active GC expression for its column family.
+      #
+      # GC Rule types:
+      #   * `max_num_versions` - A garbage-collection rule that explicitly
+      #     states the maximum number of cells to keep for all columns in a
+      #     column family.
+      #   * `max_age` - A garbage-collection rule based on the timestamp for
+      #     each cell. With this type of garbage-collection rule, you set the
+      #     time to live (TTL) for data. Cloud Bigtable looks at each column
+      #     family during garbage collection and removes any cells that have
+      #     expired.
+      #   * `union` - A union garbage-collection policy will remove all data
+      #     matching *any* of a set of given rules.
+      #   * `intersection` - An intersection garbage-collection policy will
+      #     remove all data matching *all* of a set of given rules.
+      #
+      # @example Create a table with column families.
+      #   require "google/cloud/bigtable"
+      #
+      #   bigtable = Google::Cloud::Bigtable.new
+      #
+      #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+      #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5))
+      #     cfm.add("cf2", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600))
+      #
+      #     gc_rule = Google::Cloud::Bigtable::GcRule.union(
+      #       Google::Cloud::Bigtable::GcRule.max_age(1800),
+      #       Google::Cloud::Bigtable::GcRule.max_versions(3)
+      #     )
+      #     cfm.add("cf3", gc_rule: gc_rule)
+      #   end
+      #
+      #   puts table.column_families["cf1"].gc_rule.max_versions
+      #   puts table.column_families["cf2"].gc_rule.max_age
+      #   puts table.column_families["cf3"].gc_rule.union
+      #
+      class GcRule
+        # @private
+        # Creates a new GC Rule instance.
+        #
+        # @param grpc [Google::Bigtable::Admin::V2::GcRule | nil]
+        #
+        def initialize grpc = nil
+          @grpc = grpc || Google::Bigtable::Admin::V2::GcRule.new
+        end
+
+        ##
+        # Sets a garbage-collection rule that explicitly states the maximum
+        # number of cells to keep for all columns in a column family.
+        #
+        # @param versions [Integer]
+        #
+        def max_versions= versions
+          @grpc.max_num_versions = versions
+        end
+
+        ##
+        # Gets the garbage-collection rule that explicitly states the maximum
+        # number of cells to keep for all columns in a column family.
+        #
+        # @return [Integer, nil]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5))
+        #   end
+        #
+        #   puts table.column_families["cf1"].gc_rule.max_versions
+        #
+        def max_versions
+          @grpc.max_num_versions
+        end
+
+        ##
+        # Sets a garbage-collection rule based on the timestamp for each cell.
+        # With this type of garbage-collection rule, you set the time to live
+        # (TTL) for data. Cloud Bigtable looks at each column family during
+        # garbage collection and removes any cells that have expired.
+        #
+        # @param age [Numeric] Max age in seconds. Values must be at least one
+        #   millisecond, and will be truncated to microsecond granularity.
+        #
+        def max_age= age
+          @grpc.max_age = Convert.number_to_duration age
+        end
+
+        ##
+        # Gets the garbage-collection rule based on the timestamp for each cell.
+        # With this type of garbage-collection rule, you set the time to live
+        # (TTL) for data. Cloud Bigtable looks at each column family during
+        # garbage collection and removes any cells that have expired.
+        #
+        # @return [Numeric, nil] Max age in seconds.
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600))
+        #   end
+        #
+        #   puts table.column_families["cf1"].gc_rule.max_age
+        #
+        def max_age
+          Convert.duration_to_number @grpc.max_age
+        end
+
+        ##
+        # Sets the intersection rules collection for this GcRule.
+        #
+        # @param rules [Array<Google::Cloud::Bigtable::GcRule>]
+        #   List of GcRule with nested rules.
+        #
+        def intersection= rules
+          @grpc.intersection = Google::Bigtable::Admin::V2::GcRule::Intersection.new rules: rules.map(&:to_grpc)
+        end
+
+        ##
+        #
+        # Gets the intersection rules collection for this GcRule.
+        #
+        # @return [Array<Google::Cloud::Bigtable::GcRule>, nil]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     gc_rule = Google::Cloud::Bigtable::GcRule.intersection(
+        #       Google::Cloud::Bigtable::GcRule.max_age(1800),
+        #       Google::Cloud::Bigtable::GcRule.max_versions(3)
+        #     )
+        #     cfm.add("cf1", gc_rule: gc_rule)
+        #   end
+        #
+        #   puts table.column_families["cf1"].gc_rule.intersection
+        #
+        def intersection
+          return nil unless @grpc.intersection
+          @grpc.intersection.rules.map do |gc_rule_grpc|
+            self.class.from_grpc gc_rule_grpc
+          end
+        end
+
+        ##
+        # Sets the union rules collection for this GcRule. A union
+        # garbage-collection policy will remove all data matching *any* of its
+        # set of given rules.
+        #
+        # @param rules [Array<Google::Cloud::Bigtable::GcRule>]
+        #   List of GcRule with nested rules.
+        #
+        def union= rules
+          @grpc.union = Google::Bigtable::Admin::V2::GcRule::Union.new rules: rules.map(&:to_grpc)
+        end
+
+        ##
+        # Gets the union rules collection for this GcRule. A union
+        # garbage-collection policy will remove all data matching *any* of its
+        # set of given rules.
+        #
+        # @return [Array<Google::Cloud::Bigtable::GcRule>, nil]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     gc_rule = Google::Cloud::Bigtable::GcRule.union(
+        #       Google::Cloud::Bigtable::GcRule.max_age(1800),
+        #       Google::Cloud::Bigtable::GcRule.max_versions(3)
+        #     )
+        #     cfm.add("cf1", gc_rule: gc_rule)
+        #   end
+        #
+        #   puts table.column_families["cf1"].gc_rule.union
+        #
+        def union
+          return nil unless @grpc.union
+          @grpc.union.rules.map do |gc_rule_grpc|
+            self.class.from_grpc gc_rule_grpc
+          end
+        end
+
+        ##
+        # Creates a GcRule instance with max number of versions.
+        #
+        # @param versions [Integer] Max number of versions
+        # @return [Google::Cloud::Bigtable::GcRule]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_versions(5))
+        #   end
+        #
+        def self.max_versions versions
+          new.tap do |gc_rule|
+            gc_rule.max_versions = versions
+          end
+        end
+
+        ##
+        # Creates a GcRule instance with max age.
+        #
+        # @param age [Integer] Max age in seconds.
+        # @return [Google::Cloud::Bigtable::GcRule]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     cfm.add("cf1", gc_rule: Google::Cloud::Bigtable::GcRule.max_age(600))
+        #   end
+        #
+        def self.max_age age
+          new.tap do |gc_rule|
+            gc_rule.max_age = age
+          end
+        end
+
+        ##
+        # Creates a union GcRule instance.
+        #
+        # @param rules [Google::Cloud::Bigtable::GcRule, Array<Google::Cloud::Bigtable::GcRule>]
+        #   List of GcRule with nested rules.
+        # @return [Google::Cloud::Bigtable::GcRule]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     gc_rule = Google::Cloud::Bigtable::GcRule.union(
+        #       Google::Cloud::Bigtable::GcRule.max_age(1800),
+        #       Google::Cloud::Bigtable::GcRule.max_versions(3)
+        #     )
+        #     cfm.add("cf1", gc_rule: gc_rule)
+        #   end
+        #
+        def self.union *rules
+          new.tap do |gc_rule|
+            gc_rule.union = rules
+          end
+        end
+
+        ##
+        # Creates a intersection GCRule instance.
+        #
+        # @param rules [Google::Cloud::Bigtable::GcRule, Array<Google::Cloud::Bigtable::GcRule>]
+        #   List of GcRule with nested rules.
+        # @return [Google::Cloud::Bigtable::GcRule]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.create_table("my-instance", "my-table") do |cfm|
+        #     gc_rule = Google::Cloud::Bigtable::GcRule.intersection(
+        #       Google::Cloud::Bigtable::GcRule.max_age(1800),
+        #       Google::Cloud::Bigtable::GcRule.max_versions(3)
+        #     )
+        #     cfm.add("cf1", gc_rule: gc_rule)
+        #   end
+        #
+        def self.intersection *rules
+          new.tap do |gc_rule|
+            gc_rule.intersection = rules
+          end
+        end
+
+        # @private
+        # Get gRPC instance of GC Rule
+        # @return [Google::Bigtable::Admin::V2::GcRule]
+        def to_grpc
+          @grpc
+        end
+
+        # @private
+        #
+        # Creates a new GcRule instance from a
+        # Google::Bigtable::Admin::V2::GcRule.
+        # @param grpc [Google::Bigtable::Admin::V2::GcRule]
+        # @return [Google::Cloud::Bigtable::GcRule]
+        def self.from_grpc grpc
+          new grpc
+        end
+      end
+    end
+  end
+end