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
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\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\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\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\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\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\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\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

Commit all mutations.

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

Example:

$transaction->commit();

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)