Class: Gcloud::Datastore::Entity

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

Overview

Entity represents the 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.



36
37
38
39
40
 
# File 'lib/gcloud/datastore/entity.rb', line 36

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

Instance Attribute Details

#key ⇒ Object

The Key that identifies the entity.



32
33
34
 
# File 'lib/gcloud/datastore/entity.rb', line 32

def key
  @key
end

#properties ⇒ Object (readonly)

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

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

See Gcloud::Datastore::Properties for more.



87
88
89
 
# File 'lib/gcloud/datastore/entity.rb', line 87

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.



183
184
185
186
187
188
189
190
191
 
# File 'lib/gcloud/datastore/entity.rb', line 183

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.

puts entity["name"]

If a property doesn’t exist then nil will be returned.



48
49
50
 
# File 'lib/gcloud/datastore/entity.rb', line 48

def [] prop_name
  @properties[prop_name]
end

#[]=(prop_name, prop_value) ⇒ Object

Set a property value.

entity["name"] = "User McUser"



56
57
58
 
# File 'lib/gcloud/datastore/entity.rb', line 56

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



158
159
160
161
162
163
164
165
166
 
# File 'lib/gcloud/datastore/entity.rb', line 158

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" #=> true [false, false]

Returns:

  • (Boolean) 


126
127
128
129
130
 
# File 'lib/gcloud/datastore/entity.rb', line 126

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

#persisted? ⇒ Boolean

Returns true if the record is persisted to the datastore. Otherwise returns false.

Returns:

  • (Boolean) 


109
110
111
 
# File 'lib/gcloud/datastore/entity.rb', line 109

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.



171
172
173
174
175
176
177
178
 
# File 'lib/gcloud/datastore/entity.rb', line 171

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