class Google::Cloud::Spanner::Commit

# Commit

Accepts mutations for execution within a transaction. All writes will execute atomically at a single logical point in time across columns, rows, and tables in a database.

All changes are accumulated in memory until the block passed to {Client#commit} completes.

@example

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.commit do |c|
  c.update "users", [{ id: 1, name: "Charlie", active: false }]
  c.insert "users", [{ id: 2, name: "Harvey",  active: true }]
end

Public Class Methods

new() click to toggle source

@private

# File lib/google/cloud/spanner/commit.rb, line 47
def initialize
  @mutations = []
end

Public Instance Methods

delete(table, keys = []) click to toggle source

Deletes rows from a table. Succeeds whether or not the specified rows were present.

All changes are accumulated in memory until the block passed to {Client#commit} completes.

@param [String] table The name of the table in the database to be

modified.

@param [Object, Array<Object>] keys A single, or list of keys or key

ranges to match returned data to. Values should have exactly as many
elements as there are columns in the primary key.

@example

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.commit do |c|
  c.delete "users", [1, 2, 3]
end
# File lib/google/cloud/spanner/commit.rb, line 311
def delete table, keys = []
  @mutations += [
    V1::Mutation.new(
      delete: V1::Mutation::Delete.new(
        table: table, key_set: key_set(keys)
      )
    )
  ]
  keys
end
insert(table, *rows) click to toggle source

Inserts new rows in a table. If any of the rows already exist, the write or request fails with error {Google::Cloud::AlreadyExistsError}.

All changes are accumulated in memory until the block passed to {Client#commit} completes.

@param [String] table The name of the table in the database to be

modified.

@param [Array<Hash>] rows One or more hash objects with the hash keys

matching the table's columns, and the hash values matching the
table's values.

Ruby types are mapped to Spanner types as follows:

| Spanner     | Ruby           | Notes  |
|-------------|----------------|---|
| `BOOL`      | `true`/`false` | |
| `INT64`     | `Integer`      | |
| `FLOAT64`   | `Float`        | |
| `NUMERIC`   | `BigDecimal`   | |
| `STRING`    | `String`       | |
| `DATE`      | `Date`         | |
| `TIMESTAMP` | `Time`, `DateTime` | |
| `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
| `ARRAY`     | `Array` | Nested arrays are not supported. |

See [Data
types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).

@example

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.commit do |c|
  c.insert "users", [{ id: 1, name: "Charlie", active: false },
                     { id: 2, name: "Harvey",  active: true }]
end
# File lib/google/cloud/spanner/commit.rb, line 153
def insert table, *rows
  rows = Array(rows).flatten
  return rows if rows.empty?
  rows.delete_if(&:nil?)
  rows.delete_if(&:empty?)
  @mutations += rows.map do |row|
    V1::Mutation.new(
      insert: V1::Mutation::Write.new(
        table: table, columns: row.keys.map(&:to_s),
        values: [Convert.object_to_grpc_value(row.values).list_value]
      )
    )
  end
  rows
end
mutations() click to toggle source

@private

# File lib/google/cloud/spanner/commit.rb, line 323
def mutations
  @mutations
end
replace(table, *rows) click to toggle source

Inserts or replaces rows in a table. If any of the rows already exist, it is deleted, and the column values provided are inserted instead. Unlike upsert, this means any values not explicitly written become `NULL`.

All changes are accumulated in memory until the block passed to {Client#commit} completes.

@param [String] table The name of the table in the database to be

modified.

@param [Array<Hash>] rows One or more hash objects with the hash keys

matching the table's columns, and the hash values matching the
table's values.

Ruby types are mapped to Spanner types as follows:

| Spanner     | Ruby           | Notes  |
|-------------|----------------|---|
| `BOOL`      | `true`/`false` | |
| `INT64`     | `Integer`      | |
| `FLOAT64`   | `Float`        | |
| `NUMERIC`   | `BigDecimal`   | |
| `STRING`    | `String`       | |
| `DATE`      | `Date`         | |
| `TIMESTAMP` | `Time`, `DateTime` | |
| `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
| `ARRAY`     | `Array` | Nested arrays are not supported. |

See [Data
types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).

@example

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.commit do |c|
  c.replace "users", [{ id: 1, name: "Charlie", active: false },
                     { id: 2, name: "Harvey",  active: true }]
end
# File lib/google/cloud/spanner/commit.rb, line 271
def replace table, *rows
  rows = Array(rows).flatten
  return rows if rows.empty?
  rows.delete_if(&:nil?)
  rows.delete_if(&:empty?)
  @mutations += rows.map do |row|
    V1::Mutation.new(
      replace: V1::Mutation::Write.new(
        table: table, columns: row.keys.map(&:to_s),
        values: [Convert.object_to_grpc_value(row.values).list_value]
      )
    )
  end
  rows
end
save(table, *rows)
Alias for: upsert
update(table, *rows) click to toggle source

Updates existing rows in a table. If any of the rows does not already exist, the request fails with error {Google::Cloud::NotFoundError}.

All changes are accumulated in memory until the block passed to {Client#commit} completes.

@param [String] table The name of the table in the database to be

modified.

@param [Array<Hash>] rows One or more hash objects with the hash keys

matching the table's columns, and the hash values matching the
table's values.

Ruby types are mapped to Spanner types as follows:

| Spanner     | Ruby           | Notes  |
|-------------|----------------|---|
| `BOOL`      | `true`/`false` | |
| `INT64`     | `Integer`      | |
| `FLOAT64`   | `Float`        | |
| `NUMERIC`   | `BigDecimal`   | |
| `STRING`    | `String`       | |
| `DATE`      | `Date`         | |
| `TIMESTAMP` | `Time`, `DateTime` | |
| `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
| `ARRAY`     | `Array` | Nested arrays are not supported. |

See [Data
types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).

@example

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.commit do |c|
  c.update "users", [{ id: 1, name: "Charlie", active: false },
                     { id: 2, name: "Harvey",  active: true }]
end
# File lib/google/cloud/spanner/commit.rb, line 211
def update table, *rows
  rows = Array(rows).flatten
  return rows if rows.empty?
  rows.delete_if(&:nil?)
  rows.delete_if(&:empty?)
  @mutations += rows.map do |row|
    V1::Mutation.new(
      update: V1::Mutation::Write.new(
        table: table, columns: row.keys.map(&:to_s),
        values: [Convert.object_to_grpc_value(row.values).list_value]
      )
    )
  end
  rows
end
upsert(table, *rows) click to toggle source

Inserts or updates rows in a table. If any of the rows already exist, then its column values are overwritten with the ones provided. Any column values not explicitly written are preserved.

All changes are accumulated in memory until the block passed to {Client#commit} completes.

@param [String] table The name of the table in the database to be

modified.

@param [Array<Hash>] rows One or more hash objects with the hash keys

matching the table's columns, and the hash values matching the
table's values.

Ruby types are mapped to Spanner types as follows:

| Spanner     | Ruby           | Notes  |
|-------------|----------------|---|
| `BOOL`      | `true`/`false` | |
| `INT64`     | `Integer`      | |
| `FLOAT64`   | `Float`        | |
| `NUMERIC`   | `BigDecimal`   | |
| `STRING`    | `String`       | |
| `DATE`      | `Date`         | |
| `TIMESTAMP` | `Time`, `DateTime` | |
| `BYTES`     | `File`, `IO`, `StringIO`, or similar | |
| `ARRAY`     | `Array` | Nested arrays are not supported. |

See [Data
types](https://cloud.google.com/spanner/docs/data-definition-language#data_types).

@example

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

db = spanner.client "my-instance", "my-database"

db.commit do |c|
  c.upsert "users", [{ id: 1, name: "Charlie", active: false },
                     { id: 2, name: "Harvey",  active: true }]
end
# File lib/google/cloud/spanner/commit.rb, line 94
def upsert table, *rows
  rows = Array(rows).flatten
  return rows if rows.empty?
  rows.delete_if(&:nil?)
  rows.delete_if(&:empty?)
  @mutations += rows.map do |row|
    V1::Mutation.new(
      insert_or_update: V1::Mutation::Write.new(
        table: table, columns: row.keys.map(&:to_s),
        values: [Convert.object_to_grpc_value(row.values).list_value]
      )
    )
  end
  rows
end
Also aliased as: save

Protected Instance Methods

key_set(keys) click to toggle source
# File lib/google/cloud/spanner/commit.rb, line 329
def key_set keys
  return V1::KeySet.new all: true if keys.nil?
  keys = [keys] unless keys.is_a? Array
  return V1::KeySet.new all: true if keys.empty?
  if keys_are_ranges? keys
    key_ranges = keys.map do |r|
      Convert.to_key_range r
    end
    return V1::KeySet.new ranges: key_ranges
  end
  key_list = keys.map do |key|
    key = [key] unless key.is_a? Array
    Convert.object_to_grpc_value(key).list_value
  end
  V1::KeySet.new keys: key_list
end
keys_are_ranges?(keys) click to toggle source
# File lib/google/cloud/spanner/commit.rb, line 346
def keys_are_ranges? keys
  keys.each do |key|
    return true if key.is_a? ::Range
    return true if key.is_a? Google::Cloud::Spanner::Range
  end
  false
end