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.

Examples:

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

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Entity

Create a new Entity object.



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

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

Instance Attribute Details

#key ⇒ Object

The Key that identifies the entity.



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

def key
  @key
end

#properties ⇒ Gcloud::Datastore::Properties (readonly)

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

Examples:

entity.properties[:name] = "Heidi H. Henderson"
entity.properties["name"] #=> "Heidi H. Henderson"

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

A property’s existence 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



151
152
153
 
# File 'lib/gcloud/datastore/entity.rb', line 151

def properties
  @properties
end

Class Method Details

.from_proto(proto) ⇒ Object 



303
304
305
306
307
308
309
310
311
 
# File 'lib/gcloud/datastore/entity.rb', line 303

def self.from_proto proto
  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.

Property values are converted from the Datastore value type automatically. Blob properties are returned as StringIO objects.

Examples:

Properties can be retrieved with a string name:

require "gcloud"

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

Or with a symbol name:

require "gcloud"

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

Getting a blob value returns a StringIO object:

require "gcloud"

gcloud = Gcloud.new
dataset = gcloud.datastore
user = dataset.find "User", "[email protected]"
user["avatar"] #=> StringIO("\x89PNG\r\n\x1A...")



80
81
82
 
# File 'lib/gcloud/datastore/entity.rb', line 80

def [] prop_name
  @properties[prop_name]
end

#[]=(prop_name, prop_value) ⇒ Object

Set a property value by name.

Property values are converted to use the proper Datastore value type automatically. Use an IO-compatible object (File, StringIO, Tempfile) to indicate the property value should be stored as a Datastore ‘blob`. IO-compatible objects are converted to StringIO objects when they are set.

Examples:

Properties can be set with a string name:

require "gcloud"

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

Or with a symbol name:

require "gcloud"

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

Setting a blob value using an IO:

require "gcloud"

gcloud = Gcloud.new
dataset = gcloud.datastore
user = dataset.find "User", "[email protected]"
user["avatar"] = File.open "/avatars/heidi.png"
user["avatar"] #=> StringIO("\x89PNG\r\n\x1A...")



121
122
123
 
# File 'lib/gcloud/datastore/entity.rb', line 121

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

#exclude_from_indexes!(name, flag = nil) {|value| ... } ⇒ Object

Sets whether a property should 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 is `false`. This is another way of saying that values are indexed by default.

If the property is multi-valued, each value in the list can be managed separately for exclusion from indexing. When you call this method for a multi-valued property, you can pass either a single boolean argument to be applied to all of the values, or an array that contains the boolean argument for each corresponding value in the property. For example, if a multi-valued property contains ‘[“a”, “b”]`, and only the value `“b”` should be indexed (meaning that `“a”`’ should be excluded), you should pass the array: ‘[true, false]`.

Examples:

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

Multi-valued properties can be given multiple exclude flags:

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

Or, a single flag can be applied to all values in a property:

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

Flags can also be set with a block:

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

Yields:

  • (value) —

    a block yielding each value of the property

Yield Parameters:

  • value (Object) —

    a value of the property

Yield Returns:

  • (Boolean) —

    ‘true` if the value should be excluded from indexing

See Also:



280
281
282
283
284
285
286
287
288
 
# File 'lib/gcloud/datastore/entity.rb', line 280

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`. This is another way of saying that values are indexed by default.

If the property is multi-valued, each value in the list can be managed separately for exclusion from indexing. Calling this method for a multi-valued property will return an array that contains the ‘excluded` boolean value for each corresponding value in the property. For example, if a multi-valued property contains `[“a”, “b”]`, and only the value `“b”` is indexed (meaning that `“a”`’ is excluded), the return value for this method will be ‘[true, false]`.

Examples:

Single property values will return a single flag setting:

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

A multi-valued property will return an array of flag settings:

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

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

See Also:



229
230
231
232
233
 
# File 'lib/gcloud/datastore/entity.rb', line 229

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.

Examples:

require "gcloud"

gcloud = Gcloud.new
dataset = gcloud.datastore

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

found_entity = dataset.find "User", "[email protected]"
found_entity.persisted? #=> true



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

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

#to_proto ⇒ Object 



292
293
294
295
296
297
298
299
 
# File 'lib/gcloud/datastore/entity.rb', line 292

def to_proto
  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