Module: Gcloud::Datastore

Defined in:

lib/gcloud/datastore.rb,
lib/gcloud/datastore/key.rb,
lib/gcloud/datastore/proto.rb,
lib/gcloud/datastore/query.rb,
lib/gcloud/datastore/entity.rb,
lib/gcloud/datastore/errors.rb,
lib/gcloud/datastore/dataset.rb,
lib/gcloud/datastore/connection.rb,
lib/gcloud/datastore/properties.rb,
lib/gcloud/datastore/credentials.rb,
lib/gcloud/datastore/transaction.rb,
lib/gcloud/proto/datastore_v1.pb.rb,
lib/gcloud/datastore/dataset/query_results.rb,
lib/gcloud/datastore/dataset/lookup_results.rb

Overview

# Google Cloud Datastore

Google Cloud Datastore is a fully managed, schemaless database for storing non-relational data. You should feel at home if you are familiar with relational databases, but there are some key differences to be aware of to make the most of using Datastore.

Gcloud’s goal is to provide a API that is familiar and comfortable to Rubyists. Authentication is handled by #datastore. You can provide the project and credential information to connect to the Datastore service, or if you are running on Google Compute Engine this configuration is taken care of for you.

“‘ruby require “gcloud”

gcloud = Gcloud.new “my-todo-project”,

"/path/to/keyfile.json"

dataset = gcloud.datastore entity = dataset.find “Task”, “start” entity = true dataset.save entity “‘

You can learn more about various options for connection on the [Authentication Guide](googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).

To learn more about Datastore, read the [Google Cloud Datastore Concepts Overview ](cloud.google.com/datastore/docs/concepts/overview).

## Retrieving Records

Records, called “entities” in Datastore, are retrieved by using a Key. The Key is more than a numeric identifier, it is a complex data structure that can be used to model relationships. The simplest Key has a string kind value, and either a numeric id value, or a string name value. A single record can be retrieved by calling Dataset#find and passing the parts of the key:

“‘ruby require “gcloud”

gcloud = Gcloud.new dataset = gcloud.datastore entity = dataset.find “Task”, “start” “‘

Optionally, Dataset#find can be given a Key object:

“‘ruby require “gcloud”

gcloud = Gcloud.new dataset = gcloud.datastore key = dataset.key “Task”, 12345 entity = dataset.find key “‘

See Dataset#find

## Querying Records

Multiple records can be found that match criteria. (See Query#where)

“‘ruby require “gcloud”

gcloud = Gcloud.new dataset = gcloud.datastore query = dataset.query(“List”).

where("active", "=", true)

active_lists = dataset.run query “‘

Records can also be ordered. (See Query#order)

“‘ruby require “gcloud”

gcloud = Gcloud.new dataset = gcloud.datastore query = dataset.query(“List”).

where("active", "=", true).
order("name")

active_lists = dataset.run query “‘

The number of records returned can be specified. (See Query#limit)

“‘ruby require “gcloud”

gcloud = Gcloud.new dataset = gcloud.datastore query = dataset.query(“List”).

where("active", "=", true).
order("name").
limit(5)

active_lists = dataset.run query “‘

Records’ Key structures can also be queried. (See Query#ancestor)

“‘ruby require “gcloud”

gcloud = Gcloud.new dataset = gcloud.datastore

list = dataset.find “List”, “todos” query = dataset.query(“Task”).

ancestor(list.key)

items = dataset.run query “‘

See Query and Dataset#run

## Paginating Records

All Records may not return at once, requiring multiple calls to Datastore to return them all. The returned records will have a cursor if there are more available.

“‘ruby require “gcloud”

gcloud = Gcloud.new dataset = gcloud.datastore

list = dataset.find “List”, “todos” query = dataset.query(“Task”).

ancestor(list.key)

all_tasks = [] tmp_tasks = dataset.run query while tmp_tasks.any? do

tmp_tasks.each do |task|
  all_tasks << task
end
# break loop if no more tasks available
break if tmp_tasks.cursor.nil?
# set cursor on the query
query = query.cursor tmp_tasks.cursor
# query for more records
tmp_tasks = dataset.run query

end “‘

See Dataset::LookupResults and Dataset::QueryResults

## Creating Records

New entities can be created and persisted buy calling Dataset#save. The entity must have a Key to be saved. If the Key is incomplete then it will be completed when saved.

“‘ruby require “gcloud”

gcloud = Gcloud.new dataset = gcloud.datastore entity = dataset.entity “User” do |e|

e["name"] = "Heidi Henderson"

end entity.key.id #=> nil dataset.save entity entity.key.id #=> 123456789 “‘

## Updating Records

Entities hold properties. A property has a name that is a string or symbol, and a value that is an object. Most value objects are supported, including String, Integer, Date, Time, and even other Entity or Key objects. Changes to the Entity’s properties are persisted by calling Dataset#save.

“‘ruby require “gcloud”

gcloud = Gcloud.new dataset = gcloud.datastore entity = dataset.find “User”, “heidi” # Read the status property entity #=> “inactive” # Write the status property entity = “active” # Persist the changes dataset.save entity “‘

## Deleting Records

Entities can be removed from Datastore by calling Dataset#delete and passing the Entity object or the entity’s Key object.

“‘ruby require “gcloud”

gcloud = Gcloud.new dataset = gcloud.datastore entity = dataset.find “User”, “heidi” dataset.delete entity “‘

## Transactions

Complex logic can be wrapped in a Transaction. All queries and updates within the Dataset#transaction block are run within the transaction scope, and will be automatically committed when the block completes.

“‘ruby require “gcloud”

gcloud = Gcloud.new dataset = gcloud.datastore

key = dataset.key “User”, “heidi”

user = dataset.entity key do |u|

u["name"] = "Heidi Henderson"
u["email"] = "heidi@example.net"

end

dataset.transaction do |tx|

if tx.find(user.key).nil?
  tx.save user
end

end “‘

Alternatively, if no block is given the transaction object is returned allowing you to commit or rollback manually.

“‘ruby require “gcloud”

gcloud = Gcloud.new dataset = gcloud.datastore

key = dataset.key “User”, “heidi”

user = dataset.entity key do |u|

u["name"] = "Heidi Henderson"
u["email"] = "heidi@example.net"

end

tx = dataset.transaction begin

if tx.find(user.key).nil?
  tx.save user
end
tx.commit

rescue

tx.rollback

end “‘

See Transaction and Dataset#transaction

Defined Under Namespace

Modules: Proto Classes: ApiError, Connection, Credentials, Dataset, Entity, Error, Key, KeyfileError, Properties, PropertyError, Query, Transaction, TransactionError