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
NameDescription
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
NameDescription
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
TypeDescription
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
NameDescription
identifier string

A stringified representation of {@see \Google\Cloud\Spanner\Batch\Google\Cloud\Spanner\Batch\BatchSnapshot}.

Returns
TypeDescription
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
NameDescription
partition string

Partition data

Returns
TypeDescription
Google\Cloud\Spanner\Batch\PartitionInterface

Constants

PARTITION_TYPE_KEY

Value: '__partitionTypeName'