google-cloud-bigtable 0.1.0

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

@@ -0,0 +1,105 @@
+# 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
+      # # LongrunningJob
+      #
+      # A resource representing the long-running, asynchronous processing operation.
+      # The job can be refreshed to retrieve the result object once the operation has been completed.
+      #
+      # @see https://cloud.google.com/bigtable/docs/reference/admin/rpc/google.longrunning#google.longrunning.Operation
+      #   Long-running Operation
+      #
+      class LongrunningJob
+        # @private
+        # The Google::Gax::Operation gRPC object.
+        attr_accessor :grpc
+
+        # @private
+        # The gRPC Service object.
+        attr_accessor :service
+
+        # Get result object of the operation.
+        #
+        # @return [Object, nil]
+        #   `nil` if the operation is not complete.
+        #
+        def results
+          return nil unless done?
+          return nil unless @grpc.grpc_op.result == :response
+          @grpc.results
+        end
+
+        # Checks if the processing of the instance operation is complete.
+        #
+        # @return [boolean] `true` when complete, `false` otherwise.
+        #
+        def done?
+          @grpc.done?
+        end
+
+        # Checks if the processing of the instance operation has errored.
+        #
+        # @return [boolean] `true` when errored, `false` otherwise.
+        #
+        def error?
+          @grpc.error?
+        end
+
+        ##
+        # The status if the operation associated with this job produced an
+        # error.
+        #
+        # @return [Object, Google::Rpc::Status, nil] A status object with
+        #   the status code and message, or `nil` if no error occurred.
+        #
+        def error
+          return nil unless error?
+          @grpc.error
+        end
+
+        # Reloads the job with current data from the long-running,
+        # asynchronous processing of an operation.
+        #
+        # @return [Google::Cloud::Bigtable::Instance::Job] The same job instance.
+        #
+        def reload!
+          @grpc.reload!
+          self
+        end
+
+        # Reloads the job until the operation is complete. The delay between
+        # reloads will incrementally increase.
+        #
+        def wait_until_done!
+          @grpc.wait_until_done!
+        end
+
+        # @private
+        # New BasicJob from a Google::Gax::Operation object.
+        def self.from_grpc grpc, service
+          new.tap do |job|
+            job.grpc =  grpc
+            job.service = service
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,244 @@
+# 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
+      # # MutationEntry
+      #
+      # MutationEntry is a chainable structure, which holds data for diffrent
+      # type of mutations.
+      # MutationEntry is used in following data operations
+      #
+      #   * Mutate row. See {Google::Cloud::Bigtable::Table#mutate_row}
+      #   * Mutate rows. See {Google::Cloud::Bigtable::Table#mutate_rows}
+      #   * Check and mutate row using a predicate.
+      #     see {Google::Cloud::Bigtable::Table#check_and_mutate_row}
+      #
+      # @example
+      #   entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
+      #   entry.set_cell(
+      #     "cf1", "fiel01", "XYZ", timestamp: Time.now.to_i * 1000
+      #   ).delete_cells(
+      #     "cf2",
+      #     "field02",
+      #     timestamp_from: (Time.now.to_i - 1800) * 1000,
+      #     timestamp_to: (Time.now.to_i * 1000)
+      #   ).delete_from_family("cf3").delete_from_row
+      #
+      # @example Using table
+      #   require "google/cloud/bigtable"
+      #
+      #   bigtable = Google::Cloud::Bigtable.new
+      #   table = bigtable.table("my-instance", "my-table")
+      #
+      #   entry = table.new_mutation_entry("user-1")
+      #   entry.set_cell(
+      #     "cf1", "fiel01", "XYZ", timestamp: Time.now.to_i * 1000
+      #   )
+      #
+      class MutationEntry
+        attr_accessor :row_key
+
+        # mutations gRPC list
+        # @return [Array<Google::Bigtable::V2::Mutation>]
+        attr_accessor :mutations
+
+        # Creates a mutation entry instance.
+        #
+        # @param row_key [String]
+        def initialize row_key = nil
+          @row_key = row_key
+          @mutations = []
+          @retryable = true
+        end
+
+        # Add SetCell mutation to list of mutations.
+        #
+        # A Mutation which sets the value of the specified cell.
+        #
+        # @param family [String] Table column family name.
+        #   The name of the family into which new data should be written.
+        #   Must match `[-_.a-zA-Z0-9]+`
+        # @param qualifier [String] Column qualifier name.
+        #   The qualifier of the column into which new data should be written.
+        #   Can be any byte string, including the empty string.
+        # @param value [String, Integer] Cell value data.
+        #   The value to be written into the specified cell.
+        # @param timestamp [Time, Integer] Timestamp value.
+        #   The timestamp of the cell into which new data should be written.
+        #   Use -1 for current Bigtable server time.
+        #   Otherwise, the client should set this value itself, noting that the
+        #   default value is a timestamp of zero if the field is left unspecified.
+        #   Values must match the granularity of the table (e.g. micros, millis).
+        # @return [MutationEntry]  `self` object of entry for chaining.
+        #
+        # @example
+        #   entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
+        #   entry.set_cell("cf1", "field01", "XYZ")
+        #
+        # @example With timestamp
+        #   entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
+        #   entry.set_cell(
+        #     "cf-1",
+        #     "field-1",
+        #     "XYZ"
+        #     timestamp: Time.now.to_i * 1000 # Time stamp in millis seconds.
+        #   )
+        #
+        def set_cell family, qualifier, value, timestamp: nil
+          # If value is integer then covert it to sign 64 bit int big-endian.
+          value = [value].pack("q>") if value.is_a?(Integer)
+          options = {
+            family_name: family,
+            column_qualifier: qualifier,
+            value: value
+          }
+
+          if timestamp
+            options[:timestamp_micros] = timestamp
+            @retryable = timestamp != -1
+          end
+          @mutations << Google::Bigtable::V2::Mutation.new(set_cell: options)
+          self
+        end
+
+        # Add DeleteFromColumn entry to list of mutations.
+        #
+        # A Mutation which deletes cells from the specified column, optionally
+        # restricting the deletions to a given timestamp range.
+        #
+        # @param family [String] Table column family name.
+        #   The name of the family from which cells should be deleted.
+        #   Must match `[-_.a-zA-Z0-9]+`
+        # @param qualifier [String] Column qualifier name.
+        #   The qualifier of the column from which cells should be deleted.
+        #   Can be any byte string, including the empty string.
+        # @param timestamp_from [Integer] Timestamp lower bound. Optional.
+        #   The range of timestamps within which cells should be deleted.
+        # @param timestamp_to [Integer] Timestamp upper bound. Optional.
+        #   The range of timestamps within which cells should be deleted.
+        # @return [MutationEntry] `self` object of entry for chaining.
+        #
+        # @example Without timestamp range
+        #   entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
+        #   entry.delete_cells("cf-1", "field-1")
+        #
+        # @example With timestamp range
+        #   entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
+        #   entry.delete_cells(
+        #     "cf1",
+        #     "field-1",
+        #     timestamp_from: (Time.now.to_i - 1800) * 1000,
+        #     timestamp_to: (Time.now.to_i * 1000)
+        #   )
+        # @example With lower bound timestamp range
+        #   entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
+        #   entry.delete_cells(
+        #     "cf1",
+        #     "field-1",
+        #     timestamp_from: (Time.now.to_i - 1800) * 1000
+        #   )
+        #
+        def delete_cells \
+            family,
+            qualifier,
+            timestamp_from: nil,
+            timestamp_to: nil
+          grpc = Google::Bigtable::V2::Mutation::DeleteFromColumn.new(
+            family_name: family,
+            column_qualifier: qualifier
+          )
+          if timestamp_from || timestamp_to
+            time_range = Google::Bigtable::V2::TimestampRange.new
+            time_range.start_timestamp_micros = timestamp_from if timestamp_from
+            time_range.end_timestamp_micros = timestamp_to if timestamp_to
+            grpc.time_range = time_range
+          end
+          @mutations << Google::Bigtable::V2::Mutation.new(
+            delete_from_column: grpc
+          )
+          self
+        end
+
+        # Add DeleteFromFamily to list of mutations.
+        #
+        # A Mutation which deletes all cells from the specified column family.
+        #
+        # @param family [String] Table column family name.
+        #   The name of the family from which cells should be deleted.
+        #   Must match `[-_.a-zA-Z0-9]+`
+        # @return [MutationEntry] `self` object of entry for chaining.
+        #
+        # @example
+        #   entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
+        #   entry.delete_from_family("cf-1")
+        #
+        def delete_from_family family
+          @mutations << Google::Bigtable::V2::Mutation.new(
+            delete_from_family: { family_name: family }
+          )
+          self
+        end
+
+        # Add DeleteFromRow entry to list of mutations
+        #
+        # A Mutation which deletes all cells from the containing row.
+        #
+        # @return [MutationEntry] `self` object of entry for chaining.
+        #
+        # @example
+        #   entry = Google::Cloud::Bigtable::MutationEntry.new("user-1")
+        #   entry.delete_from_row
+        #
+        def delete_from_row
+          @mutations << Google::Bigtable::V2::Mutation.new(delete_from_row: {})
+          self
+        end
+
+        # Mutation entry is retryable or not based on set_cell value.
+        #
+        # @return [Boolean]
+        #
+        def retryable?
+          @retryable
+        end
+
+        # No of mutations
+        #
+        # @return [Integer]
+
+        def length
+          @mutations.length
+        end
+
+        # @private
+        #
+        # Convert mutation entry to gRPC protobuf object.
+        #
+        # @return [Google::Bigtable::V2::MutateRowsRequest::Entry]
+        #
+        def to_grpc
+          Google::Bigtable::V2::MutateRowsRequest::Entry.new(
+            row_key: @row_key,
+            mutations: @mutations
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,338 @@
+# 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 "google/cloud/bigtable/mutation_entry"
+require "google/cloud/bigtable/row"
+require "google/cloud/bigtable/rows_mutator"
+require "google/cloud/bigtable/read_modify_write_rule"
+
+module Google
+  module Cloud
+    module Bigtable
+      # # MutationOperations
+      #
+      # Collection of mutations apis.
+      #
+      #   * Mutate single row
+      #   * Mutate multiple rows
+      #   * Read modify and write row atomically on the server
+      #   * Check and mutate row
+      #
+      module MutationOperations
+        # Mutate row.
+        #
+        # Mutates a row atomically. Cells already present in the row are left
+        # unchanged unless explicitly changed by +mutation+.
+        # Changes to be atomically applied to the specified row. Entries are applied
+        # in order, meaning that earlier mutations can be masked by later ones.
+        # Must contain at least one mutation entry and at most 100000.
+        #
+        # @param entry [Google::Cloud::Bigtable::MutationEntry]
+        #   Mutation entry with row key and list of mutations.
+        # @return [Boolean]
+        # @example Single mutation on row.
+        #   require "google/cloud"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   entry = table.new_mutation_entry.new("user-1")
+        #   entry.set_cell("cf1", "field1", "XYZ")
+        #   table.mutate_row(entry)
+        #
+        # @example Multiple mutations on row.
+        #   require "google/cloud"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   entry = table.new_mutation_entry("user-1")
+        #   entry.set_cell(
+        #     "cf-1",
+        #     "field-1",
+        #     "XYZ"
+        #     timestamp: Time.now.to_i * 1000 # Time stamp in milli seconds.
+        #   ).delete_from_column("cf2", "field02")
+        #
+        #   table.mutate_row(entry)
+        #
+        def mutate_row entry
+          client.mutate_row(
+            path,
+            entry.row_key,
+            entry.mutations,
+            app_profile_id: @app_profile_id
+          )
+          true
+        end
+
+        # Mutates multiple rows in a batch. Each individual row is mutated
+        # atomically as in MutateRow, but the entire batch is not executed
+        # atomically.
+        #
+        # @param entries [Array<Google::Cloud::Bigtable::MutationEntry>]
+        #   The row keys and corresponding mutations to be applied in bulk.
+        #   Each entry is applied as an atomic mutation, but the entries may be
+        #   applied in arbitrary order (even between entries for the same row).
+        #   At least one entry must be specified, and in total the entries can
+        #   contain at most 100000 mutations.
+        # @return [Array<Google::Bigtable::V2::MutateRowsResponse::Entry>]
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   entries = []
+        #   entries << table.new_mutation_entry("row-1").set_cell("cf1", "field1", "XYZ")
+        #   entries << table.new_mutation_entry("row-2").set_cell("cf1", "field1", "ABC")
+        #   table.mutate_row(entries)
+        #
+        def mutate_rows entries
+          RowsMutator.new(self, entries).apply_mutations
+        end
+
+        # Modifies a row atomically on the server. The method reads the latest
+        # existing timestamp and value from the specified columns and writes a new
+        # entry based on pre-defined read/modify/write rules. The new value for the
+        # timestamp is the greater of the existing timestamp or the current server
+        # time. The method returns the new contents of all modified cells.
+        #
+        # @param key [String]
+        #   The key of the row to which the read/modify/write rules should be applied.
+        # @param rules [Google::Cloud::Bigtable::ReadModifyWriteRule, Array<Google::Cloud::Bigtable::ReadModifyWriteRule>]
+        #   Rules specifying how the specified row's contents are to be transformed
+        #   into writes. Entries are applied in order, meaning that earlier rules will
+        #   affect the results of later ones.
+        # @return [Google::Cloud::Bigtable::Row]
+        # @example Apply multiple modification rules.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   rule_1 = table.new_read_modify_write_rule("cf", "field01")
+        #   rule_1.append("append-xyz")
+        #
+        #   rule_2 = table.new_read_modify_write_rule("cf", "field01")
+        #   rule_2.increment(1)
+        #
+        #   row = table.read_modify_write_row("user01", [rule_1, rule_2])
+        #
+        #   puts row.cells
+        #
+        # @example Apply single modification rules.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   rule = table.new_read_modify_write_rule("cf", "field01").append("append-xyz")
+        #
+        #   row = table.read_modify_write_row("user01", rule)
+        #
+        #   puts row.cells
+        #
+        def read_modify_write_row key, rules
+          res_row = client.read_modify_write_row(
+            path,
+            key,
+            Array(rules).map(&:to_grpc),
+            app_profile_id: @app_profile_id
+          ).row
+          row = Row.new(res_row.key)
+
+          res_row.families.each do |family|
+            family.columns.each do |column|
+              column.cells.each do |cell|
+                row_cell = Row::Cell.new(
+                  family.name,
+                  column.qualifier,
+                  cell.timestamp_micros,
+                  cell.value,
+                  cell.labels
+                )
+                row.cells[family.name] << row_cell
+              end
+            end
+          end
+          row
+        end
+
+        # Mutates a row atomically based on the output of a predicate Reader filter.
+        #
+        # NOTE: Condition predicate filter is not supported.
+        #
+        # @param key [String] Row key.
+        #   The key of the row to which the conditional mutation should be applied.
+        # @param predicate [SimpleFilter, ChainFilter, InterleaveFilter] Predicate filter.
+        #   The filter to be applied to the contents of the specified row. Depending
+        #   on whether or not any results are yielded, either +true_mutations+ or
+        #   +false_mutations+ will be executed. If unset, checks that the row contains
+        #   any values at all.
+        # @param on_match [Google::Cloud::Bigtable::MutationEntry] Mutation entry apply on predicate filter match.
+        #   Changes to be atomically applied to the specified row if +predicate_filter+
+        #   yields at least one cell when applied to +row_key+. Entries are applied in
+        #   order, meaning that earlier mutations can be masked by later ones.
+        #   Must contain at least one entry if +false_mutations+ is empty, and at most
+        #   100000.
+        # @param otherwise [Google::Cloud::Bigtable::MutationEntry] Mutation entry apply on predicate filter do not match.
+        #   Changes to be atomically applied to the specified row if +predicate_filter+
+        #   does not yield any cells when applied to +row_key+. Entries are applied in
+        #   order, meaning that earlier mutations can be masked by later ones.
+        #   Must contain at least one entry if +true_mutations+ is empty, and at most
+        #   100000.
+        # @return [Boolean]
+        #   Predicate match or not status
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   predicate_filter = Google::Cloud::Bigtable::RowFilter.key("user-10")
+        #   on_match_mutations = Google::Cloud::Bigtable::MutationEntry.new
+        #   on_match_mutations.set_cell(
+        #     "cf-1",
+        #     "field-1",
+        #     "XYZ",
+        #     timestamp: Time.now.to_i * 1000 # Time stamp in micro seconds.
+        #   ).delete_from_column("cf2", "field02")
+        #
+        #   otherwise_mutations = Google::Cloud::Bigtable::MutationEntry.new
+        #   otherwise_mutations.delete_from_family("cf3")
+        #
+        #   response = table.check_and_mutate_row(
+        #     "user01",
+        #     predicate_filter,
+        #     on_match: on_match_mutations,
+        #     otherwise: otherwise_mutations
+        #   )
+        #
+        #   if response
+        #     puts "All predicates matched"
+        #   end
+        #
+        def check_and_mutate_row \
+            key,
+            predicate,
+            on_match: nil,
+            otherwise: nil
+          true_mutations = on_match.mutations if on_match
+          false_mutations = otherwise.mutations if otherwise
+          response = client.check_and_mutate_row(
+            path,
+            key,
+            predicate_filter: predicate.to_grpc,
+            true_mutations: true_mutations,
+            false_mutations: false_mutations,
+            app_profile_id: @app_profile_id
+          )
+          response.predicate_matched
+        end
+
+        # Read sample row keys.
+        #
+        # Returns a sample of row keys in the table. The returned row keys will
+        # delimit contiguous sections of the table of approximately equal size,
+        # which can be used to break up the data for distributed tasks like
+        # mapreduces.
+        #
+        # @yieldreturn [Google::Cloud::Bigtable::SampleRowKey]
+        # @return [:yields: sample_row_key]
+        #   Yield block for each processed SampleRowKey.
+        #
+        # @example
+        #   require "google/cloud"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   table.sample_row_keys.each do |sample_row_key|
+        #     p sample_row_key.key # user00116
+        #     p sample_row_key.offset # 805306368
+        #   end
+        #
+        def sample_row_keys
+          return enum_for(:sample_row_keys) unless block_given?
+
+          response = client.sample_row_keys(
+            path,
+            app_profile_id: @app_profile_id
+          )
+          response.each do |grpc|
+            yield SampleRowKey.from_grpc(grpc)
+          end
+        end
+
+        # Create instance of mutation_entry
+        #
+        # @param row_key [String] Row key. Optional
+        #   The key of the row to which the mutation should be applied.
+        # @return [Google::Cloud::Bigtable::MutationEntry]
+        #
+        # @example
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #
+        #   entry = table.new_mutation_entry("row-key-1")
+        #
+        #   # Without row key
+        #   entry = table.new_mutation_entry
+        #
+        def new_mutation_entry row_key = nil
+          Google::Cloud::Bigtable::MutationEntry.new(row_key)
+        end
+
+        # Create instance of ReadModifyWriteRule to append or increment value
+        # of the cell qualifier.
+        #
+        # @param family [String]
+        #   The name of the family to which the read/modify/write should be applied.
+        # @param qualifier [String]
+        #   The qualifier of the column to which the read/modify/write should be
+        # @return [Google::Cloud::Bigtable::ReadModifyWriteRule]
+        #
+        # @example Create rule to append to qualifier value.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #   rule = table.new_read_modify_write_rule("cf", "qualifier-1")
+        #   rule.append("append-xyz")
+        #
+        # @example Create rule to increment qualifier value.
+        #   require "google/cloud/bigtable"
+        #
+        #   bigtable = Google::Cloud::Bigtable.new
+        #   table = bigtable.table("my-instance", "my-table")
+        #   rule = table.new_read_modify_write_rule("cf", "qualifier-1")
+        #   rule.increment(100)
+        #
+        def new_read_modify_write_rule family, qualifier
+          Google::Cloud::Bigtable::ReadModifyWriteRule.new(family, qualifier)
+        end
+      end
+    end
+  end
+end