google-cloud-datastore - Class Google::Cloud::Datastore::Dataset (v2.2.4)

Reference documentation and code samples for the google-cloud-datastore 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
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
Example 
require "google/cloud/datastore" datastore = Google::Cloud::Datastore.new datastore.commit do |c|  c.save task3, task4  c.delete task1, task2 end

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

#find

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

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.

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

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.

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

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"

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

Returns
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

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
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() { |tx| ... }
Aliases

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.

Yields
  • (tx) — a block yielding a new transaction
Yield Parameter
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) -> Google::Cloud::Datastore::Dataset::QueryResults
Aliases

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.

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

def run_query(query, namespace: nil, consistency: 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.

Returns
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

Persist one or more entities to the Datastore.

Parameter
  • entities (Entity) — One or more entity objects to be saved.
Returns
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() { |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.

Yields
  • (tx) — a block yielding a new transaction
Yield Parameter
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
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
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
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