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>, client_options=None, database=None, _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.

    • client_options (ClientOptions or dict) – (Optional) Client options used to set user options on the client. API Endpoint should be set through client_options.

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

    • database (str) – (Optional) database to pass to proxied API methods.

SCOPE(: Optional[Tuple[str, ...] = ('https://www.googleapis.com/auth/datastore', )

The scopes required for authenticating as a Cloud Datastore consumer.

aggregation_query(query)

Proxy to google.cloud.datastore.aggregation.AggregationQuery.

Using aggregation_query to count over a query:

>>> query = client.query(kind='MyKind')
>>> aggregation_query = client.aggregation_query(query)
>>> aggregation_query.count(alias='total')
<google.cloud.datastore.aggregation.AggregationQuery object at ...>
>>> aggregation_query.fetch()
<google.cloud.datastore.aggregation.AggregationResultIterator object at ...>

Adding an aggregation to the aggregation_query

>>> query = client.query(kind='MyKind')
>>> aggregation_query.add_aggregation(CountAggregation(alias='total'))
>>> aggregation_query.fetch()
<google.cloud.datastore.aggregation.AggregationResultIterator object at ...>

Adding multiple aggregations to the aggregation_query

>>> query = client.query(kind='MyKind')
>>> total_count = CountAggregation(alias='total')
>>> all_count = CountAggregation(alias='all')
>>> aggregation_query.add_aggregations([total_count, all_count])
>>> aggregation_query.fetch()
<google.cloud.datastore.aggregation.AggregationResultIterator object at ...>

Using the aggregation_query iterator

>>> query = client.query(kind='MyKind')
>>> aggregation_query = client.aggregation_query(query)
>>> aggregation_query.count(alias='total')
<google.cloud.datastore.aggregation.AggregationQuery object at ...>
>>> aggregation_query_iter = aggregation_query.fetch()
>>> for aggregation_result in aggregation_query_iter:
...     do_something_with(aggregation_result)

or manually page through results

>>> aggregation_query_iter = aggregation_query.fetch()
>>> pages = aggregation_query_iter.pages
>>>
>>> first_page = next(pages)
>>> first_page_entities = list(first_page)
>>> aggregation_query_iter.next_page_token is None
True

allocate_ids(incomplete_key, num_ids, retry=None, timeout=None)

Allocate a list of IDs from a partial key.

  • Parameters

    • incomplete_key (google.cloud.datastore.key.Key) – Partial key to use as base for allocated IDs.

    • num_ids (int) – The number of IDs to allocate.

    • retry (google.api_core.retry.Retry) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.

    • timeout (float) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

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

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.

property database()

Getter for database

delete(key, retry=None, timeout=None)

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, google.cloud.datastore.entity.Entity) – The key to be deleted from the datastore.

    • retry (google.api_core.retry.Retry) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration. Only meaningful outside of another batch / transaction.

    • timeout (float) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt. Only meaningful outside of another batch / transaction.

delete_multi(keys, retry=None, timeout=None)

Delete keys from the Cloud Datastore.

  • Parameters

    • keys (list of google.cloud.datastore.key.Key, google.cloud.datastore.entity.Entity) – The keys to be deleted from the Datastore.

    • retry (google.api_core.retry.Retry) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration. Only meaningful outside of another batch / transaction.

    • timeout (float) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt. Only meaningful outside of another batch / transaction.

entity(key=None, exclude_from_indexes=())

Proxy to google.cloud.datastore.entity.Entity.

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

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 with read_time, or will raise ValueError.

    • retry (google.api_core.retry.Retry) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.

    • timeout (float) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

    • read_time (datetime) – Read the entity from the specified time (may be null). Cannot be used with eventual consistency or inside a transaction, or will raise ValueError. This feature is in private preview.

  • Return type

    google.cloud.datastore.entity.Entity or NoneType

  • Returns

    The requested entity if it exists.

  • Raises

    ValueError if more than one of eventual==True, transaction, and read_time is specified.

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

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.

    • retry (google.api_core.retry.Retry) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.

    • timeout (float) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

    • read_time (datetime) – (Optional) Read time to use for read consistency. This feature is in private preview.

  • 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; or if more than one of eventual==True, transaction, and read_time is specified.

key(*path_args, **kwargs)

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

Passes our project and our database.

put(entity, retry=None, timeout=None)

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.

    • retry (google.api_core.retry.Retry) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration. Only meaningful outside of another batch / transaction.

    • timeout (float) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt. Only meaningful outside of another batch / transaction.

put_multi(entities, retry=None, timeout=None)

Save entities in the Cloud Datastore.

  • Parameters

    • entities (list of google.cloud.datastore.entity.Entity) – The entities to be saved to the datastore.

    • retry (google.api_core.retry.Retry) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration. Only meaningful outside of another batch / transaction.

    • timeout (float) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt. Only meaningful outside of another batch / transaction.

  • Raises

    ValueError if entities is a single entity.

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')
<google.cloud.datastore.query.Query object at ...>

Using the query iterator

>>> filters = [('property', '=', 'val')]
>>> query = client.query(kind='MyKind', filters=filters)
>>> query_iter = query.fetch()
>>> for entity in query_iter:
...     do_something_with(entity)

or manually page through results

>>> query_iter = query.fetch()
>>> 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, retry=None, timeout=None)

Reserve a list of IDs sequentially from a complete key.

DEPRECATED. Alias for reserve_ids_sequential().

Please use either reserve_ids_multi() (recommended) or reserve_ids_sequential().

reserve_ids_multi(complete_keys, retry=None, timeout=None)

Reserve IDs from a list of complete keys.

  • Parameters

    • complete_keys (list of google.cloud.datastore.key.Key) – Complete keys for which to reserve IDs.

    • retry (google.api_core.retry.Retry) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.

    • timeout (float) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

  • Return type

    class:NoneType

  • Returns

    None

  • Raises

    ValueError if any of complete_keys` is not a Complete key.

reserve_ids_sequential(complete_key, num_ids, retry=None, timeout=None)

Reserve a list of IDs sequentially from a complete key.

This will reserve the key passed as complete_key as well as additional keys derived by incrementing the last ID in the path of complete_key sequentially to obtain the number of keys specified in num_ids.

  • Parameters

    • complete_key (google.cloud.datastore.key.Key) – Complete key to use as base for reserved IDs. Key must use a numeric ID and not a string name.

    • num_ids (int) – The number of IDs to reserve.

    • retry (google.api_core.retry.Retry) – A retry object used to retry requests. If None is specified, requests will be retried using a default configuration.

    • timeout (float) – Time, in seconds, to wait for the request to complete. Note that if retry is specified, the timeout applies to each individual attempt.

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

google.cloud.datastore.client.DATASTORE_DATASET( = 'DATASTORE_DATASET )

Environment variable defining default dataset ID under GCD.

google.cloud.datastore.client.DATASTORE_EMULATOR_HOST( = 'DATASTORE_EMULATOR_HOST )

Environment variable defining host for datastore emulator server.

google.cloud.datastore.client.DISABLE_GRPC( = 'GOOGLE_CLOUD_DISABLE_GRPC )

Environment variable acting as flag to disable gRPC.