Google Cloud Datastore
Google Cloud Datastore is a fully managed, schemaless database for storingnon-relational data. You should feel at home if you are familiar with relationaldatabases, but there are some key differences to be aware of to make the most ofusing Datastore.
The goal of google-cloud is to provide an API that is comfortable to Rubyists.Your authentication credentials are detected automatically in Google CloudPlatform (GCP), including Google Compute Engine (GCE), Google Kubernetes Engine(GKE), Google App Engine (GAE), Google Cloud Functions (GCF) and Cloud Run. Inother environments you can configure authentication easily, either directly inyour code or via environment variables. Read more about the options forconnecting in theAuthentication Guide.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.new(project_id:"my-todo-project",credentials:"/path/to/keyfile.json")task=datastore.find"Task","sampleTask"task["priority"]=5datastore.savetask
To learn more about Datastore, read theGoogle Cloud Datastore Concepts Overview.
Retrieving records
Records, called "entities" in Datastore, are retrieved by using a key. The keyis more than a numeric identifier, it is a complex data structure that can beused to model relationships. The simplest key has a stringkind value andeither a numericid value or a stringname value. A single record can beretrieved by callingGoogle::Cloud::Datastore::Dataset#find and passing theparts of the key:
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtask=datastore.find"Task","sampleTask"
Optionally,Google::Cloud::Datastore::Dataset#find can be given a key object:
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtask_key=datastore.key"Task",123456task=datastore.findtask_key
SeeGoogle::Cloud::Datastore::Dataset#find
Querying records
Multiple records can be found that match criteria. (SeeGoogle::Cloud::Datastore::Query#where)
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newquery=datastore.query("Task").where("done","=",false)tasks=datastore.runquery
Records can also be ordered. (SeeGoogle::Cloud::Datastore::Query#order)
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newquery=datastore.query("Task").order("created")tasks=datastore.runquery
The number of records returned can be specified. (SeeGoogle::Cloud::Datastore::Query#limit)
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newquery=datastore.query("Task").limit(5)tasks=datastore.runquery
When using Datastore in a multitenant application, a query may be run within anamespace using thenamespace option. (SeeMultitenancy)
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newquery=datastore.query("Task").where("done","=",false)tasks=datastore.runquery,namespace:"example-ns"
Records' key structures can also be queried. (SeeGoogle::Cloud::Datastore::Query#ancestor)
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtask_list_key=datastore.key"TaskList","default"query=datastore.query("Task").ancestor(task_list_key)tasks=datastore.runquery
SeeGoogle::Cloud::Datastore::Query andGoogle::Cloud::Datastore::Dataset#run
Paginating records
All records may not return at once, but multiple calls can be made to Datastoreto return them all.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newquery=datastore.query("Task")tasks=datastore.runquerytasks.alldo|t|putst["description"]end
SeeGoogle::Cloud::Datastore::Dataset::LookupResults andGoogle::Cloud::Datastore::Dataset::QueryResults
Creating records
New entities can be created and persisted buy callingGoogle::Cloud::Datastore::Dataset#save. The entity must have a key to besaved. If the key is incomplete then it will be completed when saved.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtask=datastore.entity"Task"do|t|t["type"]="Personal"t["done"]=falset["priority"]=4t["description"]="Learn Cloud Datastore"endtask.key.id#=> nildatastore.savetasktask.key.id#=> 123456
Multiple new entities may be created in a batch.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtask1=datastore.entity"Task"do|t|t["type"]="Personal"t["done"]=falset["priority"]=4t["description"]="Learn Cloud Datastore"endtask2=datastore.entity"Task"do|t|t["type"]="Personal"t["done"]=falset["priority"]=5t["description"]="Integrate Cloud Datastore"endtasks=datastore.save(task1,task2)task_key1=tasks[0].keytask_key2=tasks[1].key
Entities in Datastore form a hierarchically structured space similar to thedirectory structure of a file system. When you create an entity, you canoptionally designate another entity as its parent; the new entity is a child ofthe parent entity.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtask_key=datastore.key"Task","sampleTask"task_key.parent=datastore.key"TaskList","default"task=datastore.entitytask_keydo|t|t["type"]="Personal"t["done"]=falset["priority"]=5t["description"]="Integrate Cloud Datastore"end
Setting properties
Entities hold properties. A property has a name that is a string or symbol, anda value that is an object. Most value objects are supported, includingString,Integer,Date,Time, and even other entity or key objects. Changes to theentity's properties are persisted by callingGoogle::Cloud::Datastore::Dataset#save.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtask=datastore.find"Task","sampleTask"# Read the priority propertytask["priority"]#=> 4# Write the priority propertytask["priority"]=5# Persist the changesdatastore.savetask
Array properties can be used to store more than one value.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtask=datastore.entity"Task","sampleTask"do|t|t["tags"]=["fun","programming"]t["collaborators"]=["alice","bob"]end
Deleting records
Entities can be removed from Datastore by callingGoogle::Cloud::Datastore::Dataset#delete and passing the entity object or theentity's key object.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtask=datastore.find"Task","sampleTask"datastore.deletetask
Multiple entities may be deleted in a batch.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtask_key1=datastore.key"Task","sampleTask1"task_key2=datastore.key"Task","sampleTask2"datastore.deletetask_key1,task_key2
Transactions
Complex logic can be wrapped in a transaction. All queries and updates withintheGoogle::Cloud::Datastore::Dataset#transaction block are run within thetransaction scope, and will be automatically committed when the block completes.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtask_key=datastore.key"Task","sampleTask"datastore.transactiondo|tx|iftx.find(task_key).nil?task=datastore.entitytask_keydo|t|t["type"]="Personal"t["done"]=falset["priority"]=4t["description"]="Learn Cloud Datastore"endtx.savetaskendend
Alternatively, if no block is given the transaction object is returned allowingyou to commit or rollback manually.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtask_key=datastore.key"Task","sampleTask"tx=datastore.transactionbeginiftx.find(task_key).nil?task=datastore.entitytask_keydo|t|t["type"]="Personal"t["done"]=falset["priority"]=4t["description"]="Learn Cloud Datastore"endtx.savetaskendtx.commitrescuetx.rollbackend
A read-only transaction cannot modify entities; in return they do not contendwith other read-write or read-only transactions. Using a read-only transactionfor transactions that only read data will potentially improve throughput.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtask_list_key=datastore.key"TaskList","default"query=datastore.query("Task").ancestor(task_list_key)tasks=nildatastore.transactionread_only:truedo|tx|task_list=tx.findtask_list_keyiftask_listtasks=tx.runqueryendend
SeeGoogle::Cloud::Datastore::Transaction andGoogle::Cloud::Datastore::Dataset#transaction
Querying metadata
Datastore provides programmatic access to some of its metadata to supportmeta-programming, implementing backend administrative functions, simplifyconsistent caching, and similar purposes. The metadata available includesinformation about the entity groups, namespaces, entity kinds, and propertiesyour application uses, as well as the property representations for eachproperty.
The special entity kind__namespace__ can be used to find all the namespacesused in your application entities.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newquery=datastore.query("__namespace__").select("__key__").where("__key__",">=",datastore.key("__namespace__","g")).where("__key__","<",datastore.key("__namespace__",="""h"))=""namespaces="datastore.run(query).map"do=""|entity|=""entity.key.name=""end="">
The special entity kind__kind__ can be used to return all the kinds used inyour application.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newquery=datastore.query("__kind__").select("__key__")kinds=datastore.run(query).mapdo|entity|entity.key.nameend
Property queries return entities of kind__property__ denoting the indexedproperties associated with an entity kind. (Unindexed properties are notincluded.)
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newquery=datastore.query("__property__").select("__key__")entities=datastore.run(query)properties_by_kind=entities.each_with_object({})do|entity,memo|kind=entity.key.parent.nameprop=entity.key.namememo[kind]||=[]memo[kind] <prop=""end="">
Property queries support ancestor filtering on a__kind__ or__property__key, to limit the query results to a single kind or property. Theproperty_representation property in the entity representing propertyp ofkindk is an array containing all representations ofp's value in any entityof kindk.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newancestor_key=datastore.key"__kind__","Task"query=datastore.query("__property__").ancestor(ancestor_key)entities=datastore.run(query)representations=entities.each_with_object({})do|entity,memo|property_name=entity.key.nameproperty_types=entity["property_representation"]memo[property_name]=property_typesend
Property queries can also be filtered with a range over the pseudo-property__key__, where the keys denote either__kind__ or__property__ entities.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newstart_key=datastore.key"__property__","priority"start_key.parent=datastore.key"__kind__","Task"query=datastore.query("__property__").select("__key__").where("__key__",">=",start_key)entities=datastore.run(query)properties_by_kind=entities.each_with_object({})do|entity,memo|kind=entity.key.parent.nameprop=entity.key.namememo[kind]||=[]memo[kind] <prop=""end="">
Configuring timeout
You can configure the requesttimeout value in seconds.
require"google/cloud/datastore"datastore=Google::Cloud::Datastore.newtimeout:120
Additional information
Google Cloud Datastore can be configured to use an emulator or to enable gRPC'slogging. To learn more, see theEmulator guide andLogging guide.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-11-04 UTC.