Cloud Spanner Client - Class Operation (1.76.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

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

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'

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