Cloud Spanner Client - Class BatchSnapshot (1.77.0)

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 calling Google\Cloud\Spanner\Batch\BatchSnapshot::serialize().

Please note that it is important that Snapshots are closed when they are no longer needed. Closing a snapshot is accomplished by calling Google\Cloud\Spanner\Batch\BatchSnapshot::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();

Namespace

Google \ Cloud \ Spanner \ Batch

Methods

__construct

Parameters
Name Description
operation Google\Cloud\Spanner\Operation

The Operation instance.
session Google\Cloud\Spanner\Session\Session

The session to use for spanner interactions.
options array

Configuration Options.
↳ id string

The Transaction ID.
↳ readTimestamp Timestamp

The read timestamp.

close

Closes all open resources.

When the snapshot is no longer needed, it is important to call this method to free up resources allocated by the Batch Client.

Methods on this instance which make service calls will fail if the snapshot has been closed.

Example:

$snapshot->close();
Parameter
Name Description
options array

[optional] Configuration Options
Returns
Type Description
void

partitionRead

Begin a partitioned read.

Example:

use Google\Cloud\Spanner\KeySet;

$keySet = new KeySet(['all' => true]);
$columns = ['id', 'firstName', 'lastName'];
$partitions = $snapshot->partitionRead('Users', $keySet, $columns);
Parameters
Name Description
table string

The table name.
keySet Google\Cloud\Spanner\KeySet

The KeySet to select rows.
columns string[]

A list of column names to return.
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 to 10000.
↳ 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 to 1000000000 (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.
Returns
Type Description
array<Google\Cloud\Spanner\Batch\ReadPartition>

partitionQuery

Begin a partitioned SQL query.

Example:

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 to 10000.
↳ 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 to 1000000000 (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 on Google\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_ARRAY and Database::TYPE_STRUCT. If the parameter type is an array, the type should be given as an array, where the first element is Database::TYPE_ARRAY and 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.
Returns
Type Description
array<Google\Cloud\Spanner\Batch\QueryPartition>

executePartition

Read rows from a partition.

Partitions are created by calling Google\Cloud\Spanner\Batch\BatchSnapshot::partitionRead() or Google\Cloud\Spanner\Batch\BatchSnapshot::partitionQuery(). Generally, those partitions will be distributed to worker processes, each of which will call this method with the partition it was given.

Example:

$result = $snapshot->executePartition($partition);
Parameters
Name Description
partition Google\Cloud\Spanner\Batch\PartitionInterface

The partition to read.
options array

Configuration Options.
Returns
Type Description
Google\Cloud\Spanner\Result

serialize

Return a stringified representation of the BatchSnapshot object.

Example:

$snapshotString = $snapshot->serialize();
Returns
Type Description
string

__toString

Cast the snapshot to a string.

Returns
Type Description
string