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

Returns:



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

def properties
  @properties
end

Class Method Details

.from_proto(proto) ⇒ Object 



277
278
279
280
281
282
283
284
285
 
# File 'lib/gcloud/datastore/entity.rb', line 277

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.

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"

Parameters:

  • prop_name (String, Symbol) —

    The name of the property.

Returns:

  • (Object, nil) —

    Returns ‘nil` if the property doesn’t exist



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"

Parameters:

  • prop_name (String, Symbol) —

    The name of the property.

  • prop_value (Object) —

    The value of the property.



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) {|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

Parameters:

  • name (String) —

    the property name

  • flag (Boolean, Array<Boolean>, nil) (defaults to: nil) —

    whether the value or values should be excluded from indexing

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:



254
255
256
257
258
259
260
261
262
 
# File 'lib/gcloud/datastore/entity.rb', line 254

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]

Returns:

  • (Boolean)

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

Returns:

  • (Boolean) 


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

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

#to_proto ⇒ Object 



266
267
268
269
270
271
272
273
 
# File 'lib/gcloud/datastore/entity.rb', line 266

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