Cloud Datastore Client - Class Transaction (1.19.0)

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();

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();

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();

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();

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();

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();

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();

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();

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();

Commit all mutations.

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

Example:

$transaction->commit();