Class: Gcloud::Datastore::Dataset
- Inherits:
-
Object
- Object
- Gcloud::Datastore::Dataset
- Defined in:
- lib/gcloud/datastore/dataset.rb,
lib/gcloud/datastore/dataset/query_results.rb,
lib/gcloud/datastore/dataset/lookup_results.rb
Overview
Dataset
Dataset is the data saved in a project’s Datastore. Dataset is analogous to a database in relational database world.
Gcloud::Datastore::Dataset is the main object for interacting with Google Datastore. Gcloud::Datastore::Entity objects are created, read, updated, and deleted by Gcloud::Datastore::Dataset.
require "gcloud"
gcloud = Gcloud.new
dataset = gcloud.datastore
query = Gcloud::Datastore::Query.new.kind("Task").
where("completed", "=", true)
tasks = dataset.run query
See Gcloud#datastore
Direct Known Subclasses
Defined Under Namespace
Classes: LookupResults, QueryResults
Instance Attribute Summary collapse
-
#connection ⇒ Object
:nodoc:.
Class Method Summary collapse
-
.default_project ⇒ Object
Default project.
Instance Method Summary collapse
-
#allocate_ids(incomplete_key, count = 1) ⇒ Object
Generate IDs for a Key before creating an entity.
-
#delete(*entities_or_keys) ⇒ Object
Remove entities from the Datastore.
-
#find(key_or_kind, id_or_name = nil) ⇒ Object
(also: #get)
Retrieve an entity by providing key information.
-
#find_all(*keys) ⇒ Object
(also: #lookup)
Retrieve the entities for the provided keys.
-
#initialize(project, credentials) ⇒ Dataset
constructor
Creates a new Dataset instance.
-
#project ⇒ Object
The Datastore project connected to.
-
#run(query) ⇒ Object
(also: #run_query)
Retrieve entities specified by a Query.
-
#save(*entities) ⇒ Object
Persist one or more entities to the Datastore.
-
#transaction ⇒ Object
Creates a Datastore Transaction.
Constructor Details
#initialize(project, credentials) ⇒ Dataset
Creates a new Dataset instance.
See Gcloud#datastore
54 55 56 57 58 |
# File 'lib/gcloud/datastore/dataset.rb', line 54 def initialize project, credentials #:nodoc: project = project.to_s # Always cast to a string fail ArgumentError, "project is missing" if project.empty? @connection = Connection.new project, credentials end |
Instance Attribute Details
#connection ⇒ Object
:nodoc:
48 49 50 |
# File 'lib/gcloud/datastore/dataset.rb', line 48 def connection @connection end |
Class Method Details
.default_project ⇒ Object
Default project.
79 80 81 82 83 |
# File 'lib/gcloud/datastore/dataset.rb', line 79 def self.default_project #:nodoc: ENV["DATASTORE_PROJECT"] || ENV["GCLOUD_PROJECT"] || ENV["GOOGLE_CLOUD_PROJECT"] end |
Instance Method Details
#allocate_ids(incomplete_key, count = 1) ⇒ Object
Generate IDs for a Key before creating an entity.
Parameters
incomplete_key
-
A Key without
id
orname
set. (Key
) count
-
The number of new key IDs to create. (
Integer
)
Returns
Array of Gcloud::Datastore::Key
Example
empty_key = Gcloud::Datastore::Key.new "Task"
task_keys = dataset.allocate_ids empty_key, 5
104 105 106 107 108 109 110 111 112 113 114 |
# File 'lib/gcloud/datastore/dataset.rb', line 104 def allocate_ids incomplete_key, count = 1 if incomplete_key.complete? fail Gcloud::Datastore::Error, "An incomplete key must be provided." end incomplete_keys = count.times.map { incomplete_key.to_proto } response = connection.allocate_ids(*incomplete_keys) Array(response.key).map do |key| Key.from_proto key end end |
#delete(*entities_or_keys) ⇒ Object
221 222 223 224 225 226 227 228 229 230 |
# File 'lib/gcloud/datastore/dataset.rb', line 221 def delete *entities_or_keys keys = entities_or_keys.map do |e_or_k| e_or_k.respond_to?(:key) ? e_or_k.key.to_proto : e_or_k.to_proto end mutation = Proto.new_mutation.tap do |m| m.delete = keys end connection.commit mutation true end |
#find(key_or_kind, id_or_name = nil) ⇒ Object Also known as: get
Retrieve an entity by providing key information.
Parameters
key_or_kind
-
A Key object or
kind
string value. (Key
orString
) id_or_name
-
The Key’s
id
orname
value if akind
was provided in the first parameter. (Integer
orString
ornil
)
Returns
Gcloud::Datastore::Entity or nil
Example
Finding an entity with a key:
key = Gcloud::Datastore::Key.new "Task", 123456
task = dataset.find key
Finding an entity with a kind
and id
/name
:
task = dataset.find "Task", 123456
167 168 169 170 171 |
# File 'lib/gcloud/datastore/dataset.rb', line 167 def find key_or_kind, id_or_name = nil key = key_or_kind key = Key.new key_or_kind, id_or_name unless key_or_kind.is_a? Key find_all(key).first end |
#find_all(*keys) ⇒ Object Also known as: lookup
Retrieve the entities for the provided keys.
Parameters
keys
-
One or more Key objects to find records for. (
Key
)
Returns
Gcloud::Datastore::Dataset::LookupResults
Example
gcloud = Gcloud.new
dataset = gcloud.datastore
key1 = Gcloud::Datastore::Key.new "Task", 123456
key2 = Gcloud::Datastore::Key.new "Task", 987654
tasks = dataset.find_all key1, key2
194 195 196 197 198 199 200 |
# File 'lib/gcloud/datastore/dataset.rb', line 194 def find_all *keys response = connection.lookup(*keys.map(&:to_proto)) entities = to_gcloud_entities response.found deferred = to_gcloud_keys response.deferred missing = to_gcloud_entities response.missing LookupResults.new entities, deferred, missing end |
#project ⇒ Object
73 74 75 |
# File 'lib/gcloud/datastore/dataset.rb', line 73 def project connection.dataset_id end |
#run(query) ⇒ Object Also known as: run_query
250 251 252 253 254 255 256 |
# File 'lib/gcloud/datastore/dataset.rb', line 250 def run query response = connection.run_query query.to_proto entities = to_gcloud_entities response.batch.entity_result cursor = Proto.encode_cursor response.batch.end_cursor more_results = Proto.to_more_results_string response.batch.more_results QueryResults.new entities, cursor, more_results end |
#save(*entities) ⇒ Object
Persist one or more entities to the Datastore.
Parameters
entities
-
One or more entity objects to be saved without
id
orname
set. (Entity
)
Returns
Array of Gcloud::Datastore::Entity
Example
dataset.save task1, task2
133 134 135 136 137 138 139 |
# File 'lib/gcloud/datastore/dataset.rb', line 133 def save *entities mutation = Proto.new_mutation save_entities_to_mutation entities, mutation response = connection.commit mutation auto_id_assign_ids response.mutation_result.insert_auto_id_key entities end |
#transaction ⇒ Object
Creates a Datastore Transaction.
Example
Runs the given block in a database transaction:
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 a Transaction object is returned:
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
308 309 310 311 312 313 314 315 316 317 318 319 |
# File 'lib/gcloud/datastore/dataset.rb', line 308 def transaction tx = Transaction.new connection return tx unless block_given? begin yield tx tx.commit rescue => e tx.rollback raise TransactionError.new("Transaction failed to commit.", e) end end |