Cloud Datastore Client - Class Transaction (1.25.0)

Version 1.25.0

• 1.32.1 (latest)
• 1.32.0
• 1.31.0
• 1.30.0
• 1.29.2
• 1.28.2
• 1.26.0
• 1.25.0
• 1.24.4
• 1.23.0
• 1.22.1
• 1.21.2
• 1.19.0
• 1.18.1
• 1.17.1

Reference documentation and code samples for the Cloud Datastore Client class Transaction.

Represents a Transaction

A transaction is a set of Datastore operations on one or more entities. Each transaction is guaranteed to be atomic, which means that transactions are never partially applied. Either all of the operations in the transaction are applied, or none of them are applied.

It is highly recommended that users read and understand the underlying concepts in Transactions before beginning.

Mutations (i.e. insert, update and delete) are not executed immediately. Calls to those methods (and their batch equivalents) will enqueue a new mutation. Calling Google\Cloud\Datastore\Transaction::commit() will execute all the mutations in the order they were enqueued, and end the transaction.

Lookups and queries can be run in a transaction, so long as they are run prior to committing or rolling back the transaction.

Transactions are an optional feature of Google Cloud Datastore. Queries, lookups and mutations can be executed outside of a Transaction from Google\Cloud\Datastore\DatastoreClient.

Example:

use Google\Cloud\Datastore\DatastoreClient;

$datastore = new DatastoreClient();

$transaction = $datastore->transaction();

Namespace

Google \ Cloud \ Datastore

Methods

insert

Insert an entity.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\Transaction::commit() to commit changes and end the transaction.

If entities with incomplete keys are provided, this method will immediately trigger a service call to allocate IDs to the entities.

Example:

$key = $datastore->key('Person', 'Bob');
$entity = $datastore->entity($key, ['firstName' => 'Bob']);

$transaction->insert($entity);
$transaction->commit();

Parameter
Name	Description
entity	Google\Cloud\Datastore\EntityInterface The entity to insert.

Returns
Type	Description
Google\Cloud\Datastore\Transaction

insertBatch

Insert multiple entities.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\Transaction::commit() to commit changes and end the transaction.

If entities with incomplete keys are provided, this method will immediately trigger a service call to allocate IDs to the entities.

Example:

$entities = [
    $datastore->entity('Person', ['firstName' => 'Bob']),
    $datastore->entity('Person', ['firstName' => 'John'])
];

$transaction->insertBatch($entities);
$transaction->commit();

Parameter
Name	Description
entities	array<Google\Cloud\Datastore\EntityInterface> The entities to insert.

Returns
Type	Description
Google\Cloud\Datastore\Transaction

update

Update an entity.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\Transaction::commit() to commit changes and end the transaction.

Example:

$entity['firstName'] = 'Bob';

$transaction->update($entity);
$transaction->commit();

Parameters
Name	Description
entity	Google\Cloud\Datastore\EntityInterface The entity to update.
options	array Configuration Options
↳ allowOverwrite	bool Entities must be updated as an entire resource. Patch operations are not supported. Because entities can be created manually, or obtained by a lookup or query, it is possible to accidentally overwrite an existing record with a new one when manually creating an entity. To provide additional safety, this flag must be set to true in order to update a record when the entity provided was not obtained through a lookup or query. Defaults to false.

Returns
Type	Description
Google\Cloud\Datastore\Transaction

updateBatch

Update multiple entities.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\Transaction::commit() to commit changes and end the transaction.

Example:

$entities[0]['firstName'] = 'Bob';
$entities[1]['firstName'] = 'John';

$transaction->updateBatch($entities);
$transaction->commit();

Parameters
Name	Description
entities	array<Google\Cloud\Datastore\EntityInterface> The entities to update.
options	array Configuration Options
↳ allowOverwrite	bool Entities must be updated as an entire resource. Patch operations are not supported. Because entities can be created manually, or obtained by a lookup or query, it is possible to accidentally overwrite an existing record with a new one when manually creating an entity. To provide additional safety, this flag must be set to true in order to update a record when the entity provided was not obtained through a lookup or query. Defaults to false.

Returns
Type	Description
Google\Cloud\Datastore\Transaction

upsert

Upsert an entity.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\Transaction::commit() to commit changes and end the transaction.

Upsert will create a record if one does not already exist, or overwrite existing record if one already exists.

If entities with incomplete keys are provided, this method will immediately trigger a service call to allocate IDs to the entities.

Example:

$key = $datastore->key('Person', 'Bob');
$entity = $datastore->entity($key, ['firstName' => 'Bob']);

$transaction->upsert($entity);
$transaction->commit();

Parameter
Name	Description
entity	Google\Cloud\Datastore\EntityInterface The entity to upsert.

Returns
Type	Description
Google\Cloud\Datastore\Transaction

upsertBatch

Upsert multiple entities.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\Transaction::commit() to commit changes and end the transaction.

Upsert will create a record if one does not already exist, or overwrite existing record if one already exists.

If entities with incomplete keys are provided, this method will immediately trigger a service call to allocate IDs to the entities.

Example:

$keys = [
    $datastore->key('Person', 'Bob'),
    $datastore->key('Person', 'John')
];

$entities = [
    $datastore->entity($keys[0], ['firstName' => 'Bob']),
    $datastore->entity($keys[1], ['firstName' => 'John'])
];

$transaction->upsertBatch($entities);
$transaction->commit();

Parameter
Name	Description
entities	array<Google\Cloud\Datastore\EntityInterface> The entities to upsert.

Returns
Type	Description
Google\Cloud\Datastore\Transaction

delete

Delete a record.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\Transaction::commit() to commit changes and end the transaction.

Example:

$key = $datastore->key('Person', 'Bob');

$transaction->delete($key);
$transaction->commit();

Parameter
Name	Description
key	Google\Cloud\Datastore\Key The key to delete

Returns
Type	Description
Google\Cloud\Datastore\Transaction

deleteBatch

Delete multiple records.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\Transaction::commit() to commit changes and end the transaction.

Example:

$keys = [
    $datastore->key('Person', 'Bob'),
    $datastore->key('Person', 'John')
];

$transaction->deleteBatch($keys);
$transaction->commit();

Parameter
Name	Description
keys	array<Google\Cloud\Datastore\Key> The keys to delete.

Returns
Type	Description
Google\Cloud\Datastore\Transaction

commit

See also:

• Commit API documentation

Parameter
Name	Description
options	array [optional] Configuration Options.

Returns
Type	Description
array	[Response Body](https://cloud.google.com/datastore/reference/rest/v1/projects/commit#response-body)