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

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

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

#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

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
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

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
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
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
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, explain_options: nil) -> Google::Cloud::Datastore::Dataset::QueryResults
Aliases

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

Parameters
  • query (Query, GqlQuery) — The query with the search criteria.
  • namespace (String) (defaults to: nil) — The namespace the query is to run within.
  • explain_options (Hash, Google::Cloud::Datastore::V1::ExplainOptions) (defaults to: nil) — The options for query explanation. See V1::ExplainOptions for details. Optional.
Returns
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 the query with explain options:

require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.transaction do |tx|  query = datastore.query("Task")  results = tx.run query, explain_options: { analyze: true }  # You must iterate through all pages of results to get the metrics.  loop do  break unless results.next?  results = results.next  end  if results.explain_metrics  stats = results.explain_metrics.execution_stats  puts "Read operations: #{stats.read_operations}"  end end

Run the query with explain options using a Google::Cloud::Datastore::V1::ExplainOptions object.

require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.transaction do |tx|  query = datastore.query("Task")  explain_options = Google::Cloud::Datastore::V1::ExplainOptions.new  results = tx.run query, explain_options: explain_options  # You must iterate through all pages of results to get the metrics.  loop do  break unless results.next?  results = results.next  end  if results.explain_metrics  stats = results.explain_metrics.execution_stats  puts "Read operations: #{stats.read_operations}"  end end

#run_aggregation

def run_aggregation(aggregate_query, namespace: nil, explain_options: nil) -> Google::Cloud::Datastore::Dataset::AggregateQueryResults

Retrieve aggregate query results specified by an AggregateQuery. The query is run within the transaction.

Parameters
  • aggregate_query (AggregateQuery, GqlQuery) — The Query object with the search criteria.
  • namespace (String) (defaults to: nil) — The namespace the query is to run within.
  • explain_options (Hash, Google::Cloud::Datastore::V1::ExplainOptions) (defaults to: nil) — The options for query explanation. See V1::ExplainOptions for details. Optional.
Returns
Examples 
require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.transaction do |tx|  query = tx.query("Task")  .where("done", "=", false)  aggregate_query = query.aggregate_query  .add_count  res = tx.run_aggregation aggregate_query end

Run the aggregate query with explain options:

require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.transaction do |tx|  query = tx.query("Task")  aggregate_query = query.aggregate_query.add_count aggregate_alias: "total"  results = tx.run_aggregation aggregate_query, explain_options: { analyze: true }  if results.explain_metrics  stats = results.explain_metrics.execution_stats  puts "Read operations: #{stats.read_operations}"  end end

#run_query

def run_query(query, namespace: nil, explain_options: 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, GqlQuery) — The query with the search criteria.
  • namespace (String) (defaults to: nil) — The namespace the query is to run within.
  • explain_options (Hash, Google::Cloud::Datastore::V1::ExplainOptions) (defaults to: nil) — The options for query explanation. See V1::ExplainOptions for details. Optional.
Returns
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 the query with explain options:

require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.transaction do |tx|  query = datastore.query("Task")  results = tx.run query, explain_options: { analyze: true }  # You must iterate through all pages of results to get the metrics.  loop do  break unless results.next?  results = results.next  end  if results.explain_metrics  stats = results.explain_metrics.execution_stats  puts "Read operations: #{stats.read_operations}"  end end

Run the query with explain options using a Google::Cloud::Datastore::V1::ExplainOptions object.

require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.transaction do |tx|  query = datastore.query("Task")  explain_options = Google::Cloud::Datastore::V1::ExplainOptions.new  results = tx.run query, explain_options: explain_options  # You must iterate through all pages of results to get the metrics.  loop do  break unless results.next?  results = results.next  end  if results.explain_metrics  stats = results.explain_metrics.execution_stats  puts "Read operations: #{stats.read_operations}"  end end

#save

def save(*entities)
Aliases

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

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

Raises

#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