Datastore Client#

Convenience wrapper for invoking APIs/factories w/ a project.

class gcloud.datastore.client.Client(project=None, namespace=None, credentials=None, http=None)[source]#

Bases: gcloud.client.Client, gcloud.client._ClientProjectMixin

Convenience wrapper for invoking APIs/factories w/ a project.

Parameters:

Parameters:	project (string) – (optional) The project to pass to proxied API methods. namespace (string) – (optional) namespace to pass to proxied API methods. credentials (`oauth2client.client.OAuth2Credentials` or `NoneType`) – The OAuth2 Credentials to use for the connection owned by this client. If not passed (and if no `http` object is passed), falls back to the default inferred from the environment. http (`httplib2.Http` or class that defines `request()`.) – An optional HTTP object to make requests. If not passed, an `http` object is created that is bound to the `credentials` for the current object.

project (string) – (optional) The project to pass to proxied API methods.
namespace (string) – (optional) namespace to pass to proxied API methods.
credentials (oauth2client.client.OAuth2Credentials or NoneType) – The OAuth2 Credentials to use for the connection owned by this client. If not passed (and if no http object is passed), falls back to the default inferred from the environment.
http (httplib2.Http or class that defines request().) – An optional HTTP object to make requests. If not passed, an http object is created that is bound to the credentials for the current object.

allocate_ids(incomplete_key, num_ids)[source]#

Allocate a list of IDs from a partial key.

Parameters:	incomplete_key (`gcloud.datastore.key.Key`) – Partial key to use as base for allocated IDs. num_ids (int) – The number of IDs to allocate.
Return type:	list of `gcloud.datastore.key.Key`
Returns:	The (complete) keys allocated with `incomplete_key` as root.
Raises:	`ValueError` if `incomplete_key` is not a partial key.

batch()[source]#: Proxy to gcloud.datastore.batch.Batch.

current_batch#

Currently-active batch.

Return type:	`gcloud.datastore.batch.Batch`, or an object implementing its API, or `NoneType` (if no batch is active).
Returns:	The batch/transaction at the top of the batch stack.

current_transaction#

Currently-active transaction.

Return type:	`gcloud.datastore.transaction.Transaction`, or an object implementing its API, or `NoneType` (if no transaction is active).
Returns:	The transaction at the top of the batch stack.

delete(key)[source]#

Delete the key in the Cloud Datastore.

Note

This is just a thin wrapper over delete_multi(). The backend API does not make a distinction between a single key or multiple keys in a commit request.

Parameters:	key (`gcloud.datastore.key.Key`) – The key to be deleted from the datastore.

delete_multi(keys)[source]#

Delete keys from the Cloud Datastore.

Parameters:	keys (list of `gcloud.datastore.key.Key`) – The keys to be deleted from the datastore.

get(key, missing=None, deferred=None, transaction=None)[source]#

Retrieve an entity from a single key (if it exists).

Note

This is just a thin wrapper over get_multi(). The backend API does not make a distinction between a single key or multiple keys in a lookup request.

Parameters:	key (`gcloud.datastore.key.Key`) – The key to be retrieved from the datastore. missing (list) – (Optional) If a list is passed, the key-only entities returned by the backend as “missing” will be copied into it. deferred (list) – (Optional) If a list is passed, the keys returned by the backend as “deferred” will be copied into it. transaction (`gcloud.datastore.transaction.Transaction`) – (Optional) Transaction to use for read consistency. If not passed, uses current transaction, if set.
Return type:	`gcloud.datastore.entity.Entity` or `NoneType`
Returns:	The requested entity if it exists.

get_multi(keys, missing=None, deferred=None, transaction=None)[source]#

Retrieve entities, along with their attributes.

Parameters:	keys (list of `gcloud.datastore.key.Key`) – The keys to be retrieved from the datastore. missing (list) – (Optional) If a list is passed, the key-only entities returned by the backend as “missing” will be copied into it. If the list is not empty, an error will occur. deferred (list) – (Optional) If a list is passed, the keys returned by the backend as “deferred” will be copied into it. If the list is not empty, an error will occur. transaction (`gcloud.datastore.transaction.Transaction`) – (Optional) Transaction to use for read consistency. If not passed, uses current transaction, if set.
Return type:	list of `gcloud.datastore.entity.Entity`
Returns:	The requested entities.
Raises:	`ValueError` if one or more of `keys` has a project which does not match our project.

key(*path_args, **kwargs)[source]#

Proxy to gcloud.datastore.key.Key.

Passes our project.

put(entity)[source]#

Save an entity in the Cloud Datastore.

Note

This is just a thin wrapper over put_multi(). The backend API does not make a distinction between a single entity or multiple entities in a commit request.

Parameters:	entity (`gcloud.datastore.entity.Entity`) – The entity to be saved to the datastore.

put_multi(entities)[source]#

Save entities in the Cloud Datastore.

Parameters:	entities (list of `gcloud.datastore.entity.Entity`) – The entities to be saved to the datastore.
Raises:	`ValueError` if `entities` is a single entity.

query(**kwargs)[source]#

Proxy to gcloud.datastore.query.Query.

Passes our project.

transaction()[source]#: Proxy to gcloud.datastore.transaction.Transaction.

Connection#

Connections to gcloud datastore API servers.

class gcloud.datastore.connection.Connection(credentials=None, http=None, api_base_url=None)[source]#

Bases: gcloud.connection.Connection

A connection to the Google Cloud Datastore via the Protobuf API.

This class should understand only the basic types (and protobufs) in method arguments, however should be capable of returning advanced types.

Parameters:	credentials (`oauth2client.client.OAuth2Credentials`) – The OAuth2 Credentials to use for this connection. http (`httplib2.Http` or class that defines `request()`.) – An optional HTTP object to make requests. api_base_url (string) – The base of the API call URL. Defaults to `API_BASE_URL`.

API_BASE_URL = 'https://datastore.googleapis.com'#: The base of the API call URL.

API_URL_TEMPLATE = '{api_base}/{api_version}/projects/{project}:{method}'#: A template for the URL of a particular API call.

API_VERSION = 'v1beta3'#: The version of the API, used in building the API call’s URL.

SCOPE = ('https://www.googleapis.com/auth/datastore',)#: The scopes required for authenticating as a Cloud Datastore consumer.

allocate_ids(project, key_pbs)[source]#

Obtain backend-generated IDs for a set of keys.

Maps the DatastoreService.AllocateIds protobuf RPC.

Parameters:	project (string) – The project to which the transaction belongs. key_pbs (list of `gcloud.datastore._generated.entity_pb2.Key`) – The keys for which the backend should allocate IDs.
Return type:	list of `gcloud.datastore._generated.entity_pb2.Key`
Returns:	An equal number of keys, with IDs filled in by the backend.

begin_transaction(project)[source]#

Begin a transaction.

Maps the DatastoreService.BeginTransaction protobuf RPC.

Parameters:	project (string) – The project to which the transaction applies.
Return type:	bytes
Returns:	The serialized transaction that was begun.

build_api_url(project, method, base_url=None, api_version=None)[source]#

Construct the URL for a particular API call.

This method is used internally to come up with the URL to use when making RPCs to the Cloud Datastore API.

Parameters:

Parameters:	project (string) – The project to connect to. This is usually your project name in the cloud console. method (string) – The API method to call (e.g. ‘runQuery’, ‘lookup’). base_url (string) – The base URL where the API lives. You shouldn’t have to provide this. api_version (string) – The version of the API to connect to. You shouldn’t have to provide this.

project (string) – The project to connect to. This is usually your project name in the cloud console.
method (string) – The API method to call (e.g. ‘runQuery’, ‘lookup’).
base_url (string) – The base URL where the API lives. You shouldn’t have to provide this.
api_version (string) – The version of the API to connect to. You shouldn’t have to provide this.

commit(project, request, transaction_id)[source]#

Commit mutations in context of current transation (if any).

Maps the DatastoreService.Commit protobuf RPC.

Parameters:	project (string) – The project to which the transaction applies. request (`_generated.datastore_pb2.CommitRequest`) – The protobuf with the mutations being committed. transaction_id (string or None) – The transaction ID returned from `begin_transaction()`. Non-transactional batches must pass `None`.

Note

This method will mutate request before using it.

Return type:	tuple
Returns’:	The pair of the number of index updates and a list of `_generated.entity_pb2.Key` for each incomplete key that was completed in the commit.

lookup(project, key_pbs, eventual=False, transaction_id=None)[source]#

Lookup keys from a project in the Cloud Datastore.

Maps the DatastoreService.Lookup protobuf RPC.

This uses mostly protobufs (gcloud.datastore._generated.entity_pb2.Key as input and gcloud.datastore._generated.entity_pb2.Entity as output). It is used under the hood in Client.get():

>>> from gcloud import datastore
>>> client = datastore.Client(project='project')
>>> key = client.key('MyKind', 1234)
>>> client.get(key)
[<Entity object>]

Using a Connection directly:

>>> connection.lookup('project', [key.to_protobuf()])
[<Entity protobuf>]

Parameters:	project (string) – The project to look up the keys in. key_pbs (list of `gcloud.datastore._generated.entity_pb2.Key`) – The keys to retrieve from the datastore. eventual (bool) – If False (the default), request `STRONG` read consistency. If True, request `EVENTUAL` read consistency. transaction_id (string) – If passed, make the request in the scope of the given transaction. Incompatible with `eventual==True`.
Return type:	tuple
Returns:	A triple of (`results`, `missing`, `deferred`) where both `results` and `missing` are lists of `gcloud.datastore._generated.entity_pb2.Entity` and `deferred` is a list of `gcloud.datastore._generated.entity_pb2.Key`.

rollback(project, transaction_id)[source]#

Rollback the connection’s existing transaction.

Maps the DatastoreService.Rollback protobuf RPC.

Parameters:	project (string) – The project to which the transaction belongs. transaction_id (string) – The transaction ID returned from `begin_transaction()`.

run_query(project, query_pb, namespace=None, eventual=False, transaction_id=None)[source]#

Run a query on the Cloud Datastore.

Maps the DatastoreService.RunQuery protobuf RPC.

Given a Query protobuf, sends a runQuery request to the Cloud Datastore API and returns a list of entity protobufs matching the query.

You typically wouldn’t use this method directly, in favor of the gcloud.datastore.query.Query.fetch() method.

Under the hood, the gcloud.datastore.query.Query class uses this method to fetch data:

>>> from gcloud import datastore
>>> client = datastore.Client()
>>> query = client.query(kind='MyKind')
>>> query.add_filter('property', '=', 'val')

Using the query iterator’s next_page() method:

>>> query_iter = query.fetch()
>>> entities, more_results, cursor = query_iter.next_page()
>>> entities
[<list of Entity unmarshalled from protobuf>]
>>> more_results
<boolean of more results>
>>> cursor
<string containing cursor where fetch stopped>

Under the hood this is doing:

>>> connection.run_query('project', query.to_protobuf())
[<list of Entity Protobufs>], cursor, more_results, skipped_results

Parameters:	project (string) – The project over which to run the query. query_pb (`gcloud.datastore._generated.query_pb2.Query`) – The Protobuf representing the query to run. namespace (string) – The namespace over which to run the query. eventual (bool) – If False (the default), request `STRONG` read consistency. If True, request `EVENTUAL` read consistency. transaction_id (string) – If passed, make the request in the scope of the given transaction. Incompatible with `eventual==True`.
Return type:	tuple
Returns:	Four-tuple containing the entities returned, the end cursor of the query, a `more_results` enum and a count of the number of skipped results.