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

Returns:



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

def properties
  @properties
end

Class Method Details

.from_grpc(grpc) ⇒ Object

object.



374
375
376
377
378
379
380
 
# File 'lib/gcloud/datastore/entity.rb', line 374

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...")

Parameters:

  • prop_name (String, Symbol) —

    The name of the property.

Returns:

  • (Object, nil) —

    Returns ‘nil` if the property doesn’t exist



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...")

Parameters:

  • prop_name (String, Symbol) —

    The name of the property.

  • prop_value (Object) —

    The value of the property.



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

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:



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]

Returns:

  • (Boolean)

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

Returns:

  • (Boolean) 


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

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

#serialized_size ⇒ Object

The number of bytes the Entity will take to serialize during API calls.



355
356
357
 
# File 'lib/gcloud/datastore/entity.rb', line 355

def serialized_size
  to_grpc.to_proto.length
end

#to_grpc ⇒ Object

object.



362
363
364
365
366
367
368
369
 
# File 'lib/gcloud/datastore/entity.rb', line 362

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