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));
}
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.strong
bool
Read at a timestamp where all previously committed transactions are visible.
↳ transactionOptions.readTimestamp
Timestamp
Executes all reads at the given timestamp.
↳ transactionOptions.exactStaleness
Duration
Represents a number of seconds. Executes all reads at a timestamp that is $exactStaleness old.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[],[],null,["# Cloud Spanner Client - Class BatchClient (1.104.0)\n\nVersion latestkeyboard_arrow_down\n\n- [1.104.0 (latest)](/php/docs/reference/cloud-spanner/latest/Batch.BatchClient)\n- [1.103.0](/php/docs/reference/cloud-spanner/1.103.0/Batch.BatchClient)\n- [1.102.0](/php/docs/reference/cloud-spanner/1.102.0/Batch.BatchClient)\n- [1.101.0](/php/docs/reference/cloud-spanner/1.101.0/Batch.BatchClient)\n- [1.100.0](/php/docs/reference/cloud-spanner/1.100.0/Batch.BatchClient)\n- [1.98.0](/php/docs/reference/cloud-spanner/1.98.0/Batch.BatchClient)\n- [1.97.0](/php/docs/reference/cloud-spanner/1.97.0/Batch.BatchClient)\n- [1.96.0](/php/docs/reference/cloud-spanner/1.96.0/Batch.BatchClient)\n- [1.95.0](/php/docs/reference/cloud-spanner/1.95.0/Batch.BatchClient)\n- [1.94.0](/php/docs/reference/cloud-spanner/1.94.0/Batch.BatchClient)\n- [1.93.1](/php/docs/reference/cloud-spanner/1.93.1/Batch.BatchClient)\n- [1.92.1](/php/docs/reference/cloud-spanner/1.92.1/Batch.BatchClient)\n- [1.91.0](/php/docs/reference/cloud-spanner/1.91.0/Batch.BatchClient)\n- [1.90.0](/php/docs/reference/cloud-spanner/1.90.0/Batch.BatchClient)\n- [1.89.0](/php/docs/reference/cloud-spanner/1.89.0/Batch.BatchClient)\n- [1.88.0](/php/docs/reference/cloud-spanner/1.88.0/Batch.BatchClient)\n- [1.87.0](/php/docs/reference/cloud-spanner/1.87.0/Batch.BatchClient)\n- [1.86.0](/php/docs/reference/cloud-spanner/1.86.0/Batch.BatchClient)\n- [1.85.0](/php/docs/reference/cloud-spanner/1.85.0/Batch.BatchClient)\n- [1.84.0](/php/docs/reference/cloud-spanner/1.84.0/Batch.BatchClient)\n- [1.83.0](/php/docs/reference/cloud-spanner/1.83.0/Batch.BatchClient)\n- [1.82.0](/php/docs/reference/cloud-spanner/1.82.0/Batch.BatchClient)\n- [1.81.0](/php/docs/reference/cloud-spanner/1.81.0/Batch.BatchClient)\n- [1.80.0](/php/docs/reference/cloud-spanner/1.80.0/Batch.BatchClient)\n- [1.79.0](/php/docs/reference/cloud-spanner/1.79.0/Batch.BatchClient)\n- [1.78.0](/php/docs/reference/cloud-spanner/1.78.0/Batch.BatchClient)\n- [1.77.0](/php/docs/reference/cloud-spanner/1.77.0/Batch.BatchClient)\n- [1.76.1](/php/docs/reference/cloud-spanner/1.76.1/Batch.BatchClient)\n- [1.68.0](/php/docs/reference/cloud-spanner/1.68.0/Batch.BatchClient)\n- [1.67.0](/php/docs/reference/cloud-spanner/1.67.0/Batch.BatchClient)\n- [1.66.0](/php/docs/reference/cloud-spanner/1.66.0/Batch.BatchClient)\n- [1.65.0](/php/docs/reference/cloud-spanner/1.65.0/Batch.BatchClient)\n- [1.64.0](/php/docs/reference/cloud-spanner/1.64.0/Batch.BatchClient)\n- [1.63.2](/php/docs/reference/cloud-spanner/1.63.2/Batch.BatchClient)\n- [1.62.1](/php/docs/reference/cloud-spanner/1.62.1/Batch.BatchClient)\n- [1.61.0](/php/docs/reference/cloud-spanner/1.61.0/Batch.BatchClient)\n- [1.60.0](/php/docs/reference/cloud-spanner/1.60.0/Batch.BatchClient)\n- [1.59.0](/php/docs/reference/cloud-spanner/1.59.0/Batch.BatchClient)\n- [1.58.4](/php/docs/reference/cloud-spanner/1.58.4/Batch.BatchClient)\n- [1.57.0](/php/docs/reference/cloud-spanner/1.57.0/Batch.BatchClient)\n- [1.56.0](/php/docs/reference/cloud-spanner/1.56.0/Batch.BatchClient)\n- [1.55.0](/php/docs/reference/cloud-spanner/1.55.0/Batch.BatchClient)\n- [1.54.2](/php/docs/reference/cloud-spanner/1.54.2/Batch.BatchClient) \nReference documentation and code samples for the Cloud Spanner Client class BatchClient.\n\nProvides Batch APIs used to read data from a Cloud Spanner database.\n\nBatch Clients are useful when one wants to read or query a large amount of\ndata from Cloud Spanner across multiple processes, even across multiple\nmachines. It allows creation of partitions of a Cloud Spanner database in\norder to facilitate reading or querying of each partition independently at\nthe same snapshot.\n\nExample: \n\n use Google\\Cloud\\Spanner\\SpannerClient;\n\n $spanner = new SpannerClient();\n $batch = $spanner-\u003ebatch('instance-id', 'database-id');\n\n // Using Cloud Pub/Sub to share partitions with workers\n use Google\\Cloud\\PubSub\\PubSubClient;\n\n $pubsub = new PubSubClient();\n $topic = $pubsub-\u003etopic('partition-queries');\n\n $snapshot = $batch-\u003esnapshot();\n\n // Executing a partition query will return a list of Partitions.\n $partitions = $snapshot-\u003epartitionQuery('SELECT * FROM Users WHERE firstName = %s AND location = %s', [\n 'parameters' =\u003e [\n 'firstName' =\u003e 'John',\n 'location' =\u003e 'USA'\n ]\n ]);\n\n // Each partition is published to Cloud Pub/Sub, where it can be executed by\n // a worker.\n foreach ($partitions as $partition) {\n $topic-\u003epublish([\n 'attributes' =\u003e [\n 'snapshot' =\u003e $snapshot-\u003eserialize(),\n 'partition' =\u003e $partition-\u003eserialize()\n ]\n ]);\n }\n\n // Once all workers have finished, we will close the snapshot.\n // The logic to determine whether the snapshot is no longer needed will vary\n // and is not implemented here.\n do {\n $finished = areWorkersDone();\n\n if ($finished) {\n $snapshot-\u003eclose();\n }\n } while(!$finished);\n\n // Using Cloud Pub/Sub to consume a partition and return a result.\n use Google\\Cloud\\PubSub\\PubSubClient;\n\n $pubsub = new PubSubClient();\n $subscription = $pubsub-\u003esubscription('partition-query-consumer');\n\n $messages = $subscription-\u003epull([\n 'returnImmediately' =\u003e true,\n 'maxMessages' =\u003e 1\n ]);\n\n if ($messages) {\n $message = $messages[0];\n $snapshot = $batch-\u003esnapshotFromString($message-\u003eattribute('snapshot'));\n $partition = $batch-\u003epartitionFromString($message-\u003eattribute('partition'));\n\n // Do something with the query result.\n processResult($snapshot-\u003eexecutePartition($partition));\n }\n\nNamespace\n---------\n\nGoogle \\\\ Cloud \\\\ Spanner \\\\ Batch\n\nMethods\n-------\n\n### __construct\n\n### snapshot\n\nCreate a batch snapshot.\n\nExample: \n\n $snapshot = $batch-\u003esnapshot();\n\n### snapshotFromString\n\nCreate a [BatchSnapshot](/php/docs/reference/cloud-spanner/latest/Batch.BatchSnapshot) from a snapshot\nidentifier.\n\nThis method can be used to deserialize a snapshot which is\nshared across multiple servers or processes.\n\nExample: \n\n $snapshot = $batch-\u003esnapshotFromString($snapshotString);\n\n### partitionFromString\n\nCreate a PartitionInterface instance.\n\nThis method can be used to deserialize a partition which is\nshared across multiple servers or processes.\n\nExample: \n\n $partition = $batch-\u003epartitionFromString($partitionString);\n\nConstants\n---------\n\n### PARTITION_TYPE_KEY\n\n Value: '__partitionTypeName'"]]