Cloud Spanner Client - Class BatchClient (1.57.0)

Reference documentation and code samples for the Cloud Spanner Client class BatchClient.

Provides Batch APIs used to read data from a Cloud Spanner database.

Batch Clients are useful when one wants to read or query a large amount of data from Cloud Spanner across multiple processes, even across multiple machines. It allows creation of partitions of a Cloud Spanner database in order to facilitate reading or querying of each partition independently at the same snapshot.

Example:

use Google\Cloud\Spanner\SpannerClient;

$spanner = new SpannerClient();
$batch = $spanner->batch('instance-id', 'database-id');

// Using Cloud Pub/Sub to share partitions with workers
use Google\Cloud\PubSub\PubSubClient;

$pubsub = new PubSubClient();
$topic = $pubsub->topic('partition-queries');

$snapshot = $batch->snapshot();

// Executing a partition query will return a list of Partitions.
$partitions = $snapshot->partitionQuery('SELECT * FROM Users WHERE firstName = %s AND location = %s', [
    'parameters' => [
        'firstName' => 'John',
        'location' => 'USA'
    ]
]);

// Each partition is published to Cloud Pub/Sub, where it can be executed by
// a worker.
foreach ($partitions as $partition) {
    $topic->publish([
        'attributes' => [
            'snapshot' => $snapshot->serialize(),
            'partition' => $partition->serialize()
        ]
    ]);
}

// Once all workers have finished, we will close the snapshot.
// The logic to determine whether the snapshot is no longer needed will vary
// and is not implemented here.
do {
    $finished = areWorkersDone();

    if ($finished) {
        $snapshot->close();
    }
} while(!$finished);

// Using Cloud Pub/Sub to consume a partition and return a result.
use Google\Cloud\PubSub\PubSubClient;

$pubsub = new PubSubClient();
$subscription = $pubsub->subscription('partition-query-consumer');

$messages = $subscription->pull([
    'returnImmediately' => true,
    'maxMessages' => 1
]);

if ($messages) {
    $message = $messages[0];
    $snapshot = $batch->snapshotFromString($message->attribute('snapshot'));
    $partition = $batch->partitionFromString($message->attribute('partition'));

    // Do something with the query result.
    processResult($snapshot->executePartition($partition));
}

Methods

__construct

Parameters
Name	Description
`operation`	`Google\Cloud\Spanner\Operation` A Cloud Spanner Operations wrapper.
`databaseName`	`string` The database name to which the batch client instance is scoped.
`options`	`array` Configuration options.
`↳ databaseRole`	`string` The user created database role which creates the session.

snapshot

Create a batch snapshot.

Example:

$snapshot = $batch->snapshot();

Parameters
Name	Description
`options`	`array` Configuration Options `See [ReadOnly](https://cloud.google.com/spanner/reference/rpc/google.spanner.v1#google.spanner.v1.TransactionOptions.ReadOnly) for detailed description of available options.`
`↳ transactionOptions`	`bool` .strong Read at a timestamp where all previously committed transactions are visible.
`↳ transactionOptions`	`Timestamp` .readTimestamp Executes all reads at the given timestamp.
`↳ transactionOptions`	`Duration` .exactStaleness Represents a number of seconds. Executes all reads at a timestamp that is $exactStaleness old.
`↳ sessionOptions`	`array` Configuration options for session creation.

Returns
Type	Description
`Google\Cloud\Spanner\Batch\BatchSnapshot`

snapshotFromString

Create a Google\Cloud\Spanner\Batch\BatchSnapshot from a snapshot identifier.

This method can be used to deserialize a snapshot which is shared across multiple servers or processes.

Example:

$snapshot = $batch->snapshotFromString($snapshotString);

Parameter
Name	Description
`identifier`	`string` A stringified representation of {@see \Google\Cloud\Spanner\Batch\Google\Cloud\Spanner\Batch\BatchSnapshot}.

Returns
Type	Description
`Google\Cloud\Spanner\Batch\BatchSnapshot`

partitionFromString

Create a Google\Cloud\Spanner\Batch\PartitionInterface instance.

This method can be used to deserialize a partition which is shared across multiple servers or processes.

Example:

$partition = $batch->partitionFromString($partitionString);

Parameter
Name	Description
`partition`	`string` Partition data

Returns
Type	Description
`Google\Cloud\Spanner\Batch\PartitionInterface`

Constants

PARTITION_TYPE_KEY

Value: '__partitionTypeName'