Summary of entries of Classes for datastore.
Classes
AggregationQuery
An Aggregation query against the Cloud Datastore.
This class serves as an abstraction for creating aggregations over query in the Cloud Datastore.
AggregationResult
A class representing result from Aggregation Query
AggregationResultIterator
Represent the state of a given execution of a Query.
AvgAggregation
Representation of a "Avg" aggregation query.
BaseAggregation
Base class representing an Aggregation operation in Datastore
CountAggregation
Representation of a "Count" aggregation query.
SumAggregation
Representation of a "Sum" aggregation query.
Batch
An abstraction representing a collected group of updates / deletes.
Used to build up a bulk mutation.
For example, the following snippet of code will put the two save
operations and the delete
operation into the same mutation, and send
them to the server in a single API request:
.. testsetup:: batch
import uuid
from google.cloud import datastore
unique = str(uuid.uuid4())[0:8]
client = datastore.Client(namespace='ns{}'.format(unique))
.. doctest:: batch
>>> entity1 = datastore.Entity(client.key('EntityKind', 1234))
>>> entity2 = datastore.Entity(client.key('EntityKind', 2345))
>>> key3 = client.key('EntityKind', 3456)
>>> batch = client.batch()
>>> batch.begin()
>>> batch.put(entity1)
>>> batch.put(entity2)
>>> batch.delete(key3)
>>> batch.commit()
You can also use a batch as a context manager, in which case
commit
will be called automatically if its block exits without
raising an exception:
.. doctest:: batch
>>> with client.batch() as batch:
... batch.put(entity1)
... batch.put(entity2)
... batch.delete(key3)
By default, no updates will be sent if the block exits with an error:
.. doctest:: batch
>>> def do_some_work(batch):
... return
>>> with client.batch() as batch:
... do_some_work(batch)
... raise Exception() # rolls back
Traceback (most recent call last):
...
Exception
.. testcleanup:: txn
with client.batch() as batch:
batch.delete(client.key('EntityKind', 1234))
batch.delete(client.key('EntityKind', 2345))
Client
Convenience wrapper for invoking APIs/factories w/ a project.
.. doctest::
from google.cloud import datastore client = datastore.Client()
Entity
Entities are akin to rows in a relational database
An entity storing the actual instance of data.
Each entity is officially represented with a xref_Key, however it is possible that you might create an entity with only a partial key (that is, a key with a kind, and possibly a parent, but without an ID). In such a case, the datastore service will automatically assign an ID to the partial key.
Entities in this API act like dictionaries with extras built in that allow you to delete or persist the data stored on the entity.
Entities are mutable and act like a subclass of a dictionary. This means you could take an existing entity and change the key to duplicate the object.
Use xref_get to retrieve an existing entity:
.. testsetup:: entity-ctor
import uuid
from google.cloud import datastore
unique = str(uuid.uuid4())[0:8]
client = datastore.Client(namespace='ns{}'.format(unique))
entity = datastore.Entity(client.key('EntityKind', 1234))
entity['property'] = 'value'
client.put(entity)
.. doctest:: entity-ctor
>>> key = client.key('EntityKind', 1234)
>>> client.get(key)
<Entity('EntityKind', 1234) {'property': 'value'}>
You can the set values on the entity just like you would on any other dictionary.
.. doctest:: entity-ctor
>>> entity['age'] = 20
>>> entity['name'] = 'JJ'
.. testcleanup:: entity-ctor
client.delete(entity.key)
However, not all types are allowed as a value for a Google Cloud Datastore entity. The following basic types are supported by the API:
datetime.datetime
- xref_Key
bool
float
int
(as well aslong
in Python 2)unicode
(calledstr
in Python 3)bytes
(calledstr
in Python 2)- xref_GeoPoint
- :data:
None
In addition, three container types are supported:
list
- xref_Entity
dict
(will just be treated like anEntity
without a key orexclude_from_indexes
)
Each entry in a list must be one of the value types (basic or
container) and each value in an
xref_Entity must as well. In
this case an xref_Entity as a
container acts as a dict
, but also has the special annotations
of key
and exclude_from_indexes
.
And you can treat an entity like a regular Python dictionary:
.. testsetup:: entity-dict
from google.cloud import datastore
entity = datastore.Entity()
entity['age'] = 20
entity['name'] = 'JJ'
.. doctest:: entity-dict
>>> sorted(entity.keys())
['age', 'name']
>>> sorted(entity.items())
[('age', 20), ('name', 'JJ')]
GeoPoint
Simple container for a geo point value.
Key
An immutable representation of a datastore Key.
.. testsetup:: key-ctor
from google.cloud import datastore
project = 'my-special-pony' client = datastore.Client(project=project) Key = datastore.Key
parent_key = client.key('Parent', 'foo')
To create a basic key directly:
.. doctest:: key-ctor
Key('EntityKind', 1234, project=project) <Key('EntityKind', 1234), project=...> Key('EntityKind', 'foo', project=project) <Key('EntityKind', 'foo'), project=...>
Though typical usage comes via the xref_key factory:
.. doctest:: key-ctor
client.key('EntityKind', 1234) <Key('EntityKind', 1234), project=...> client.key('EntityKind', 'foo') <Key('EntityKind', 'foo'), project=...>
To create a key with a parent:
.. doctest:: key-ctor
client.key('Parent', 'foo', 'Child', 1234) <Key('Parent', 'foo', 'Child', 1234), project=...> client.key('Child', 1234, parent=parent_key) <Key('Parent', 'foo', 'Child', 1234), project=...>
To create a partial key:
.. doctest:: key-ctor
client.key('Parent', 'foo', 'Child') <Key('Parent', 'foo', 'Child'), project=...>
To create a key from a non-default database:
.. doctest:: key-ctor
Key('EntityKind', 1234, project=project, database='mydb') <Key('EntityKind', 1234), project=my-special-pony, database=mydb>
And
Class representation of an AND Filter.
BaseCompositeFilter
Base class for a Composite Filter. (either OR or AND).
BaseFilter
Base class for Filters
Iterator
Represent the state of a given execution of a Query.
Or
Class representation of an OR Filter.
PropertyFilter
Class representation of a Property Filter
Query
A Query against the Cloud Datastore.
This class serves as an abstraction for creating a query over data stored in the Cloud Datastore.
Transaction
An abstraction representing datastore Transactions.
Transactions can be used to build up a bulk mutation and ensure all or none succeed (transactionally).
For example, the following snippet of code will put the two save
operations (either insert
or upsert
) into the same
mutation, and execute those within a transaction:
.. testsetup:: txn
import uuid
from google.cloud import datastore
unique = str(uuid.uuid4())[0:8]
client = datastore.Client(namespace='ns{}'.format(unique))
.. doctest:: txn
>>> entity1 = datastore.Entity(client.key('EntityKind', 1234))
>>> entity2 = datastore.Entity(client.key('EntityKind', 2345))
>>> with client.transaction():
... client.put_multi([entity1, entity2])
Because it derives from xref_Batch,
Transaction
also provides put
and delete
methods:
.. doctest:: txn
with client.transaction() as xact: ... xact.put(entity1) ... xact.delete(entity2.key)
By default, the transaction is rolled back if the transaction block exits with an error:
.. doctest:: txn
>>> def do_some_work():
... return
>>> class SomeException(Exception):
... pass
>>> with client.transaction():
... do_some_work()
... raise SomeException # rolls back
Traceback (most recent call last):
...
SomeException
If the transaction block exits without an exception, it will commit by default.
Once you exit the transaction (or callcommit
), the
automatically generated ID will be assigned to the entity:
.. doctest:: txn
>>> with client.transaction():
... thing2 = datastore.Entity(key=client.key('Thing'))
... client.put(thing2)
... print(thing2.key.is_partial) # There is no ID on this key.
...
True
>>> print(thing2.key.is_partial) # There *is* an ID.
False
If you don't want to use the context manager you can initialize a transaction manually:
.. doctest:: txn
transaction = client.transaction() transaction.begin()
thing3 = datastore.Entity(key=client.key('Thing')) transaction.put(thing3)
transaction.commit()
.. testcleanup:: txn
with client.batch() as batch:
batch.delete(client.key('EntityKind', 1234))
batch.delete(client.key('EntityKind', 2345))
batch.delete(thing1.key)
batch.delete(thing2.key)
batch.delete(thing3.key)
DatastoreAdminClient
Google Cloud Datastore Admin API
The Datastore Admin API provides several admin services for Cloud Datastore.
Concepts: Project, namespace, kind, and entity as defined in the Google Cloud Datastore API.
Operation: An Operation represents work being performed in the background.
EntityFilter: Allows specifying a subset of entities in a project. This is specified as a combination of kinds and namespaces (either or both of which may be all).
Export/Import Service:
- The Export/Import service provides the ability to copy all or a subset of entities to/from Google Cloud Storage.
- Exported data may be imported into Cloud Datastore for any Google Cloud Platform project. It is not restricted to the export source project. It is possible to export from one project and then import into another.
- Exported data can also be loaded into Google BigQuery for analysis.
- Exports and imports are performed asynchronously. An Operation resource is created for each export/import. The state (including any errors encountered) of the export/import may be queried via the Operation resource.
Index Service:
- The index service manages Cloud Datastore composite indexes.
- Index creation and deletion are performed asynchronously. An Operation resource is created for each such asynchronous operation. The state of the operation (including any errors encountered) may be queried via the Operation resource.
Operation Service:
- The Operations collection provides a record of actions performed for the specified project (including any operations in progress). Operations are not created directly but through calls on other collections or resources.
- An operation that is not yet done may be cancelled. The request to cancel is asynchronous and the operation may continue to run for some time after the request to cancel is made.
- An operation that is done may be deleted so that it is no longer listed as part of the Operation collection.
- ListOperations returns all pending operations, but not completed operations.
- Operations are created by service DatastoreAdmin, but are accessed via service google.longrunning.Operations.
Modules
aggregation
API documentation for datastore.aggregation
module.
batch
Create / interact with a batch of updates / deletes.
Batches provide the ability to execute multiple operations in a single request to the Cloud Datastore API.
See https://cloud.google.com/datastore/docs/concepts/entities#batch_operations
client
Convenience wrapper for invoking APIs/factories w/ a project.
entity
Class for representing a single entity in the Cloud Datastore.
helpers
Helper functions for dealing with Cloud Datastore's Protobuf API.
The non-private functions are part of the API.
key
Create / interact with Google Cloud Datastore keys.
query
Create / interact with Google Cloud Datastore queries.
transaction
Create / interact with Google Cloud Datastore transactions.
client
API documentation for datastore_admin_v1.services.datastore_admin.client
module.