Class Client (2.1.6)

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.

Inheritance

builtins.object > google.cloud.client._ClientFactoryMixin > google.cloud.client.Client > builtins.object > google.cloud.client._ClientProjectMixin > google.cloud.client.ClientWithProject > Client

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, retry=None, timeout=None)

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

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

Name	Description
key	`Key, 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

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

Delete keys from the Cloud Datastore.

Parameters

Name	Description
keys	`list of Key, 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.

get

get(
    key,
    missing=None,
    deferred=None,
    transaction=None,
    eventual=False,
    retry=None,
    timeout=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

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

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,
    retry=None,
    timeout=None,
)

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

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

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

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

Save entities in the Cloud Datastore.

Parameters

Name	Description
entities	`list of 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.

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

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

Reserve IDs from a list of complete keys.

Parameters

Name	Description
complete_keys	`list` of 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.

Exceptions

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

Returns

Type	Description
class:`NoneType`	None

reserve_ids_sequential

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

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

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.