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.
- prop_name (String, Symbol) — The name of the property.
-
(Object, nil) — Returns
nil
if the property doesn't exist
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.
- prop_name (String, Symbol) — The name of the property.
- prop_value (Object) — The value of the property.
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]
.
- name (String) — the property name
- flag (Boolean, Array<Boolean>, nil) — whether the value or values should be excluded from indexing
- (value) — a block yielding each value of the property
- value (Object) — a value of the property
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]
.
- (Boolean)
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.
- (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
.
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.
- (Boolean)
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.
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.