Firestore in Datastore mode API - Class Google::Cloud::Datastore::Dataset (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::Dataset.

Dataset

Dataset is the data saved in a project's Datastore. Dataset is analogous to a database in relational database world.

Dataset is the main object for interacting with Google Datastore. Entity objects are created, read, updated, and deleted by Dataset.

See Google::Cloud#datastore

Inherits

• Object

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query("Task").
  where("done", "=", false)

tasks = datastore.run query

Methods

#allocate_ids

def allocate_ids(incomplete_key, count = 1) -> Array<Google::Cloud::Datastore::Key>

Generate IDs for a Key before creating an entity.

Parameters

• incomplete_key (Key) — A Key without id or name set.
• count (String) — The number of new key IDs to create.

Returns

• (Array<Google::Cloud::Datastore::Key>)

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key = datastore.key "Task"
task_keys = datastore.allocate_ids task_key, 5

#commit

def commit() { |commit| ... } -> Array<Google::Cloud::Datastore::Entity>

Make multiple changes in a single commit.

Yields

• (commit) — a block for making changes

Yield Parameter

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

Returns

• (Array<Google::Cloud::Datastore::Entity>) — The entities that were persisted.

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

datastore.commit do |c|
  c.save task3, task4
  c.delete task1, task2
end

#database_id

def database_id() -> String

The Datastore database connected to.

Returns

• (String) — ID of the database

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new(
  project_id: "my-todo-project",
  credentials: "/path/to/keyfile.json",
  database_id: "my-database"
)

datastore.database_id #=> "my-database"

#delete

def delete(*entities_or_keys) -> Boolean

Remove entities from the Datastore.

Parameter

• entities_or_keys (Entity, Key) — One or more Entity or Key objects to remove.

Returns

• (Boolean) — Returns true if successful

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

datastore.delete task1, task2

#entity

def entity(*key_or_path, project: nil, namespace: nil) { |entity| ... } -> Google::Cloud::Datastore::Entity

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

Parameters

• key_or_path (Key, 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.

Yields

• (entity) — a block yielding a new entity

Yield Parameter

• entity (Entity) — the newly created entity object

Returns

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

Examples

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.entity

The previous example is equivalent to:

require "google/cloud/datastore"

task = Google::Cloud::Datastore::Entity.new

The key can also be passed in as an object:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

Or the key values can be passed in as parameters:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

The previous example is equivalent to:

require "google/cloud/datastore"

task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
task = Google::Cloud::Datastore::Entity.new
task.key = task_key

The newly created entity can also be configured using block:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

The previous example is equivalent to:

require "google/cloud/datastore"

task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"
task = Google::Cloud::Datastore::Entity.new
task.key = task_key
task["type"] = "Personal"
task["done"] = false
task["priority"] = 4
task["description"] = "Learn Cloud Datastore"

#filter

def filter(name, operator, value) -> Google::Cloud::Datastore::Filter

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

Parameters

• name (String) — The property to filter by.
• operator (String) — The operator to filter by. Defaults to nil.
• value (Object) —

  The value to compare the property to. Defaults to nil. Possible values are:

  • Integer
  • Float/BigDecimal
  • String
  • Boolean
  • Array
  • Date/Time
  • StringIO
  • Google::Cloud::Datastore::Key
  • Google::Cloud::Datastore::Entity
  • nil

Returns

• (Google::Cloud::Datastore::Filter)

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

filter = datastore.filter("done", "=", false)

#find

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

Aliases

• #get

Retrieve an entity by key.

Parameters

• key_or_kind (Key, String) — A Key object or kind string value.
• id_or_name (Integer, String, nil) — The Key's id or name value if a kind was provided in the first parameter.
• consistency (Symbol) (defaults to: nil) — The non-transactional read consistency to use. Cannot be set to :strong for global queries. Accepted values are :eventual and :strong.

  The default consistency depends on the type of lookup used. See Eventual Consistency in Google Cloud Datastore for more information.

• read_time (Time) (defaults to: nil) — Reads entities as they were at the given time. This may not be older than 270 seconds. Optional

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, consistency: nil, read_time: nil) -> Google::Cloud::Datastore::Dataset::LookupResults

Aliases

• #lookup

Retrieve the entities for the provided keys. The order of results is undefined and has no relation to the order of keys arguments.

Parameters

• keys (Key) — One or more Key objects to find records for.
• consistency (Symbol) (defaults to: nil) — The non-transactional read consistency to use. Cannot be set to :strong for global queries. Accepted values are :eventual and :strong.

  The default consistency depends on the type of lookup used. See Eventual Consistency in Google Cloud Datastore for more information.

• read_time (Time) (defaults to: nil) — Reads entities as they were at the given time. This may not be older than 270 seconds. Optional

Returns

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

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key1 = datastore.key "Task", "sampleTask1"
task_key2 = datastore.key "Task", "sampleTask2"
tasks = datastore.find_all task_key1, task_key2

#get

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

Alias Of: #find

Retrieve an entity by key.

Parameters

• key_or_kind (Key, String) — A Key object or kind string value.
• id_or_name (Integer, String, nil) — The Key's id or name value if a kind was provided in the first parameter.
• consistency (Symbol) (defaults to: nil) — The non-transactional read consistency to use. Cannot be set to :strong for global queries. Accepted values are :eventual and :strong.

  The default consistency depends on the type of lookup used. See Eventual Consistency in Google Cloud Datastore for more information.

• read_time (Time) (defaults to: nil) — Reads entities as they were at the given time. This may not be older than 270 seconds. Optional

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"

#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

gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
                          done: false
tasks = datastore.run gql_query

The previous example is equivalent to:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

gql_query = Google::Cloud::Datastore::GqlQuery.new
gql_query.query_string = "SELECT * FROM Task WHERE done = @done"
gql_query.named_bindings = {done: false}
tasks = datastore.run gql_query

#insert

def insert(*entities) -> Array<Google::Cloud::Datastore::Entity>

Insert one or more entities to the Datastore. An InvalidArgumentError will raised if the entities cannot be inserted.

Parameter

• entities (Entity) — One or more entity objects to be inserted.

Returns

• (Array<Google::Cloud::Datastore::Entity>)

Examples

Insert a new entity:

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
task.key.id #=> nil
datastore.insert task
task.key.id #=> 123456

Insert multiple new entities in a batch:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

task2 = datastore.entity "Task" do |t|
  t["type"] = "Personal"
  t["done"] = false
  t["priority"] = 5
  t["description"] = "Integrate Cloud Datastore"
end

task_key1, task_key2 = datastore.insert(task1, task2).map(&:key)

#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

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

The previous example is equivalent to:

require "google/cloud/datastore"

task_key = Google::Cloud::Datastore::Key.new "Task", "sampleTask"

Create an empty key:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

key = datastore.key

Create an incomplete key:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

key = datastore.key "User"

Create a key with a parent:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

key = datastore.key [["TaskList", "default"],
                     ["Task", "sampleTask"]]
key.path #=> [["TaskList", "default"], ["Task", "sampleTask"]]

Create a key with multi-level ancestry:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

key = datastore.key([
  ["User", "alice"],
  ["TaskList", "default"],
  ["Task", "sampleTask"]
])
key.path.count #=> 3
key.path[0] #=> ["User", "alice"]
key.path[1] #=> ["TaskList", "default"]
key.path[2] #=> ["Task", "sampleTask"]

Create an incomplete key with a parent:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

key = datastore.key "TaskList", "default", "Task"
key.path #=> [["TaskList", "default"], ["Task", nil]]

Create a key with a project and namespace:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

key = datastore.key ["TaskList", "default"], ["Task", "sampleTask"],
                    project: "my-todo-project",
                    namespace: "example-ns"
key.path #=> [["TaskList", "default"], ["Task", "sampleTask"]]
key.project #=> "my-todo-project"
key.namespace #=> "example-ns"

#lookup

def lookup(*keys, consistency: nil, read_time: nil) -> Google::Cloud::Datastore::Dataset::LookupResults

Alias Of: #find_all

Retrieve the entities for the provided keys. The order of results is undefined and has no relation to the order of keys arguments.

Parameters

• keys (Key) — One or more Key objects to find records for.
• consistency (Symbol) (defaults to: nil) — The non-transactional read consistency to use. Cannot be set to :strong for global queries. Accepted values are :eventual and :strong.

  The default consistency depends on the type of lookup used. See Eventual Consistency in Google Cloud Datastore for more information.

• read_time (Time) (defaults to: nil) — Reads entities as they were at the given time. This may not be older than 270 seconds. Optional

Returns

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

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_key1 = datastore.key "Task", "sampleTask1"
task_key2 = datastore.key "Task", "sampleTask2"
tasks = datastore.find_all task_key1, task_key2

#project

def project()

Alias Of: #project_id

The Datastore project connected to.

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new(
  project_id: "my-todo-project",
  credentials: "/path/to/keyfile.json"
)

datastore.project_id #=> "my-todo-project"

#project_id

def project_id()

Aliases

• #project

The Datastore project connected to.

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new(
  project_id: "my-todo-project",
  credentials: "/path/to/keyfile.json"
)

datastore.project_id #=> "my-todo-project"

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

Examples

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query("Task").
  where("done", "=", false)
tasks = datastore.run query

The previous example is equivalent to:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = Google::Cloud::Datastore::Query.new.
  kind("Task").
  where("done", "=", false)
tasks = datastore.run query

#read_only_transaction

def read_only_transaction(read_time: nil) { |tx| ... }

Aliases

• #snapshot

Creates a read-only transaction that provides a consistent snapshot of Cloud Datastore. This can be useful when multiple reads are needed to render a page or export data that must be consistent.

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.

Read-only single-group transactions never fail due to concurrent modifications, so you don't have to implement retries upon failure. However, multi-entity-group transactions can fail due to concurrent modifications, so these should have retries.

Parameter

• read_time (Time) (defaults to: nil) — Reads entities at the given time. This may not be older than 60 seconds. Optional

Yields

• (tx) — a block yielding a new transaction

Yield Parameter

• tx (ReadOnlyTransaction) — the transaction 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

#run

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

Aliases

• #run_query

Retrieve entities specified by a Query.

Parameters

• query (Query, GqlQuery) — The object with the search criteria.
• namespace (String) (defaults to: nil) — The namespace the query is to run within.
• consistency (Symbol) (defaults to: nil) — The non-transactional read consistency to use. Cannot be set to :strong for global queries. Accepted values are :eventual and :strong.

  The default consistency depends on the type of query used. See Eventual Consistency in Google Cloud Datastore for more information.

• read_time (Time) (defaults to: nil) — Reads entities as they were at the given time. This may not be older than 270 seconds. Optional

Returns

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

Examples

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query("Task").
  where("done", "=", false)
tasks = datastore.run query

Run an ancestor query with eventual consistency:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_list_key = datastore.key "TaskList", "default"
query = datastore.query.kind("Task").
  ancestor(task_list_key)

tasks = datastore.run query, consistency: :eventual

Run the query within a namespace with the namespace option:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query("Task").
  where("done", "=", false)
tasks = datastore.run query, namespace: "example-ns"

Run the query with a GQL string.

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
                          done: false
tasks = datastore.run gql_query

Run the GQL query within a namespace with namespace option:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
                          done: false
tasks = datastore.run gql_query, namespace: "example-ns"

#run_aggregation

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

Retrieve aggregate results specified by an AggregateQuery.

Parameters

• query (AggregateQuery, GqlQuery) — The object with the aggregate criteria.
• namespace (String) (defaults to: nil) — The namespace the query is to run within.
• consistency (Symbol) (defaults to: nil) — The non-transactional read consistency to use. Cannot be set to :strong for global queries. Accepted values are :eventual and :strong.
• read_time (Time) (defaults to: nil) — Reads entities as they were at the given time. This may not be older than 270 seconds. Optional

  The default consistency depends on the type of query used. See Eventual Consistency in Google Cloud Datastore for more information.

Returns

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

Examples

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query("Task")
                 .where("done", "=", false)

aggregate_query = query.aggregate_query

res = datastore.run_aggregation aggregate_query

Run an aggregate ancestor query with eventual consistency:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_list_key = datastore.key "TaskList", "default"
query = datastore.query.kind("Task")
                 .ancestor(task_list_key)

aggregate_query = query.aggregate_query

res = datastore.run_aggregation aggregate_query, consistency: :eventual

Run the aggregate query within a namespace with the namespace option:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query("Task")
                 .where("done", "=", false)

aggregate_query = query.aggregate_query

res = datastore.run_aggregation aggregate_query, namespace: "example-ns"

Run the aggregate query with a GQL string.

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

gql_query = datastore.gql "SELECT COUNT(*) FROM Task WHERE done = @done",
                          done: false
res = datastore.run_aggregation gql_query

Run the aggregate GQL query within a namespace with namespace option:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

gql_query = datastore.gql "SELECT COUNT(*) FROM Task WHERE done = @done",
                          done: false
res = datastore.run_aggregation gql_query, namespace: "example-ns"

#run_query

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

Alias Of: #run

Retrieve entities specified by a Query.

Parameters

• query (Query, GqlQuery) — The object with the search criteria.
• namespace (String) (defaults to: nil) — The namespace the query is to run within.
• consistency (Symbol) (defaults to: nil) — The non-transactional read consistency to use. Cannot be set to :strong for global queries. Accepted values are :eventual and :strong.

  The default consistency depends on the type of query used. See Eventual Consistency in Google Cloud Datastore for more information.

• read_time (Time) (defaults to: nil) — Reads entities as they were at the given time. This may not be older than 270 seconds. Optional

Returns

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

Examples

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query("Task").
  where("done", "=", false)
tasks = datastore.run query

Run an ancestor query with eventual consistency:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task_list_key = datastore.key "TaskList", "default"
query = datastore.query.kind("Task").
  ancestor(task_list_key)

tasks = datastore.run query, consistency: :eventual

Run the query within a namespace with the namespace option:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query("Task").
  where("done", "=", false)
tasks = datastore.run query, namespace: "example-ns"

Run the query with a GQL string.

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
                          done: false
tasks = datastore.run gql_query

Run the GQL query within a namespace with namespace option:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

gql_query = datastore.gql "SELECT * FROM Task WHERE done = @done",
                          done: false
tasks = datastore.run gql_query, namespace: "example-ns"

#save

def save(*entities) -> Array<Google::Cloud::Datastore::Entity>

Aliases

• #upsert

Persist one or more entities to the Datastore.

Parameter

• entities (Entity) — One or more entity objects to be saved.

Returns

• (Array<Google::Cloud::Datastore::Entity>)

Examples

Insert a new entity:

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
task.key.id #=> nil
datastore.save task
task.key.id #=> 123456

Insert multiple new entities in a batch:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

task2 = datastore.entity "Task" do |t|
  t["type"] = "Personal"
  t["done"] = false
  t["priority"] = 5
  t["description"] = "Integrate Cloud Datastore"
end

task_key1, task_key2 = datastore.save(task1, task2).map(&:key)

Update an existing entity:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.find "Task", "sampleTask"
task["priority"] = 5
datastore.save task

#snapshot

def snapshot(read_time: nil) { |tx| ... }

Alias Of: #read_only_transaction

Creates a read-only transaction that provides a consistent snapshot of Cloud Datastore. This can be useful when multiple reads are needed to render a page or export data that must be consistent.

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.

Read-only single-group transactions never fail due to concurrent modifications, so you don't have to implement retries upon failure. However, multi-entity-group transactions can fail due to concurrent modifications, so these should have retries.

Parameter

• read_time (Time) (defaults to: nil) — Reads entities at the given time. This may not be older than 60 seconds. Optional

Yields

• (tx) — a block yielding a new transaction

Yield Parameter

• tx (ReadOnlyTransaction) — the transaction 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

#transaction

def transaction(deadline: nil, previous_transaction: nil) { |tx| ... }

Creates a Datastore Transaction.

Transactions using the block syntax are committed upon block completion and are automatically retried when known errors are raised during commit. All other errors will be passed on.

All changes are accumulated in memory until the block completes. Transactions will be automatically retried when possible, until deadline is reached. This operation makes separate API requests to begin and commit the transaction.

Parameters

• deadline (Numeric) (defaults to: nil) — The total amount of time in seconds the transaction has to succeed. The default is 60.
• previous_transaction (String) (defaults to: nil) — The transaction identifier of a transaction that is being retried. Read-write transactions may fail due to contention. A read-write transaction can be retried by specifying previous_transaction when creating the new transaction.

  Specifying previous_transaction provides information that can be used to improve throughput. In particular, if transactional operations A and B conflict, specifying the previous_transaction can help to prevent livelock. (See Transaction#id)

Yields

• (tx) — a block yielding a new transaction

Yield Parameter

• tx (Transaction) — the transaction object

Examples

Runs the given block in a database transaction:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

datastore.transaction do |tx|
  if tx.find(task.key).nil?
    tx.save task
  end
end

If no block is given, a Transaction object is returned:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.entity "Task", "sampleTask" 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

#update

def update(*entities) -> Array<Google::Cloud::Datastore::Entity>

Update one or more entities to the Datastore. An InvalidArgumentError will raised if the entities cannot be updated.

Parameter

• entities (Entity) — One or more entity objects to be updated.

Returns

• (Array<Google::Cloud::Datastore::Entity>)

Examples

Update an existing entity:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.find "Task", "sampleTask"
task["done"] = true
datastore.save task

Update multiple new entities in a batch:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

query = datastore.query("Task").where("done", "=", false)
tasks = datastore.run query
tasks.each { |t| t["done"] = true }
datastore.update tasks

#upsert

def upsert(*entities) -> Array<Google::Cloud::Datastore::Entity>

Alias Of: #save

Persist one or more entities to the Datastore.

Parameter

• entities (Entity) — One or more entity objects to be saved.

Returns

• (Array<Google::Cloud::Datastore::Entity>)

Examples

Insert a new entity:

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
task.key.id #=> nil
datastore.save task
task.key.id #=> 123456

Insert multiple new entities in a batch:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

task2 = datastore.entity "Task" do |t|
  t["type"] = "Personal"
  t["done"] = false
  t["priority"] = 5
  t["description"] = "Integrate Cloud Datastore"
end

task_key1, task_key2 = datastore.save(task1, task2).map(&:key)

Update an existing entity:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.find "Task", "sampleTask"
task["priority"] = 5
datastore.save task