Class: Gcloud::Datastore::Entity

Inherits:
Object
  • Object
show all
Defined in:
lib/gcloud/datastore/entity.rb

Overview

Entity

Entity represents a Datastore record. Every Entity has a Key, and a list of properties.

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Entity

Create a new Entity object.



39
40
41
42
43
 
# File 'lib/gcloud/datastore/entity.rb', line 39

def initialize
  @properties = Properties.new
  @key = Key.new
  @_exclude_indexes = {}
end

Instance Attribute Details

#key ⇒ Object

The Key that identifies the entity.



35
36
37
 
# File 'lib/gcloud/datastore/entity.rb', line 35

def key
  @key
end

#properties ⇒ Object (readonly)

Retrieve properties in a hash-like structure. Properties can be accessed or set by string or symbol.

Returns

Gcloud::Datastore::Properties

Example

entity.properties[:name] = "User McUser"
entity.properties["name"] #=> "User McUser"

entity.properties.each do |name, value|
  puts "property #{name} has a value of #{value}"
end

A property’s existance can be determined by calling exist?

entity.properties.exist? :name #=> true
entity.properties.exist? "name" #=> true
entity.properties.exist? :expiration #=> false

A property can be removed from the entity.

entity.properties.delete :name
entity.save

The properties can be converted to a hash:

prop_hash = entity.properties.to_h



147
148
149
 
# File 'lib/gcloud/datastore/entity.rb', line 147

def properties
  @properties
end

Class Method Details

.from_proto(proto) ⇒ Object

Create a new Entity from a protocol buffer object. This is not part of the public API.



272
273
274
275
276
277
278
279
280
 
# File 'lib/gcloud/datastore/entity.rb', line 272

def self.from_proto proto #:nodoc:
  entity = Entity.new
  entity.key = Key.from_proto proto.key
  Array(proto.property).each do |p|
    entity[p.name] = Proto.from_proto_value p.value
  end
  entity.send :update_exclude_indexes!, proto
  entity
end

Instance Method Details

#[](prop_name) ⇒ Object

Retrieve a property value by providing the name.

Parameters

prop_name

The name of the property. (String or Symbol)

Returns

Object if the property exists, nil if the property doesn’t exist

Example

Properties can be retrieved with a string name:

require "gcloud"

gcloud = Gcloud.new
dataset = gcloud.datastore
user = dataset.find "User", "heidi"
user["name"] #=> "Heidi Henderson"

Or with a symbol name:

require "gcloud"

gcloud = Gcloud.new
dataset = gcloud.datastore
user = dataset.find "User", "heidi"
user[:name] #=> "Heidi Henderson"



77
78
79
 
# File 'lib/gcloud/datastore/entity.rb', line 77

def [] prop_name
  @properties[prop_name]
end

#[]=(prop_name, prop_value) ⇒ Object

Set a property value by name.

Parameters

prop_name

The name of the property. (String or Symbol)

prop_value

The value of the property. (Object)

Example

Properties can be set with a string name:

require "gcloud"

gcloud = Gcloud.new
dataset = gcloud.datastore
user = dataset.find "User", "heidi"
user["name"] = "Heidi H. Henderson"

Or with a symbol name:

require "gcloud"

gcloud = Gcloud.new
dataset = gcloud.datastore
user = dataset.find "User", "heidi"
user[:name] = "Heidi H. Henderson"



111
112
113
 
# File 'lib/gcloud/datastore/entity.rb', line 111

def []= prop_name, prop_value
  @properties[prop_name] = prop_value
end

#exclude_from_indexes!(name, flag = nil, &block) ⇒ Object

Flag a property to be excluded from the Datastore indexes. Setting true will exclude the property from the indexes. Setting false will include the property on any applicable indexes. The default value for the flag is false.

entity["age"] = 21
entity.exclude_from_indexes! "age", true

Properties that are arrays can be given multiple exclude flags.

entity["tags"] = ["ruby", "code"]
entity.exclude_from_indexes! "tags", [true, false]

Or, array properties can be given a single flag that will be applied to each item in the array.

entity["tags"] = ["ruby", "code"]
entity.exclude_from_indexes! "tags", true

Flags can also be set with a block for either single and array values.

entity["age"] = 21
entity.exclude_from_indexes! "age" do |age|
  age > 18
end



247
248
249
250
251
252
253
254
255
 
# File 'lib/gcloud/datastore/entity.rb', line 247

def exclude_from_indexes! name, flag = nil, &block
  name = name.to_s
  flag = block if block_given?
  if flag.nil?
    @_exclude_indexes.delete name
  else
    @_exclude_indexes[name] = flag
  end
end

#exclude_from_indexes?(name) ⇒ Boolean

Indicates if a property is flagged to be excluded from the Datastore indexes. The default value is false.

Single property values will return a single flag setting.

entity["age"] = 21
entity.exclude_from_indexes? "age" #=> false

Array property values will return an array of flag settings.

entity["tags"] = ["ruby", "code"]
entity.exclude_from_indexes? "tags" #=> [false, false]

Returns:

  • (Boolean) 


215
216
217
218
219
 
# File 'lib/gcloud/datastore/entity.rb', line 215

def exclude_from_indexes? name
  value = self[name]
  flag = @_exclude_indexes[name.to_s]
  map_exclude_flag_to_value flag, value
end

#persisted? ⇒ Boolean

Indicates if the record is persisted. Default is false.

Example

require "gcloud"

gcloud = Gcloud.new
dataset = gcloud.datastore

new_entity = Gcloud::Datastore::Entity.new
new_entity.persisted? #=> false

found_entity = dataset.find "User", "heidi"
found_entity.persisted? #=> true

Returns:

  • (Boolean) 


198
199
200
 
# File 'lib/gcloud/datastore/entity.rb', line 198

def persisted?
  @key && @key.frozen?
end

#to_proto ⇒ Object

Convert the Entity to a protocol buffer object. This is not part of the public API.



260
261
262
263
264
265
266
267
 
# File 'lib/gcloud/datastore/entity.rb', line 260

def to_proto #:nodoc:
  entity = Proto::Entity.new.tap do |e|
    e.key = @key.to_proto
    e.property = Proto.to_proto_properties @properties.to_h
  end
  update_properties_indexed! entity
  entity
end