Firestore in Datastore mode API - Class Google::Cloud::Datastore::Transaction (v2.5.0)

Version 2.5.0

• 2.10.0 (latest)
• 2.9.0
• 2.8.0
• 2.7.1
• 2.6.0
• 2.5.0
• 2.4.0
• 2.3.1
• 2.2.4

Reference documentation and code samples for the Firestore in Datastore mode API class Google::Cloud::Datastore::Transaction.

Transaction

Special Connection instance for running transactions.

See Dataset#transaction

Inherits

• Google::Cloud::Datastore::Dataset

Example

Transactional update:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

def transfer_funds from_key, to_key, amount
  datastore.transaction do |tx|
    from = tx.find from_key
    from["balance"] -= amount
    to = tx.find to_key
    to["balance"] += amount
    tx.save from, to
  end
end

Methods

#begin_transaction

def begin_transaction()

Alias Of: #start

Begins a transaction. This method is run when a new Transaction is created.

Raises

• (TransactionError)

#commit

def commit() { |commit| ... }

Commits a transaction.

Yields

• (commit) — an optional block for making changes

Yield Parameter

• commit (Commit) — The object that changes are made on

Examples

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.entity "Task" do |t|
  t["type"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end

tx = datastore.transaction
begin
  if tx.find(task.key).nil?
    tx.save task
  end
  tx.commit
rescue
  tx.rollback
end

Commit can be passed a block, same as Dataset#commit:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

tx = datastore.transaction
begin
  tx.commit do |c|
  c.save task3, task4
  c.delete task1, task2
  end
rescue
  tx.rollback
end

#delete

def delete(*entities_or_keys)

Remove entities in a transaction.

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

datastore.transaction do |tx|
  if tx.find(task_list.key).nil?
    tx.delete task1, task2
  end
end

#find

def find(key_or_kind, id_or_name = nil) -> Google::Cloud::Datastore::Entity, nil

Aliases

• #get

Retrieve an entity by providing key information. The lookup is run within the transaction.

Parameter

• key_or_kind (Key, String) — A Key object or kind string value.

Returns

• (Google::Cloud::Datastore::Entity, nil)

Examples

Finding an entity with a key:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key = datastore.key "Task", "sampleTask"
task = datastore.find task_key

Finding an entity with a kind and id/name:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.find "Task", "sampleTask"

#find_all

def find_all(*keys) -> Google::Cloud::Datastore::Dataset::LookupResults

Aliases

• #lookup

Retrieve the entities for the provided keys. The lookup is run within the transaction.

Parameter

• keys (Key) — One or more Key objects to find records for.

Returns

• (Google::Cloud::Datastore::Dataset::LookupResults)

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key1 = datastore.key "Task", 123456
task_key2 = datastore.key "Task", 987654
tasks = datastore.find_all task_key1, task_key2

#get

def get(key_or_kind, id_or_name = nil) -> Google::Cloud::Datastore::Entity, nil

Alias Of: #find

Retrieve an entity by providing key information. The lookup is run within the transaction.

Parameter

• key_or_kind (Key, String) — A Key object or kind string value.

Returns

• (Google::Cloud::Datastore::Entity, nil)

Examples

Finding an entity with a key:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key = datastore.key "Task", "sampleTask"
task = datastore.find task_key

Finding an entity with a kind and id/name:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.find "Task", "sampleTask"

#id

def id() -> String

The identifier of the transaction.

Returns

• (String) — the current value of id

#insert

def insert(*entities)

Insert entities in a transaction. An InvalidArgumentError will raised if the entities cannot be inserted.

Example

Transactional insert:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key = datastore.key "Task", "sampleTask"

task = nil
datastore.transaction do |tx|
  task = tx.find task_key
  if task.nil?
    task = datastore.entity task_key do |t|
      t["type"] = "Personal"
      t["done"] = false
      t["priority"] = 4
      t["description"] = "Learn Cloud Datastore"
    end
    tx.insert task
  end
end

#lookup

def lookup(*keys) -> Google::Cloud::Datastore::Dataset::LookupResults

Alias Of: #find_all

Retrieve the entities for the provided keys. The lookup is run within the transaction.

Parameter

• keys (Key) — One or more Key objects to find records for.

Returns

• (Google::Cloud::Datastore::Dataset::LookupResults)

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key1 = datastore.key "Task", 123456
task_key2 = datastore.key "Task", 987654
tasks = datastore.find_all task_key1, task_key2

#reset!

def reset!()

Reset the transaction. #start must be called afterwards.

#rollback

def rollback()

Rolls a transaction back.

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.entity "Task" do |t|
  t["type"] = "Personal"
  t["done"] = false
  t["priority"] = 4
  t["description"] = "Learn Cloud Datastore"
end

tx = datastore.transaction
begin
  if tx.find(task.key).nil?
    tx.save task
  end
  tx.commit
rescue
  tx.rollback
end

#run

def run(query, namespace: nil) -> Google::Cloud::Datastore::Dataset::QueryResults

Aliases

• #run_query

Retrieve entities specified by a Query. The query is run within the transaction.

Parameters

• query (Query) — The Query object with the search criteria.
• namespace (String) (defaults to: nil) — The namespace the query is to run within.

Returns

• (Google::Cloud::Datastore::Dataset::QueryResults)

Examples

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

datastore.transaction do |tx|
  query = datastore.query("Task")
  tasks = tx.run query
end

Run the query within a namespace with the namespace option:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = Google::Cloud::Datastore::Query.new.kind("Task").
  where("done", "=", false)
datastore.transaction do |tx|
  tasks = tx.run query, namespace: "example-ns"
end

#run_query

def run_query(query, namespace: nil) -> Google::Cloud::Datastore::Dataset::QueryResults

Alias Of: #run

Retrieve entities specified by a Query. The query is run within the transaction.

Parameters

• query (Query) — The Query object with the search criteria.
• namespace (String) (defaults to: nil) — The namespace the query is to run within.

Returns

• (Google::Cloud::Datastore::Dataset::QueryResults)

Examples

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

datastore.transaction do |tx|
  query = datastore.query("Task")
  tasks = tx.run query
end

Run the query within a namespace with the namespace option:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = Google::Cloud::Datastore::Query.new.kind("Task").
  where("done", "=", false)
datastore.transaction do |tx|
  tasks = tx.run query, namespace: "example-ns"
end

#save

def save(*entities)

Aliases

• #upsert

Persist entities in a transaction.

Example

Transactional get or create:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key = datastore.key "Task", "sampleTask"

task = nil
datastore.transaction do |tx|
  task = tx.find task_key
  if task.nil?
    task = datastore.entity task_key do |t|
      t["type"] = "Personal"
      t["done"] = false
      t["priority"] = 4
      t["description"] = "Learn Cloud Datastore"
    end
    tx.save task
  end
end

#start

def start()

Aliases

• #begin_transaction

Begins a transaction. This method is run when a new Transaction is created.

Raises

• (TransactionError)

#update

def update(*entities)

Update entities in a transaction. An InvalidArgumentError will raised if the entities cannot be updated.

Example

Transactional update:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key = datastore.key "Task", "sampleTask"

task = nil
datastore.transaction do |tx|
  task = tx.find task_key
  if task
    task["done"] = true
    tx.update task
  end
end

#upsert

def upsert(*entities)

Alias Of: #save

Persist entities in a transaction.

Example

Transactional get or create:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key = datastore.key "Task", "sampleTask"

task = nil
datastore.transaction do |tx|
  task = tx.find task_key
  if task.nil?
    task = datastore.entity task_key do |t|
      t["type"] = "Personal"
      t["done"] = false
      t["priority"] = 4
      t["description"] = "Learn Cloud Datastore"
    end
    tx.save task
  end
end