Firestore in Datastore mode API - Class Google::Cloud::Datastore::Entity (v2.9.0)

Reference documentation and code samples for the Firestore in Datastore mode API class Google::Cloud::Datastore::Entity.

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.

Inherits

Object

Examples

Create a new entity using a block:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

task = Google::Cloud::Datastore::Entity.new
task.key = task_key

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

Methods

#[]

def [](prop_name) -> Object, nil

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.

Parameter

prop_name (String, Symbol) — The name of the property.

Returns

(Object, nil) — Returns nil if the property doesn't exist

Examples

Properties can be retrieved with a string name:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

Or with a symbol name:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

Getting a blob value returns a StringIO object:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

user = datastore.find "User", "alice"
user["avatar"].class #=> StringIO

Getting a geo point value returns a Hash:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

user = datastore.find "User", "alice"
user["location"].keys #=> [:latitude, :longitude]

Getting a blob value returns a StringIO object:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

user = datastore.find "User", "alice"
user["avatar"].class #=> StringIO

#[]=

def []=(prop_name, prop_value)

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.

Parameters

prop_name (String, Symbol) — The name of the property.
prop_value (Object) — The value of the property.

Examples

Properties can be set with a string name:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

Or with a symbol name:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

Setting a blob value using an IO:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

user = datastore.find "User", "alice"
user["avatar"] = File.open "/avatars/alice.png"
user["avatar"].class #=> StringIO

Setting a geo point value using a Hash:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

Setting a blob value using an IO:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

user = datastore.find "User", "alice"
user["avatar"] = File.open "/avatars/alice.png"
user["avatar"].class #=> StringIO

#exclude_from_indexes!

def exclude_from_indexes!(name, flag = nil, &block) { |value| ... }

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].

Parameters

name (String) — the property name
flag (Boolean, Array<Boolean>, nil) — whether the value or values should be excluded from indexing

Yields

(value) — a block yielding each value of the property

Yield Parameter

value (Object) — a value of the property

Examples

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

entity = datastore.find "Task", "sampleTask"

entity["priority"] = 4
entity.exclude_from_indexes! "priority", true

Multi-valued properties can be given multiple exclude flags:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

entity = datastore.find "Task", "sampleTask"

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

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

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

entity = datastore.find "Task", "sampleTask"

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

Flags can also be set with a block:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

entity = datastore.find "Task", "sampleTask"

entity["priority"] = 4
entity.exclude_from_indexes! "priority" do |priority|
  priority > 4
end

#exclude_from_indexes?

def 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].

Returns

(Boolean)

Examples

Single property values will return a single flag setting:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.find "Task", "sampleTask"

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

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

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.find "Task", "sampleTask"

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

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

#initialize

def initialize() -> Entity

Create a new Entity object.

Returns

(Entity) — a new instance of Entity

#key

def key()

The Key that identifies the entity.

#key=

def key=(new_key)

Sets the Key that identifies the entity.

Once the entity is saved, the key is frozen and immutable. Trying to set a key when immutable will raise a RuntimeError.

Examples

The key can be set before the entity is saved:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = Google::Cloud::Datastore::Entity.new
task.key = datastore.key "Task"
datastore.save task

Once the entity is saved, the key is frozen and immutable:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.find "Task", "sampleTask"
task.persisted? #=> true
# Because the entity is persisted, the following would raise
# task.key = datastore.key "Task"
task.key.frozen? #=> true
# Because the key is frozen, the following would raise
# task.key.id = 9876543221

#persisted?

def persisted?() -> Boolean

Indicates if the record is persisted. Default is false.

Returns

(Boolean)

Example

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

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

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

#properties

def properties() -> Google::Cloud::Datastore::Properties

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

Returns

(Google::Cloud::Datastore::Properties)

Examples

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.find "Task", "sampleTask"

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?:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.find "Task", "sampleTask"

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

A property can be removed from the entity:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.find "Task", "sampleTask"

task.properties.delete :description
datastore.update task

The properties can be converted to a hash:

require "google/cloud/datastore"

datastore = Google::Cloud::Datastore.new

task = datastore.find "Task", "sampleTask"

prop_hash = task.properties.to_h

#serialized_size

def serialized_size()

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