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

Instance Method Summary collapse

Constructor Details

#initializeEntity

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

#keyObject

The Key that identifies the entity.


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

def key
  @key
end

#propertiesGcloud::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

125
126
127
# File 'lib/gcloud/datastore/entity.rb', line 125

def properties
  @properties
end

Instance Method Details

#[](prop_name) ⇒ Object?

Retrieve a property value by providing the name.

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"

69
70
71
# File 'lib/gcloud/datastore/entity.rb', line 69

def [] prop_name
  @properties[prop_name]
end

#[]=(prop_name, prop_value) ⇒ Object

Set a property value by name.

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"

95
96
97
# File 'lib/gcloud/datastore/entity.rb', line 95

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

#exclude_from_indexes!(name, flag = nil, &block) ⇒ 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

See Also:


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

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:


203
204
205
206
207
# File 'lib/gcloud/datastore/entity.rb', line 203

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

173
174
175
# File 'lib/gcloud/datastore/entity.rb', line 173

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