Cloud Datastore Client - Class Transaction (1.21.2)

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\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\Google\Cloud\Datastore\DatastoreClient.

Example:

use Google\Cloud\Datastore\DatastoreClient;

$datastore = new DatastoreClient();

$transaction = $datastore->transaction();

Methods

insert

Insert an entity.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\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
NameDescription
entity Google\Cloud\Datastore\EntityInterface

The entity to insert.

Returns
TypeDescription
Google\Cloud\Datastore\Transaction

insertBatch

Insert multiple entities.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\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
NameDescription
entities array<Google\Cloud\Datastore\EntityInterface>

The entities to insert.

Returns
TypeDescription
Google\Cloud\Datastore\Transaction

update

Update an entity.

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

Example:

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

$transaction->update($entity);
$transaction->commit();
Parameters
NameDescription
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
TypeDescription
Google\Cloud\Datastore\Transaction

updateBatch

Update multiple entities.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\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
NameDescription
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
TypeDescription
Google\Cloud\Datastore\Transaction

upsert

Upsert an entity.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\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
NameDescription
entity Google\Cloud\Datastore\EntityInterface

The entity to upsert.

Returns
TypeDescription
Google\Cloud\Datastore\Transaction

upsertBatch

Upsert multiple entities.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\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
NameDescription
entities array<Google\Cloud\Datastore\EntityInterface>

The entities to upsert.

Returns
TypeDescription
Google\Cloud\Datastore\Transaction

delete

Delete a record.

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

Example:

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

$transaction->delete($key);
$transaction->commit();
Parameter
NameDescription
key Google\Cloud\Datastore\Key

The key to delete

Returns
TypeDescription
Google\Cloud\Datastore\Transaction

deleteBatch

Delete multiple records.

Changes are not immediately committed to Cloud Datastore when calling this method. Use Google\Cloud\Datastore\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
NameDescription
keys array<Google\Cloud\Datastore\Key>

The keys to delete.

Returns
TypeDescription
Google\Cloud\Datastore\Transaction

commit

Commit all mutations.

Calling this method will end the operation (and close the transaction, if one is specified).

Example:

$transaction->commit();
Parameter
NameDescription
options array

[optional] Configuration Options.

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