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.

Entities in Datastore form a hierarchically structured space similar to the directory structure of a file system. When you create an entity, you can optionally designate another entity as its parent; the new entity is a child of the parent entity.

Examples:

Create a new entity using a block:

task = datastore.entity "Task", "sampleTask" do |t|
  t["type"] = "Personal"
  t["created"] = Time.now
  t["done"] = false
  t["priority"] = 4
  t["percent_complete"] = 10.0
  t["description"] = "Learn Cloud Datastore"
end

Create a new entity belonging to an existing parent entity:

task_key = datastore.key "Task", "sampleTask"
task_key.parent = datastore.key "TaskList", "default"

task = Gcloud::Datastore::Entity.new
task.key = task_key

task["type"] = "Personal"
task["done"] = false
task["priority"] = 4
task["description"] = "Learn Cloud Datastore"

See Also:

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize ⇒ Entity

Create a new Entity object.



64
65
66
67
68
 
# File 'lib/gcloud/datastore/entity.rb', line 64

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

Instance Attribute Details

#key ⇒ Object

The Key that identifies the entity.



60
61
62
 
# File 'lib/gcloud/datastore/entity.rb', line 60

def key
  @key
end

#properties ⇒ Gcloud::Datastore::Properties

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

Examples:

task.properties[:description] = "Learn Cloud Datastore"
task.properties["description"] #=> "Learn Cloud Datastore"

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

A property’s existence can be determined by calling exist?:

task.properties.exist? :description #=> true
task.properties.exist? "description" #=> true
task.properties.exist? :expiration #=> false

A property can be removed from the entity:

task.properties.delete :description
task.save

The properties can be converted to a hash:

prop_hash = task.properties.to_h



214
215
216
 
# File 'lib/gcloud/datastore/entity.rb', line 214

def properties
  @properties
end

Class Method Details

.from_grpc(grpc) ⇒ Object

object.



368
369
370
371
372
373
374
 
# File 'lib/gcloud/datastore/entity.rb', line 368

def self.from_grpc grpc
  entity = Entity.new
  entity.key = Key.from_grpc grpc.key
  entity.send :properties=, Properties.from_grpc(grpc.properties)
  entity.send :update_exclude_indexes!, grpc.properties
  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. Location properties are returned as a Hash with :longitude and :latitude keys.

Examples:

Properties can be retrieved with a string name:

require "gcloud"

gcloud = Gcloud.new
datastore = gcloud.datastore
task = datastore.find "Task", "sampleTask"
task["description"] #=> "Learn Cloud Datastore"

Or with a symbol name:

require "gcloud"

gcloud = Gcloud.new
datastore = gcloud.datastore
task = datastore.find "Task", "sampleTask"
task[:description] #=> "Learn Cloud Datastore"

Getting a blob value returns a StringIO object:

require "gcloud"

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

Getting a geo point value returns a Hash:

require "gcloud"

gcloud = Gcloud.new
datastore = gcloud.datastore
user = datastore.find "User", "alice"
user["location"] #=> { longitude: -122.0862462,
                 #     latitude: 37.4220041 }

Getting a blob value returns a StringIO object:

require "gcloud"

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



123
124
125
 
# File 'lib/gcloud/datastore/entity.rb', line 123

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. Use a Hash with :longitude and :latitude keys to indicate the property value should be stored as a Geo Point/LatLng.

Examples:

Properties can be set with a string name:

require "gcloud"

gcloud = Gcloud.new
datastore = gcloud.datastore
task = datastore.find "Task", "sampleTask"
task["description"] = "Learn Cloud Datastore"
task["tags"] = ["fun", "programming"]

Or with a symbol name:

require "gcloud"

gcloud = Gcloud.new
datastore = gcloud.datastore
task = datastore.find "Task", "sampleTask"
task[:description] = "Learn Cloud Datastore"
task[:tags] = ["fun", "programming"]

Setting a blob value using an IO:

require "gcloud"

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

Setting a geo point value using a Hash:

require "gcloud"

gcloud = Gcloud.new
datastore = gcloud.datastore
user = datastore.find "User", "alice"
user["location"] = { longitude: -122.0862462, latitude: 37.4220041 }

Setting a blob value using an IO:

require "gcloud"

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



184
185
186
 
# File 'lib/gcloud/datastore/entity.rb', line 184

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["priority"] = 4
entity.exclude_from_indexes! "priority", true

Multi-valued properties can be given multiple exclude flags:

entity["tags"] = ["fun", "programming"]
entity.exclude_from_indexes! "tags", [true, false]

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

entity["tags"] = ["fun", "programming"]
entity.exclude_from_indexes! "tags", true

Flags can also be set with a block:

entity["priority"] = 4
entity.exclude_from_indexes! "priority" do |priority|
  priority > 4
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:



343
344
345
346
347
348
349
350
351
 
# File 'lib/gcloud/datastore/entity.rb', line 343

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:

task["priority"] = 4
task.exclude_from_indexes? "priority" #=> false

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

task["tags"] = ["fun", "programming"]
task.exclude_from_indexes! "tags", [true, false]

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

See Also:



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

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
datastore = gcloud.datastore

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

task = datastore.find "Task", "sampleTask"
task.persisted? #=> true



262
263
264
 
# File 'lib/gcloud/datastore/entity.rb', line 262

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

#to_grpc ⇒ Object

object.



356
357
358
359
360
361
362
363
 
# File 'lib/gcloud/datastore/entity.rb', line 356

def to_grpc
  grpc = Google::Datastore::V1beta3::Entity.new(
    key: @key.to_grpc,
    properties: @properties.to_grpc
  )
  update_properties_indexed! grpc.properties
  grpc
end