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_grpc=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. This parameter should be considered private, and could change in the future.
  • _use_grpc (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. This parameter should be considered private, and could change in the future.
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.