Datastore Client

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

class google.cloud.datastore.client.Client(project=None, namespace=None, credentials=None, client_info=<google.api_core.gapic_v1.client_info.ClientInfo object>, _http=None, _use_grpc=None)

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.

    • client_info (google.api_core.gapic_v1.client_info.ClientInfo or google.api_core.client_info.ClientInfo) – (Optional) The client info used to send a user-agent string along with API requests. If None, then default info will be used. Generally, you only need to set this if you’re developing your own library or partner tool.

    • _http (Session) – (Optional) HTTP object to make requests. Can be any object that defines request() with the same interface as requests.Session.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(: Optional[Tuple[str, ...] = ('https://www.googleapis.com/auth/datastore', )

The scopes required for authenticating as a Cloud Datastore consumer.

allocate_ids(incomplete_key, num_ids)

Allocate a list of IDs from a partial key.

property base_url()

Getter for API base URL.

batch()

Proxy to google.cloud.datastore.batch.Batch.

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

property current_transaction()

Currently-active transaction.

delete(key)

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.

delete_multi(keys)

Delete keys from the Cloud Datastore.

get(key, missing=None, deferred=None, transaction=None, eventual=False)

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.

    • eventual (bool) – (Optional) Defaults to strongly consistent (False). Setting True will use eventual consistency, but cannot be used inside a transaction or will raise ValueError.

  • Return type

    google.cloud.datastore.entity.Entity or NoneType

  • Returns

    The requested entity if it exists.

  • Raises

    ValueError if eventual is True and in a transaction.

get_multi(keys, missing=None, deferred=None, transaction=None, eventual=False)

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.

    • eventual (bool) – (Optional) Defaults to strongly consistent (False). Setting True will use eventual consistency, but cannot be used inside a transaction or will raise ValueError.

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

  • Raises

    ValueError if eventual is True and in a transaction.

key(*path_args, **kwargs)

Proxy to google.cloud.datastore.key.Key.

Passes our project.

put(entity)

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.

put_multi(entities)

Save entities in the Cloud Datastore.

query(**kwargs)

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 is None
True

  • Parameters

    kwargs – Parameters for initializing and instance of Query.

  • Return type

    Query

  • Returns

    A query object.

reserve_ids(complete_key, num_ids)

Reserve a list of IDs from a complete key.

  • Parameters

  • Return type

    class:NoneType

  • Returns

    None

  • Raises

    ValueError if complete_key` is not a Complete key.

transaction(**kwargs)

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

  • Parameters

    kwargs – Keyword arguments to be passed in.