Datastore Client#

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

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

Bases: google.cloud.client.Client, google.cloud.client._ClientProjectMixin

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

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.
allocate_ids(incomplete_key, num_ids)[source]#

Allocate a list of IDs from a partial key.

Parameters:
Return type:

list of google.cloud.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 google.cloud.datastore.batch.Batch.

current_batch#

Currently-active batch.

Return type:google.cloud.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:google.cloud.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 (google.cloud.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 google.cloud.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 (google.cloud.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 (Transaction) – (Optional) Transaction to use for read consistency. If not passed, uses current transaction, if set.
Return type:

google.cloud.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 google.cloud.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 (Transaction) – (Optional) Transaction to use for read consistency. If not passed, uses current transaction, if set.
Return type:

list of google.cloud.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 google.cloud.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 (google.cloud.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 google.cloud.datastore.entity.Entity) – The entities to be saved to the datastore.
Raises:ValueError if entities is a single entity.
query(**kwargs)[source]#

Proxy to google.cloud.datastore.query.Query.

Passes our project.

Using query to search a datastore:

>>> from google.cloud 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:kwargs (dict) – Parameters for initializing and instance of google.cloud.datastore.query.Query.
Return type:google.cloud.datastore.query.Query
Returns:An instance of google.cloud.datastore.query.Query
transaction()[source]#

Proxy to google.cloud.datastore.transaction.Transaction.

Connection#

Connections to Google Cloud Datastore API servers.

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

Bases: google.cloud.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 it should be capable of returning advanced types.

Parameters:
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 = 'v1'#

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 google.cloud.datastore._generated.entity_pb2.Key) – The keys for which the backend should allocate IDs.
Return type:

list of 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:
  • 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.
Return type:

str

Returns:

The API URL created.

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

Commit mutations in context of current transaction (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 (google.cloud.datastore._generated.entity_pb2.Key as input and google.cloud.datastore._generated.entity_pb2.Entity as output). It is used under the hood in Client.get():

>>> from google.cloud 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 google.cloud.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 google.cloud.datastore._generated.entity_pb2.Entity and deferred is a list of google.cloud.datastore._generated.entity_pb2.Key.

rollback(project, transaction_id)[source]#

Rollback the connection’s existing transaction.

Maps the DatastoreService.Rollback protobuf RPC.

Parameters:
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 google.cloud.datastore.query.Query.fetch() method.

Under the hood, the google.cloud.datastore.query.Query class uses this method to fetch data.

Parameters:
  • project (string) – The project over which to run the query.
  • query_pb (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.

google.cloud.datastore.connection.DATASTORE_API_HOST = 'datastore.googleapis.com'#

Datastore API request host.

google.cloud.datastore.connection.DATASTORE_API_PORT = 443#

Datastore API request port.