Class Client (1.15.5)

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, 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` 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` 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 (1.15.5)

Parameters

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