Class Client (1.10.0)

Version 1.10.0

• 2.20.1 (latest)
• 2.20.0
• 2.19.0
• 2.18.0
• 2.17.0
• 2.16.1
• 2.15.2
• 2.14.0
• 2.13.2
• 2.12.0
• 2.11.1
• 2.10.0
• 2.9.0
• 2.8.3
• 2.7.2
• 2.6.2
• 2.5.1
• 2.4.0
• 2.3.0
• 2.2.0
• 2.1.6
• 2.0.1
• 1.15.5
• 1.14.0
• 1.13.2
• 1.12.0
• 1.11.0
• 1.10.0
• 1.9.0

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)

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

.. doctest::

from google.cloud import datastore client = datastore.Client()

Parameters
Name	Description
project	str (Optional) The project to pass to proxied API methods.
namespace	str (Optional) namespace to pass to proxied API methods.
credentials	google.auth.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	google.api_core.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	requests.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.

Properties

base_url

Getter for API base URL.

current_batch

Currently-active batch.

Returns
Type	Description
Batch, or an object implementing its API, or NoneType (if no batch is active).	The batch/transaction at the top of the batch stack.

current_transaction

Currently-active transaction.

Returns
Type	Description
Transaction, or an object implementing its API, or NoneType (if no transaction is active).	The transaction at the top of the batch stack.

Methods

allocate_ids

allocate_ids(incomplete_key, num_ids)

Allocate a list of IDs from a partial key.

Parameters
Name	Description
incomplete_key	Key Partial key to use as base for allocated IDs.
num_ids	int The number of IDs to allocate.

Exceptions
Type	Description
`ValueError	if incomplete_key is not a partial key.

Returns
Type	Description
list of Key	The (complete) keys allocated with incomplete_key as root.

batch

batch()

Proxy to Batch.

delete

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.

Parameter
Name	Description
key	Key The key to be deleted from the datastore.

delete_multi

delete_multi(keys)

Delete keys from the Cloud Datastore.

Parameter
Name	Description
keys	list of Key The keys to be deleted from the Datastore.

get

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
Name	Description
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.

Exceptions
Type	Description
`ValueError	if eventual is True and in a transaction.

Returns
Type	Description
Entity or NoneType	The requested entity if it exists.

get_multi

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

Retrieve entities, along with their attributes.

Parameters
Name	Description
keys	list of 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.

Exceptions
Type	Description
`ValueError	if one or more of keys has a project which does not match our project.
`ValueError	if eventual is True and in a transaction.

Returns
Type	Description
list of Entity	The requested entities.

key

key(*path_args, **kwargs)

Proxy to Key.

Passes our project.

put

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.

Parameter
Name	Description
entity	Entity The entity to be saved to the datastore.

put_multi

put_multi(entities)

Save entities in the Cloud Datastore.

Parameter
Name	Description
entities	list of Entity The entities to be saved to the datastore.

Exceptions
Type	Description
`ValueError	if entities is a single entity.

query

query(**kwargs)

Proxy to xref_Query.

Passes our project.

Using query to search a datastore:

.. testsetup:: query

import os
import uuid

from google.cloud import datastore

unique = os.getenv('CIRCLE_BUILD_NUM', str(uuid.uuid4())[0:8])
client = datastore.Client(namespace='ns{}'.format(unique))
query = client.query(kind='_Doctest')

def do_something(entity):
    pass

.. doctest:: query

>>> query = client.query(kind='MyKind')
>>> query.add_filter('property', '=', 'val')

Using the query iterator

.. doctest:: query

>>> query_iter = query.fetch()
>>> for entity in query_iter:
...     do_something(entity)

or manually page through results

.. testsetup:: query-page

import os
import uuid

from google.cloud import datastore
from tests.system.test_system import Config  # system tests

unique = os.getenv('CIRCLE_BUILD_NUM', str(uuid.uuid4())[0:8])
client = datastore.Client(namespace='ns{}'.format(unique))

key = client.key('_Doctest')
entity1 = datastore.Entity(key=key)
entity1['foo'] = 1337
entity2 = datastore.Entity(key=key)
entity2['foo'] = 42
Config.TO_DELETE.extend([entity1, entity2])
client.put_multi([entity1, entity2])

query = client.query(kind='_Doctest')
cursor = None

.. doctest:: query-page

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

Returns
Type	Description
Query	A query object.

reserve_ids

reserve_ids(complete_key, num_ids)

Reserve a list of IDs from a complete key.

Parameters
Name	Description
complete_key	Key Partial key to use as base for reserved IDs.
num_ids	int The number of IDs to reserve.

Exceptions
Type	Description
`ValueError	if complete_key is not a Complete key.

Returns
Type	Description
class:NoneType	None

transaction

transaction(**kwargs)

Proxy to xref_Transaction.