Firestore in Datastore mode API - Class Google::Cloud::Datastore::ReadOnlyTransaction (v2.13.1)

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

ReadOnlyTransaction

Represents a read-only Datastore transaction that only allows reads.

A read-only transaction cannot modify entities; in return they do not contend with other read-write or read-only transactions. Using a read-only transaction for transactions that only read data will potentially improve throughput.

See Dataset#transaction

Inherits

  • Object

Example

require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new task_list_key = datastore.key "TaskList", "default" query = datastore.query("Task").  ancestor(task_list_key) tasks = nil datastore.read_only_transaction do |tx|  task_list = tx.find task_list_key  if task_list  tasks = tx.run query  end end

Methods

#begin_transaction

def begin_transaction()
Alias Of: #start

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

Raises

#commit

def commit()

Commits the transaction.

Example 
require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new task_list_key = datastore.key "TaskList", "default" tx = datastore.transaction task_list = tx.find task_list_key if task_list  query = tx.query("Task").  ancestor(task_list_key)  tasks = tx.run query end tx.commit

#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
Example 
require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new task_list_key = datastore.key "TaskList", "default" datastore.read_only_transaction do |tx|  task_list = tx.find task_list_key end

#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 datastore.read_only_transaction do |tx|  tasks = tx.find_all task_key1, task_key2 end

#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
Example 
require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new task_list_key = datastore.key "TaskList", "default" datastore.read_only_transaction do |tx|  task_list = tx.find task_list_key end

#gql

def gql(query, bindings = {}) -> Google::Cloud::Datastore::GqlQuery

Create a new GqlQuery instance. This is a convenience method to make the creation of GqlQuery objects easier.

Parameters
  • query (String) — The GQL query string.
  • bindings (Hash) — Named bindings for the GQL query string, each key must match regex [A-Za-z_$][A-Za-z_$0-9]*, must not match regex __.*__, and must not be "". The value must be an Object that can be stored as an Entity property value, or a Cursor.
Returns
Examples 
require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.read_only_transaction do |tx|  gql_query = tx.gql "SELECT * FROM Task WHERE done = @done",  done: false  tasks = tx.run gql_query end

The previous example is equivalent to:

require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.read_only_transaction do |tx|  gql_query = Google::Cloud::Datastore::GqlQuery.new  gql_query.query_string = "SELECT * FROM Task WHERE done = @done"  gql_query.named_bindings = {done: false}  tasks = tx.run gql_query end

#id

def id()

Returns the value of attribute id.

#key

def key(*path, project: nil, namespace: nil) -> Google::Cloud::Datastore::Key

Create a new Key instance. This is a convenience method to make the creation of Key objects easier.

Parameters
  • path (Array<Array(String,(String|Integer|nil))>) — An optional list of pairs for the key's path. Each pair may include the key's kind (String) and an id (Integer) or name (String). This is optional.
  • project (String) (defaults to: nil) — The project of the Key. This is optional.
  • namespace (String) (defaults to: nil) — namespace kind of the Key. This is optional.
Returns
Examples 
require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.read_only_transaction do |tx|  task_key = tx.key "Task", "sampleTask" end

The previous example is equivalent to:

require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.read_only_transaction do |tx|  task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask" end

Create a key with a parent:

require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.read_only_transaction do |tx|  key = tx.key [["TaskList", "default"], ["Task", "sampleTask"]]  results = tx.find_all key end

Create a key with multi-level ancestry:

require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.read_only_transaction do |tx|  key = tx.key([  ["User", "alice"],  ["TaskList", "default"],  ["Task", "sampleTask"]  ])  results = tx.find_all key end

Create a key with a project and namespace:

require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.read_only_transaction do |tx|  key = tx.key ["TaskList", "default"], ["Task", "sampleTask"],  project: "my-todo-project",  namespace: "example-ns"  results = tx.find_all key 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 datastore.read_only_transaction do |tx|  tasks = tx.find_all task_key1, task_key2 end

#query

def query(*kinds) -> Google::Cloud::Datastore::Query

Create a new Query instance. This is a convenience method to make the creation of Query objects easier.

Parameter
  • kinds (String) — The kind of entities to query. This is optional.
Returns
Example 
require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.read_only_transaction do |tx|  query = tx.query("Task").  where("done", "=", false)  tasks = tx.run query end

#read_time

def read_time()

Reads entities at the given time. This may not be older than 60 seconds.

#reset!

def reset!()

Reset the transaction. #start must be called afterwards.

#rollback

def rollback()

Rolls back the transaction.

Example 
require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new task_list_key = datastore.key "TaskList", "default" tx = datastore.transaction task_list = tx.find task_list_key if task_list  query = tx.query("Task").  ancestor(task_list_key)  tasks = tx.run query end tx.rollback

#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.read_only_transaction do |tx|  query = tx.query("Task").  where("done", "=", false)  tasks = tx.run query end

Run the query with explain options:

require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.read_only_transaction do |tx|  query = tx.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.read_only_transaction do |tx|  query = tx.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.
Returns
Examples 
require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.read_only_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.read_only_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.read_only_transaction do |tx|  query = tx.query("Task").  where("done", "=", false)  tasks = tx.run query end

Run the query with explain options:

require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.read_only_transaction do |tx|  query = tx.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.read_only_transaction do |tx|  query = tx.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

#start

def start()
Aliases

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

Raises