Cloud Spanner API - Class Google::Cloud::Spanner::Commit (v2.37.0)

2.37.0 (latest) 2.36.1 2.35.0 2.34.0 2.33.0 2.32.0 2.31.0 2.30.0 2.29.0 2.28.0 2.27.0 2.26.0 2.25.0 2.24.0 2.23.0 2.22.0 2.21.0 2.20.0 2.19.1 2.18.1 2.17.0 2.16.1 2.15.0 2.14.0 2.13.0 2.12.1 2.11.0

Reference documentation and code samples for the Cloud Spanner API 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 Google::Cloud::Spanner::Client#commit completes.

Inherits

• Object

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

Methods

#ack_message

def ack_message(queue, key, ignore_not_found: false) -> Object, Array<Object>

Acknowledges a message in a queue, which removes it from the queue.

All changes are accumulated in memory until the block passed to Google::Cloud::Spanner::Client#commit completes.

Parameters

• queue (String) — The name of the queue.
• key (Object, Array<Object>) — A single key or array of composite key parts to match.
• ignore_not_found (Boolean) (defaults to: false) — If true, the ack succeeds even if the message doesn't exist. Optional. The default is false, which fails the commit with NOT_FOUND when the message doesn't exist.

Returns

• (Object, Array<Object>) — The key of the message.

Examples

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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

db.commit do |c|
  c.ack_message "OrderQueue", 101
end

Ack a message whether or not it exists

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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

db.commit do |c|
  c.ack_message "OrderQueue", 101, ignore_not_found: true
end

#delete

def delete(table, keys = [])

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 Google::Cloud::Spanner::Client#commit completes.

Parameters

• table (String) — The name of the table in the database to be modified.
• keys (Object, Array<Object>) — 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

#insert

def insert(table, *rows)

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

All changes are accumulated in memory until the block passed to Google::Cloud::Spanner::Client#commit completes.

Parameters

• table (String) — The name of the table in the database to be modified.
• rows (Array<Hash>) — 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 | | | FLOAT32 | Float | | | NUMERIC | BigDecimal | | | STRING | String | | | DATE | Date | | | TIMESTAMP | Time, DateTime | | | BYTES | File, IO, StringIO, or similar | | | ARRAY | Array | Nested arrays are not supported. | | PROTO | Determined by proto_fqn | |

  See 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

#replace

def replace(table, *rows)

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 Google::Cloud::Spanner::Client#commit completes.

Parameters

• table (String) — The name of the table in the database to be modified.
• rows (Array<Hash>) — 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 | | | FLOAT32 | Float | | | NUMERIC | BigDecimal | | | STRING | String | | | DATE | Date | | | TIMESTAMP | Time, DateTime | | | BYTES | File, IO, StringIO, or similar | | | ARRAY | Array | Nested arrays are not supported. | | PROTO | Determined by proto_fqn | |

  See 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

#save

def save(table, *rows)

Alias Of: #upsert

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 Google::Cloud::Spanner::Client#commit completes.

Parameters

• table (String) — The name of the table in the database to be modified.
• rows (Array<Hash>) — 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 | | | FLOAT32 | Float | | | NUMERIC | BigDecimal | | | STRING | String | | | DATE | Date | | | TIMESTAMP | Time, DateTime | | | BYTES | File, IO, StringIO, or similar | | | ARRAY | Array | Nested arrays are not supported. | | PROTO | Determined by proto_fqn | |

  See 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

#send_message

def send_message(queue, key, payload, deliver_time: nil) -> Object, Array<Object>

Sends a message to a queue.

All changes are accumulated in memory until the block passed to Google::Cloud::Spanner::Client#commit completes.

Parameters

• queue (String) — The name of the queue.
• key (Object, Array<Object>) — A single key or array of composite key parts for the message.
• payload (String, IO, StringIO, Hash, Google::Protobuf::MessageExts) —

  The message payload. It is converted the same way as column values (see #upsert), so its type must match the queue's payload column, such as a String for STRING or a StringIO for BYTES:

  • String - Sent as text.
  • IO, StringIO, File - Sent as bytes (Base64-encoded). Ruby has no bytes type, so wrap binary data in a StringIO.
  • Hash - Serialized to a JSON string.
  • Google::Protobuf::MessageExts - Serialized and Base64-encoded.
• deliver_time (Time, nil) (defaults to: nil) — The time at which Spanner begins trying to deliver the message. Optional. If not set, the message is delivered immediately. A time in the past is replaced with a time closer to the current time.

Returns

• (Object, Array<Object>) — The key of the message.

Raises

• (ArgumentError) — If the payload type is unsupported.

Examples

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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

# OrderQueue has a STRING(MAX) payload column.
db.commit do |c|
  c.send_message "OrderQueue", 101, "Order payload"
end

Send binary data to a queue with a BYTES payload column

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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

db.commit do |c|
  c.send_message "LabelQueue", 101, StringIO.new(File.binread("label.png"))
end

Deliver the message in five minutes

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new

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

db.commit do |c|
  c.send_message "OrderQueue", 101, "Order payload",
                 deliver_time: Time.now + 300
end

#update

def update(table, *rows)

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

All changes are accumulated in memory until the block passed to Google::Cloud::Spanner::Client#commit completes.

Parameters

• table (String) — The name of the table in the database to be modified.
• rows (Array<Hash>) — 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 | | | FLOAT32 | Float | | | NUMERIC | BigDecimal | | | STRING | String | | | DATE | Date | | | TIMESTAMP | Time, DateTime | | | BYTES | File, IO, StringIO, or similar | | | ARRAY | Array | Nested arrays are not supported. | | PROTO | Determined by proto_fqn | |

  See 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

#upsert

def upsert(table, *rows)

Aliases

• #save

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 Google::Cloud::Spanner::Client#commit completes.

Parameters

• table (String) — The name of the table in the database to be modified.
• rows (Array<Hash>) — 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 | | | FLOAT32 | Float | | | NUMERIC | BigDecimal | | | STRING | String | | | DATE | Date | | | TIMESTAMP | Time, DateTime | | | BYTES | File, IO, StringIO, or similar | | | ARRAY | Array | Nested arrays are not supported. | | PROTO | Determined by proto_fqn | |

  See 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