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

Version 2.9.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::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

• (TransactionError)

#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

• #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)

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

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

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

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

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

• (Google::Cloud::Datastore::GqlQuery)

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

• (Google::Cloud::Datastore::Key)

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

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

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

• (Google::Cloud::Datastore::Query)

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

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

#run_aggregation

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

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

Parameters

• query (AggregateQuery, GqlQuery) — 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::AggregateQueryResults)

Example

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

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

#start

def start()

Aliases

• #begin_transaction

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

Raises

• (TransactionError)