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.

Class Client (2.1.6) Stay organized with collections Save and categorize content based on your preferences.

Parameters

Inheritance

Properties

base_url

current_batch

current_transaction

Methods

allocate_ids

batch

delete

delete_multi

get

get_multi

key

put

put_multi

query

reserve_ids

reserve_ids_multi

reserve_ids_sequential

transaction

Class Client (2.1.6)