Class: Gcloud::Datastore::Dataset

Inherits:
Object
  • Object
show all
Defined in:
lib/gcloud/datastore/dataset.rb,
lib/gcloud/datastore/dataset/query_results.rb,
lib/gcloud/datastore/dataset/lookup_results.rb

Overview

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.

dataset = Gcloud.datastore "my-todo-project",
                           "/path/to/keyfile.json"

query = Gcloud::Datastore::Query.new.kind("Task").
  where("completed", "=", true)

tasks = dataset.run query

See Gcloud.datastore

Direct Known Subclasses

Transaction

Defined Under Namespace

Classes: LookupResults, QueryResults

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(project, credentials) ⇒ Dataset

Creates a new Dataset instance.

See Gcloud.datastore



49
50
51
 
# File 'lib/gcloud/datastore/dataset.rb', line 49

def initialize project, credentials #:nodoc:
  @connection = Connection.new project, credentials
end

Instance Attribute Details

#connection ⇒ Object

:nodoc:



43
44
45
 
# File 'lib/gcloud/datastore/dataset.rb', line 43

def connection
  @connection
end

Instance Method Details

#allocate_ids(incomplete_key, count = 1) ⇒ Object

Generate IDs for a Key before creating an entity.

dataset = Gcloud.datastore
empty_key = Gcloud::Datastore::Key.new "Task"
task_keys = dataset.allocate_ids empty_key, 5



65
66
67
68
69
70
71
72
73
74
75
 
# File 'lib/gcloud/datastore/dataset.rb', line 65

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

Remove entities from the Datastore. Accepts Entity and Key objects.

dataset = Gcloud.datastore
dataset.delete task1, task2



132
133
134
135
136
137
138
139
140
141
 
# File 'lib/gcloud/datastore/dataset.rb', line 132

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. Either a Key object or kind and id/name can be provided.

dataset = Gcloud.datastore
key = Gcloud::Datastore::Key.new "Task", 123456
task = dataset.find key

dataset = Gcloud.datastore
task = dataset.find "Task", 123456



100
101
102
103
104
 
# File 'lib/gcloud/datastore/dataset.rb', line 100

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.

dataset = Gcloud.datastore
key1 = Gcloud::Datastore::Key.new "Task", 123456
key2 = Gcloud::Datastore::Key.new "Task", 987654
tasks = dataset.find_all key1, key2

The entities returned from the lookup are returned in a Dataset::LookupResults object.



117
118
119
120
121
122
123
 
# File 'lib/gcloud/datastore/dataset.rb', line 117

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

The project connected to.



55
56
57
 
# File 'lib/gcloud/datastore/dataset.rb', line 55

def project
  connection.dataset_id
end

#run(query) ⇒ Object Also known as: run_query

Retrieve entities specified by a Query.

query = Gcloud::Datastore::Query.new.kind("Task").
  where("completed", "=", true)
tasks = dataset.run query

The entities returned from the query are returned in a Dataset::QueryResults object.



152
153
154
155
156
157
158
 
# File 'lib/gcloud/datastore/dataset.rb', line 152

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 entities to the Datastore.

dataset = Gcloud.datastore
dataset.save task1, task2



82
83
84
85
86
87
88
 
# File 'lib/gcloud/datastore/dataset.rb', line 82

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

Runs the given block in a database transaction. If no block is given the transaction object is returned.

user = Gcloud::Datastore::Entity.new
user.key = Gcloud::Datastore::Key.new "User", "username"
user["name"] = "Test"
user["email"] = "[email protected]"

dataset.transaction do |tx|
  if tx.find(user.key).nil?
    tx.save user
  end
end

Alternatively, you can manually commit or rollback by using the returned transaction object.

user = Gcloud::Datastore::Entity.new
user.key = Gcloud::Datastore::Key.new "User", "username"
user["name"] = "Test"
user["email"] = "[email protected]"

tx = dataset.transaction
begin
  if tx.find(user.key).nil?
    tx.save user
  end
  tx.commit
rescue
  tx.rollback
end



193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/gcloud/datastore/dataset.rb', line 193

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