Reference documentation and code samples for the Cloud Spanner Client class BatchSnapshot.
Represents a Read-Only Batch Transaction in Cloud Spanner.
Batch Snapshots can be shared with other servers or processes by casting the
object to a string, or by callingBatchSnapshot::serialize().
Please note that it is important that Snapshots are closed when they are no
longer needed. Closing a snapshot is accomplished by callingBatchSnapshot::close(). Snapshots should be
closed only after all workers have finished processing. Closing a snapshot
before all workers have processed will result in call failures.
Example:
use Google\Cloud\Spanner\SpannerClient;
$spanner = new SpannerClient();
$batch = $spanner->batch('instance-id', 'database-id');
$snapshot = $batch->snapshot();
// Serialize a snapshot to share it with another worker.
$snapshotString = (string) $snapshot;
// Calling BatchSnapshot::serialize() has the same effect.
$snapshotString = $snapshot->serialize();
The desired maximum number of partitions to return. For example, this may be set to the number of workers available. The maximum value is currently 200,000. This is only a hint. The actual number of partitions returned may not always match the requested value.Defaults to10000.
↳ partitionSizeBytes
int
The desired data size for each partition generated. This is only a hint. The actual size of each partition may be smaller or larger than this size request.Defaults to1000000000(i.e. 1 GiB).
↳ index
string
The name of an index on the table.
↳ dataBoostEnabled
bool
This is an optional parameter which can be used for partition read and query to execute the request via spanner independent compute resources.
use Google\Cloud\Spanner\Timestamp;
$queryString = 'SELECT * FROM Users WHERE joinDate < @joinDate AND lastLogin > @loginCutoff';
$partitions = $snapshot->partitionQuery($queryString, [
'parameters' => [
'joinDate' => new Timestamp(new \DateTime('2017-01-01')),
'loginDate' => new Timestamp(new \DateTime('2017-12-31'))
]
]);
Parameters
Name
Description
sql
string
The query string to execute.
options
array
Configuration Options
↳ maxPartitions
int
The desired maximum number of partitions to return. For example, this may be set to the number of workers available. The maximum value is currently 200,000. This is only a hint. The actual number of partitions returned may not always match the requested value.Defaults to10000.
↳ partitionSizeBytes
int
The desired data size for each partition generated. This is only a hint. The actual size of each partition may be smaller or larger than this size request.Defaults to1000000000(i.e. 1 GiB).
↳ parameters
array
A key/value array of Query Parameters, where the key is represented in the query string prefixed by a@symbol.
↳ types
array
A key/value array of Query Parameter types. Generally, Google Cloud PHP can infer types. Explicit type definitions are only necessary for null parameter values. Accepted values are defined as constants onGoogle\Cloud\Spanner\ValueMapper, and are as follows:Database::TYPE_BOOL,Database::TYPE_INT64,Database::TYPE_FLOAT64,Database::TYPE_TIMESTAMP,Database::TYPE_DATE,Database::TYPE_STRING,Database::TYPE_BYTES,Database::TYPE_ARRAYandDatabase::TYPE_STRUCT. If the parameter type is an array, the type should be given as an array, where the first element isDatabase::TYPE_ARRAYand the second element is the array type, for instance[Database::TYPE_ARRAY, Database::TYPE_INT64].
↳ dataBoostEnabled
bool
This is an optional parameter which can be used for partition read and query to execute the request via spanner independent compute resources.
[[["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 BatchSnapshot (1.104.0)\n\nVersion latestkeyboard_arrow_down\n\n- [1.104.0 (latest)](/php/docs/reference/cloud-spanner/latest/Batch.BatchSnapshot)\n- [1.103.0](/php/docs/reference/cloud-spanner/1.103.0/Batch.BatchSnapshot)\n- [1.102.0](/php/docs/reference/cloud-spanner/1.102.0/Batch.BatchSnapshot)\n- [1.101.0](/php/docs/reference/cloud-spanner/1.101.0/Batch.BatchSnapshot)\n- [1.100.0](/php/docs/reference/cloud-spanner/1.100.0/Batch.BatchSnapshot)\n- [1.98.0](/php/docs/reference/cloud-spanner/1.98.0/Batch.BatchSnapshot)\n- [1.97.0](/php/docs/reference/cloud-spanner/1.97.0/Batch.BatchSnapshot)\n- [1.96.0](/php/docs/reference/cloud-spanner/1.96.0/Batch.BatchSnapshot)\n- [1.95.0](/php/docs/reference/cloud-spanner/1.95.0/Batch.BatchSnapshot)\n- [1.94.0](/php/docs/reference/cloud-spanner/1.94.0/Batch.BatchSnapshot)\n- [1.93.1](/php/docs/reference/cloud-spanner/1.93.1/Batch.BatchSnapshot)\n- [1.92.1](/php/docs/reference/cloud-spanner/1.92.1/Batch.BatchSnapshot)\n- [1.91.0](/php/docs/reference/cloud-spanner/1.91.0/Batch.BatchSnapshot)\n- [1.90.0](/php/docs/reference/cloud-spanner/1.90.0/Batch.BatchSnapshot)\n- [1.89.0](/php/docs/reference/cloud-spanner/1.89.0/Batch.BatchSnapshot)\n- [1.88.0](/php/docs/reference/cloud-spanner/1.88.0/Batch.BatchSnapshot)\n- [1.87.0](/php/docs/reference/cloud-spanner/1.87.0/Batch.BatchSnapshot)\n- [1.86.0](/php/docs/reference/cloud-spanner/1.86.0/Batch.BatchSnapshot)\n- [1.85.0](/php/docs/reference/cloud-spanner/1.85.0/Batch.BatchSnapshot)\n- [1.84.0](/php/docs/reference/cloud-spanner/1.84.0/Batch.BatchSnapshot)\n- [1.83.0](/php/docs/reference/cloud-spanner/1.83.0/Batch.BatchSnapshot)\n- [1.82.0](/php/docs/reference/cloud-spanner/1.82.0/Batch.BatchSnapshot)\n- [1.81.0](/php/docs/reference/cloud-spanner/1.81.0/Batch.BatchSnapshot)\n- [1.80.0](/php/docs/reference/cloud-spanner/1.80.0/Batch.BatchSnapshot)\n- [1.79.0](/php/docs/reference/cloud-spanner/1.79.0/Batch.BatchSnapshot)\n- [1.78.0](/php/docs/reference/cloud-spanner/1.78.0/Batch.BatchSnapshot)\n- [1.77.0](/php/docs/reference/cloud-spanner/1.77.0/Batch.BatchSnapshot)\n- [1.76.1](/php/docs/reference/cloud-spanner/1.76.1/Batch.BatchSnapshot)\n- [1.68.0](/php/docs/reference/cloud-spanner/1.68.0/Batch.BatchSnapshot)\n- [1.67.0](/php/docs/reference/cloud-spanner/1.67.0/Batch.BatchSnapshot)\n- [1.66.0](/php/docs/reference/cloud-spanner/1.66.0/Batch.BatchSnapshot)\n- [1.65.0](/php/docs/reference/cloud-spanner/1.65.0/Batch.BatchSnapshot)\n- [1.64.0](/php/docs/reference/cloud-spanner/1.64.0/Batch.BatchSnapshot)\n- [1.63.2](/php/docs/reference/cloud-spanner/1.63.2/Batch.BatchSnapshot)\n- [1.62.1](/php/docs/reference/cloud-spanner/1.62.1/Batch.BatchSnapshot)\n- [1.61.0](/php/docs/reference/cloud-spanner/1.61.0/Batch.BatchSnapshot)\n- [1.60.0](/php/docs/reference/cloud-spanner/1.60.0/Batch.BatchSnapshot)\n- [1.59.0](/php/docs/reference/cloud-spanner/1.59.0/Batch.BatchSnapshot)\n- [1.58.4](/php/docs/reference/cloud-spanner/1.58.4/Batch.BatchSnapshot)\n- [1.57.0](/php/docs/reference/cloud-spanner/1.57.0/Batch.BatchSnapshot)\n- [1.56.0](/php/docs/reference/cloud-spanner/1.56.0/Batch.BatchSnapshot)\n- [1.55.0](/php/docs/reference/cloud-spanner/1.55.0/Batch.BatchSnapshot)\n- [1.54.2](/php/docs/reference/cloud-spanner/1.54.2/Batch.BatchSnapshot) \nReference documentation and code samples for the Cloud Spanner Client class BatchSnapshot.\n\nRepresents a Read-Only Batch Transaction in Cloud Spanner.\n\nBatch Snapshots can be shared with other servers or processes by casting the\nobject to a string, or by calling [BatchSnapshot::serialize()](/php/docs/reference/cloud-spanner/latest/Batch.BatchSnapshot#_Google_Cloud_Spanner_Batch_BatchSnapshot__serialize__).\n\nPlease note that it is important that Snapshots are closed when they are no\nlonger needed. Closing a snapshot is accomplished by calling\n[BatchSnapshot::close()](/php/docs/reference/cloud-spanner/latest/Batch.BatchSnapshot#_Google_Cloud_Spanner_Batch_BatchSnapshot__close__). Snapshots should be\nclosed only after all workers have finished processing. Closing a snapshot\nbefore all workers have processed will result in call failures.\n\nExample: \n\n use Google\\Cloud\\Spanner\\SpannerClient;\n\n $spanner = new SpannerClient();\n $batch = $spanner-\u003ebatch('instance-id', 'database-id');\n $snapshot = $batch-\u003esnapshot();\n\n // Serialize a snapshot to share it with another worker.\n $snapshotString = (string) $snapshot;\n\n // Calling BatchSnapshot::serialize() has the same effect.\n $snapshotString = $snapshot-\u003eserialize();\n\nNamespace\n---------\n\nGoogle \\\\ Cloud \\\\ Spanner \\\\ Batch\n\nMethods\n-------\n\n### __construct\n\n### close\n\nCloses all open resources.\n\nWhen the snapshot is no longer needed, it is important to call this method\nto free up resources allocated by the Batch Client.\n\nMethods on this instance which make service calls will fail if the snapshot\nhas been closed.\n\nExample: \n\n $snapshot-\u003eclose();\n\n### partitionRead\n\nBegin a partitioned read.\n\nExample: \n\n use Google\\Cloud\\Spanner\\KeySet;\n\n $keySet = new KeySet(['all' =\u003e true]);\n $columns = ['id', 'firstName', 'lastName'];\n $partitions = $snapshot-\u003epartitionRead('Users', $keySet, $columns);\n\n### partitionQuery\n\nBegin a partitioned SQL query.\n\nExample: \n\n use Google\\Cloud\\Spanner\\Timestamp;\n\n $queryString = 'SELECT * FROM Users WHERE joinDate \u003c @joinDate AND lastLogin \u003e @loginCutoff';\n $partitions = $snapshot-\u003epartitionQuery($queryString, [\n 'parameters' =\u003e [\n 'joinDate' =\u003e new Timestamp(new \\DateTime('2017-01-01')),\n 'loginDate' =\u003e new Timestamp(new \\DateTime('2017-12-31'))\n ]\n ]);\n\n### executePartition\n\nRead rows from a partition.\n\nPartitions are created by calling [BatchSnapshot::partitionRead()](/php/docs/reference/cloud-spanner/latest/Batch.BatchSnapshot#_Google_Cloud_Spanner_Batch_BatchSnapshot__partitionRead__)\nor [BatchSnapshot::partitionQuery()](/php/docs/reference/cloud-spanner/latest/Batch.BatchSnapshot#_Google_Cloud_Spanner_Batch_BatchSnapshot__partitionQuery__).\nGenerally, those partitions will be distributed to worker processes, each\nof which will call this method with the partition it was given.\n\nExample: \n\n $result = $snapshot-\u003eexecutePartition($partition);\n\n### serialize\n\nReturn a stringified representation of the BatchSnapshot object.\n\nExample: \n\n $snapshotString = $snapshot-\u003eserialize();\n\n### __toString\n\nCast the snapshot to a string."]]
