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)[source]# Bases:
google.cloud.client.Client
,google.cloud.client._ClientProjectMixin
Convenience wrapper for invoking APIs/factories w/ a project.
Parameters: - project (string) – (optional) The project to pass to proxied API methods.
- namespace (string) – (optional) namespace to pass to proxied API methods.
- credentials (
oauth2client.client.OAuth2Credentials
orNoneType
) – The OAuth2 Credentials to use for the connection owned by this client. If not passed (and if nohttp
object is passed), falls back to the default inferred from the environment. - http (
httplib2.Http
or class that definesrequest()
.) – An optional HTTP object to make requests. If not passed, anhttp
object is created that is bound to thecredentials
for the current object.
-
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.- incomplete_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, orNoneType
(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, 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)[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
orNoneType
Returns: The requested entity if it exists.
- key (
-
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: Returns: The requested entities.
Raises: ValueError
if one or more ofkeys
has a project which does not match our project.- keys (list of
-
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:
>>> from google.cloud import datastore >>> client = datastore.Client() >>> query = client.query(kind='MyKind') >>> query.add_filter('property', '=', 'val')
Using the query iterator’s
next_page()
method:>>> query_iter = query.fetch() >>> entities, more_results, cursor = query_iter.next_page() >>> entities [<list of Entity unmarshalled from protobuf>] >>> more_results <boolean of more results> >>> cursor <string containing cursor where fetch stopped>
Under the hood this is doing:
>>> connection.run_query('project', query.to_protobuf()) [<list of Entity Protobufs>], cursor, more_results, skipped_results
Parameters: kwargs (dict) – Parameters for initializing and instance of google.cloud.datastore.query.Query
.Return type: google.cloud.datastore.query.Query
Returns: An instance of google.cloud.datastore.query.Query
Connection#
Connections to Google Cloud Datastore API servers.
-
class
google.cloud.datastore.connection.
Connection
(credentials=None, http=None)[source]# Bases:
google.cloud.connection.Connection
A connection to the Google Cloud Datastore via the Protobuf API.
This class should understand only the basic types (and protobufs) in method arguments, however it should be capable of returning advanced types.
Parameters: - credentials (
oauth2client.client.OAuth2Credentials
) – The OAuth2 Credentials to use for this connection. - http (
httplib2.Http
or class that definesrequest()
.) – An optional HTTP object to make requests.
-
API_BASE_URL
= 'https://datastore.googleapis.com'# The base of the API call URL.
-
API_URL_TEMPLATE
= '{api_base}/{api_version}/projects/{project}:{method}'# A template for the URL of a particular API call.
-
API_VERSION
= 'v1'# The version of the API, used in building the API call’s URL.
-
SCOPE
= ('https://www.googleapis.com/auth/datastore',)# The scopes required for authenticating as a Cloud Datastore consumer.
-
allocate_ids
(project, key_pbs)[source]# Obtain backend-generated IDs for a set of keys.
Maps the
DatastoreService.AllocateIds
protobuf RPC.Parameters: - project (string) – The project to which the transaction belongs.
- key_pbs (list of
google.cloud.datastore._generated.entity_pb2.Key
) – The keys for which the backend should allocate IDs.
Return type: list of
datastore._generated.entity_pb2.Key
Returns: An equal number of keys, with IDs filled in by the backend.
-
begin_transaction
(project)[source]# Begin a transaction.
Maps the
DatastoreService.BeginTransaction
protobuf RPC.Parameters: project (string) – The project to which the transaction applies. Return type: bytes Returns: The serialized transaction that was begun.
-
build_api_url
(project, method, base_url=None, api_version=None)[source]# Construct the URL for a particular API call.
This method is used internally to come up with the URL to use when making RPCs to the Cloud Datastore API.
Parameters: - project (string) – The project to connect to. This is usually your project name in the cloud console.
- method (string) – The API method to call (e.g. ‘runQuery’, ‘lookup’).
- base_url (string) – The base URL where the API lives. You shouldn’t have to provide this.
- api_version (string) – The version of the API to connect to. You shouldn’t have to provide this.
Return type: Returns: The API URL created.
-
commit
(project, request, transaction_id)[source]# Commit mutations in context of current transaction (if any).
Maps the
DatastoreService.Commit
protobuf RPC.Parameters: - project (string) – The project to which the transaction applies.
- request (
_generated.datastore_pb2.CommitRequest
) – The protobuf with the mutations being committed. - transaction_id (string or None) – The transaction ID returned from
begin_transaction()
. Non-transactional batches must passNone
.
Note
This method will mutate
request
before using it.Return type: tuple Returns: The pair of the number of index updates and a list of _generated.entity_pb2.Key
for each incomplete key that was completed in the commit.
-
lookup
(project, key_pbs, eventual=False, transaction_id=None)[source]# Lookup keys from a project in the Cloud Datastore.
Maps the
DatastoreService.Lookup
protobuf RPC.This uses mostly protobufs (
google.cloud.datastore._generated.entity_pb2.Key
as input andgoogle.cloud.datastore._generated.entity_pb2.Entity
as output). It is used under the hood inClient.get()
:>>> from google.cloud import datastore >>> client = datastore.Client(project='project') >>> key = client.key('MyKind', 1234) >>> client.get(key) [<Entity object>]
Using a
Connection
directly:>>> connection.lookup('project', [key.to_protobuf()]) [<Entity protobuf>]
Parameters: - project (string) – The project to look up the keys in.
- key_pbs (list of
google.cloud.datastore._generated.entity_pb2.Key
) – The keys to retrieve from the datastore. - eventual (bool) – If False (the default), request
STRONG
read consistency. If True, requestEVENTUAL
read consistency. - transaction_id (string) – If passed, make the request in the scope of
the given transaction. Incompatible with
eventual==True
.
Return type: Returns: A triple of (
results
,missing
,deferred
) where bothresults
andmissing
are lists ofgoogle.cloud.datastore._generated.entity_pb2.Entity
anddeferred
is a list ofgoogle.cloud.datastore._generated.entity_pb2.Key
.
-
rollback
(project, transaction_id)[source]# Rollback the connection’s existing transaction.
Maps the
DatastoreService.Rollback
protobuf RPC.Parameters: - project (string) – The project to which the transaction belongs.
- transaction_id (string) – The transaction ID returned from
begin_transaction()
.
-
run_query
(project, query_pb, namespace=None, eventual=False, transaction_id=None)[source]# Run a query on the Cloud Datastore.
Maps the
DatastoreService.RunQuery
protobuf RPC.Given a Query protobuf, sends a
runQuery
request to the Cloud Datastore API and returns a list of entity protobufs matching the query.You typically wouldn’t use this method directly, in favor of the
google.cloud.datastore.query.Query.fetch()
method.Under the hood, the
google.cloud.datastore.query.Query
class uses this method to fetch data.Parameters: - project (string) – The project over which to run the query.
- query_pb (
datastore._generated.query_pb2.Query
) – The Protobuf representing the query to run. - namespace (string) – The namespace over which to run the query.
- eventual (bool) – If False (the default), request
STRONG
read consistency. If True, requestEVENTUAL
read consistency. - transaction_id (string) – If passed, make the request in the scope of
the given transaction. Incompatible with
eventual==True
.
Return type: Returns: Four-tuple containing the entities returned, the end cursor of the query, a
more_results
enum and a count of the number of skipped results.
- credentials (
-
google.cloud.datastore.connection.
DATASTORE_API_HOST
= 'datastore.googleapis.com'# Datastore API request host.