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, use_gax=None)[source]#

Bases: google.cloud.client.ClientWithProject

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

>>> from google.cloud import datastore
>>> client = datastore.Client()
Parameters:
  • project (str) – (optional) The project to pass to proxied API methods.
  • namespace (str) – (optional) namespace to pass to proxied API methods.
  • credentials (Credentials) – (Optional) The OAuth2 Credentials to use for this client. If not passed (and if no http object is passed), falls back to the default inferred from the environment.
  • http (Http) – (Optional) HTTP object to make requests. Can be any object that defines request() with the same interface as request(). If not passed, an http object is created that is bound to the credentials for the current object.
  • use_gax (bool) – (Optional) Explicitly specifies whether to use the gRPC transport (via GAX) or HTTP. If unset, falls back to the GOOGLE_CLOUD_DISABLE_GRPC environment variable.
SCOPE = ('https://www.googleapis.com/auth/datastore',)#

The scopes required for authenticating as a Cloud Datastore consumer.

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:

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

Using the query iterator

>>> query_iter = query.fetch()
>>> for entity in query_iter:
...     do_something(entity)

or manually page through results

>>> query_iter = query.fetch(start_cursor=cursor)
>>> pages = query_iter.pages
>>>
>>> first_page = next(pages)
>>> first_page_entities = list(first_page)
>>> query_iter.next_page_token
b'...'
Parameters:kwargs (dict) – Parameters for initializing and instance of Query.
Return type:Query
Returns:A query object.
transaction()[source]#

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