Cloud Spanner Client - Class Operation (1.80.0)

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

Common interface for running operations against Cloud Spanner. This class is intended for internal use by the client library only. Implementors should access these operations via Google\Cloud\Spanner\Database or Google\Cloud\Spanner\Transaction.

Usage examples may be found in classes making use of this class:

Namespace

Google \ Cloud \ Spanner

Methods

__construct

Parameters
Name Description
connection Google\Cloud\Spanner\Connection\ConnectionInterface

A connection to Google Cloud Spanner. This object is created by SpannerClient, and should not be instantiated outside of this client.

returnInt64AsObject bool

If true, 64 bit integers will be returned as a Google\Cloud\Core\Int64 object for 32 bit platform compatibility.

mutation

Create a formatted mutation.

Parameters
Name Description
operation string

The operation type.

table string

The table name.

mutation array

The mutation data, represented as a set of key/value pairs.

Returns
Type Description
array

deleteMutation

Create a formatted delete mutation.

Parameters
Name Description
table string

The table name.

keySet Google\Cloud\Spanner\KeySet

The keys to delete.

Returns
Type Description
array

commit

Commit all enqueued mutations.

Parameters
Name Description
session Google\Cloud\Spanner\Session\Session

The session ID to use for the commit.

mutations array

A list of mutations to apply.

options array

Configuration options.

↳ transactionId string

The ID of the transaction.

↳ returnCommitStats bool

If true, return the full response. Defaults to false.

↳ maxCommitDelay Duration

The amount of latency this request is willing to incur in order to improve throughput. Defaults to null.

↳ requestOptions array

Request options. For more information on available options, please see the upstream documentation. Please note, if using the priority setting you may utilize the constants available on Google\Cloud\Spanner\V1\RequestOptions\Priority to set a value.

Returns
Type Description
Google\Cloud\Spanner\Timestamp The commit Timestamp.

commitWithResponse

Parameters
Name Description
session Google\Cloud\Spanner\Session\Session

The session ID to use for the commit.

mutations array

A list of mutations to apply.

options array

Configuration options.

↳ transactionId string

The ID of the transaction.

↳ returnCommitStats bool

If true, return the full response. Defaults to false.

↳ maxCommitDelay Duration

The amount of latency this request is willing to incur in order to improve throughput. Defaults to null.

↳ requestOptions array

Request options. For more information on available options, please see the upstream documentation. Please note, if using the priority setting you may utilize the constants available on Google\Cloud\Spanner\V1\RequestOptions\Priority to set a value.

Returns
Type Description
array An array containing {@see \Google\Cloud\Spanner\Timestamp} at index 0 and the commit response as an array at index 1.

rollback

Rollback a Transaction.

Parameters
Name Description
session Google\Cloud\Spanner\Session\Session

The session to use for the rollback. Note that the session MUST be the same one in which the transaction was created.

transactionId string

The transaction to roll back.

options array

[optional] Configuration Options.

Returns
Type Description
void

execute

Run a query.

Parameters
Name Description
session Google\Cloud\Spanner\Session\Session

The session to use to execute the SQL.

sql string

The query string.

options array

Configuration options.

↳ requestOptions array

Request options. For more information on available options, please see the upstream documentation. Please note, if using the priority setting you may utilize the constants available on Google\Cloud\Spanner\V1\RequestOptions\Priority to set a value.

↳ transaction array

Transaction selector options.

↳ transaction array

.begin The begin transaction options. Refer

↳ directedReadOptions array

Directed read options. Google\Cloud\Spanner\V1\DirectedReadOptions If using the replicaSelection::type setting, utilize the constants available in Google\Cloud\Spanner\V1\DirectedReadOptions\ReplicaSelection\Type to set a value.

Returns
Type Description
Google\Cloud\Spanner\Result

executeUpdate

Execute a DML statement and return an affected row count.

Parameters
Name Description
session Google\Cloud\Spanner\Session\Session

The session in which the update operation should be executed.

transaction Google\Cloud\Spanner\Transaction

The transaction in which the operation should be executed.

sql string

The SQL string to execute.

options array

Configuration options.

↳ requestOptions array

Request options. For more information on available options, please see the upstream documentation. Please note, if using the priority setting you may utilize the constants available on Google\Cloud\Spanner\V1\RequestOptions\Priority to set a value.

↳ transaction array

Transaction selector options.

↳ transaction array

.begin The begin transaction options. Refer

Returns
Type Description
int

executeUpdateBatch

Execute multiple DML statements.

For detailed usage instructions, see Google\Cloud\Spanner\Transaction::executeUpdateBatch().

Parameters
Name Description
session Google\Cloud\Spanner\Session\Session

The session in which the update operation should be executed.

transaction Google\Cloud\Spanner\Transaction

The transaction in which the operation should be executed.

statements array[]

A list of DML statements to run. Each statement must contain a sql key, where the value is a DML string. If the DML contains placeholders, values are provided as a key/value array in key parameters. If parameter types are required, they must be provided in key paramTypes. Generally, Google Cloud PHP can infer types. Explicit type declarations are required in the case of struct parameters, or when a null value exists as a parameter. Accepted values for primitive types are defined as constants on Google\Cloud\Spanner\Database, 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. If the value is an array, use Google\Cloud\Spanner\ArrayType to declare the array parameter types. Likewise, for structs, use Google\Cloud\Spanner\StructType.

options array

Configuration Options.

↳ requestOptions array

Request options. For more information on available options, please see the upstream documentation. Please note, if using the priority setting you may utilize the constants available on Google\Cloud\Spanner\V1\RequestOptions\Priority to set a value.

↳ transaction array

Transaction selector options.

↳ transaction array

.begin The begin transaction options. Refer

Returns
Type Description
Google\Cloud\Spanner\BatchDmlResult

read

Lookup rows in a database.

Parameters
Name Description
session Google\Cloud\Spanner\Session\Session

The session in which to read data.

table string

The table name.

keySet Google\Cloud\Spanner\KeySet

The KeySet to select rows.

columns array

A list of column names to return.

options array

Configuration Options.

↳ index string

The name of an index on the table.

↳ offset int

The number of rows to offset results by.

↳ limit int

The number of results to return.

↳ requestOptions array

Request options. For more information on available options, please see the upstream documentation. Please note, if using the priority setting you may utilize the constants available on Google\Cloud\Spanner\V1\RequestOptions\Priority to set a value.

↳ transaction array

Transaction selector options.

↳ transaction array

.begin The begin transaction options. Refer

↳ directedReadOptions array

Directed read options. Google\Cloud\Spanner\V1\DirectedReadOptions If using the replicaSelection::type setting, utilize the constants available in Google\Cloud\Spanner\V1\DirectedReadOptions\ReplicaSelection\Type to set a value.

Returns
Type Description
Google\Cloud\Spanner\Result

transaction

Parameters
Name Description
session Google\Cloud\Spanner\Session\Session

The session to start the transaction in.

options array

Configuration Options.

↳ singleUse bool

If true, a Transaction ID will not be allocated up front. Instead, the transaction will be considered "single-use", and may be used for only a single operation. Defaults to false.

↳ isRetry bool

If true, the resulting transaction will indicate that it is the result of a retry operation. Defaults to false.

↳ begin array

The begin transaction options. Refer

Returns
Type Description
Google\Cloud\Spanner\Transaction

createTransaction

Create a Transaction instance from a response object.

Parameters
Name Description
session Google\Cloud\Spanner\Session\Session

The session the transaction belongs to.

res array

[optional] The createTransaction response.

options array

[optional] Options for the transaction object. @type array $begin The begin transaction options. Refer

Returns
Type Description
Google\Cloud\Spanner\Transaction

snapshot

Parameters
Name Description
session Google\Cloud\Spanner\Session\Session

The session to start the snapshot in.

options array

Configuration Options.

↳ singleUse bool

If true, a Transaction ID will not be allocated up front. Instead, the transaction will be considered "single-use", and may be used for only a single operation. Defaults to false.

↳ className string

If set, an instance of the given class will be instantiated. This setting is intended for internal use. Defaults to Google\Cloud\Spanner\Snapshot.

↳ directedReadOptions array

Directed read options. Google\Cloud\Spanner\V1\DirectedReadOptions If using the replicaSelection::type setting, utilize the constants available in Google\Cloud\Spanner\V1\DirectedReadOptions\ReplicaSelection\Type to set a value.

Returns
Type Description
mixed

createSnapshot

Create a Snapshot instance from a response object.

Parameters
Name Description
session Google\Cloud\Spanner\Session\Session

The session the snapshot belongs to.

res array

[optional] The createTransaction response.

className string

[optional] The class to instantiate with a snapshot. Defaults to Google\Cloud\Spanner\Snapshot.

Returns
Type Description
mixed

createSession

Create a new session.

Sessions are handled behind the scenes and this method does not need to be called directly.

Parameters
Name Description
databaseName string

The database name

options array

Configuration options.

↳ labels array

Labels to be applied to each session created in the pool. Label keys must be between 1 and 63 characters long and must conform to the following regular expression: [a-z]([-a-z0-9]*[a-z0-9])?. Label values must be between 0 and 63 characters long and must conform to the regular expression ([a-z]([-a-z0-9]*[a-z0-9])?)?. No more than 64 labels can be associated with a given session. See https://goo.gl/xmQnxf for more information on and examples of labels.

↳ creator_role string

The user created database role which creates the session.

Returns
Type Description
Google\Cloud\Spanner\Session\Session

session

Lazily instantiates a session. There are no network requests made at this point. To see the operations that can be performed on a session please see Google\Cloud\Spanner\Session\Session.

Sessions are handled behind the scenes and this method does not need to be called directly.

Parameter
Name Description
sessionName string

The session's name.

Returns
Type Description
Google\Cloud\Spanner\Session\Session

partitionQuery

Begin a partitioned SQL query.

Parameters
Name Description
session Google\Cloud\Spanner\Session\Session

The session to run in.

transactionId string

The transaction to run in.

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 be smaller than this maximum count request. 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].

Returns
Type Description
array<Google\Cloud\Spanner\Batch\QueryPartition>

partitionRead

Begin a partitioned read.

Parameters
Name Description
session Google\Cloud\Spanner\Session\Session

The session to run in.

transactionId string

The transaction to run in.

table string

The table name.

keySet Google\Cloud\Spanner\KeySet

The KeySet to select rows.

columns array

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 be smaller than this maximum count request. 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.

Returns
Type Description
array<Google\Cloud\Spanner\Batch\ReadPartition>

__debugInfo

Represent the class in a more readable and digestable fashion.

Constants

OP_INSERT

Value: 'insert'

OP_UPDATE

Value: 'update'

OP_INSERT_OR_UPDATE

Value: 'insertOrUpdate'

OP_REPLACE

Value: 'replace'

OP_DELETE

Value: 'delete'