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 Gcloud#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.
require "gcloud"
gcloud = Gcloud.new "my-todo-project",
"/path/to/keyfile.json"
dataset = gcloud.datastore
entity = dataset.find "Task", "start"
entity["completed"] = true
dataset.save entity
You can learn more about various options for connection on the Authentication Guide.
To learn more about Datastore, read the Google Cloud Datastore 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 Gcloud::Datastore::Dataset#find and passing the parts of the key:
require "gcloud"
gcloud = Gcloud.new
dataset = gcloud.datastore
entity = dataset.find "Task", "start"
Optionally, Gcloud::Datastore::Dataset#find can be given a Key object:
require "gcloud"
gcloud = Gcloud.new
dataset = gcloud.datastore
key = Gcloud::Datastore::Key.new "Task", 12345
entity = dataset.find key
See Gcloud::Datastore::Dataset#find
Querying Records
Multiple records can be found that match criteria. (See Gcloud::Datastore::Query#where)
require "gcloud"
gcloud = Gcloud.new
dataset = gcloud.datastore
query = Gcloud::Datastore::Query.new
query.kind("List").
where("active", "=", true)
active_lists = dataset.run query
Records can also be ordered. (See Gcloud::Datastore::Query#order)
require "gcloud"
gcloud = Gcloud.new
dataset = gcloud.datastore
query = Gcloud::Datastore::Query.new
query.kind("List").
where("active", "=", true).
order("name")
active_lists = dataset.run query
The number of records returned can be specified. (See Gcloud::Datastore::Query#limit)
require "gcloud"
gcloud = Gcloud.new
dataset = gcloud.datastore
query = Gcloud::Datastore::Query.new
query.kind("List").
where("active", "=", true).
order("name").
limit(5)
active_lists = dataset.run query
Records’ Key structures can also be queried. (See Gcloud::Datastore::Query#ancestor)
require "gcloud"
gcloud = Gcloud.new
dataset = gcloud.datastore
list = dataset.find "List", "todos"
query = Gcloud::Datastore::Query.new
query.kind("Task").
ancestor(list.key)
items = dataset.run query
See Gcloud::Datastore::Query and Gcloud::Datastore::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.
require "gcloud"
gcloud = Gcloud.new
dataset = gcloud.datastore
list = dataset.find "List", "todos"
query = Gcloud::Datastore::Query.new
query.kind("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 Gcloud::Datastore::Dataset::LookupResults and Gcloud::Datastore::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.
require "gcloud"
gcloud = Gcloud.new
dataset = gcloud.datastore
entity = Gcloud::Datastore::Entity.new
entity.key = Gcloud::Datastore::Key.new "User"
entity["name"] = "Heidi Henderson"
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.
require "gcloud"
gcloud = Gcloud.new
dataset = gcloud.datastore
entity = dataset.find "User", "heidi"
# Read the status property
entity["status"] #=> "inactive"
# Write the status property
entity["status"] = "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.
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.
require "gcloud"
gcloud = Gcloud.new
dataset = gcloud.datastore
key = Gcloud::Datastore::Key.new "User", "heidi"
user = Gcloud::Datastore::Entity.new
user.key = key
user["name"] = "Heidi Henderson"
user["email"] = "[email protected]"
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.
require "gcloud"
gcloud = Gcloud.new
dataset = gcloud.datastore
key = Gcloud::Datastore::Key.new "User", "heidi"
user = Gcloud::Datastore::Entity.new
user.key = key
user["name"] = "Heidi Henderson"
user["email"] = "[email protected]"
tx = dataset.transaction
begin
if tx.find(user.key).nil?
tx.save user
end
tx.commit
rescue
tx.rollback
end
See Gcloud::Datastore::Transaction and Gcloud::Datastore::Dataset#transaction
Defined Under Namespace
Modules: Proto Classes: ApiError, Connection, Credentials, Dataset, Entity, Error, Key, KeyfileError, Properties, PropertyError, Query, Transaction, TransactionError