Cloud Bigtable API - Module Google::Cloud::Bigtable::MutationOperations (v2.11.0)

Reference documentation and code samples for the Cloud Bigtable API module Google::Cloud::Bigtable::MutationOperations.

MutationOperations

Collection of mutations APIs.

Mutate single row
Mutate multiple rows
Read modify and write row atomically on the server
Check and mutate row

Methods

#check_and_mutate_row

def check_and_mutate_row(key, predicate, on_match: nil, otherwise: nil) -> Boolean

Mutates a row atomically based on the output of a predicate reader filter.

NOTE: Condition predicate filter is not supported.

Parameters

key (String) — Row key. The row key of the row to which the conditional mutation should be applied.
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.
on_match (Google::Cloud::Bigtable::MutationEntry) (defaults to: nil) — Mutation entry applied to 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 100,000 entries.
otherwise (Google::Cloud::Bigtable::MutationEntry) (defaults to: nil) — Mutation entry applied when predicate filter does 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 100,000 entries.

Returns

(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(
  "cf1",
  "field1",
  "XYZ",
  timestamp: (Time.now.to_f * 1_000_000).round(-3) # microseconds
).delete_cells "cf2", "field02"

otherwise_mutations = Google::Cloud::Bigtable::MutationEntry.new
otherwise_mutations.delete_from_family "cf3"

predicate_matched = table.check_and_mutate_row(
  "user01",
  predicate_filter,
  on_match: on_match_mutations,
  otherwise: otherwise_mutations
)

if predicate_matched
  puts "All predicates matched"
end

#mutate_row

def mutate_row(entry) -> Boolean

Mutates a row atomically. Cells in the row are left unchanged unless explicitly changed by the mutations. Changes to be atomically applied to the specified row. Entries are applied in order, meaning that earlier mutations can be masked by later mutations. Must contain at least one mutation and at most 100,000.

Parameter

entry (Google::Cloud::Bigtable::MutationEntry) — Mutation entry with row key and list of mutations.

Returns

(Boolean)

Examples

Single mutation on row.

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", "field1", "XYZ"
table.mutate_row entry

Multiple mutations on row.

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",
  "field1",
  "XYZ",
  timestamp: (Time.now.to_f * 1_000_000).round(-3) # microseconds
).delete_cells "cf2", "field02"

table.mutate_row entry

#mutate_rows

def mutate_rows(entries) -> Array<Google::Cloud::Bigtable::V2::MutateRowsResponse::Entry>

Mutates multiple rows in a batch. Each individual row is mutated atomically as in ##mutate_row, but the entire batch is not executed atomically.

Parameter

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 a maximum of 100,000 mutations.

Returns

(Array<Google::Cloud::Bigtable::V2::MutateRowsResponse::Entry>)

Example

require "google/cloud/bigtable"

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")
responses = table.mutate_rows entries

responses.each do |response|
  puts response.status.description
end

#new_mutation_entry

def new_mutation_entry(row_key = nil) -> Google::Cloud::Bigtable::MutationEntry

Creates a mutation entry instance.

Parameter

row_key (String) — Row key. Optional. The row key of the row to which the mutation should be applied.

Returns

(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

#new_read_modify_write_rule

def new_read_modify_write_rule(family, qualifier) -> Google::Cloud::Bigtable::ReadModifyWriteRule

Create a read/modify/write rule to append or increment the value of the cell qualifier.

Parameters

family (String) — The name of the column family to which the read/modify/write rule should be applied.
qualifier (String) — The qualifier of the column to which the read/modify/write rule should be applied.

Returns

(Google::Cloud::Bigtable::ReadModifyWriteRule)

Examples

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"

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

#read_modify_write_row

def read_modify_write_row(key, rules) -> Google::Cloud::Bigtable::Row

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.

Parameters

key (String) — The row key of the row to which the read/modify/write rules should be applied.
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.

Returns

(Google::Cloud::Bigtable::Row)

Examples

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

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