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

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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025年10月30日 UTC.