Class Client (2.0.1)

Client(project=None,namespace=None,credentials=None,client_info=<google.api_core.gapic_v1.client_info.ClientInfoobject>,client_options=None,_http=None,_use_grpc=None)

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

.. doctest::

from google.cloud import datastoreclient = 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 orgoogle.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 ordict` (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, orNoneType (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, orNoneType (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 ofKey`	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 overdelete_multi.The backend API does not make a distinction between a single key ormultiple 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 ofKey` 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 overget_multi.The backend API does not make a distinction between a single key ormultiple 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 orNoneType`	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 ofKey` 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 ofEntity`	The requested entities.

put

put(entity,retry=None,timeout=None)

Save an entity in the Cloud Datastore.

Note:This is just a thin wrapper overput_multi.The backend API does not make a distinction between a singleentity 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 ofEntity` 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 ourproject.

Using query to search a datastore:

.. testsetup:: query

import osimport uuidfrom google.cloud importdatastoreunique = 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 osimport uuidfrom google.cloud importdatastorefrom tests.system.test_system import Config  # system testsunique = 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'] = 1337entity2 =datastore.Entity(key=key)entity2['foo'] = 42Config.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 NoneTrue

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

Please use eitherreserve_ids_multi (recommended) orreserve_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 ofKey` 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 ascomplete_key as well asadditional keys derived by incrementing the last ID in the path ofcomplete_key sequentially to obtain the number of keys specified innum_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.

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-16 UTC.

Movatterモバイル変換

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

Parameters