Datastore Client#

Convenience wrapper for invoking APIs/factories w/ a dataset ID.

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

Bases: gcloud.client.Client

Convenience wrapper for invoking APIs/factories w/ a dataset ID.

Parameters:

Parameters:	dataset_id (string) – (optional) dataset ID 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.

dataset_id (string) – (optional) dataset ID 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 (A `gcloud.datastore.key.Key`) – Partial key to use as base for allocated IDs. num_ids (integer) – 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.

Passes our dataset_id.

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)[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 (an empty list or None.) – If a list is passed, the key-only entities returned by the backend as “missing” will be copied into it. Use only as a keyword param. deferred (an empty list or None.) – If a list is passed, the keys returned by the backend as “deferred” will be copied into it. Use only as a keyword param.
Return type:	`gcloud.datastore.entity.Entity` or `NoneType`
Returns:	The requested entity if it exists.

get_multi(keys, missing=None, deferred=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 (an empty list or None.) – If a list is passed, the key-only entities returned by the backend as “missing” will be copied into it. Use only as a keyword param. deferred (an empty list or None.) – If a list is passed, the keys returned by the backend as “deferred” will be copied into it. Use only as a keyword param.
Return type:	list of `gcloud.datastore.entity.Entity`
Returns:	The requested entities.
Raises:	ValueError if one or more of `keys` has a dataset ID which does not match our dataset ID.

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

Proxy to gcloud.datastore.key.Key.

Passes our dataset_id.

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

transaction()[source]#

Proxy to gcloud.datastore.transaction.Transaction.

Passes our dataset_id.

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 the value from `gcloud.connection`.

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

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

allocate_ids(dataset_id, key_pbs)[source]#

Obtain backend-generated IDs for a set of keys.

Maps the DatastoreService.AllocateIds protobuf RPC.

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

begin_transaction(dataset_id, serializable=False)[source]#

Begin a transaction.

Maps the DatastoreService.BeginTransaction protobuf RPC.

Parameters:	dataset_id (string) – The ID dataset to which the transaction applies. serializable (boolean) – Boolean indicating if the isolation level of the transaction should be SERIALIZABLE (True) or SNAPSHOT (False).
Return type:	`_datastore_v1_pb2.BeginTransactionResponse`
Returns’:	the result protobuf for the begin transaction request.

build_api_url(dataset_id, 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:	dataset_id (string) – The ID of the dataset to connect to. This is usually your project name in the cloud console. method (string) – The API method to call (ie, 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.

dataset_id (string) – The ID of the dataset to connect to. This is usually your project name in the cloud console.
method (string) – The API method to call (ie, 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(dataset_id, mutation_pb, transaction_id)[source]#

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

Maps the DatastoreService.Commit protobuf RPC.

Parameters:	dataset_id (string) – The ID dataset to which the transaction applies. mutation_pb (`datastore_pb.Mutation`.) – The protobuf for the mutations being saved. transaction_id (string or None) – The transaction ID returned from `begin_transaction()`. Non-transactional batches must pass `None`.
Return type:	`gcloud.datastore._datastore_v1_pb2.MutationResult`.
Returns’:	the result protobuf for the mutation.

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

Lookup keys from a dataset in the Cloud Datastore.

Maps the DatastoreService.Lookup protobuf RPC.

This method deals only with protobufs (gcloud.datastore._datastore_v1_pb2.Key and gcloud.datastore._datastore_v1_pb2.Entity) and is used under the hood in gcloud.datastore.get():

>>> from gcloud import datastore
>>> key = datastore.Key('MyKind', 1234, dataset_id='dataset-id')
>>> datastore.get(key)
[<Entity object>]

Using the connection class directly:

>>> connection.lookup('dataset-id', [key.to_protobuf()])
[<Entity protobuf>]

Parameters:	dataset_id (string) – The ID of the dataset to look up the keys. key_pbs (list of `gcloud.datastore._datastore_v1_pb2.Key`) – The keys to retrieve from the datastore. eventual (boolean) – 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._datastore_v1_pb2.Entity` and `deferred` is a list of `gcloud.datastore._datastore_v1_pb2.Key`.

rollback(dataset_id, transaction_id)[source]#

Rollback the connection’s existing transaction.

Maps the DatastoreService.Rollback protobuf RPC.

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

run_query(dataset_id, 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

>>> query = datastore.Query(kind='MyKind')
>>> query.add_filter('property', '=', 'val')

Using the query’s fetch_page method...

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

Under the hood this is doing...

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

Parameters:

Parameters:	dataset_id (string) – The ID of the dataset over which to run the query. query_pb (`gcloud.datastore._datastore_v1_pb2.Query`) – The Protobuf representing the query to run. namespace (string) – The namespace over which to run the query. eventual (boolean) – 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`.

dataset_id (string) – The ID of the dataset over which to run the query.
query_pb (gcloud.datastore._datastore_v1_pb2.Query) – The Protobuf representing the query to run.
namespace (string) – The namespace over which to run the query.
eventual (boolean) – 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.

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