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)[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.client_info (
google.api_core.gapic_v1.client_info.ClientInfo
orgoogle.api_core.client_info.ClientInfo
) – (Optional) The client info used to send a user-agent string along with API requests. IfNone
, 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 definesrequest()
with the same interface asrequests.Session.request()
. If not passed, an_http
object is created that is bound to thecredentials
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
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.
- Return type
list of
google.cloud.datastore.key.Key
- Returns
The (complete) keys allocated with
incomplete_key
as root.- Raises
ValueError
ifincomplete_key
is not a partial key.
-
property
base_url
# Getter for API base URL.
-
batch
()[source]# 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, orNoneType
(if no batch is active).- Returns
The batch/transaction at the top of the batch stack.
-
property
current_transaction
# Currently-active transaction.
- Return type
google.cloud.datastore.transaction.Transaction
, or an object implementing its API, orNoneType
(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, eventual=False)[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.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
orNoneType
- 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)[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.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
- Returns
The requested entities.
- Raises
ValueError
if one or more ofkeys
has a project which does not match our project.- Raises
ValueError
if eventual is True and in a transaction.
-
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
ifentities
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 is None True
-
reserve_ids
(complete_key, num_ids)[source]# Reserve a list of IDs from a complete key.
- Parameters
complete_key (
google.cloud.datastore.key.Key
) – Partial key to use as base for reserved IDs.num_ids (int) – The number of IDs to reserve.
- Return type
class:NoneType
- Returns
None
- Raises
ValueError
if complete_key` is not a Complete key.
-
transaction
(**kwargs)[source]# Proxy to
google.cloud.datastore.transaction.Transaction
.- Parameters
kwargs – Keyword arguments to be passed in.