Blame - docs/dyn/spanner_v1.projects.instances.databases.sessions.html - platform/external/python/google-api-python-client

2019-06-14 16:50:42 -0700

[diff] [blame]

84

<code><a href="#create">create(database, body, x__xgafv=None)</a></code></p>

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

85

<p class="firstline">Creates a new session. A session can be used to perform</p>

86

87

<code><a href="#delete">delete(name, x__xgafv=None)</a></code></p>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

88

<p class="firstline">Ends a session, releasing server resources associated with it. This will</p>

89

90

<code><a href="#executeBatchDml">executeBatchDml(session, body, x__xgafv=None)</a></code></p>

91

<p class="firstline">Executes a batch of SQL DML statements. This method allows many statements</p>

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

92

93

<code><a href="#executeSql">executeSql(session, body, x__xgafv=None)</a></code></p>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

94

<p class="firstline">Executes an SQL statement, returning all results in a single reply. This</p>

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

95

96

<code><a href="#executeStreamingSql">executeStreamingSql(session, body, x__xgafv=None)</a></code></p>

97

<p class="firstline">Like ExecuteSql, except returns the result</p>

98

99

<code><a href="#get">get(name, x__xgafv=None)</a></code></p>

100

<p class="firstline">Gets a session. Returns `NOT_FOUND` if the session does not exist.</p>

101

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

102

<code><a href="#list">list(database, pageSize=None, filter=None, pageToken=None, x__xgafv=None)</a></code></p>

103

<p class="firstline">Lists all sessions in a given database.</p>

104

105

<code><a href="#list_next">list_next(previous_request, previous_response)</a></code></p>

106

<p class="firstline">Retrieves the next page of results.</p>

107

108

<code><a href="#partitionQuery">partitionQuery(session, body, x__xgafv=None)</a></code></p>

109

<p class="firstline">Creates a set of partition tokens that can be used to execute a query</p>

110

111

<code><a href="#partitionRead">partitionRead(session, body, x__xgafv=None)</a></code></p>

112

<p class="firstline">Creates a set of partition tokens that can be used to execute a read</p>

113

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

114

<code><a href="#read">read(session, body, x__xgafv=None)</a></code></p>

115

<p class="firstline">Reads rows from the database using key lookups and scans, as a</p>

116

117

<code><a href="#rollback">rollback(session, body, x__xgafv=None)</a></code></p>

118

<p class="firstline">Rolls back a transaction, releasing any locks it holds. It is a good</p>

119

120

<code><a href="#streamingRead">streamingRead(session, body, x__xgafv=None)</a></code></p>

121

<p class="firstline">Like Read, except returns the result set as a</p>

122

<h3>Method Details</h3>

123

124

<code class="details" id="beginTransaction">beginTransaction(session, body, x__xgafv=None)</code>

125

<pre>Begins a new transaction. This step can often be skipped:

126

Read, ExecuteSql and

127

Commit can begin a new transaction as a

side-effect.

Args:

session: string, Required. The session in which the transaction runs. (required)

132

body: object, The request body. (required)

133

The object takes the form of:

134

135

{ # The request for BeginTransaction.

136

"options": { # # Transactions # Required. Options for the new transaction.

137

#

138

#

139

# Each session can have at most one active transaction at a time. After the

140

# active transaction is completed, the session can immediately be

141

# re-used for the next transaction. It is not necessary to create a

142

# new session for each transaction.

143

#

144

# # Transaction Modes

145

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

146

# Cloud Spanner supports three transaction modes:

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

147

#

148

# 1. Locking read-write. This type of transaction is the only way

149

# to write data into Cloud Spanner. These transactions rely on

150

# pessimistic locking and, if necessary, two-phase commit.

151

# Locking read-write transactions may abort, requiring the

152

# application to retry.

153

#

154

# 2. Snapshot read-only. This transaction type provides guaranteed

155

# consistency across several reads, but does not allow

156

# writes. Snapshot read-only transactions can be configured to

157

# read at timestamps in the past. Snapshot read-only

158

# transactions do not need to be committed.

159

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

160

# 3. Partitioned DML. This type of transaction is used to execute

161

# a single Partitioned DML statement. Partitioned DML partitions

162

# the key space and runs the DML statement over each partition

163

# in parallel using separate, internal transactions that commit

164

# independently. Partitioned DML transactions do not need to be

165

# committed.

166

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

167

# For transactions that only read, snapshot read-only transactions

168

# provide simpler semantics and are almost always faster. In

169

# particular, read-only transactions do not take locks, so they do

170

# not conflict with read-write transactions. As a consequence of not

171

# taking locks, they also do not abort, so retry loops are not needed.

172

#

173

# Transactions may only read/write data in a single database. They

174

# may, however, read/write data in different tables within that

175

# database.

176

#

177

# ## Locking Read-Write Transactions

178

#

179

# Locking transactions may be used to atomically read-modify-write

180

# data anywhere in a database. This type of transaction is externally

181

# consistent.

182

#

183

# Clients should attempt to minimize the amount of time a transaction

184

# is active. Faster transactions commit with higher probability

185

# and cause less contention. Cloud Spanner attempts to keep read locks

186

# active as long as the transaction continues to do reads, and the

187

# transaction has not been terminated by

188

# Commit or

189

# Rollback. Long periods of

190

# inactivity at the client may cause Cloud Spanner to release a

191

# transaction's locks and abort it.

192

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

193

# Conceptually, a read-write transaction consists of zero or more

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

194

# reads or SQL statements followed by

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

195

# Commit. At any time before

196

# Commit, the client can send a

197

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

203

# are still valid at commit time, and it is able to acquire write

204

# locks for all writes. Cloud Spanner can abort the transaction for any

205

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

206

# that the transaction has not modified any user data in Cloud Spanner.

207

#

208

# Unless the transaction commits, Cloud Spanner makes no guarantees about

209

# how long the transaction's locks were held for. It is an error to

210

# use Cloud Spanner locks for any sort of mutual exclusion other than

211

# between Cloud Spanner transactions themselves.

212

#

213

# ### Retrying Aborted Transactions

214

#

215

# When a transaction aborts, the application can choose to retry the

216

# whole transaction again. To maximize the chances of successfully

217

# committing the retry, the client should execute the retry in the

218

# same session as the original attempt. The original session's lock

219

# priority increases with each consecutive abort, meaning that each

220

# attempt has a slightly better chance of success than the previous.

221

#

222

# Under some circumstances (e.g., many transactions attempting to

223

# modify the same row(s)), a transaction can abort many times in a

224

# short period before successfully committing. Thus, it is not a good

225

# idea to cap the number of retries a transaction can attempt;

226

# instead, it is better to limit the total amount of wall time spent

227

# retrying.

228

#

229

# ### Idle Transactions

230

#

231

# A transaction is considered idle if it has no outstanding reads or

232

# SQL queries and has not started a read or SQL query within the last 10

233

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

234

# don't hold on to locks indefinitely. In that case, the commit will

235

# fail with error `ABORTED`.

236

#

237

# If this behavior is undesirable, periodically executing a simple

238

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

239

# transaction from becoming idle.

240

#

241

# ## Snapshot Read-Only Transactions

242

#

243

# Snapshot read-only transactions provides a simpler method than

244

# locking read-write transactions for doing several consistent

245

# reads. However, this type of transaction does not support writes.

246

#

247

# Snapshot transactions do not take locks. Instead, they work by

248

# choosing a Cloud Spanner timestamp, then executing all reads at that

249

# timestamp. Since they do not acquire locks, they do not block

250

# concurrent read-write transactions.

251

#

252

# Unlike locking read-write transactions, snapshot read-only

253

# transactions never abort. They can fail if the chosen read

254

# timestamp is garbage collected; however, the default garbage

255

# collection policy is generous enough that most applications do not

256

# need to worry about this in practice.

257

#

258

# Snapshot read-only transactions do not need to call

259

# Commit or

260

# Rollback (and in fact are not

261

# permitted to do so).

262

#

263

# To execute a snapshot transaction, the client specifies a timestamp

264

# bound, which tells Cloud Spanner how to choose a read timestamp.

265

#

266

# The types of timestamp bound are:

267

#

268

# - Strong (the default).

269

# - Bounded staleness.

270

# - Exact staleness.

271

#

272

# If the Cloud Spanner database to be read is geographically distributed,

273

# stale read-only transactions can execute more quickly than strong

274

# or read-write transaction, because they are able to execute far

275

# from the leader replica.

276

#

277

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

282

# that have committed before the start of the read. Furthermore, all

283

# rows yielded by a single read are consistent with each other -- if

284

# any part of the read observes a transaction, all parts of the read

285

# see the transaction.

286

#

287

# Strong reads are not repeatable: two consecutive strong read-only

288

# transactions might return inconsistent results if there are

289

# concurrent writes. If consistency across reads is required, the

290

# reads should be executed within a transaction or at an exact read

291

# timestamp.

292

#

293

# See TransactionOptions.ReadOnly.strong.

294

#

295

# ### Exact Staleness

296

#

297

# These timestamp bounds execute reads at a user-specified

298

# timestamp. Reads at a timestamp are guaranteed to see a consistent

299

# prefix of the global transaction history: they observe

300

# modifications done by all transactions with a commit timestamp <=

301

# the read timestamp, and observe none of the modifications done by

302

# transactions with a larger commit timestamp. They will block until

303

# all conflicting transactions that may be assigned commit timestamps

304

# <= the read timestamp have finished.

305

#

306

# The timestamp can either be expressed as an absolute Cloud Spanner commit

307

# timestamp or a staleness relative to the current time.

308

#

309

# These modes do not require a "negotiation phase" to pick a

310

# timestamp. As a result, they execute slightly faster than the

311

# equivalent boundedly stale concurrency modes. On the other hand,

312

# boundedly stale reads usually return fresher results.

313

#

314

# See TransactionOptions.ReadOnly.read_timestamp and

315

# TransactionOptions.ReadOnly.exact_staleness.

316

#

317

# ### Bounded Staleness

318

#

319

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

320

# subject to a user-provided staleness bound. Cloud Spanner chooses the

321

# newest timestamp within the staleness bound that allows execution

322

# of the reads at the closest available replica without blocking.

323

#

324

# All rows yielded are consistent with each other -- if any part of

325

# the read observes a transaction, all parts of the read see the

326

# transaction. Boundedly stale reads are not repeatable: two stale

327

# reads, even if they use the same staleness bound, can execute at

328

# different timestamps and thus return inconsistent results.

329

#

330

# Boundedly stale reads execute in two phases: the first phase

331

# negotiates a timestamp among all replicas needed to serve the

332

# read. In the second phase, reads are executed at the negotiated

333

# timestamp.

334

#

335

# As a result of the two phase execution, bounded staleness reads are

336

# usually a little slower than comparable exact staleness

337

# reads. However, they are typically able to return fresher

338

# results, and are more likely to execute at the closest replica.

339

#

340

# Because the timestamp negotiation requires up-front knowledge of

341

# which rows will be read, it can only be used with single-use

342

# read-only transactions.

343

#

344

# See TransactionOptions.ReadOnly.max_staleness and

345

# TransactionOptions.ReadOnly.min_read_timestamp.

346

#

347

# ### Old Read Timestamps and Garbage Collection

348

#

349

# Cloud Spanner continuously garbage collects deleted and overwritten data

350

# in the background to reclaim storage space. This process is known

351

# as "version GC". By default, version GC reclaims versions after they

352

# are one hour old. Because of this, Cloud Spanner cannot perform reads

353

# at read timestamps more than one hour in the past. This

354

# restriction also applies to in-progress reads and/or SQL queries whose

355

# timestamp become too old while executing. Reads and SQL queries with

356

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

357

#

358

# ## Partitioned DML Transactions

359

#

360

# Partitioned DML transactions are used to execute DML statements with a

361

# different execution strategy that provides different, and often better,

362

# scalability properties for large, table-wide operations than DML in a

363

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

364

# should prefer using ReadWrite transactions.

365

#

366

# Partitioned DML partitions the keyspace and runs the DML statement on each

367

# partition in separate, internal transactions. These transactions commit

368

# automatically when complete, and run independently from one another.

369

#

370

# To reduce lock contention, this execution strategy only acquires read locks

371

# on rows that match the WHERE clause of the statement. Additionally, the

372

# smaller per-partition transactions hold locks for less time.

373

#

374

# That said, Partitioned DML is not a drop-in replacement for standard DML used

375

# in ReadWrite transactions.

376

#

377

# - The DML statement must be fully-partitionable. Specifically, the statement

378

# must be expressible as the union of many statements which each access only

379

# a single row of the table.

380

#

381

# - The statement is not applied atomically to all rows of the table. Rather,

382

# the statement is applied atomically to partitions of the table, in

383

# independent transactions. Secondary index rows are updated atomically

384

# with the base table rows.

385

#

386

# - Partitioned DML does not guarantee exactly-once execution semantics

387

# against a partition. The statement will be applied at least once to each

388

# partition. It is strongly recommended that the DML statement should be

389

# idempotent to avoid unexpected results. For instance, it is potentially

390

# dangerous to run a statement such as

391

# `UPDATE table SET column = column + 1` as it could be run multiple times

392

# against some rows.

393

#

394

# - The partitions are committed automatically - there is no support for

395

# Commit or Rollback. If the call returns an error, or if the client issuing

396

# the ExecuteSql call dies, it is possible that some rows had the statement

397

# executed on them successfully. It is also possible that statement was

398

# never executed against other rows.

399

#

400

# - Partitioned DML transactions may only contain the execution of a single

401

# DML statement via ExecuteSql or ExecuteStreamingSql.

402

#

403

# - If any error is encountered during the execution of the partitioned DML

404

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

405

# value that cannot be stored due to schema constraints), then the

406

# operation is stopped at that point and an error is returned. It is

407

# possible that at this point, some partitions have been committed (or even

408

# committed multiple times), and other partitions have not been run at all.

409

#

410

# Given the above, Partitioned DML is good fit for large, database-wide,

411

# operations that are idempotent, such as deleting old rows from a very large

412

# table.

413

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

414

#

415

# Authorization to begin a read-write transaction requires

416

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

417

# on the `session` resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

418

# transaction type has no options.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

419

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

420

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

421

#

422

# Authorization to begin a read-only transaction requires

423

# `spanner.databases.beginReadOnlyTransaction` permission

424

# on the `session` resource.

425

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

426

#

427

# This is useful for requesting fresher data than some previous

428

# read, or data that is fresh enough to observe the effects of some

429

# previously committed transaction whose timestamp is known.

430

#

431

# Note that this option can only be used in single-use transactions.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

432

#

433

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

434

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

435

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

436

# the Transaction message that describes the transaction.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

437

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

438

# seconds. Guarantees that all writes that have committed more

439

# than the specified number of seconds ago are visible. Because

440

# Cloud Spanner chooses the exact timestamp, this mode works even if

441

# the client's local clock is substantially skewed from Cloud Spanner

442

# commit timestamps.

443

#

444

# Useful for reading the freshest data available at a nearby

445

# replica, while bounding the possible staleness if the local

446

# replica has fallen behind.

447

#

448

# Note that this option can only be used in single-use

449

# transactions.

450

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

451

# old. The timestamp is chosen soon after the read is started.

452

#

453

# Guarantees that all writes that have committed more than the

454

# specified number of seconds ago are visible. Because Cloud Spanner

455

# chooses the exact timestamp, this mode works even if the client's

456

# local clock is substantially skewed from Cloud Spanner commit

457

# timestamps.

458

#

459

# Useful for reading at nearby replicas without the distributed

460

# timestamp negotiation overhead of `max_staleness`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

461

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

462

# reads at a specific timestamp are repeatable; the same read at

463

# the same timestamp always returns the same data. If the

464

# timestamp is in the future, the read will block until the

465

# specified timestamp, modulo the read's deadline.

466

#

467

# Useful for large scale consistent reads such as mapreduces, or

468

# for coordinating many reads against a consistent snapshot of the

469

# data.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

470

#

471

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

472

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

473

"strong": True or False, # Read at a timestamp where all previously committed transactions

474

# are visible.

475

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

476

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

477

#

478

# Authorization to begin a Partitioned DML transaction requires

479

# `spanner.databases.beginPartitionedDmlTransaction` permission

480

# on the `session` resource.

481

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

492

493

{ # A transaction.

494

"readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen

495

# for the transaction. Not returned by default: see

496

# TransactionOptions.ReadOnly.return_read_timestamp.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

497

#

498

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

499

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

500

"id": "A String", # `id` may be used to identify the transaction in subsequent

# Read,

# ExecuteSql,

# Commit, or

# Rollback calls.

#

# Single-use read-only transactions do not have IDs, because

507

# single-use transactions do not support multiple requests.

}</pre>

</div>

<code class="details" id="commit">commit(session, body, x__xgafv=None)</code>

513

<pre>Commits a transaction. The request includes the mutations to be

514

applied to rows in the database.

515

516

`Commit` might return an `ABORTED` error. This can occur at any time;

517

commonly, the cause is conflicts with concurrent

518

transactions. However, it can also happen for a variety of other

519

reasons. If `Commit` returns `ABORTED`, the caller should re-attempt

520

the transaction from the beginning, re-using the same session.

521

522

Args:

523

session: string, Required. The session in which the transaction to be committed is running. (required)

524

body: object, The request body. (required)

525

The object takes the form of:

526

527

{ # The request for Commit.

528

"transactionId": "A String", # Commit a previously-started transaction.

529

"mutations": [ # The mutations to be executed when this transaction commits. All

530

# mutations are applied atomically, in the order they appear in

531

# this list.

532

{ # A modification to one or more Cloud Spanner rows. Mutations can be

533

# applied to a Cloud Spanner database by sending them in a

534

# Commit call.

535

"insert": { # Arguments to insert, update, insert_or_update, and # Insert new rows in a table. If any of the rows already exist,

536

# the write or transaction fails with error `ALREADY_EXISTS`.

537

# replace operations.

538

"table": "A String", # Required. The table whose rows will be written.

539

"values": [ # The values to be written. `values` can contain more than one

540

# list of values. If it does, then multiple rows are written, one

541

# for each entry in `values`. Each list in `values` must have

542

# exactly as many entries as there are entries in columns

543

# above. Sending multiple lists is equivalent to sending multiple

544

# `Mutation`s, each containing one `values` entry and repeating

545

# table and columns. Individual values in each list are

546

# encoded as described here.

[

"",

],

],

"columns": [ # The names of the columns in table to be written.

552

#

553

# The list of columns must contain enough columns to allow

554

# Cloud Spanner to derive values for all primary key columns in the

555

# row(s) to be modified.

556

"A String",

557

],

558

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

559

"replace": { # Arguments to insert, update, insert_or_update, and # Like insert, except that if the row already exists, it is

560

# deleted, and the column values provided are inserted

561

# instead. Unlike insert_or_update, this means any values not

562

# explicitly written become `NULL`.

563

# replace operations.

564

"table": "A String", # Required. The table whose rows will be written.

565

"values": [ # The values to be written. `values` can contain more than one

566

# list of values. If it does, then multiple rows are written, one

567

# for each entry in `values`. Each list in `values` must have

568

# exactly as many entries as there are entries in columns

569

# above. Sending multiple lists is equivalent to sending multiple

570

# `Mutation`s, each containing one `values` entry and repeating

571

# table and columns. Individual values in each list are

572

# encoded as described here.

[

"",

],

],

"columns": [ # The names of the columns in table to be written.

578

#

579

# The list of columns must contain enough columns to allow

580

# Cloud Spanner to derive values for all primary key columns in the

581

# row(s) to be modified.

582

"A String",

583

],

584

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

585

"insertOrUpdate": { # Arguments to insert, update, insert_or_update, and # Like insert, except that if the row already exists, then

586

# its column values are overwritten with the ones provided. Any

587

# column values not explicitly written are preserved.

588

# replace operations.

589

"table": "A String", # Required. The table whose rows will be written.

590

"values": [ # The values to be written. `values` can contain more than one

591

# list of values. If it does, then multiple rows are written, one

592

# for each entry in `values`. Each list in `values` must have

593

# exactly as many entries as there are entries in columns

594

# above. Sending multiple lists is equivalent to sending multiple

595

# `Mutation`s, each containing one `values` entry and repeating

596

# table and columns. Individual values in each list are

597

# encoded as described here.

[

"",

],

],

"columns": [ # The names of the columns in table to be written.

603

#

604

# The list of columns must contain enough columns to allow

605

# Cloud Spanner to derive values for all primary key columns in the

606

# row(s) to be modified.

"A String",

],

},

"update": { # Arguments to insert, update, insert_or_update, and # Update existing rows in a table. If any of the rows does not

611

# already exist, the transaction fails with error `NOT_FOUND`.

612

# replace operations.

613

"table": "A String", # Required. The table whose rows will be written.

614

"values": [ # The values to be written. `values` can contain more than one

615

# list of values. If it does, then multiple rows are written, one

616

# for each entry in `values`. Each list in `values` must have

617

# exactly as many entries as there are entries in columns

618

# above. Sending multiple lists is equivalent to sending multiple

619

# `Mutation`s, each containing one `values` entry and repeating

620

# table and columns. Individual values in each list are

621

# encoded as described here.

[

"",

],

],

"columns": [ # The names of the columns in table to be written.

627

#

628

# The list of columns must contain enough columns to allow

629

# Cloud Spanner to derive values for all primary key columns in the

630

# row(s) to be modified.

631

"A String",

632

],

633

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

634

"delete": { # Arguments to delete operations. # Delete rows from a table. Succeeds whether or not the named

635

# rows were present.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

636

"table": "A String", # Required. The table whose rows will be deleted.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

637

"keySet": { # `KeySet` defines a collection of Cloud Spanner keys and/or key ranges. All # Required. The primary keys of the rows within table to delete.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

638

# Delete is idempotent. The transaction will succeed even if some or all

639

# rows do not exist.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

640

# the keys are expected to be in the same table or index. The keys need

641

# not be sorted in any particular way.

642

#

643

# If the same key is specified multiple times in the set (for example

644

# if two ranges, two keys, or a key and a range overlap), Cloud Spanner

645

# behaves as if the key were only specified once.

646

"ranges": [ # A list of key ranges. See KeyRange for more information about

647

# key range specifications.

648

{ # KeyRange represents a range of rows in a table or index.

649

#

650

# A range has a start key and an end key. These keys can be open or

651

# closed, indicating if the range includes rows with that key.

652

#

653

# Keys are represented by lists, where the ith value in the list

654

# corresponds to the ith component of the table or index primary key.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

655

# Individual values are encoded as described

656

# here.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

657

#

658

# For example, consider the following table definition:

659

#

660

# CREATE TABLE UserEvents (

661

# UserName STRING(MAX),

662

# EventDate STRING(10)

663

# ) PRIMARY KEY(UserName, EventDate);

664

#

665

# The following keys name rows in this table:

666

#

667

# "Bob", "2014-09-23"

668

#

669

# Since the `UserEvents` table's `PRIMARY KEY` clause names two

670

# columns, each `UserEvents` key has two elements; the first is the

671

# `UserName`, and the second is the `EventDate`.

672

#

673

# Key ranges with multiple components are interpreted

674

# lexicographically by component using the table or index key's declared

675

# sort order. For example, the following range returns all events for

676

# user `"Bob"` that occurred in the year 2015:

677

#

678

# "start_closed": ["Bob", "2015-01-01"]

679

# "end_closed": ["Bob", "2015-12-31"]

680

#

681

# Start and end keys can omit trailing key components. This affects the

682

# inclusion and exclusion of rows that exactly match the provided key

683

# components: if the key is closed, then rows that exactly match the

684

# provided components are included; if the key is open, then rows

685

# that exactly match are not included.

686

#

687

# For example, the following range includes all events for `"Bob"` that

688

# occurred during and after the year 2000:

689

#

690

# "start_closed": ["Bob", "2000-01-01"]

691

# "end_closed": ["Bob"]

692

#

693

# The next example retrieves all events for `"Bob"`:

694

#

695

# "start_closed": ["Bob"]

696

# "end_closed": ["Bob"]

697

#

698

# To retrieve events before the year 2000:

699

#

700

# "start_closed": ["Bob"]

701

# "end_open": ["Bob", "2000-01-01"]

702

#

703

# The following range includes all rows in the table:

#

# "start_closed": []

# "end_closed": []

#

# This range returns all users whose `UserName` begins with any

709

# character from A to C:

710

#

711

# "start_closed": ["A"]

712

# "end_open": ["D"]

713

#

714

# This range returns all users whose `UserName` begins with B:

715

#

716

# "start_closed": ["B"]

717

# "end_open": ["C"]

718

#

719

# Key ranges honor column sort order. For example, suppose a table is

720

# defined as follows:

721

#

722

# CREATE TABLE DescendingSortedTable {

723

# Key INT64,

724

# ...

725

# ) PRIMARY KEY(Key DESC);

726

#

727

# The following range retrieves all rows with key values between 1

728

# and 100 inclusive:

729

#

730

# "start_closed": ["100"]

731

# "end_closed": ["1"]

732

#

733

# Note that 100 is passed as the start, and 1 is passed as the end,

734

# because `Key` is a descending column in the schema.

735

"endOpen": [ # If the end is open, then the range excludes rows whose first

736

# `len(end_open)` key columns exactly match `end_open`.

737

"",

738

],

739

"startOpen": [ # If the start is open, then the range excludes rows whose first

740

# `len(start_open)` key columns exactly match `start_open`.

741

"",

742

],

743

"endClosed": [ # If the end is closed, then the range includes all rows whose

744

# first `len(end_closed)` key columns exactly match `end_closed`.

745

"",

746

],

747

"startClosed": [ # If the start is closed, then the range includes all rows whose

748

# first `len(start_closed)` key columns exactly match `start_closed`.

"",

],

},

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

753

"keys": [ # A list of specific keys. Entries in `keys` should have exactly as

754

# many elements as there are columns in the primary or index key

755

# with which this `KeySet` is used. Individual key values are

756

# encoded as described here.

[

"",

],

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

761

"all": True or False, # For convenience `all` can be set to `true` to indicate that this

762

# `KeySet` matches all keys in the table or index. Note that any keys

763

# specified in `keys` or `ranges` are only yielded once.

764

},

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

765

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

766

},

767

],

768

"singleUseTransaction": { # # Transactions # Execute mutations in a temporary transaction. Note that unlike

769

# commit of a previously-started transaction, commit with a

770

# temporary transaction is non-idempotent. That is, if the

771

# `CommitRequest` is sent to Cloud Spanner more than once (for

772

# instance, due to retries in the application, or in the

773

# transport library), it is possible that the mutations are

774

# executed more than once. If this is undesirable, use

775

# BeginTransaction and

# Commit instead.

#

#

# Each session can have at most one active transaction at a time. After the

780

# active transaction is completed, the session can immediately be

781

# re-used for the next transaction. It is not necessary to create a

782

# new session for each transaction.

783

#

784

# # Transaction Modes

785

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

786

# Cloud Spanner supports three transaction modes:

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

787

#

788

# 1. Locking read-write. This type of transaction is the only way

789

# to write data into Cloud Spanner. These transactions rely on

790

# pessimistic locking and, if necessary, two-phase commit.

791

# Locking read-write transactions may abort, requiring the

792

# application to retry.

793

#

794

# 2. Snapshot read-only. This transaction type provides guaranteed

795

# consistency across several reads, but does not allow

796

# writes. Snapshot read-only transactions can be configured to

797

# read at timestamps in the past. Snapshot read-only

798

# transactions do not need to be committed.

799

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

800

# 3. Partitioned DML. This type of transaction is used to execute

801

# a single Partitioned DML statement. Partitioned DML partitions

802

# the key space and runs the DML statement over each partition

803

# in parallel using separate, internal transactions that commit

804

# independently. Partitioned DML transactions do not need to be

805

# committed.

806

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

807

# For transactions that only read, snapshot read-only transactions

808

# provide simpler semantics and are almost always faster. In

809

# particular, read-only transactions do not take locks, so they do

810

# not conflict with read-write transactions. As a consequence of not

811

# taking locks, they also do not abort, so retry loops are not needed.

812

#

813

# Transactions may only read/write data in a single database. They

814

# may, however, read/write data in different tables within that

815

# database.

816

#

817

# ## Locking Read-Write Transactions

818

#

819

# Locking transactions may be used to atomically read-modify-write

820

# data anywhere in a database. This type of transaction is externally

821

# consistent.

822

#

823

# Clients should attempt to minimize the amount of time a transaction

824

# is active. Faster transactions commit with higher probability

825

# and cause less contention. Cloud Spanner attempts to keep read locks

826

# active as long as the transaction continues to do reads, and the

827

# transaction has not been terminated by

828

# Commit or

829

# Rollback. Long periods of

830

# inactivity at the client may cause Cloud Spanner to release a

831

# transaction's locks and abort it.

832

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

833

# Conceptually, a read-write transaction consists of zero or more

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

834

# reads or SQL statements followed by

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

835

# Commit. At any time before

836

# Commit, the client can send a

837

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

843

# are still valid at commit time, and it is able to acquire write

844

# locks for all writes. Cloud Spanner can abort the transaction for any

845

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

846

# that the transaction has not modified any user data in Cloud Spanner.

847

#

848

# Unless the transaction commits, Cloud Spanner makes no guarantees about

849

# how long the transaction's locks were held for. It is an error to

850

# use Cloud Spanner locks for any sort of mutual exclusion other than

851

# between Cloud Spanner transactions themselves.

852

#

853

# ### Retrying Aborted Transactions

854

#

855

# When a transaction aborts, the application can choose to retry the

856

# whole transaction again. To maximize the chances of successfully

857

# committing the retry, the client should execute the retry in the

858

# same session as the original attempt. The original session's lock

859

# priority increases with each consecutive abort, meaning that each

860

# attempt has a slightly better chance of success than the previous.

861

#

862

# Under some circumstances (e.g., many transactions attempting to

863

# modify the same row(s)), a transaction can abort many times in a

864

# short period before successfully committing. Thus, it is not a good

865

# idea to cap the number of retries a transaction can attempt;

866

# instead, it is better to limit the total amount of wall time spent

867

# retrying.

868

#

869

# ### Idle Transactions

870

#

871

# A transaction is considered idle if it has no outstanding reads or

872

# SQL queries and has not started a read or SQL query within the last 10

873

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

874

# don't hold on to locks indefinitely. In that case, the commit will

875

# fail with error `ABORTED`.

876

#

877

# If this behavior is undesirable, periodically executing a simple

878

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

879

# transaction from becoming idle.

880

#

881

# ## Snapshot Read-Only Transactions

882

#

883

# Snapshot read-only transactions provides a simpler method than

884

# locking read-write transactions for doing several consistent

885

# reads. However, this type of transaction does not support writes.

886

#

887

# Snapshot transactions do not take locks. Instead, they work by

888

# choosing a Cloud Spanner timestamp, then executing all reads at that

889

# timestamp. Since they do not acquire locks, they do not block

890

# concurrent read-write transactions.

891

#

892

# Unlike locking read-write transactions, snapshot read-only

893

# transactions never abort. They can fail if the chosen read

894

# timestamp is garbage collected; however, the default garbage

895

# collection policy is generous enough that most applications do not

896

# need to worry about this in practice.

897

#

898

# Snapshot read-only transactions do not need to call

899

# Commit or

900

# Rollback (and in fact are not

901

# permitted to do so).

902

#

903

# To execute a snapshot transaction, the client specifies a timestamp

904

# bound, which tells Cloud Spanner how to choose a read timestamp.

905

#

906

# The types of timestamp bound are:

907

#

908

# - Strong (the default).

909

# - Bounded staleness.

910

# - Exact staleness.

911

#

912

# If the Cloud Spanner database to be read is geographically distributed,

913

# stale read-only transactions can execute more quickly than strong

914

# or read-write transaction, because they are able to execute far

915

# from the leader replica.

916

#

917

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

922

# that have committed before the start of the read. Furthermore, all

923

# rows yielded by a single read are consistent with each other -- if

924

# any part of the read observes a transaction, all parts of the read

925

# see the transaction.

926

#

927

# Strong reads are not repeatable: two consecutive strong read-only

928

# transactions might return inconsistent results if there are

929

# concurrent writes. If consistency across reads is required, the

930

# reads should be executed within a transaction or at an exact read

931

# timestamp.

932

#

933

# See TransactionOptions.ReadOnly.strong.

934

#

935

# ### Exact Staleness

936

#

937

# These timestamp bounds execute reads at a user-specified

938

# timestamp. Reads at a timestamp are guaranteed to see a consistent

939

# prefix of the global transaction history: they observe

940

# modifications done by all transactions with a commit timestamp <=

941

# the read timestamp, and observe none of the modifications done by

942

# transactions with a larger commit timestamp. They will block until

943

# all conflicting transactions that may be assigned commit timestamps

944

# <= the read timestamp have finished.

945

#

946

# The timestamp can either be expressed as an absolute Cloud Spanner commit

947

# timestamp or a staleness relative to the current time.

948

#

949

# These modes do not require a "negotiation phase" to pick a

950

# timestamp. As a result, they execute slightly faster than the

951

# equivalent boundedly stale concurrency modes. On the other hand,

952

# boundedly stale reads usually return fresher results.

953

#

954

# See TransactionOptions.ReadOnly.read_timestamp and

955

# TransactionOptions.ReadOnly.exact_staleness.

956

#

957

# ### Bounded Staleness

958

#

959

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

960

# subject to a user-provided staleness bound. Cloud Spanner chooses the

961

# newest timestamp within the staleness bound that allows execution

962

# of the reads at the closest available replica without blocking.

963

#

964

# All rows yielded are consistent with each other -- if any part of

965

# the read observes a transaction, all parts of the read see the

966

# transaction. Boundedly stale reads are not repeatable: two stale

967

# reads, even if they use the same staleness bound, can execute at

968

# different timestamps and thus return inconsistent results.

969

#

970

# Boundedly stale reads execute in two phases: the first phase

971

# negotiates a timestamp among all replicas needed to serve the

972

# read. In the second phase, reads are executed at the negotiated

973

# timestamp.

974

#

975

# As a result of the two phase execution, bounded staleness reads are

976

# usually a little slower than comparable exact staleness

977

# reads. However, they are typically able to return fresher

978

# results, and are more likely to execute at the closest replica.

979

#

980

# Because the timestamp negotiation requires up-front knowledge of

981

# which rows will be read, it can only be used with single-use

982

# read-only transactions.

983

#

984

# See TransactionOptions.ReadOnly.max_staleness and

985

# TransactionOptions.ReadOnly.min_read_timestamp.

986

#

987

# ### Old Read Timestamps and Garbage Collection

988

#

989

# Cloud Spanner continuously garbage collects deleted and overwritten data

990

# in the background to reclaim storage space. This process is known

991

# as "version GC". By default, version GC reclaims versions after they

992

# are one hour old. Because of this, Cloud Spanner cannot perform reads

993

# at read timestamps more than one hour in the past. This

994

# restriction also applies to in-progress reads and/or SQL queries whose

995

# timestamp become too old while executing. Reads and SQL queries with

996

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

997

#

998

# ## Partitioned DML Transactions

999

#

1000

# Partitioned DML transactions are used to execute DML statements with a

1001

# different execution strategy that provides different, and often better,

1002

# scalability properties for large, table-wide operations than DML in a

1003

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

1004

# should prefer using ReadWrite transactions.

1005

#

1006

# Partitioned DML partitions the keyspace and runs the DML statement on each

1007

# partition in separate, internal transactions. These transactions commit

1008

# automatically when complete, and run independently from one another.

1009

#

1010

# To reduce lock contention, this execution strategy only acquires read locks

1011

# on rows that match the WHERE clause of the statement. Additionally, the

1012

# smaller per-partition transactions hold locks for less time.

1013

#

1014

# That said, Partitioned DML is not a drop-in replacement for standard DML used

1015

# in ReadWrite transactions.

1016

#

1017

# - The DML statement must be fully-partitionable. Specifically, the statement

1018

# must be expressible as the union of many statements which each access only

1019

# a single row of the table.

1020

#

1021

# - The statement is not applied atomically to all rows of the table. Rather,

1022

# the statement is applied atomically to partitions of the table, in

1023

# independent transactions. Secondary index rows are updated atomically

1024

# with the base table rows.

1025

#

1026

# - Partitioned DML does not guarantee exactly-once execution semantics

1027

# against a partition. The statement will be applied at least once to each

1028

# partition. It is strongly recommended that the DML statement should be

1029

# idempotent to avoid unexpected results. For instance, it is potentially

1030

# dangerous to run a statement such as

1031

# `UPDATE table SET column = column + 1` as it could be run multiple times

1032

# against some rows.

1033

#

1034

# - The partitions are committed automatically - there is no support for

1035

# Commit or Rollback. If the call returns an error, or if the client issuing

1036

# the ExecuteSql call dies, it is possible that some rows had the statement

1037

# executed on them successfully. It is also possible that statement was

1038

# never executed against other rows.

1039

#

1040

# - Partitioned DML transactions may only contain the execution of a single

1041

# DML statement via ExecuteSql or ExecuteStreamingSql.

1042

#

1043

# - If any error is encountered during the execution of the partitioned DML

1044

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

1045

# value that cannot be stored due to schema constraints), then the

1046

# operation is stopped at that point and an error is returned. It is

1047

# possible that at this point, some partitions have been committed (or even

1048

# committed multiple times), and other partitions have not been run at all.

1049

#

1050

# Given the above, Partitioned DML is good fit for large, database-wide,

1051

# operations that are idempotent, such as deleting old rows from a very large

1052

# table.

1053

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1054

#

1055

# Authorization to begin a read-write transaction requires

1056

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

1057

# on the `session` resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1058

# transaction type has no options.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1059

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1060

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1061

#

1062

# Authorization to begin a read-only transaction requires

1063

# `spanner.databases.beginReadOnlyTransaction` permission

1064

# on the `session` resource.

1065

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

1066

#

1067

# This is useful for requesting fresher data than some previous

1068

# read, or data that is fresh enough to observe the effects of some

1069

# previously committed transaction whose timestamp is known.

1070

#

1071

# Note that this option can only be used in single-use transactions.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1072

#

1073

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

1074

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1075

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

1076

# the Transaction message that describes the transaction.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1077

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

1078

# seconds. Guarantees that all writes that have committed more

1079

# than the specified number of seconds ago are visible. Because

1080

# Cloud Spanner chooses the exact timestamp, this mode works even if

1081

# the client's local clock is substantially skewed from Cloud Spanner

1082

# commit timestamps.

1083

#

1084

# Useful for reading the freshest data available at a nearby

1085

# replica, while bounding the possible staleness if the local

1086

# replica has fallen behind.

1087

#

1088

# Note that this option can only be used in single-use

1089

# transactions.

1090

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

1091

# old. The timestamp is chosen soon after the read is started.

1092

#

1093

# Guarantees that all writes that have committed more than the

1094

# specified number of seconds ago are visible. Because Cloud Spanner

1095

# chooses the exact timestamp, this mode works even if the client's

1096

# local clock is substantially skewed from Cloud Spanner commit

1097

# timestamps.

1098

#

1099

# Useful for reading at nearby replicas without the distributed

1100

# timestamp negotiation overhead of `max_staleness`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1101

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

1102

# reads at a specific timestamp are repeatable; the same read at

1103

# the same timestamp always returns the same data. If the

1104

# timestamp is in the future, the read will block until the

1105

# specified timestamp, modulo the read's deadline.

1106

#

1107

# Useful for large scale consistent reads such as mapreduces, or

1108

# for coordinating many reads against a consistent snapshot of the

1109

# data.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1110

#

1111

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

1112

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1113

"strong": True or False, # Read at a timestamp where all previously committed transactions

1114

# are visible.

1115

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1116

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

1117

#

1118

# Authorization to begin a Partitioned DML transaction requires

1119

# `spanner.databases.beginPartitionedDmlTransaction` permission

1120

# on the `session` resource.

1121

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1132

1133

{ # The response for Commit.

1134

"commitTimestamp": "A String", # The Cloud Spanner timestamp at which the transaction committed.

}</pre>

</div>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1139

<code class="details" id="create">create(database, body, x__xgafv=None)</code>

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1140

<pre>Creates a new session. A session can be used to perform

1141

transactions that read and/or modify data in a Cloud Spanner database.

1142

Sessions are meant to be reused for many consecutive

1143

transactions.

1144

1145

Sessions can only execute one transaction at a time. To execute

1146

multiple concurrent read-write/write-only transactions, create

1147

multiple sessions. Note that standalone reads and queries use a

1148

transaction internally, and count toward the one transaction

1149

limit.

1150

1151

Cloud Spanner limits the number of sessions that can exist at any given

1152

time; thus, it is a good idea to delete idle and/or unneeded sessions.

Sai Cheemalapati

e833b79

2017-03-24 15:06:46 -0700

[diff] [blame]

1153

Aside from explicit deletes, Cloud Spanner can delete sessions for which no

1154

operations are sent for more than an hour. If a session is deleted,

1155

requests to it return `NOT_FOUND`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1156

1157

Idle sessions can be kept alive by sending a trivial SQL query

1158

periodically, e.g., `"SELECT 1"`.

1159

1160

Args:

1161

database: string, Required. The database in which the new session is created. (required)

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1162

body: object, The request body. (required)

1163

The object takes the form of:

1164

1165

{ # The request for CreateSession.

1166

"session": { # A session in the Cloud Spanner API. # The session to create.

1167

"labels": { # The labels for the session.

1168

#

1169

# * Label keys must be between 1 and 63 characters long and must conform to

1170

# the following regular expression: `[a-z]([-a-z0-9]*[a-z0-9])?`.

1171

# * Label values must be between 0 and 63 characters long and must conform

1172

# to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`.

1173

# * No more than 64 labels can be associated with a given session.

1174

#

1175

# See https://goo.gl/xmQnxf for more information on and examples of labels.

1176

"a_key": "A String",

1177

},

1178

"name": "A String", # The name of the session. This is always system-assigned; values provided

1179

# when creating a session are ignored.

1180

"approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is

1181

# typically earlier than the actual last use time.

1182

"createTime": "A String", # Output only. The timestamp when the session is created.

},

}

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1186

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1193

1194

{ # A session in the Cloud Spanner API.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1195

"labels": { # The labels for the session.

1196

#

1197

# * Label keys must be between 1 and 63 characters long and must conform to

1198

# the following regular expression: `[a-z]([-a-z0-9]*[a-z0-9])?`.

1199

# * Label values must be between 0 and 63 characters long and must conform

1200

# to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`.

1201

# * No more than 64 labels can be associated with a given session.

1202

#

1203

# See https://goo.gl/xmQnxf for more information on and examples of labels.

1204

"a_key": "A String",

1205

},

1206

"name": "A String", # The name of the session. This is always system-assigned; values provided

1207

# when creating a session are ignored.

1208

"approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is

1209

# typically earlier than the actual last use time.

1210

"createTime": "A String", # Output only. The timestamp when the session is created.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

}</pre>

</div>

<code class="details" id="delete">delete(name, x__xgafv=None)</code>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1216

<pre>Ends a session, releasing server resources associated with it. This will

1217

asynchronously trigger cancellation of any operations that are running with

1218

this session.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1219

1220

Args:

1221

name: string, Required. The name of the session to delete. (required)

1222

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

1229

1230

{ # A generic empty message that you can re-use to avoid defining duplicated

1231

# empty messages in your APIs. A typical example is to use it as the request

1232

# or the response type of an API method. For instance:

1233

#

1234

# service Foo {

1235

# rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);

1236

# }

1237

#

1238

# The JSON representation for `Empty` is empty JSON object `{}`.

}</pre>

</div>

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1243

<code class="details" id="executeBatchDml">executeBatchDml(session, body, x__xgafv=None)</code>

1244

<pre>Executes a batch of SQL DML statements. This method allows many statements

1245

to be run with lower latency than submitting them sequentially with

1246

ExecuteSql.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1247

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1248

Statements are executed in order, sequentially.

1249

ExecuteBatchDmlResponse will contain a

1250

ResultSet for each DML statement that has successfully executed. If a

1251

statement fails, its error status will be returned as part of the

1252

ExecuteBatchDmlResponse. Execution will

1253

stop at the first failed statement; the remaining statements will not run.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1254

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1255

ExecuteBatchDml is expected to return an OK status with a response even if

1256

there was an error while processing one of the DML statements. Clients must

1257

inspect response.status to determine if there were any errors while

1258

processing the request.

1259

1260

See more details in

1261

ExecuteBatchDmlRequest and

1262

ExecuteBatchDmlResponse.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1263

1264

Args:

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1265

session: string, Required. The session in which the DML statements should be performed. (required)

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1266

body: object, The request body. (required)

1267

The object takes the form of:

1268

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1269

{ # The request for ExecuteBatchDml

1270

"seqno": "A String", # A per-transaction sequence number used to identify this request. This is

1271

# used in the same space as the seqno in

1272

# ExecuteSqlRequest. See more details

1273

# in ExecuteSqlRequest.

1274

"transaction": { # This message is used to select the transaction in which a # The transaction to use. A ReadWrite transaction is required. Single-use

1275

# transactions are not supported (to avoid replay). The caller must either

1276

# supply an existing transaction ID or begin a new transaction.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1277

# Read or

1278

# ExecuteSql call runs.

1279

#

1280

# See TransactionOptions for more information about transactions.

1281

"begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in

1282

# it. The transaction ID of the new transaction is returned in

1283

# ResultSetMetadata.transaction, which is a Transaction.

1284

#

1285

#

1286

# Each session can have at most one active transaction at a time. After the

1287

# active transaction is completed, the session can immediately be

1288

# re-used for the next transaction. It is not necessary to create a

1289

# new session for each transaction.

1290

#

1291

# # Transaction Modes

1292

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1293

# Cloud Spanner supports three transaction modes:

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1294

#

1295

# 1. Locking read-write. This type of transaction is the only way

1296

# to write data into Cloud Spanner. These transactions rely on

1297

# pessimistic locking and, if necessary, two-phase commit.

1298

# Locking read-write transactions may abort, requiring the

1299

# application to retry.

1300

#

1301

# 2. Snapshot read-only. This transaction type provides guaranteed

1302

# consistency across several reads, but does not allow

1303

# writes. Snapshot read-only transactions can be configured to

1304

# read at timestamps in the past. Snapshot read-only

1305

# transactions do not need to be committed.

1306

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1307

# 3. Partitioned DML. This type of transaction is used to execute

1308

# a single Partitioned DML statement. Partitioned DML partitions

1309

# the key space and runs the DML statement over each partition

1310

# in parallel using separate, internal transactions that commit

1311

# independently. Partitioned DML transactions do not need to be

1312

# committed.

1313

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1314

# For transactions that only read, snapshot read-only transactions

1315

# provide simpler semantics and are almost always faster. In

1316

# particular, read-only transactions do not take locks, so they do

1317

# not conflict with read-write transactions. As a consequence of not

1318

# taking locks, they also do not abort, so retry loops are not needed.

1319

#

1320

# Transactions may only read/write data in a single database. They

1321

# may, however, read/write data in different tables within that

1322

# database.

1323

#

1324

# ## Locking Read-Write Transactions

1325

#

1326

# Locking transactions may be used to atomically read-modify-write

1327

# data anywhere in a database. This type of transaction is externally

1328

# consistent.

1329

#

1330

# Clients should attempt to minimize the amount of time a transaction

1331

# is active. Faster transactions commit with higher probability

1332

# and cause less contention. Cloud Spanner attempts to keep read locks

1333

# active as long as the transaction continues to do reads, and the

1334

# transaction has not been terminated by

1335

# Commit or

1336

# Rollback. Long periods of

1337

# inactivity at the client may cause Cloud Spanner to release a

1338

# transaction's locks and abort it.

1339

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1340

# Conceptually, a read-write transaction consists of zero or more

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1341

# reads or SQL statements followed by

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1342

# Commit. At any time before

1343

# Commit, the client can send a

1344

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

1350

# are still valid at commit time, and it is able to acquire write

1351

# locks for all writes. Cloud Spanner can abort the transaction for any

1352

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

1353

# that the transaction has not modified any user data in Cloud Spanner.

1354

#

1355

# Unless the transaction commits, Cloud Spanner makes no guarantees about

1356

# how long the transaction's locks were held for. It is an error to

1357

# use Cloud Spanner locks for any sort of mutual exclusion other than

1358

# between Cloud Spanner transactions themselves.

1359

#

1360

# ### Retrying Aborted Transactions

1361

#

1362

# When a transaction aborts, the application can choose to retry the

1363

# whole transaction again. To maximize the chances of successfully

1364

# committing the retry, the client should execute the retry in the

1365

# same session as the original attempt. The original session's lock

1366

# priority increases with each consecutive abort, meaning that each

1367

# attempt has a slightly better chance of success than the previous.

1368

#

1369

# Under some circumstances (e.g., many transactions attempting to

1370

# modify the same row(s)), a transaction can abort many times in a

1371

# short period before successfully committing. Thus, it is not a good

1372

# idea to cap the number of retries a transaction can attempt;

1373

# instead, it is better to limit the total amount of wall time spent

1374

# retrying.

1375

#

1376

# ### Idle Transactions

1377

#

1378

# A transaction is considered idle if it has no outstanding reads or

1379

# SQL queries and has not started a read or SQL query within the last 10

1380

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

1381

# don't hold on to locks indefinitely. In that case, the commit will

1382

# fail with error `ABORTED`.

1383

#

1384

# If this behavior is undesirable, periodically executing a simple

1385

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

1386

# transaction from becoming idle.

1387

#

1388

# ## Snapshot Read-Only Transactions

1389

#

1390

# Snapshot read-only transactions provides a simpler method than

1391

# locking read-write transactions for doing several consistent

1392

# reads. However, this type of transaction does not support writes.

1393

#

1394

# Snapshot transactions do not take locks. Instead, they work by

1395

# choosing a Cloud Spanner timestamp, then executing all reads at that

1396

# timestamp. Since they do not acquire locks, they do not block

1397

# concurrent read-write transactions.

1398

#

1399

# Unlike locking read-write transactions, snapshot read-only

1400

# transactions never abort. They can fail if the chosen read

1401

# timestamp is garbage collected; however, the default garbage

1402

# collection policy is generous enough that most applications do not

1403

# need to worry about this in practice.

1404

#

1405

# Snapshot read-only transactions do not need to call

1406

# Commit or

1407

# Rollback (and in fact are not

1408

# permitted to do so).

1409

#

1410

# To execute a snapshot transaction, the client specifies a timestamp

1411

# bound, which tells Cloud Spanner how to choose a read timestamp.

1412

#

1413

# The types of timestamp bound are:

1414

#

1415

# - Strong (the default).

1416

# - Bounded staleness.

1417

# - Exact staleness.

1418

#

1419

# If the Cloud Spanner database to be read is geographically distributed,

1420

# stale read-only transactions can execute more quickly than strong

1421

# or read-write transaction, because they are able to execute far

1422

# from the leader replica.

1423

#

1424

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

1429

# that have committed before the start of the read. Furthermore, all

1430

# rows yielded by a single read are consistent with each other -- if

1431

# any part of the read observes a transaction, all parts of the read

1432

# see the transaction.

1433

#

1434

# Strong reads are not repeatable: two consecutive strong read-only

1435

# transactions might return inconsistent results if there are

1436

# concurrent writes. If consistency across reads is required, the

1437

# reads should be executed within a transaction or at an exact read

1438

# timestamp.

1439

#

1440

# See TransactionOptions.ReadOnly.strong.

1441

#

1442

# ### Exact Staleness

1443

#

1444

# These timestamp bounds execute reads at a user-specified

1445

# timestamp. Reads at a timestamp are guaranteed to see a consistent

1446

# prefix of the global transaction history: they observe

1447

# modifications done by all transactions with a commit timestamp <=

1448

# the read timestamp, and observe none of the modifications done by

1449

# transactions with a larger commit timestamp. They will block until

1450

# all conflicting transactions that may be assigned commit timestamps

1451

# <= the read timestamp have finished.

1452

#

1453

# The timestamp can either be expressed as an absolute Cloud Spanner commit

1454

# timestamp or a staleness relative to the current time.

1455

#

1456

# These modes do not require a "negotiation phase" to pick a

1457

# timestamp. As a result, they execute slightly faster than the

1458

# equivalent boundedly stale concurrency modes. On the other hand,

1459

# boundedly stale reads usually return fresher results.

1460

#

1461

# See TransactionOptions.ReadOnly.read_timestamp and

1462

# TransactionOptions.ReadOnly.exact_staleness.

1463

#

1464

# ### Bounded Staleness

1465

#

1466

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

1467

# subject to a user-provided staleness bound. Cloud Spanner chooses the

1468

# newest timestamp within the staleness bound that allows execution

1469

# of the reads at the closest available replica without blocking.

1470

#

1471

# All rows yielded are consistent with each other -- if any part of

1472

# the read observes a transaction, all parts of the read see the

1473

# transaction. Boundedly stale reads are not repeatable: two stale

1474

# reads, even if they use the same staleness bound, can execute at

1475

# different timestamps and thus return inconsistent results.

1476

#

1477

# Boundedly stale reads execute in two phases: the first phase

1478

# negotiates a timestamp among all replicas needed to serve the

1479

# read. In the second phase, reads are executed at the negotiated

1480

# timestamp.

1481

#

1482

# As a result of the two phase execution, bounded staleness reads are

1483

# usually a little slower than comparable exact staleness

1484

# reads. However, they are typically able to return fresher

1485

# results, and are more likely to execute at the closest replica.

1486

#

1487

# Because the timestamp negotiation requires up-front knowledge of

1488

# which rows will be read, it can only be used with single-use

1489

# read-only transactions.

1490

#

1491

# See TransactionOptions.ReadOnly.max_staleness and

1492

# TransactionOptions.ReadOnly.min_read_timestamp.

1493

#

1494

# ### Old Read Timestamps and Garbage Collection

1495

#

1496

# Cloud Spanner continuously garbage collects deleted and overwritten data

1497

# in the background to reclaim storage space. This process is known

1498

# as "version GC". By default, version GC reclaims versions after they

1499

# are one hour old. Because of this, Cloud Spanner cannot perform reads

1500

# at read timestamps more than one hour in the past. This

1501

# restriction also applies to in-progress reads and/or SQL queries whose

1502

# timestamp become too old while executing. Reads and SQL queries with

1503

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1504

#

1505

# ## Partitioned DML Transactions

1506

#

1507

# Partitioned DML transactions are used to execute DML statements with a

1508

# different execution strategy that provides different, and often better,

1509

# scalability properties for large, table-wide operations than DML in a

1510

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

1511

# should prefer using ReadWrite transactions.

1512

#

1513

# Partitioned DML partitions the keyspace and runs the DML statement on each

1514

# partition in separate, internal transactions. These transactions commit

1515

# automatically when complete, and run independently from one another.

1516

#

1517

# To reduce lock contention, this execution strategy only acquires read locks

1518

# on rows that match the WHERE clause of the statement. Additionally, the

1519

# smaller per-partition transactions hold locks for less time.

1520

#

1521

# That said, Partitioned DML is not a drop-in replacement for standard DML used

1522

# in ReadWrite transactions.

1523

#

1524

# - The DML statement must be fully-partitionable. Specifically, the statement

1525

# must be expressible as the union of many statements which each access only

1526

# a single row of the table.

1527

#

1528

# - The statement is not applied atomically to all rows of the table. Rather,

1529

# the statement is applied atomically to partitions of the table, in

1530

# independent transactions. Secondary index rows are updated atomically

1531

# with the base table rows.

1532

#

1533

# - Partitioned DML does not guarantee exactly-once execution semantics

1534

# against a partition. The statement will be applied at least once to each

1535

# partition. It is strongly recommended that the DML statement should be

1536

# idempotent to avoid unexpected results. For instance, it is potentially

1537

# dangerous to run a statement such as

1538

# `UPDATE table SET column = column + 1` as it could be run multiple times

1539

# against some rows.

1540

#

1541

# - The partitions are committed automatically - there is no support for

1542

# Commit or Rollback. If the call returns an error, or if the client issuing

1543

# the ExecuteSql call dies, it is possible that some rows had the statement

1544

# executed on them successfully. It is also possible that statement was

1545

# never executed against other rows.

1546

#

1547

# - Partitioned DML transactions may only contain the execution of a single

1548

# DML statement via ExecuteSql or ExecuteStreamingSql.

1549

#

1550

# - If any error is encountered during the execution of the partitioned DML

1551

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

1552

# value that cannot be stored due to schema constraints), then the

1553

# operation is stopped at that point and an error is returned. It is

1554

# possible that at this point, some partitions have been committed (or even

1555

# committed multiple times), and other partitions have not been run at all.

1556

#

1557

# Given the above, Partitioned DML is good fit for large, database-wide,

1558

# operations that are idempotent, such as deleting old rows from a very large

1559

# table.

1560

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1561

#

1562

# Authorization to begin a read-write transaction requires

1563

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

1564

# on the `session` resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1565

# transaction type has no options.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1566

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1567

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1568

#

1569

# Authorization to begin a read-only transaction requires

1570

# `spanner.databases.beginReadOnlyTransaction` permission

1571

# on the `session` resource.

1572

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

1573

#

1574

# This is useful for requesting fresher data than some previous

1575

# read, or data that is fresh enough to observe the effects of some

1576

# previously committed transaction whose timestamp is known.

1577

#

1578

# Note that this option can only be used in single-use transactions.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1579

#

1580

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

1581

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1582

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

1583

# the Transaction message that describes the transaction.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1584

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

1585

# seconds. Guarantees that all writes that have committed more

1586

# than the specified number of seconds ago are visible. Because

1587

# Cloud Spanner chooses the exact timestamp, this mode works even if

1588

# the client's local clock is substantially skewed from Cloud Spanner

1589

# commit timestamps.

1590

#

1591

# Useful for reading the freshest data available at a nearby

1592

# replica, while bounding the possible staleness if the local

1593

# replica has fallen behind.

1594

#

1595

# Note that this option can only be used in single-use

1596

# transactions.

1597

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

1598

# old. The timestamp is chosen soon after the read is started.

1599

#

1600

# Guarantees that all writes that have committed more than the

1601

# specified number of seconds ago are visible. Because Cloud Spanner

1602

# chooses the exact timestamp, this mode works even if the client's

1603

# local clock is substantially skewed from Cloud Spanner commit

1604

# timestamps.

1605

#

1606

# Useful for reading at nearby replicas without the distributed

1607

# timestamp negotiation overhead of `max_staleness`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1608

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

1609

# reads at a specific timestamp are repeatable; the same read at

1610

# the same timestamp always returns the same data. If the

1611

# timestamp is in the future, the read will block until the

1612

# specified timestamp, modulo the read's deadline.

1613

#

1614

# Useful for large scale consistent reads such as mapreduces, or

1615

# for coordinating many reads against a consistent snapshot of the

1616

# data.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1617

#

1618

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

1619

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1620

"strong": True or False, # Read at a timestamp where all previously committed transactions

1621

# are visible.

1622

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1623

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

1624

#

1625

# Authorization to begin a Partitioned DML transaction requires

1626

# `spanner.databases.beginPartitionedDmlTransaction` permission

1627

# on the `session` resource.

1628

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1629

},

1630

"singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.

1631

# This is the most efficient way to execute a transaction that

1632

# consists of a single SQL query.

1633

#

1634

#

1635

# Each session can have at most one active transaction at a time. After the

1636

# active transaction is completed, the session can immediately be

1637

# re-used for the next transaction. It is not necessary to create a

1638

# new session for each transaction.

1639

#

1640

# # Transaction Modes

1641

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1642

# Cloud Spanner supports three transaction modes:

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1643

#

1644

# 1. Locking read-write. This type of transaction is the only way

1645

# to write data into Cloud Spanner. These transactions rely on

1646

# pessimistic locking and, if necessary, two-phase commit.

1647

# Locking read-write transactions may abort, requiring the

1648

# application to retry.

1649

#

1650

# 2. Snapshot read-only. This transaction type provides guaranteed

1651

# consistency across several reads, but does not allow

1652

# writes. Snapshot read-only transactions can be configured to

1653

# read at timestamps in the past. Snapshot read-only

1654

# transactions do not need to be committed.

1655

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1656

# 3. Partitioned DML. This type of transaction is used to execute

1657

# a single Partitioned DML statement. Partitioned DML partitions

1658

# the key space and runs the DML statement over each partition

1659

# in parallel using separate, internal transactions that commit

1660

# independently. Partitioned DML transactions do not need to be

1661

# committed.

1662

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1663

# For transactions that only read, snapshot read-only transactions

1664

# provide simpler semantics and are almost always faster. In

1665

# particular, read-only transactions do not take locks, so they do

1666

# not conflict with read-write transactions. As a consequence of not

1667

# taking locks, they also do not abort, so retry loops are not needed.

1668

#

1669

# Transactions may only read/write data in a single database. They

1670

# may, however, read/write data in different tables within that

1671

# database.

1672

#

1673

# ## Locking Read-Write Transactions

1674

#

1675

# Locking transactions may be used to atomically read-modify-write

1676

# data anywhere in a database. This type of transaction is externally

1677

# consistent.

1678

#

1679

# Clients should attempt to minimize the amount of time a transaction

1680

# is active. Faster transactions commit with higher probability

1681

# and cause less contention. Cloud Spanner attempts to keep read locks

1682

# active as long as the transaction continues to do reads, and the

1683

# transaction has not been terminated by

1684

# Commit or

1685

# Rollback. Long periods of

1686

# inactivity at the client may cause Cloud Spanner to release a

1687

# transaction's locks and abort it.

1688

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1689

# Conceptually, a read-write transaction consists of zero or more

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1690

# reads or SQL statements followed by

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1691

# Commit. At any time before

1692

# Commit, the client can send a

1693

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

1699

# are still valid at commit time, and it is able to acquire write

1700

# locks for all writes. Cloud Spanner can abort the transaction for any

1701

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

1702

# that the transaction has not modified any user data in Cloud Spanner.

1703

#

1704

# Unless the transaction commits, Cloud Spanner makes no guarantees about

1705

# how long the transaction's locks were held for. It is an error to

1706

# use Cloud Spanner locks for any sort of mutual exclusion other than

1707

# between Cloud Spanner transactions themselves.

1708

#

1709

# ### Retrying Aborted Transactions

1710

#

1711

# When a transaction aborts, the application can choose to retry the

1712

# whole transaction again. To maximize the chances of successfully

1713

# committing the retry, the client should execute the retry in the

1714

# same session as the original attempt. The original session's lock

1715

# priority increases with each consecutive abort, meaning that each

1716

# attempt has a slightly better chance of success than the previous.

1717

#

1718

# Under some circumstances (e.g., many transactions attempting to

1719

# modify the same row(s)), a transaction can abort many times in a

1720

# short period before successfully committing. Thus, it is not a good

1721

# idea to cap the number of retries a transaction can attempt;

1722

# instead, it is better to limit the total amount of wall time spent

1723

# retrying.

1724

#

1725

# ### Idle Transactions

1726

#

1727

# A transaction is considered idle if it has no outstanding reads or

1728

# SQL queries and has not started a read or SQL query within the last 10

1729

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

1730

# don't hold on to locks indefinitely. In that case, the commit will

1731

# fail with error `ABORTED`.

1732

#

1733

# If this behavior is undesirable, periodically executing a simple

1734

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

1735

# transaction from becoming idle.

1736

#

1737

# ## Snapshot Read-Only Transactions

1738

#

1739

# Snapshot read-only transactions provides a simpler method than

1740

# locking read-write transactions for doing several consistent

1741

# reads. However, this type of transaction does not support writes.

1742

#

1743

# Snapshot transactions do not take locks. Instead, they work by

1744

# choosing a Cloud Spanner timestamp, then executing all reads at that

1745

# timestamp. Since they do not acquire locks, they do not block

1746

# concurrent read-write transactions.

1747

#

1748

# Unlike locking read-write transactions, snapshot read-only

1749

# transactions never abort. They can fail if the chosen read

1750

# timestamp is garbage collected; however, the default garbage

1751

# collection policy is generous enough that most applications do not

1752

# need to worry about this in practice.

1753

#

1754

# Snapshot read-only transactions do not need to call

1755

# Commit or

1756

# Rollback (and in fact are not

1757

# permitted to do so).

1758

#

1759

# To execute a snapshot transaction, the client specifies a timestamp

1760

# bound, which tells Cloud Spanner how to choose a read timestamp.

1761

#

1762

# The types of timestamp bound are:

1763

#

1764

# - Strong (the default).

1765

# - Bounded staleness.

1766

# - Exact staleness.

1767

#

1768

# If the Cloud Spanner database to be read is geographically distributed,

1769

# stale read-only transactions can execute more quickly than strong

1770

# or read-write transaction, because they are able to execute far

1771

# from the leader replica.

1772

#

1773

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

1778

# that have committed before the start of the read. Furthermore, all

1779

# rows yielded by a single read are consistent with each other -- if

1780

# any part of the read observes a transaction, all parts of the read

1781

# see the transaction.

1782

#

1783

# Strong reads are not repeatable: two consecutive strong read-only

1784

# transactions might return inconsistent results if there are

1785

# concurrent writes. If consistency across reads is required, the

1786

# reads should be executed within a transaction or at an exact read

1787

# timestamp.

1788

#

1789

# See TransactionOptions.ReadOnly.strong.

1790

#

1791

# ### Exact Staleness

1792

#

1793

# These timestamp bounds execute reads at a user-specified

1794

# timestamp. Reads at a timestamp are guaranteed to see a consistent

1795

# prefix of the global transaction history: they observe

1796

# modifications done by all transactions with a commit timestamp <=

1797

# the read timestamp, and observe none of the modifications done by

1798

# transactions with a larger commit timestamp. They will block until

1799

# all conflicting transactions that may be assigned commit timestamps

1800

# <= the read timestamp have finished.

1801

#

1802

# The timestamp can either be expressed as an absolute Cloud Spanner commit

1803

# timestamp or a staleness relative to the current time.

1804

#

1805

# These modes do not require a "negotiation phase" to pick a

1806

# timestamp. As a result, they execute slightly faster than the

1807

# equivalent boundedly stale concurrency modes. On the other hand,

1808

# boundedly stale reads usually return fresher results.

1809

#

1810

# See TransactionOptions.ReadOnly.read_timestamp and

1811

# TransactionOptions.ReadOnly.exact_staleness.

1812

#

1813

# ### Bounded Staleness

1814

#

1815

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

1816

# subject to a user-provided staleness bound. Cloud Spanner chooses the

1817

# newest timestamp within the staleness bound that allows execution

1818

# of the reads at the closest available replica without blocking.

1819

#

1820

# All rows yielded are consistent with each other -- if any part of

1821

# the read observes a transaction, all parts of the read see the

1822

# transaction. Boundedly stale reads are not repeatable: two stale

1823

# reads, even if they use the same staleness bound, can execute at

1824

# different timestamps and thus return inconsistent results.

1825

#

1826

# Boundedly stale reads execute in two phases: the first phase

1827

# negotiates a timestamp among all replicas needed to serve the

1828

# read. In the second phase, reads are executed at the negotiated

1829

# timestamp.

1830

#

1831

# As a result of the two phase execution, bounded staleness reads are

1832

# usually a little slower than comparable exact staleness

1833

# reads. However, they are typically able to return fresher

1834

# results, and are more likely to execute at the closest replica.

1835

#

1836

# Because the timestamp negotiation requires up-front knowledge of

1837

# which rows will be read, it can only be used with single-use

1838

# read-only transactions.

1839

#

1840

# See TransactionOptions.ReadOnly.max_staleness and

1841

# TransactionOptions.ReadOnly.min_read_timestamp.

1842

#

1843

# ### Old Read Timestamps and Garbage Collection

1844

#

1845

# Cloud Spanner continuously garbage collects deleted and overwritten data

1846

# in the background to reclaim storage space. This process is known

1847

# as "version GC". By default, version GC reclaims versions after they

1848

# are one hour old. Because of this, Cloud Spanner cannot perform reads

1849

# at read timestamps more than one hour in the past. This

1850

# restriction also applies to in-progress reads and/or SQL queries whose

1851

# timestamp become too old while executing. Reads and SQL queries with

1852

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1853

#

1854

# ## Partitioned DML Transactions

1855

#

1856

# Partitioned DML transactions are used to execute DML statements with a

1857

# different execution strategy that provides different, and often better,

1858

# scalability properties for large, table-wide operations than DML in a

1859

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

1860

# should prefer using ReadWrite transactions.

1861

#

1862

# Partitioned DML partitions the keyspace and runs the DML statement on each

1863

# partition in separate, internal transactions. These transactions commit

1864

# automatically when complete, and run independently from one another.

1865

#

1866

# To reduce lock contention, this execution strategy only acquires read locks

1867

# on rows that match the WHERE clause of the statement. Additionally, the

1868

# smaller per-partition transactions hold locks for less time.

1869

#

1870

# That said, Partitioned DML is not a drop-in replacement for standard DML used

1871

# in ReadWrite transactions.

1872

#

1873

# - The DML statement must be fully-partitionable. Specifically, the statement

1874

# must be expressible as the union of many statements which each access only

1875

# a single row of the table.

1876

#

1877

# - The statement is not applied atomically to all rows of the table. Rather,

1878

# the statement is applied atomically to partitions of the table, in

1879

# independent transactions. Secondary index rows are updated atomically

1880

# with the base table rows.

1881

#

1882

# - Partitioned DML does not guarantee exactly-once execution semantics

1883

# against a partition. The statement will be applied at least once to each

1884

# partition. It is strongly recommended that the DML statement should be

1885

# idempotent to avoid unexpected results. For instance, it is potentially

1886

# dangerous to run a statement such as

1887

# `UPDATE table SET column = column + 1` as it could be run multiple times

1888

# against some rows.

1889

#

1890

# - The partitions are committed automatically - there is no support for

1891

# Commit or Rollback. If the call returns an error, or if the client issuing

1892

# the ExecuteSql call dies, it is possible that some rows had the statement

1893

# executed on them successfully. It is also possible that statement was

1894

# never executed against other rows.

1895

#

1896

# - Partitioned DML transactions may only contain the execution of a single

1897

# DML statement via ExecuteSql or ExecuteStreamingSql.

1898

#

1899

# - If any error is encountered during the execution of the partitioned DML

1900

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

1901

# value that cannot be stored due to schema constraints), then the

1902

# operation is stopped at that point and an error is returned. It is

1903

# possible that at this point, some partitions have been committed (or even

1904

# committed multiple times), and other partitions have not been run at all.

1905

#

1906

# Given the above, Partitioned DML is good fit for large, database-wide,

1907

# operations that are idempotent, such as deleting old rows from a very large

1908

# table.

1909

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1910

#

1911

# Authorization to begin a read-write transaction requires

1912

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

1913

# on the `session` resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1914

# transaction type has no options.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1915

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1916

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1917

#

1918

# Authorization to begin a read-only transaction requires

1919

# `spanner.databases.beginReadOnlyTransaction` permission

1920

# on the `session` resource.

1921

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

1922

#

1923

# This is useful for requesting fresher data than some previous

1924

# read, or data that is fresh enough to observe the effects of some

1925

# previously committed transaction whose timestamp is known.

1926

#

1927

# Note that this option can only be used in single-use transactions.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1928

#

1929

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

1930

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1931

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

1932

# the Transaction message that describes the transaction.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1933

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

1934

# seconds. Guarantees that all writes that have committed more

1935

# than the specified number of seconds ago are visible. Because

1936

# Cloud Spanner chooses the exact timestamp, this mode works even if

1937

# the client's local clock is substantially skewed from Cloud Spanner

1938

# commit timestamps.

1939

#

1940

# Useful for reading the freshest data available at a nearby

1941

# replica, while bounding the possible staleness if the local

1942

# replica has fallen behind.

1943

#

1944

# Note that this option can only be used in single-use

1945

# transactions.

1946

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

1947

# old. The timestamp is chosen soon after the read is started.

1948

#

1949

# Guarantees that all writes that have committed more than the

1950

# specified number of seconds ago are visible. Because Cloud Spanner

1951

# chooses the exact timestamp, this mode works even if the client's

1952

# local clock is substantially skewed from Cloud Spanner commit

1953

# timestamps.

1954

#

1955

# Useful for reading at nearby replicas without the distributed

1956

# timestamp negotiation overhead of `max_staleness`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

1957

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

1958

# reads at a specific timestamp are repeatable; the same read at

1959

# the same timestamp always returns the same data. If the

1960

# timestamp is in the future, the read will block until the

1961

# specified timestamp, modulo the read's deadline.

1962

#

1963

# Useful for large scale consistent reads such as mapreduces, or

1964

# for coordinating many reads against a consistent snapshot of the

1965

# data.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1966

#

1967

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

1968

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1969

"strong": True or False, # Read at a timestamp where all previously committed transactions

1970

# are visible.

1971

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1972

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

1973

#

1974

# Authorization to begin a Partitioned DML transaction requires

1975

# `spanner.databases.beginPartitionedDmlTransaction` permission

1976

# on the `session` resource.

1977

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

1978

},

1979

"id": "A String", # Execute the read or SQL query in a previously-started transaction.

1980

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

1981

"statements": [ # The list of statements to execute in this batch. Statements are executed

1982

# serially, such that the effects of statement i are visible to statement

1983

# i+1. Each statement must be a DML statement. Execution will stop at the

1984

# first failed statement; the remaining statements will not run.

1985

#

1986

# REQUIRES: `statements_size()` > 0.

1987

{ # A single DML statement.

1988

"paramTypes": { # It is not always possible for Cloud Spanner to infer the right SQL type

1989

# from a JSON value. For example, values of type `BYTES` and values

1990

# of type `STRING` both appear in params as JSON strings.

1991

#

1992

# In these cases, `param_types` can be used to specify the exact

1993

# SQL type for some or all of the SQL statement parameters. See the

1994

# definition of Type for more information

1995

# about SQL types.

1996

"a_key": { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a

1997

# table cell or returned from an SQL query.

1998

"structType": # Object with schema name: StructType # If code == STRUCT, then `struct_type`

1999

# provides type information for the struct's fields.

2000

"code": "A String", # Required. The TypeCode for this type.

2001

"arrayElementType": # Object with schema name: Type # If code == ARRAY, then `array_element_type`

2002

# is the type of the array elements.

2003

},

2004

},

2005

"params": { # The DML string can contain parameter placeholders. A parameter

2006

# placeholder consists of `'@'` followed by the parameter

2007

# name. Parameter names consist of any combination of letters,

2008

# numbers, and underscores.

2009

#

2010

# Parameters can appear anywhere that a literal value is expected. The

2011

# same parameter name can be used more than once, for example:

2012

# `"WHERE id > @msg_id AND id < @msg_id + 100"`

2013

#

2014

# It is an error to execute an SQL statement with unbound parameters.

2015

#

2016

# Parameter values are specified using `params`, which is a JSON

2017

# object whose keys are parameter names, and whose values are the

2018

# corresponding parameter values.

2019

"a_key": "", # Properties of the object.

2020

},

2021

"sql": "A String", # Required. The DML string.

},

],

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

2033

2034

{ # The response for ExecuteBatchDml. Contains a list

2035

# of ResultSet, one for each DML statement that has successfully executed.

2036

# If a statement fails, the error is returned as part of the response payload.

2037

# Clients can determine whether all DML statements have run successfully, or if

2038

# a statement failed, using one of the following approaches:

2039

#

2040

# 1. Check if `'status'` field is `OkStatus`.

2041

# 2. Check if `result_sets_size()` equals the number of statements in

2042

# ExecuteBatchDmlRequest.

2043

#

2044

# Example 1: A request with 5 DML statements, all executed successfully.

2045

#

2046

# Result: A response with 5 ResultSets, one for each statement in the same

2047

# order, and an `OkStatus`.

2048

#

2049

# Example 2: A request with 5 DML statements. The 3rd statement has a syntax

2050

# error.

2051

#

2052

# Result: A response with 2 ResultSets, for the first 2 statements that

2053

# run successfully, and a syntax error (`INVALID_ARGUMENT`) status. From

2054

# `result_set_size()` client can determine that the 3rd statement has failed.

2055

"status": { # The `Status` type defines a logical error model that is suitable for # If all DML statements are executed successfully, status will be OK.

2056

# Otherwise, the error status of the first failed statement.

2057

# different programming environments, including REST APIs and RPC APIs. It is

2058

# used by [gRPC](https://github.com/grpc). The error model is designed to be:

2059

#

2060

# - Simple to use and understand for most users

2061

# - Flexible enough to meet unexpected needs

#

# # Overview

#

# The `Status` message contains three pieces of data: error code, error

2066

# message, and error details. The error code should be an enum value of

2067

# google.rpc.Code, but it may accept additional error codes if needed. The

2068

# error message should be a developer-facing English message that helps

2069

# developers *understand* and *resolve* the error. If a localized user-facing

2070

# error message is needed, put the localized message in the error details or

2071

# localize it in the client. The optional error details may contain arbitrary

2072

# information about the error. There is a predefined set of error detail types

2073

# in the package `google.rpc` that can be used for common error conditions.

#

# # Language mapping

#

# The `Status` message is the logical representation of the error model, but it

2078

# is not necessarily the actual wire format. When the `Status` message is

2079

# exposed in different client libraries and different wire protocols, it can be

2080

# mapped differently. For example, it will likely be mapped to some exceptions

2081

# in Java, but more likely mapped to some error codes in C.

#

# # Other uses

#

# The error model and the `Status` message can be used in a variety of

2086

# environments, either with or without APIs, to provide a

2087

# consistent developer experience across different environments.

2088

#

2089

# Example uses of this error model include:

2090

#

2091

# - Partial errors. If a service needs to return partial errors to the client,

2092

# it may embed the `Status` in the normal response to indicate the partial

2093

# errors.

2094

#

2095

# - Workflow errors. A typical workflow has multiple steps. Each step may

2096

# have a `Status` message for error reporting.

2097

#

2098

# - Batch operations. If a client uses batch request and batch response, the

2099

# `Status` message should be used directly inside batch response, one for

2100

# each error sub-response.

2101

#

2102

# - Asynchronous operations. If an API call embeds asynchronous operation

2103

# results in its response, the status of those operations should be

2104

# represented directly using the `Status` message.

2105

#

2106

# - Logging. If some API errors are stored in logs, the message `Status` could

2107

# be used directly after any stripping needed for security/privacy reasons.

2108

"message": "A String", # A developer-facing error message, which should be in English. Any

2109

# user-facing error message should be localized and sent in the

2110

# google.rpc.Status.details field, or localized by the client.

2111

"code": 42, # The status code, which should be an enum value of google.rpc.Code.

2112

"details": [ # A list of messages that carry the error details. There is a common set of

2113

# message types for APIs to use.

2114

{

2115

"a_key": "", # Properties of the object. Contains field @type with type URL.

},

],

},

"resultSets": [ # ResultSets, one for each statement in the request that ran successfully, in

2120

# the same order as the statements in the request. Each ResultSet will

2121

# not contain any rows. The ResultSetStats in each ResultSet will

2122

# contain the number of rows modified by the statement.

2123

#

2124

# Only the first ResultSet in the response contains a valid

2125

# ResultSetMetadata.

2126

{ # Results from Read or

2127

# ExecuteSql.

2128

"rows": [ # Each element in `rows` is a row whose format is defined by

2129

# metadata.row_type. The ith element

2130

# in each row matches the ith field in

2131

# metadata.row_type. Elements are

2132

# encoded based on type as described

# here.

[

"",

],

],

"stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the SQL statement that

2139

# produced this result set. These can be requested by setting

2140

# ExecuteSqlRequest.query_mode.

2141

# DML statements always produce stats containing the number of rows

2142

# modified, unless executed using the

2143

# ExecuteSqlRequest.QueryMode.PLAN ExecuteSqlRequest.query_mode.

2144

# Other fields may or may not be populated, based on the

2145

# ExecuteSqlRequest.query_mode.

2146

"rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it

2147

# returns a lower bound of the rows modified.

2148

"rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.

2149

"queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.

2150

"planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting

2151

# with the plan root. Each PlanNode's `id` corresponds to its index in

2152

# `plan_nodes`.

2153

{ # Node information for nodes appearing in a QueryPlan.plan_nodes.

2154

"index": 42, # The `PlanNode`'s index in node list.

2155

"kind": "A String", # Used to determine the type of node. May be needed for visualizing

2156

# different kinds of nodes differently. For example, If the node is a

2157

# SCALAR node, it will have a condensed representation

2158

# which can be used to directly embed a description of the node in its

2159

# parent.

2160

"displayName": "A String", # The display name for the node.

2161

"executionStats": { # The execution statistics associated with the node, contained in a group of

2162

# key-value pairs. Only present if the plan was returned as a result of a

2163

# profile query. For example, number of executions, number of rows/time per

2164

# execution etc.

2165

"a_key": "", # Properties of the object.

2166

},

2167

"childLinks": [ # List of child node `index`es and their relationship to this parent.

2168

{ # Metadata associated with a parent-child relationship appearing in a

2169

# PlanNode.

2170

"variable": "A String", # Only present if the child node is SCALAR and corresponds

2171

# to an output variable of the parent node. The field carries the name of

2172

# the output variable.

2173

# For example, a `TableScan` operator that reads rows from a table will

2174

# have child links to the `SCALAR` nodes representing the output variables

2175

# created for each column that is read by the operator. The corresponding

2176

# `variable` fields will be set to the variable names assigned to the

2177

# columns.

2178

"childIndex": 42, # The node to which the link points.

2179

"type": "A String", # The type of the link. For example, in Hash Joins this could be used to

2180

# distinguish between the build child and the probe child, or in the case

2181

# of the child being an output variable, to represent the tag associated

2182

# with the output variable.

2183

},

2184

],

2185

"shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.

2186

# `SCALAR` PlanNode(s).

2187

"subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases

2188

# where the `description` string of this node references a `SCALAR`

2189

# subquery contained in the expression subtree rooted at this node. The

2190

# referenced `SCALAR` subquery may not necessarily be a direct child of

# this node.

"a_key": 42,

},

"description": "A String", # A string representation of the expression subtree rooted at this node.

2195

},

2196

"metadata": { # Attributes relevant to the node contained in a group of key-value pairs.

2197

# For example, a Parameter Reference node could have the following

2198

# information in its metadata:

2199

#

2200

# {

2201

# "parameter_reference": "param1",

2202

# "parameter_type": "array"

2203

# }

2204

"a_key": "", # Properties of the object.

},

},

],

},

"queryStats": { # Aggregated statistics from the execution of the query. Only present when

2210

# the query is profiled. For example, a query could return the statistics as

# follows:

#

# {

# "rows_returned": "3",

2215

# "elapsed_time": "1.22 secs",

2216

# "cpu_time": "1.19 secs"

2217

# }

2218

"a_key": "", # Properties of the object.

2219

},

2220

},

2221

"metadata": { # Metadata about a ResultSet or PartialResultSet. # Metadata about the result set, such as row type information.

2222

"rowType": { # `StructType` defines the fields of a STRUCT type. # Indicates the field names and types for the rows in the result

2223

# set. For example, a SQL query like `"SELECT UserId, UserName FROM

2224

# Users"` could return a `row_type` value like:

2225

#

2226

# "fields": [

2227

# { "name": "UserId", "type": { "code": "INT64" } },

2228

# { "name": "UserName", "type": { "code": "STRING" } },

2229

# ]

2230

"fields": [ # The list of fields that make up this struct. Order is

2231

# significant, because values of this struct type are represented as

2232

# lists, where the order of field values matches the order of

2233

# fields in the StructType. In turn, the order of fields

2234

# matches the order of columns in a read request, or the order of

2235

# fields in the `SELECT` clause of a query.

2236

{ # Message representing a single field of a struct.

2237

"type": { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a # The type of the field.

2238

# table cell or returned from an SQL query.

2239

"structType": # Object with schema name: StructType # If code == STRUCT, then `struct_type`

2240

# provides type information for the struct's fields.

2241

"code": "A String", # Required. The TypeCode for this type.

2242

"arrayElementType": # Object with schema name: Type # If code == ARRAY, then `array_element_type`

2243

# is the type of the array elements.

2244

},

2245

"name": "A String", # The name of the field. For reads, this is the column name. For

2246

# SQL queries, it is the column alias (e.g., `"Word"` in the

2247

# query `"SELECT 'hello' AS Word"`), or the column name (e.g.,

2248

# `"ColName"` in the query `"SELECT ColName FROM Table"`). Some

2249

# columns might have an empty name (e.g., !"SELECT

2250

# UPPER(ColName)"`). Note that a query result can contain

2251

# multiple fields with the same name.

},

],

},

"transaction": { # A transaction. # If the read or SQL query began a transaction as a side-effect, the

2256

# information about the new transaction is yielded here.

2257

"readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen

2258

# for the transaction. Not returned by default: see

2259

# TransactionOptions.ReadOnly.return_read_timestamp.

2260

#

2261

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

2262

# Example: `"2014-10-02T15:01:23.045123456Z"`.

2263

"id": "A String", # `id` may be used to identify the transaction in subsequent

# Read,

# ExecuteSql,

# Commit, or

# Rollback calls.

#

# Single-use read-only transactions do not have IDs, because

2270

# single-use transactions do not support multiple requests.

},

},

},

],

}</pre>

</div>

<code class="details" id="executeSql">executeSql(session, body, x__xgafv=None)</code>

2280

<pre>Executes an SQL statement, returning all results in a single reply. This

2281

method cannot be used to return a result set larger than 10 MiB;

2282

if the query yields more data than that, the query fails with

2283

a `FAILED_PRECONDITION` error.

2284

2285

Operations inside read-write transactions might return `ABORTED`. If

2286

this occurs, the application should restart the transaction from

2287

the beginning. See Transaction for more details.

2288

2289

Larger result sets can be fetched in streaming fashion by calling

2290

ExecuteStreamingSql instead.

2291

2292

Args:

2293

session: string, Required. The session in which the SQL query should be performed. (required)

2294

body: object, The request body. (required)

2295

The object takes the form of:

2296

2297

{ # The request for ExecuteSql and

2298

# ExecuteStreamingSql.

2299

"transaction": { # This message is used to select the transaction in which a # The transaction to use. If none is provided, the default is a

2300

# temporary read-only transaction with strong concurrency.

2301

#

2302

# The transaction to use.

2303

#

2304

# For queries, if none is provided, the default is a temporary read-only

2305

# transaction with strong concurrency.

2306

#

2307

# Standard DML statements require a ReadWrite transaction. Single-use

2308

# transactions are not supported (to avoid replay). The caller must

2309

# either supply an existing transaction ID or begin a new transaction.

2310

#

2311

# Partitioned DML requires an existing PartitionedDml transaction ID.

2312

# Read or

2313

# ExecuteSql call runs.

2314

#

2315

# See TransactionOptions for more information about transactions.

2316

"begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in

2317

# it. The transaction ID of the new transaction is returned in

2318

# ResultSetMetadata.transaction, which is a Transaction.

2319

#

2320

#

2321

# Each session can have at most one active transaction at a time. After the

2322

# active transaction is completed, the session can immediately be

2323

# re-used for the next transaction. It is not necessary to create a

2324

# new session for each transaction.

2325

#

2326

# # Transaction Modes

2327

#

2328

# Cloud Spanner supports three transaction modes:

2329

#

2330

# 1. Locking read-write. This type of transaction is the only way

2331

# to write data into Cloud Spanner. These transactions rely on

2332

# pessimistic locking and, if necessary, two-phase commit.

2333

# Locking read-write transactions may abort, requiring the

2334

# application to retry.

2335

#

2336

# 2. Snapshot read-only. This transaction type provides guaranteed

2337

# consistency across several reads, but does not allow

2338

# writes. Snapshot read-only transactions can be configured to

2339

# read at timestamps in the past. Snapshot read-only

2340

# transactions do not need to be committed.

2341

#

2342

# 3. Partitioned DML. This type of transaction is used to execute

2343

# a single Partitioned DML statement. Partitioned DML partitions

2344

# the key space and runs the DML statement over each partition

2345

# in parallel using separate, internal transactions that commit

2346

# independently. Partitioned DML transactions do not need to be

2347

# committed.

2348

#

2349

# For transactions that only read, snapshot read-only transactions

2350

# provide simpler semantics and are almost always faster. In

2351

# particular, read-only transactions do not take locks, so they do

2352

# not conflict with read-write transactions. As a consequence of not

2353

# taking locks, they also do not abort, so retry loops are not needed.

2354

#

2355

# Transactions may only read/write data in a single database. They

2356

# may, however, read/write data in different tables within that

2357

# database.

2358

#

2359

# ## Locking Read-Write Transactions

2360

#

2361

# Locking transactions may be used to atomically read-modify-write

2362

# data anywhere in a database. This type of transaction is externally

2363

# consistent.

2364

#

2365

# Clients should attempt to minimize the amount of time a transaction

2366

# is active. Faster transactions commit with higher probability

2367

# and cause less contention. Cloud Spanner attempts to keep read locks

2368

# active as long as the transaction continues to do reads, and the

2369

# transaction has not been terminated by

2370

# Commit or

2371

# Rollback. Long periods of

2372

# inactivity at the client may cause Cloud Spanner to release a

2373

# transaction's locks and abort it.

2374

#

2375

# Conceptually, a read-write transaction consists of zero or more

2376

# reads or SQL statements followed by

2377

# Commit. At any time before

2378

# Commit, the client can send a

2379

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

2385

# are still valid at commit time, and it is able to acquire write

2386

# locks for all writes. Cloud Spanner can abort the transaction for any

2387

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

2388

# that the transaction has not modified any user data in Cloud Spanner.

2389

#

2390

# Unless the transaction commits, Cloud Spanner makes no guarantees about

2391

# how long the transaction's locks were held for. It is an error to

2392

# use Cloud Spanner locks for any sort of mutual exclusion other than

2393

# between Cloud Spanner transactions themselves.

2394

#

2395

# ### Retrying Aborted Transactions

2396

#

2397

# When a transaction aborts, the application can choose to retry the

2398

# whole transaction again. To maximize the chances of successfully

2399

# committing the retry, the client should execute the retry in the

2400

# same session as the original attempt. The original session's lock

2401

# priority increases with each consecutive abort, meaning that each

2402

# attempt has a slightly better chance of success than the previous.

2403

#

2404

# Under some circumstances (e.g., many transactions attempting to

2405

# modify the same row(s)), a transaction can abort many times in a

2406

# short period before successfully committing. Thus, it is not a good

2407

# idea to cap the number of retries a transaction can attempt;

2408

# instead, it is better to limit the total amount of wall time spent

2409

# retrying.

2410

#

2411

# ### Idle Transactions

2412

#

2413

# A transaction is considered idle if it has no outstanding reads or

2414

# SQL queries and has not started a read or SQL query within the last 10

2415

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

2416

# don't hold on to locks indefinitely. In that case, the commit will

2417

# fail with error `ABORTED`.

2418

#

2419

# If this behavior is undesirable, periodically executing a simple

2420

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

2421

# transaction from becoming idle.

2422

#

2423

# ## Snapshot Read-Only Transactions

2424

#

2425

# Snapshot read-only transactions provides a simpler method than

2426

# locking read-write transactions for doing several consistent

2427

# reads. However, this type of transaction does not support writes.

2428

#

2429

# Snapshot transactions do not take locks. Instead, they work by

2430

# choosing a Cloud Spanner timestamp, then executing all reads at that

2431

# timestamp. Since they do not acquire locks, they do not block

2432

# concurrent read-write transactions.

2433

#

2434

# Unlike locking read-write transactions, snapshot read-only

2435

# transactions never abort. They can fail if the chosen read

2436

# timestamp is garbage collected; however, the default garbage

2437

# collection policy is generous enough that most applications do not

2438

# need to worry about this in practice.

2439

#

2440

# Snapshot read-only transactions do not need to call

2441

# Commit or

2442

# Rollback (and in fact are not

2443

# permitted to do so).

2444

#

2445

# To execute a snapshot transaction, the client specifies a timestamp

2446

# bound, which tells Cloud Spanner how to choose a read timestamp.

2447

#

2448

# The types of timestamp bound are:

2449

#

2450

# - Strong (the default).

2451

# - Bounded staleness.

2452

# - Exact staleness.

2453

#

2454

# If the Cloud Spanner database to be read is geographically distributed,

2455

# stale read-only transactions can execute more quickly than strong

2456

# or read-write transaction, because they are able to execute far

2457

# from the leader replica.

2458

#

2459

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

2464

# that have committed before the start of the read. Furthermore, all

2465

# rows yielded by a single read are consistent with each other -- if

2466

# any part of the read observes a transaction, all parts of the read

2467

# see the transaction.

2468

#

2469

# Strong reads are not repeatable: two consecutive strong read-only

2470

# transactions might return inconsistent results if there are

2471

# concurrent writes. If consistency across reads is required, the

2472

# reads should be executed within a transaction or at an exact read

2473

# timestamp.

2474

#

2475

# See TransactionOptions.ReadOnly.strong.

2476

#

2477

# ### Exact Staleness

2478

#

2479

# These timestamp bounds execute reads at a user-specified

2480

# timestamp. Reads at a timestamp are guaranteed to see a consistent

2481

# prefix of the global transaction history: they observe

2482

# modifications done by all transactions with a commit timestamp <=

2483

# the read timestamp, and observe none of the modifications done by

2484

# transactions with a larger commit timestamp. They will block until

2485

# all conflicting transactions that may be assigned commit timestamps

2486

# <= the read timestamp have finished.

2487

#

2488

# The timestamp can either be expressed as an absolute Cloud Spanner commit

2489

# timestamp or a staleness relative to the current time.

2490

#

2491

# These modes do not require a "negotiation phase" to pick a

2492

# timestamp. As a result, they execute slightly faster than the

2493

# equivalent boundedly stale concurrency modes. On the other hand,

2494

# boundedly stale reads usually return fresher results.

2495

#

2496

# See TransactionOptions.ReadOnly.read_timestamp and

2497

# TransactionOptions.ReadOnly.exact_staleness.

2498

#

2499

# ### Bounded Staleness

2500

#

2501

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

2502

# subject to a user-provided staleness bound. Cloud Spanner chooses the

2503

# newest timestamp within the staleness bound that allows execution

2504

# of the reads at the closest available replica without blocking.

2505

#

2506

# All rows yielded are consistent with each other -- if any part of

2507

# the read observes a transaction, all parts of the read see the

2508

# transaction. Boundedly stale reads are not repeatable: two stale

2509

# reads, even if they use the same staleness bound, can execute at

2510

# different timestamps and thus return inconsistent results.

2511

#

2512

# Boundedly stale reads execute in two phases: the first phase

2513

# negotiates a timestamp among all replicas needed to serve the

2514

# read. In the second phase, reads are executed at the negotiated

2515

# timestamp.

2516

#

2517

# As a result of the two phase execution, bounded staleness reads are

2518

# usually a little slower than comparable exact staleness

2519

# reads. However, they are typically able to return fresher

2520

# results, and are more likely to execute at the closest replica.

2521

#

2522

# Because the timestamp negotiation requires up-front knowledge of

2523

# which rows will be read, it can only be used with single-use

2524

# read-only transactions.

2525

#

2526

# See TransactionOptions.ReadOnly.max_staleness and

2527

# TransactionOptions.ReadOnly.min_read_timestamp.

2528

#

2529

# ### Old Read Timestamps and Garbage Collection

2530

#

2531

# Cloud Spanner continuously garbage collects deleted and overwritten data

2532

# in the background to reclaim storage space. This process is known

2533

# as "version GC". By default, version GC reclaims versions after they

2534

# are one hour old. Because of this, Cloud Spanner cannot perform reads

2535

# at read timestamps more than one hour in the past. This

2536

# restriction also applies to in-progress reads and/or SQL queries whose

2537

# timestamp become too old while executing. Reads and SQL queries with

2538

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

2539

#

2540

# ## Partitioned DML Transactions

2541

#

2542

# Partitioned DML transactions are used to execute DML statements with a

2543

# different execution strategy that provides different, and often better,

2544

# scalability properties for large, table-wide operations than DML in a

2545

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

2546

# should prefer using ReadWrite transactions.

2547

#

2548

# Partitioned DML partitions the keyspace and runs the DML statement on each

2549

# partition in separate, internal transactions. These transactions commit

2550

# automatically when complete, and run independently from one another.

2551

#

2552

# To reduce lock contention, this execution strategy only acquires read locks

2553

# on rows that match the WHERE clause of the statement. Additionally, the

2554

# smaller per-partition transactions hold locks for less time.

2555

#

2556

# That said, Partitioned DML is not a drop-in replacement for standard DML used

2557

# in ReadWrite transactions.

2558

#

2559

# - The DML statement must be fully-partitionable. Specifically, the statement

2560

# must be expressible as the union of many statements which each access only

2561

# a single row of the table.

2562

#

2563

# - The statement is not applied atomically to all rows of the table. Rather,

2564

# the statement is applied atomically to partitions of the table, in

2565

# independent transactions. Secondary index rows are updated atomically

2566

# with the base table rows.

2567

#

2568

# - Partitioned DML does not guarantee exactly-once execution semantics

2569

# against a partition. The statement will be applied at least once to each

2570

# partition. It is strongly recommended that the DML statement should be

2571

# idempotent to avoid unexpected results. For instance, it is potentially

2572

# dangerous to run a statement such as

2573

# `UPDATE table SET column = column + 1` as it could be run multiple times

2574

# against some rows.

2575

#

2576

# - The partitions are committed automatically - there is no support for

2577

# Commit or Rollback. If the call returns an error, or if the client issuing

2578

# the ExecuteSql call dies, it is possible that some rows had the statement

2579

# executed on them successfully. It is also possible that statement was

2580

# never executed against other rows.

2581

#

2582

# - Partitioned DML transactions may only contain the execution of a single

2583

# DML statement via ExecuteSql or ExecuteStreamingSql.

2584

#

2585

# - If any error is encountered during the execution of the partitioned DML

2586

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

2587

# value that cannot be stored due to schema constraints), then the

2588

# operation is stopped at that point and an error is returned. It is

2589

# possible that at this point, some partitions have been committed (or even

2590

# committed multiple times), and other partitions have not been run at all.

2591

#

2592

# Given the above, Partitioned DML is good fit for large, database-wide,

2593

# operations that are idempotent, such as deleting old rows from a very large

2594

# table.

2595

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

2596

#

2597

# Authorization to begin a read-write transaction requires

2598

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

2599

# on the `session` resource.

2600

# transaction type has no options.

2601

},

2602

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

2603

#

2604

# Authorization to begin a read-only transaction requires

2605

# `spanner.databases.beginReadOnlyTransaction` permission

2606

# on the `session` resource.

2607

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

2608

#

2609

# This is useful for requesting fresher data than some previous

2610

# read, or data that is fresh enough to observe the effects of some

2611

# previously committed transaction whose timestamp is known.

2612

#

2613

# Note that this option can only be used in single-use transactions.

2614

#

2615

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

2616

# Example: `"2014-10-02T15:01:23.045123456Z"`.

2617

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

2618

# the Transaction message that describes the transaction.

2619

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

2620

# seconds. Guarantees that all writes that have committed more

2621

# than the specified number of seconds ago are visible. Because

2622

# Cloud Spanner chooses the exact timestamp, this mode works even if

2623

# the client's local clock is substantially skewed from Cloud Spanner

2624

# commit timestamps.

2625

#

2626

# Useful for reading the freshest data available at a nearby

2627

# replica, while bounding the possible staleness if the local

2628

# replica has fallen behind.

2629

#

2630

# Note that this option can only be used in single-use

2631

# transactions.

2632

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

2633

# old. The timestamp is chosen soon after the read is started.

2634

#

2635

# Guarantees that all writes that have committed more than the

2636

# specified number of seconds ago are visible. Because Cloud Spanner

2637

# chooses the exact timestamp, this mode works even if the client's

2638

# local clock is substantially skewed from Cloud Spanner commit

2639

# timestamps.

2640

#

2641

# Useful for reading at nearby replicas without the distributed

2642

# timestamp negotiation overhead of `max_staleness`.

2643

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

2644

# reads at a specific timestamp are repeatable; the same read at

2645

# the same timestamp always returns the same data. If the

2646

# timestamp is in the future, the read will block until the

2647

# specified timestamp, modulo the read's deadline.

2648

#

2649

# Useful for large scale consistent reads such as mapreduces, or

2650

# for coordinating many reads against a consistent snapshot of the

2651

# data.

2652

#

2653

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

2654

# Example: `"2014-10-02T15:01:23.045123456Z"`.

2655

"strong": True or False, # Read at a timestamp where all previously committed transactions

2656

# are visible.

2657

},

2658

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

2659

#

2660

# Authorization to begin a Partitioned DML transaction requires

2661

# `spanner.databases.beginPartitionedDmlTransaction` permission

2662

# on the `session` resource.

2663

},

2664

},

2665

"singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.

2666

# This is the most efficient way to execute a transaction that

2667

# consists of a single SQL query.

2668

#

2669

#

2670

# Each session can have at most one active transaction at a time. After the

2671

# active transaction is completed, the session can immediately be

2672

# re-used for the next transaction. It is not necessary to create a

2673

# new session for each transaction.

2674

#

2675

# # Transaction Modes

2676

#

2677

# Cloud Spanner supports three transaction modes:

2678

#

2679

# 1. Locking read-write. This type of transaction is the only way

2680

# to write data into Cloud Spanner. These transactions rely on

2681

# pessimistic locking and, if necessary, two-phase commit.

2682

# Locking read-write transactions may abort, requiring the

2683

# application to retry.

2684

#

2685

# 2. Snapshot read-only. This transaction type provides guaranteed

2686

# consistency across several reads, but does not allow

2687

# writes. Snapshot read-only transactions can be configured to

2688

# read at timestamps in the past. Snapshot read-only

2689

# transactions do not need to be committed.

2690

#

2691

# 3. Partitioned DML. This type of transaction is used to execute

2692

# a single Partitioned DML statement. Partitioned DML partitions

2693

# the key space and runs the DML statement over each partition

2694

# in parallel using separate, internal transactions that commit

2695

# independently. Partitioned DML transactions do not need to be

2696

# committed.

2697

#

2698

# For transactions that only read, snapshot read-only transactions

2699

# provide simpler semantics and are almost always faster. In

2700

# particular, read-only transactions do not take locks, so they do

2701

# not conflict with read-write transactions. As a consequence of not

2702

# taking locks, they also do not abort, so retry loops are not needed.

2703

#

2704

# Transactions may only read/write data in a single database. They

2705

# may, however, read/write data in different tables within that

2706

# database.

2707

#

2708

# ## Locking Read-Write Transactions

2709

#

2710

# Locking transactions may be used to atomically read-modify-write

2711

# data anywhere in a database. This type of transaction is externally

2712

# consistent.

2713

#

2714

# Clients should attempt to minimize the amount of time a transaction

2715

# is active. Faster transactions commit with higher probability

2716

# and cause less contention. Cloud Spanner attempts to keep read locks

2717

# active as long as the transaction continues to do reads, and the

2718

# transaction has not been terminated by

2719

# Commit or

2720

# Rollback. Long periods of

2721

# inactivity at the client may cause Cloud Spanner to release a

2722

# transaction's locks and abort it.

2723

#

2724

# Conceptually, a read-write transaction consists of zero or more

2725

# reads or SQL statements followed by

2726

# Commit. At any time before

2727

# Commit, the client can send a

2728

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

2734

# are still valid at commit time, and it is able to acquire write

2735

# locks for all writes. Cloud Spanner can abort the transaction for any

2736

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

2737

# that the transaction has not modified any user data in Cloud Spanner.

2738

#

2739

# Unless the transaction commits, Cloud Spanner makes no guarantees about

2740

# how long the transaction's locks were held for. It is an error to

2741

# use Cloud Spanner locks for any sort of mutual exclusion other than

2742

# between Cloud Spanner transactions themselves.

2743

#

2744

# ### Retrying Aborted Transactions

2745

#

2746

# When a transaction aborts, the application can choose to retry the

2747

# whole transaction again. To maximize the chances of successfully

2748

# committing the retry, the client should execute the retry in the

2749

# same session as the original attempt. The original session's lock

2750

# priority increases with each consecutive abort, meaning that each

2751

# attempt has a slightly better chance of success than the previous.

2752

#

2753

# Under some circumstances (e.g., many transactions attempting to

2754

# modify the same row(s)), a transaction can abort many times in a

2755

# short period before successfully committing. Thus, it is not a good

2756

# idea to cap the number of retries a transaction can attempt;

2757

# instead, it is better to limit the total amount of wall time spent

2758

# retrying.

2759

#

2760

# ### Idle Transactions

2761

#

2762

# A transaction is considered idle if it has no outstanding reads or

2763

# SQL queries and has not started a read or SQL query within the last 10

2764

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

2765

# don't hold on to locks indefinitely. In that case, the commit will

2766

# fail with error `ABORTED`.

2767

#

2768

# If this behavior is undesirable, periodically executing a simple

2769

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

2770

# transaction from becoming idle.

2771

#

2772

# ## Snapshot Read-Only Transactions

2773

#

2774

# Snapshot read-only transactions provides a simpler method than

2775

# locking read-write transactions for doing several consistent

2776

# reads. However, this type of transaction does not support writes.

2777

#

2778

# Snapshot transactions do not take locks. Instead, they work by

2779

# choosing a Cloud Spanner timestamp, then executing all reads at that

2780

# timestamp. Since they do not acquire locks, they do not block

2781

# concurrent read-write transactions.

2782

#

2783

# Unlike locking read-write transactions, snapshot read-only

2784

# transactions never abort. They can fail if the chosen read

2785

# timestamp is garbage collected; however, the default garbage

2786

# collection policy is generous enough that most applications do not

2787

# need to worry about this in practice.

2788

#

2789

# Snapshot read-only transactions do not need to call

2790

# Commit or

2791

# Rollback (and in fact are not

2792

# permitted to do so).

2793

#

2794

# To execute a snapshot transaction, the client specifies a timestamp

2795

# bound, which tells Cloud Spanner how to choose a read timestamp.

2796

#

2797

# The types of timestamp bound are:

2798

#

2799

# - Strong (the default).

2800

# - Bounded staleness.

2801

# - Exact staleness.

2802

#

2803

# If the Cloud Spanner database to be read is geographically distributed,

2804

# stale read-only transactions can execute more quickly than strong

2805

# or read-write transaction, because they are able to execute far

2806

# from the leader replica.

2807

#

2808

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

2813

# that have committed before the start of the read. Furthermore, all

2814

# rows yielded by a single read are consistent with each other -- if

2815

# any part of the read observes a transaction, all parts of the read

2816

# see the transaction.

2817

#

2818

# Strong reads are not repeatable: two consecutive strong read-only

2819

# transactions might return inconsistent results if there are

2820

# concurrent writes. If consistency across reads is required, the

2821

# reads should be executed within a transaction or at an exact read

2822

# timestamp.

2823

#

2824

# See TransactionOptions.ReadOnly.strong.

2825

#

2826

# ### Exact Staleness

2827

#

2828

# These timestamp bounds execute reads at a user-specified

2829

# timestamp. Reads at a timestamp are guaranteed to see a consistent

2830

# prefix of the global transaction history: they observe

2831

# modifications done by all transactions with a commit timestamp <=

2832

# the read timestamp, and observe none of the modifications done by

2833

# transactions with a larger commit timestamp. They will block until

2834

# all conflicting transactions that may be assigned commit timestamps

2835

# <= the read timestamp have finished.

2836

#

2837

# The timestamp can either be expressed as an absolute Cloud Spanner commit

2838

# timestamp or a staleness relative to the current time.

2839

#

2840

# These modes do not require a "negotiation phase" to pick a

2841

# timestamp. As a result, they execute slightly faster than the

2842

# equivalent boundedly stale concurrency modes. On the other hand,

2843

# boundedly stale reads usually return fresher results.

2844

#

2845

# See TransactionOptions.ReadOnly.read_timestamp and

2846

# TransactionOptions.ReadOnly.exact_staleness.

2847

#

2848

# ### Bounded Staleness

2849

#

2850

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

2851

# subject to a user-provided staleness bound. Cloud Spanner chooses the

2852

# newest timestamp within the staleness bound that allows execution

2853

# of the reads at the closest available replica without blocking.

2854

#

2855

# All rows yielded are consistent with each other -- if any part of

2856

# the read observes a transaction, all parts of the read see the

2857

# transaction. Boundedly stale reads are not repeatable: two stale

2858

# reads, even if they use the same staleness bound, can execute at

2859

# different timestamps and thus return inconsistent results.

2860

#

2861

# Boundedly stale reads execute in two phases: the first phase

2862

# negotiates a timestamp among all replicas needed to serve the

2863

# read. In the second phase, reads are executed at the negotiated

2864

# timestamp.

2865

#

2866

# As a result of the two phase execution, bounded staleness reads are

2867

# usually a little slower than comparable exact staleness

2868

# reads. However, they are typically able to return fresher

2869

# results, and are more likely to execute at the closest replica.

2870

#

2871

# Because the timestamp negotiation requires up-front knowledge of

2872

# which rows will be read, it can only be used with single-use

2873

# read-only transactions.

2874

#

2875

# See TransactionOptions.ReadOnly.max_staleness and

2876

# TransactionOptions.ReadOnly.min_read_timestamp.

2877

#

2878

# ### Old Read Timestamps and Garbage Collection

2879

#

2880

# Cloud Spanner continuously garbage collects deleted and overwritten data

2881

# in the background to reclaim storage space. This process is known

2882

# as "version GC". By default, version GC reclaims versions after they

2883

# are one hour old. Because of this, Cloud Spanner cannot perform reads

2884

# at read timestamps more than one hour in the past. This

2885

# restriction also applies to in-progress reads and/or SQL queries whose

2886

# timestamp become too old while executing. Reads and SQL queries with

2887

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

2888

#

2889

# ## Partitioned DML Transactions

2890

#

2891

# Partitioned DML transactions are used to execute DML statements with a

2892

# different execution strategy that provides different, and often better,

2893

# scalability properties for large, table-wide operations than DML in a

2894

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

2895

# should prefer using ReadWrite transactions.

2896

#

2897

# Partitioned DML partitions the keyspace and runs the DML statement on each

2898

# partition in separate, internal transactions. These transactions commit

2899

# automatically when complete, and run independently from one another.

2900

#

2901

# To reduce lock contention, this execution strategy only acquires read locks

2902

# on rows that match the WHERE clause of the statement. Additionally, the

2903

# smaller per-partition transactions hold locks for less time.

2904

#

2905

# That said, Partitioned DML is not a drop-in replacement for standard DML used

2906

# in ReadWrite transactions.

2907

#

2908

# - The DML statement must be fully-partitionable. Specifically, the statement

2909

# must be expressible as the union of many statements which each access only

2910

# a single row of the table.

2911

#

2912

# - The statement is not applied atomically to all rows of the table. Rather,

2913

# the statement is applied atomically to partitions of the table, in

2914

# independent transactions. Secondary index rows are updated atomically

2915

# with the base table rows.

2916

#

2917

# - Partitioned DML does not guarantee exactly-once execution semantics

2918

# against a partition. The statement will be applied at least once to each

2919

# partition. It is strongly recommended that the DML statement should be

2920

# idempotent to avoid unexpected results. For instance, it is potentially

2921

# dangerous to run a statement such as

2922

# `UPDATE table SET column = column + 1` as it could be run multiple times

2923

# against some rows.

2924

#

2925

# - The partitions are committed automatically - there is no support for

2926

# Commit or Rollback. If the call returns an error, or if the client issuing

2927

# the ExecuteSql call dies, it is possible that some rows had the statement

2928

# executed on them successfully. It is also possible that statement was

2929

# never executed against other rows.

2930

#

2931

# - Partitioned DML transactions may only contain the execution of a single

2932

# DML statement via ExecuteSql or ExecuteStreamingSql.

2933

#

2934

# - If any error is encountered during the execution of the partitioned DML

2935

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

2936

# value that cannot be stored due to schema constraints), then the

2937

# operation is stopped at that point and an error is returned. It is

2938

# possible that at this point, some partitions have been committed (or even

2939

# committed multiple times), and other partitions have not been run at all.

2940

#

2941

# Given the above, Partitioned DML is good fit for large, database-wide,

2942

# operations that are idempotent, such as deleting old rows from a very large

2943

# table.

2944

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

2945

#

2946

# Authorization to begin a read-write transaction requires

2947

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

2948

# on the `session` resource.

2949

# transaction type has no options.

2950

},

2951

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

2952

#

2953

# Authorization to begin a read-only transaction requires

2954

# `spanner.databases.beginReadOnlyTransaction` permission

2955

# on the `session` resource.

2956

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

2957

#

2958

# This is useful for requesting fresher data than some previous

2959

# read, or data that is fresh enough to observe the effects of some

2960

# previously committed transaction whose timestamp is known.

2961

#

2962

# Note that this option can only be used in single-use transactions.

2963

#

2964

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

2965

# Example: `"2014-10-02T15:01:23.045123456Z"`.

2966

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

2967

# the Transaction message that describes the transaction.

2968

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

2969

# seconds. Guarantees that all writes that have committed more

2970

# than the specified number of seconds ago are visible. Because

2971

# Cloud Spanner chooses the exact timestamp, this mode works even if

2972

# the client's local clock is substantially skewed from Cloud Spanner

2973

# commit timestamps.

2974

#

2975

# Useful for reading the freshest data available at a nearby

2976

# replica, while bounding the possible staleness if the local

2977

# replica has fallen behind.

2978

#

2979

# Note that this option can only be used in single-use

2980

# transactions.

2981

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

2982

# old. The timestamp is chosen soon after the read is started.

2983

#

2984

# Guarantees that all writes that have committed more than the

2985

# specified number of seconds ago are visible. Because Cloud Spanner

2986

# chooses the exact timestamp, this mode works even if the client's

2987

# local clock is substantially skewed from Cloud Spanner commit

2988

# timestamps.

2989

#

2990

# Useful for reading at nearby replicas without the distributed

2991

# timestamp negotiation overhead of `max_staleness`.

2992

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

2993

# reads at a specific timestamp are repeatable; the same read at

2994

# the same timestamp always returns the same data. If the

2995

# timestamp is in the future, the read will block until the

2996

# specified timestamp, modulo the read's deadline.

2997

#

2998

# Useful for large scale consistent reads such as mapreduces, or

2999

# for coordinating many reads against a consistent snapshot of the

3000

# data.

3001

#

3002

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

3003

# Example: `"2014-10-02T15:01:23.045123456Z"`.

3004

"strong": True or False, # Read at a timestamp where all previously committed transactions

3005

# are visible.

3006

},

3007

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

3008

#

3009

# Authorization to begin a Partitioned DML transaction requires

3010

# `spanner.databases.beginPartitionedDmlTransaction` permission

3011

# on the `session` resource.

3012

},

3013

},

3014

"id": "A String", # Execute the read or SQL query in a previously-started transaction.

3015

},

3016

"seqno": "A String", # A per-transaction sequence number used to identify this request. This

3017

# makes each request idempotent such that if the request is received multiple

3018

# times, at most one will succeed.

3019

#

3020

# The sequence number must be monotonically increasing within the

3021

# transaction. If a request arrives for the first time with an out-of-order

3022

# sequence number, the transaction may be aborted. Replays of previously

3023

# handled requests will yield the same response as the first execution.

3024

#

3025

# Required for DML statements. Ignored for queries.

3026

"resumeToken": "A String", # If this request is resuming a previously interrupted SQL statement

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3027

# execution, `resume_token` should be copied from the last

3028

# PartialResultSet yielded before the interruption. Doing this

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3029

# enables the new SQL statement execution to resume where the last one left

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3030

# off. The rest of the request parameters must exactly match the

3031

# request that yielded this token.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3032

"partitionToken": "A String", # If present, results will be restricted to the specified partition

3033

# previously created using PartitionQuery(). There must be an exact

3034

# match for the values of fields common to this message and the

3035

# PartitionQueryRequest message used to create this partition_token.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3036

"paramTypes": { # It is not always possible for Cloud Spanner to infer the right SQL type

3037

# from a JSON value. For example, values of type `BYTES` and values

3038

# of type `STRING` both appear in params as JSON strings.

3039

#

3040

# In these cases, `param_types` can be used to specify the exact

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3041

# SQL type for some or all of the SQL statement parameters. See the

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3042

# definition of Type for more information

3043

# about SQL types.

3044

"a_key": { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a

3045

# table cell or returned from an SQL query.

3046

"structType": # Object with schema name: StructType # If code == STRUCT, then `struct_type`

3047

# provides type information for the struct's fields.

3048

"code": "A String", # Required. The TypeCode for this type.

3049

"arrayElementType": # Object with schema name: Type # If code == ARRAY, then `array_element_type`

3050

# is the type of the array elements.

3051

},

3052

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3053

"queryMode": "A String", # Used to control the amount of debugging information returned in

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3054

# ResultSetStats. If partition_token is set, query_mode can only

3055

# be set to QueryMode.NORMAL.

3056

"sql": "A String", # Required. The SQL string.

3057

"params": { # The SQL string can contain parameter placeholders. A parameter

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3058

# placeholder consists of `'@'` followed by the parameter

3059

# name. Parameter names consist of any combination of letters,

3060

# numbers, and underscores.

3061

#

3062

# Parameters can appear anywhere that a literal value is expected. The same

3063

# parameter name can be used more than once, for example:

3064

# `"WHERE id > @msg_id AND id < @msg_id + 100"`

3065

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3066

# It is an error to execute an SQL statement with unbound parameters.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3067

#

3068

# Parameter values are specified using `params`, which is a JSON

3069

# object whose keys are parameter names, and whose values are the

3070

# corresponding parameter values.

3071

"a_key": "", # Properties of the object.

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

3082

3083

{ # Results from Read or

3084

# ExecuteSql.

3085

"rows": [ # Each element in `rows` is a row whose format is defined by

3086

# metadata.row_type. The ith element

3087

# in each row matches the ith field in

3088

# metadata.row_type. Elements are

3089

# encoded based on type as described

# here.

[

"",

],

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3095

"stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the SQL statement that

3096

# produced this result set. These can be requested by setting

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3097

# ExecuteSqlRequest.query_mode.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3098

# DML statements always produce stats containing the number of rows

3099

# modified, unless executed using the

3100

# ExecuteSqlRequest.QueryMode.PLAN ExecuteSqlRequest.query_mode.

3101

# Other fields may or may not be populated, based on the

3102

# ExecuteSqlRequest.query_mode.

3103

"rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it

3104

# returns a lower bound of the rows modified.

3105

"rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3106

"queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.

3107

"planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting

3108

# with the plan root. Each PlanNode's `id` corresponds to its index in

3109

# `plan_nodes`.

3110

{ # Node information for nodes appearing in a QueryPlan.plan_nodes.

3111

"index": 42, # The `PlanNode`'s index in node list.

3112

"kind": "A String", # Used to determine the type of node. May be needed for visualizing

3113

# different kinds of nodes differently. For example, If the node is a

3114

# SCALAR node, it will have a condensed representation

3115

# which can be used to directly embed a description of the node in its

3116

# parent.

3117

"displayName": "A String", # The display name for the node.

3118

"executionStats": { # The execution statistics associated with the node, contained in a group of

3119

# key-value pairs. Only present if the plan was returned as a result of a

3120

# profile query. For example, number of executions, number of rows/time per

3121

# execution etc.

3122

"a_key": "", # Properties of the object.

3123

},

3124

"childLinks": [ # List of child node `index`es and their relationship to this parent.

3125

{ # Metadata associated with a parent-child relationship appearing in a

3126

# PlanNode.

3127

"variable": "A String", # Only present if the child node is SCALAR and corresponds

3128

# to an output variable of the parent node. The field carries the name of

3129

# the output variable.

3130

# For example, a `TableScan` operator that reads rows from a table will

3131

# have child links to the `SCALAR` nodes representing the output variables

3132

# created for each column that is read by the operator. The corresponding

3133

# `variable` fields will be set to the variable names assigned to the

3134

# columns.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

3135

"childIndex": 42, # The node to which the link points.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3136

"type": "A String", # The type of the link. For example, in Hash Joins this could be used to

3137

# distinguish between the build child and the probe child, or in the case

3138

# of the child being an output variable, to represent the tag associated

3139

# with the output variable.

3140

},

3141

],

3142

"shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.

3143

# `SCALAR` PlanNode(s).

3144

"subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases

3145

# where the `description` string of this node references a `SCALAR`

3146

# subquery contained in the expression subtree rooted at this node. The

3147

# referenced `SCALAR` subquery may not necessarily be a direct child of

# this node.

"a_key": 42,

},

"description": "A String", # A string representation of the expression subtree rooted at this node.

3152

},

3153

"metadata": { # Attributes relevant to the node contained in a group of key-value pairs.

3154

# For example, a Parameter Reference node could have the following

3155

# information in its metadata:

3156

#

3157

# {

3158

# "parameter_reference": "param1",

3159

# "parameter_type": "array"

3160

# }

3161

"a_key": "", # Properties of the object.

},

},

],

},

"queryStats": { # Aggregated statistics from the execution of the query. Only present when

3167

# the query is profiled. For example, a query could return the statistics as

# follows:

#

# {

# "rows_returned": "3",

3172

# "elapsed_time": "1.22 secs",

3173

# "cpu_time": "1.19 secs"

3174

# }

3175

"a_key": "", # Properties of the object.

3176

},

3177

},

3178

"metadata": { # Metadata about a ResultSet or PartialResultSet. # Metadata about the result set, such as row type information.

3179

"rowType": { # `StructType` defines the fields of a STRUCT type. # Indicates the field names and types for the rows in the result

3180

# set. For example, a SQL query like `"SELECT UserId, UserName FROM

3181

# Users"` could return a `row_type` value like:

3182

#

3183

# "fields": [

3184

# { "name": "UserId", "type": { "code": "INT64" } },

3185

# { "name": "UserName", "type": { "code": "STRING" } },

3186

# ]

3187

"fields": [ # The list of fields that make up this struct. Order is

3188

# significant, because values of this struct type are represented as

3189

# lists, where the order of field values matches the order of

3190

# fields in the StructType. In turn, the order of fields

3191

# matches the order of columns in a read request, or the order of

3192

# fields in the `SELECT` clause of a query.

3193

{ # Message representing a single field of a struct.

3194

"type": { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a # The type of the field.

3195

# table cell or returned from an SQL query.

3196

"structType": # Object with schema name: StructType # If code == STRUCT, then `struct_type`

3197

# provides type information for the struct's fields.

3198

"code": "A String", # Required. The TypeCode for this type.

3199

"arrayElementType": # Object with schema name: Type # If code == ARRAY, then `array_element_type`

3200

# is the type of the array elements.

3201

},

3202

"name": "A String", # The name of the field. For reads, this is the column name. For

3203

# SQL queries, it is the column alias (e.g., `"Word"` in the

3204

# query `"SELECT 'hello' AS Word"`), or the column name (e.g.,

3205

# `"ColName"` in the query `"SELECT ColName FROM Table"`). Some

3206

# columns might have an empty name (e.g., !"SELECT

3207

# UPPER(ColName)"`). Note that a query result can contain

3208

# multiple fields with the same name.

},

],

},

"transaction": { # A transaction. # If the read or SQL query began a transaction as a side-effect, the

3213

# information about the new transaction is yielded here.

3214

"readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen

3215

# for the transaction. Not returned by default: see

3216

# TransactionOptions.ReadOnly.return_read_timestamp.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3217

#

3218

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

3219

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3220

"id": "A String", # `id` may be used to identify the transaction in subsequent

# Read,

# ExecuteSql,

# Commit, or

# Rollback calls.

#

# Single-use read-only transactions do not have IDs, because

3227

# single-use transactions do not support multiple requests.

},

},

}</pre>

</div>

<code class="details" id="executeStreamingSql">executeStreamingSql(session, body, x__xgafv=None)</code>

3235

<pre>Like ExecuteSql, except returns the result

3236

set as a stream. Unlike ExecuteSql, there

3237

is no limit on the size of the returned result set. However, no

3238

individual row in the result set can exceed 100 MiB, and no

3239

column value can exceed 10 MiB.

3240

3241

Args:

3242

session: string, Required. The session in which the SQL query should be performed. (required)

3243

body: object, The request body. (required)

3244

The object takes the form of:

3245

3246

{ # The request for ExecuteSql and

3247

# ExecuteStreamingSql.

3248

"transaction": { # This message is used to select the transaction in which a # The transaction to use. If none is provided, the default is a

3249

# temporary read-only transaction with strong concurrency.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3250

#

3251

# The transaction to use.

3252

#

3253

# For queries, if none is provided, the default is a temporary read-only

3254

# transaction with strong concurrency.

3255

#

3256

# Standard DML statements require a ReadWrite transaction. Single-use

3257

# transactions are not supported (to avoid replay). The caller must

3258

# either supply an existing transaction ID or begin a new transaction.

3259

#

3260

# Partitioned DML requires an existing PartitionedDml transaction ID.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3261

# Read or

3262

# ExecuteSql call runs.

3263

#

3264

# See TransactionOptions for more information about transactions.

3265

"begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in

3266

# it. The transaction ID of the new transaction is returned in

3267

# ResultSetMetadata.transaction, which is a Transaction.

3268

#

3269

#

3270

# Each session can have at most one active transaction at a time. After the

3271

# active transaction is completed, the session can immediately be

3272

# re-used for the next transaction. It is not necessary to create a

3273

# new session for each transaction.

3274

#

3275

# # Transaction Modes

3276

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3277

# Cloud Spanner supports three transaction modes:

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3278

#

3279

# 1. Locking read-write. This type of transaction is the only way

3280

# to write data into Cloud Spanner. These transactions rely on

3281

# pessimistic locking and, if necessary, two-phase commit.

3282

# Locking read-write transactions may abort, requiring the

3283

# application to retry.

3284

#

3285

# 2. Snapshot read-only. This transaction type provides guaranteed

3286

# consistency across several reads, but does not allow

3287

# writes. Snapshot read-only transactions can be configured to

3288

# read at timestamps in the past. Snapshot read-only

3289

# transactions do not need to be committed.

3290

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3291

# 3. Partitioned DML. This type of transaction is used to execute

3292

# a single Partitioned DML statement. Partitioned DML partitions

3293

# the key space and runs the DML statement over each partition

3294

# in parallel using separate, internal transactions that commit

3295

# independently. Partitioned DML transactions do not need to be

3296

# committed.

3297

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3298

# For transactions that only read, snapshot read-only transactions

3299

# provide simpler semantics and are almost always faster. In

3300

# particular, read-only transactions do not take locks, so they do

3301

# not conflict with read-write transactions. As a consequence of not

3302

# taking locks, they also do not abort, so retry loops are not needed.

3303

#

3304

# Transactions may only read/write data in a single database. They

3305

# may, however, read/write data in different tables within that

3306

# database.

3307

#

3308

# ## Locking Read-Write Transactions

3309

#

3310

# Locking transactions may be used to atomically read-modify-write

3311

# data anywhere in a database. This type of transaction is externally

3312

# consistent.

3313

#

3314

# Clients should attempt to minimize the amount of time a transaction

3315

# is active. Faster transactions commit with higher probability

3316

# and cause less contention. Cloud Spanner attempts to keep read locks

3317

# active as long as the transaction continues to do reads, and the

3318

# transaction has not been terminated by

3319

# Commit or

3320

# Rollback. Long periods of

3321

# inactivity at the client may cause Cloud Spanner to release a

3322

# transaction's locks and abort it.

3323

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3324

# Conceptually, a read-write transaction consists of zero or more

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3325

# reads or SQL statements followed by

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3326

# Commit. At any time before

3327

# Commit, the client can send a

3328

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

3334

# are still valid at commit time, and it is able to acquire write

3335

# locks for all writes. Cloud Spanner can abort the transaction for any

3336

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

3337

# that the transaction has not modified any user data in Cloud Spanner.

3338

#

3339

# Unless the transaction commits, Cloud Spanner makes no guarantees about

3340

# how long the transaction's locks were held for. It is an error to

3341

# use Cloud Spanner locks for any sort of mutual exclusion other than

3342

# between Cloud Spanner transactions themselves.

3343

#

3344

# ### Retrying Aborted Transactions

3345

#

3346

# When a transaction aborts, the application can choose to retry the

3347

# whole transaction again. To maximize the chances of successfully

3348

# committing the retry, the client should execute the retry in the

3349

# same session as the original attempt. The original session's lock

3350

# priority increases with each consecutive abort, meaning that each

3351

# attempt has a slightly better chance of success than the previous.

3352

#

3353

# Under some circumstances (e.g., many transactions attempting to

3354

# modify the same row(s)), a transaction can abort many times in a

3355

# short period before successfully committing. Thus, it is not a good

3356

# idea to cap the number of retries a transaction can attempt;

3357

# instead, it is better to limit the total amount of wall time spent

3358

# retrying.

3359

#

3360

# ### Idle Transactions

3361

#

3362

# A transaction is considered idle if it has no outstanding reads or

3363

# SQL queries and has not started a read or SQL query within the last 10

3364

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

3365

# don't hold on to locks indefinitely. In that case, the commit will

3366

# fail with error `ABORTED`.

3367

#

3368

# If this behavior is undesirable, periodically executing a simple

3369

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

3370

# transaction from becoming idle.

3371

#

3372

# ## Snapshot Read-Only Transactions

3373

#

3374

# Snapshot read-only transactions provides a simpler method than

3375

# locking read-write transactions for doing several consistent

3376

# reads. However, this type of transaction does not support writes.

3377

#

3378

# Snapshot transactions do not take locks. Instead, they work by

3379

# choosing a Cloud Spanner timestamp, then executing all reads at that

3380

# timestamp. Since they do not acquire locks, they do not block

3381

# concurrent read-write transactions.

3382

#

3383

# Unlike locking read-write transactions, snapshot read-only

3384

# transactions never abort. They can fail if the chosen read

3385

# timestamp is garbage collected; however, the default garbage

3386

# collection policy is generous enough that most applications do not

3387

# need to worry about this in practice.

3388

#

3389

# Snapshot read-only transactions do not need to call

3390

# Commit or

3391

# Rollback (and in fact are not

3392

# permitted to do so).

3393

#

3394

# To execute a snapshot transaction, the client specifies a timestamp

3395

# bound, which tells Cloud Spanner how to choose a read timestamp.

3396

#

3397

# The types of timestamp bound are:

3398

#

3399

# - Strong (the default).

3400

# - Bounded staleness.

3401

# - Exact staleness.

3402

#

3403

# If the Cloud Spanner database to be read is geographically distributed,

3404

# stale read-only transactions can execute more quickly than strong

3405

# or read-write transaction, because they are able to execute far

3406

# from the leader replica.

3407

#

3408

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

3413

# that have committed before the start of the read. Furthermore, all

3414

# rows yielded by a single read are consistent with each other -- if

3415

# any part of the read observes a transaction, all parts of the read

3416

# see the transaction.

3417

#

3418

# Strong reads are not repeatable: two consecutive strong read-only

3419

# transactions might return inconsistent results if there are

3420

# concurrent writes. If consistency across reads is required, the

3421

# reads should be executed within a transaction or at an exact read

3422

# timestamp.

3423

#

3424

# See TransactionOptions.ReadOnly.strong.

3425

#

3426

# ### Exact Staleness

3427

#

3428

# These timestamp bounds execute reads at a user-specified

3429

# timestamp. Reads at a timestamp are guaranteed to see a consistent

3430

# prefix of the global transaction history: they observe

3431

# modifications done by all transactions with a commit timestamp <=

3432

# the read timestamp, and observe none of the modifications done by

3433

# transactions with a larger commit timestamp. They will block until

3434

# all conflicting transactions that may be assigned commit timestamps

3435

# <= the read timestamp have finished.

3436

#

3437

# The timestamp can either be expressed as an absolute Cloud Spanner commit

3438

# timestamp or a staleness relative to the current time.

3439

#

3440

# These modes do not require a "negotiation phase" to pick a

3441

# timestamp. As a result, they execute slightly faster than the

3442

# equivalent boundedly stale concurrency modes. On the other hand,

3443

# boundedly stale reads usually return fresher results.

3444

#

3445

# See TransactionOptions.ReadOnly.read_timestamp and

3446

# TransactionOptions.ReadOnly.exact_staleness.

3447

#

3448

# ### Bounded Staleness

3449

#

3450

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

3451

# subject to a user-provided staleness bound. Cloud Spanner chooses the

3452

# newest timestamp within the staleness bound that allows execution

3453

# of the reads at the closest available replica without blocking.

3454

#

3455

# All rows yielded are consistent with each other -- if any part of

3456

# the read observes a transaction, all parts of the read see the

3457

# transaction. Boundedly stale reads are not repeatable: two stale

3458

# reads, even if they use the same staleness bound, can execute at

3459

# different timestamps and thus return inconsistent results.

3460

#

3461

# Boundedly stale reads execute in two phases: the first phase

3462

# negotiates a timestamp among all replicas needed to serve the

3463

# read. In the second phase, reads are executed at the negotiated

3464

# timestamp.

3465

#

3466

# As a result of the two phase execution, bounded staleness reads are

3467

# usually a little slower than comparable exact staleness

3468

# reads. However, they are typically able to return fresher

3469

# results, and are more likely to execute at the closest replica.

3470

#

3471

# Because the timestamp negotiation requires up-front knowledge of

3472

# which rows will be read, it can only be used with single-use

3473

# read-only transactions.

3474

#

3475

# See TransactionOptions.ReadOnly.max_staleness and

3476

# TransactionOptions.ReadOnly.min_read_timestamp.

3477

#

3478

# ### Old Read Timestamps and Garbage Collection

3479

#

3480

# Cloud Spanner continuously garbage collects deleted and overwritten data

3481

# in the background to reclaim storage space. This process is known

3482

# as "version GC". By default, version GC reclaims versions after they

3483

# are one hour old. Because of this, Cloud Spanner cannot perform reads

3484

# at read timestamps more than one hour in the past. This

3485

# restriction also applies to in-progress reads and/or SQL queries whose

3486

# timestamp become too old while executing. Reads and SQL queries with

3487

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3488

#

3489

# ## Partitioned DML Transactions

3490

#

3491

# Partitioned DML transactions are used to execute DML statements with a

3492

# different execution strategy that provides different, and often better,

3493

# scalability properties for large, table-wide operations than DML in a

3494

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

3495

# should prefer using ReadWrite transactions.

3496

#

3497

# Partitioned DML partitions the keyspace and runs the DML statement on each

3498

# partition in separate, internal transactions. These transactions commit

3499

# automatically when complete, and run independently from one another.

3500

#

3501

# To reduce lock contention, this execution strategy only acquires read locks

3502

# on rows that match the WHERE clause of the statement. Additionally, the

3503

# smaller per-partition transactions hold locks for less time.

3504

#

3505

# That said, Partitioned DML is not a drop-in replacement for standard DML used

3506

# in ReadWrite transactions.

3507

#

3508

# - The DML statement must be fully-partitionable. Specifically, the statement

3509

# must be expressible as the union of many statements which each access only

3510

# a single row of the table.

3511

#

3512

# - The statement is not applied atomically to all rows of the table. Rather,

3513

# the statement is applied atomically to partitions of the table, in

3514

# independent transactions. Secondary index rows are updated atomically

3515

# with the base table rows.

3516

#

3517

# - Partitioned DML does not guarantee exactly-once execution semantics

3518

# against a partition. The statement will be applied at least once to each

3519

# partition. It is strongly recommended that the DML statement should be

3520

# idempotent to avoid unexpected results. For instance, it is potentially

3521

# dangerous to run a statement such as

3522

# `UPDATE table SET column = column + 1` as it could be run multiple times

3523

# against some rows.

3524

#

3525

# - The partitions are committed automatically - there is no support for

3526

# Commit or Rollback. If the call returns an error, or if the client issuing

3527

# the ExecuteSql call dies, it is possible that some rows had the statement

3528

# executed on them successfully. It is also possible that statement was

3529

# never executed against other rows.

3530

#

3531

# - Partitioned DML transactions may only contain the execution of a single

3532

# DML statement via ExecuteSql or ExecuteStreamingSql.

3533

#

3534

# - If any error is encountered during the execution of the partitioned DML

3535

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

3536

# value that cannot be stored due to schema constraints), then the

3537

# operation is stopped at that point and an error is returned. It is

3538

# possible that at this point, some partitions have been committed (or even

3539

# committed multiple times), and other partitions have not been run at all.

3540

#

3541

# Given the above, Partitioned DML is good fit for large, database-wide,

3542

# operations that are idempotent, such as deleting old rows from a very large

3543

# table.

3544

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3545

#

3546

# Authorization to begin a read-write transaction requires

3547

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

3548

# on the `session` resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3549

# transaction type has no options.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3550

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3551

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3552

#

3553

# Authorization to begin a read-only transaction requires

3554

# `spanner.databases.beginReadOnlyTransaction` permission

3555

# on the `session` resource.

3556

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

3557

#

3558

# This is useful for requesting fresher data than some previous

3559

# read, or data that is fresh enough to observe the effects of some

3560

# previously committed transaction whose timestamp is known.

3561

#

3562

# Note that this option can only be used in single-use transactions.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3563

#

3564

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

3565

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3566

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

3567

# the Transaction message that describes the transaction.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3568

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

3569

# seconds. Guarantees that all writes that have committed more

3570

# than the specified number of seconds ago are visible. Because

3571

# Cloud Spanner chooses the exact timestamp, this mode works even if

3572

# the client's local clock is substantially skewed from Cloud Spanner

3573

# commit timestamps.

3574

#

3575

# Useful for reading the freshest data available at a nearby

3576

# replica, while bounding the possible staleness if the local

3577

# replica has fallen behind.

3578

#

3579

# Note that this option can only be used in single-use

3580

# transactions.

3581

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

3582

# old. The timestamp is chosen soon after the read is started.

3583

#

3584

# Guarantees that all writes that have committed more than the

3585

# specified number of seconds ago are visible. Because Cloud Spanner

3586

# chooses the exact timestamp, this mode works even if the client's

3587

# local clock is substantially skewed from Cloud Spanner commit

3588

# timestamps.

3589

#

3590

# Useful for reading at nearby replicas without the distributed

3591

# timestamp negotiation overhead of `max_staleness`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3592

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

3593

# reads at a specific timestamp are repeatable; the same read at

3594

# the same timestamp always returns the same data. If the

3595

# timestamp is in the future, the read will block until the

3596

# specified timestamp, modulo the read's deadline.

3597

#

3598

# Useful for large scale consistent reads such as mapreduces, or

3599

# for coordinating many reads against a consistent snapshot of the

3600

# data.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3601

#

3602

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

3603

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3604

"strong": True or False, # Read at a timestamp where all previously committed transactions

3605

# are visible.

3606

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3607

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

3608

#

3609

# Authorization to begin a Partitioned DML transaction requires

3610

# `spanner.databases.beginPartitionedDmlTransaction` permission

3611

# on the `session` resource.

3612

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3613

},

3614

"singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.

3615

# This is the most efficient way to execute a transaction that

3616

# consists of a single SQL query.

3617

#

3618

#

3619

# Each session can have at most one active transaction at a time. After the

3620

# active transaction is completed, the session can immediately be

3621

# re-used for the next transaction. It is not necessary to create a

3622

# new session for each transaction.

3623

#

3624

# # Transaction Modes

3625

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3626

# Cloud Spanner supports three transaction modes:

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3627

#

3628

# 1. Locking read-write. This type of transaction is the only way

3629

# to write data into Cloud Spanner. These transactions rely on

3630

# pessimistic locking and, if necessary, two-phase commit.

3631

# Locking read-write transactions may abort, requiring the

3632

# application to retry.

3633

#

3634

# 2. Snapshot read-only. This transaction type provides guaranteed

3635

# consistency across several reads, but does not allow

3636

# writes. Snapshot read-only transactions can be configured to

3637

# read at timestamps in the past. Snapshot read-only

3638

# transactions do not need to be committed.

3639

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3640

# 3. Partitioned DML. This type of transaction is used to execute

3641

# a single Partitioned DML statement. Partitioned DML partitions

3642

# the key space and runs the DML statement over each partition

3643

# in parallel using separate, internal transactions that commit

3644

# independently. Partitioned DML transactions do not need to be

3645

# committed.

3646

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3647

# For transactions that only read, snapshot read-only transactions

3648

# provide simpler semantics and are almost always faster. In

3649

# particular, read-only transactions do not take locks, so they do

3650

# not conflict with read-write transactions. As a consequence of not

3651

# taking locks, they also do not abort, so retry loops are not needed.

3652

#

3653

# Transactions may only read/write data in a single database. They

3654

# may, however, read/write data in different tables within that

3655

# database.

3656

#

3657

# ## Locking Read-Write Transactions

3658

#

3659

# Locking transactions may be used to atomically read-modify-write

3660

# data anywhere in a database. This type of transaction is externally

3661

# consistent.

3662

#

3663

# Clients should attempt to minimize the amount of time a transaction

3664

# is active. Faster transactions commit with higher probability

3665

# and cause less contention. Cloud Spanner attempts to keep read locks

3666

# active as long as the transaction continues to do reads, and the

3667

# transaction has not been terminated by

3668

# Commit or

3669

# Rollback. Long periods of

3670

# inactivity at the client may cause Cloud Spanner to release a

3671

# transaction's locks and abort it.

3672

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3673

# Conceptually, a read-write transaction consists of zero or more

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3674

# reads or SQL statements followed by

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3675

# Commit. At any time before

3676

# Commit, the client can send a

3677

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

3683

# are still valid at commit time, and it is able to acquire write

3684

# locks for all writes. Cloud Spanner can abort the transaction for any

3685

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

3686

# that the transaction has not modified any user data in Cloud Spanner.

3687

#

3688

# Unless the transaction commits, Cloud Spanner makes no guarantees about

3689

# how long the transaction's locks were held for. It is an error to

3690

# use Cloud Spanner locks for any sort of mutual exclusion other than

3691

# between Cloud Spanner transactions themselves.

3692

#

3693

# ### Retrying Aborted Transactions

3694

#

3695

# When a transaction aborts, the application can choose to retry the

3696

# whole transaction again. To maximize the chances of successfully

3697

# committing the retry, the client should execute the retry in the

3698

# same session as the original attempt. The original session's lock

3699

# priority increases with each consecutive abort, meaning that each

3700

# attempt has a slightly better chance of success than the previous.

3701

#

3702

# Under some circumstances (e.g., many transactions attempting to

3703

# modify the same row(s)), a transaction can abort many times in a

3704

# short period before successfully committing. Thus, it is not a good

3705

# idea to cap the number of retries a transaction can attempt;

3706

# instead, it is better to limit the total amount of wall time spent

3707

# retrying.

3708

#

3709

# ### Idle Transactions

3710

#

3711

# A transaction is considered idle if it has no outstanding reads or

3712

# SQL queries and has not started a read or SQL query within the last 10

3713

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

3714

# don't hold on to locks indefinitely. In that case, the commit will

3715

# fail with error `ABORTED`.

3716

#

3717

# If this behavior is undesirable, periodically executing a simple

3718

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

3719

# transaction from becoming idle.

3720

#

3721

# ## Snapshot Read-Only Transactions

3722

#

3723

# Snapshot read-only transactions provides a simpler method than

3724

# locking read-write transactions for doing several consistent

3725

# reads. However, this type of transaction does not support writes.

3726

#

3727

# Snapshot transactions do not take locks. Instead, they work by

3728

# choosing a Cloud Spanner timestamp, then executing all reads at that

3729

# timestamp. Since they do not acquire locks, they do not block

3730

# concurrent read-write transactions.

3731

#

3732

# Unlike locking read-write transactions, snapshot read-only

3733

# transactions never abort. They can fail if the chosen read

3734

# timestamp is garbage collected; however, the default garbage

3735

# collection policy is generous enough that most applications do not

3736

# need to worry about this in practice.

3737

#

3738

# Snapshot read-only transactions do not need to call

3739

# Commit or

3740

# Rollback (and in fact are not

3741

# permitted to do so).

3742

#

3743

# To execute a snapshot transaction, the client specifies a timestamp

3744

# bound, which tells Cloud Spanner how to choose a read timestamp.

3745

#

3746

# The types of timestamp bound are:

3747

#

3748

# - Strong (the default).

3749

# - Bounded staleness.

3750

# - Exact staleness.

3751

#

3752

# If the Cloud Spanner database to be read is geographically distributed,

3753

# stale read-only transactions can execute more quickly than strong

3754

# or read-write transaction, because they are able to execute far

3755

# from the leader replica.

3756

#

3757

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

3762

# that have committed before the start of the read. Furthermore, all

3763

# rows yielded by a single read are consistent with each other -- if

3764

# any part of the read observes a transaction, all parts of the read

3765

# see the transaction.

3766

#

3767

# Strong reads are not repeatable: two consecutive strong read-only

3768

# transactions might return inconsistent results if there are

3769

# concurrent writes. If consistency across reads is required, the

3770

# reads should be executed within a transaction or at an exact read

3771

# timestamp.

3772

#

3773

# See TransactionOptions.ReadOnly.strong.

3774

#

3775

# ### Exact Staleness

3776

#

3777

# These timestamp bounds execute reads at a user-specified

3778

# timestamp. Reads at a timestamp are guaranteed to see a consistent

3779

# prefix of the global transaction history: they observe

3780

# modifications done by all transactions with a commit timestamp <=

3781

# the read timestamp, and observe none of the modifications done by

3782

# transactions with a larger commit timestamp. They will block until

3783

# all conflicting transactions that may be assigned commit timestamps

3784

# <= the read timestamp have finished.

3785

#

3786

# The timestamp can either be expressed as an absolute Cloud Spanner commit

3787

# timestamp or a staleness relative to the current time.

3788

#

3789

# These modes do not require a "negotiation phase" to pick a

3790

# timestamp. As a result, they execute slightly faster than the

3791

# equivalent boundedly stale concurrency modes. On the other hand,

3792

# boundedly stale reads usually return fresher results.

3793

#

3794

# See TransactionOptions.ReadOnly.read_timestamp and

3795

# TransactionOptions.ReadOnly.exact_staleness.

3796

#

3797

# ### Bounded Staleness

3798

#

3799

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

3800

# subject to a user-provided staleness bound. Cloud Spanner chooses the

3801

# newest timestamp within the staleness bound that allows execution

3802

# of the reads at the closest available replica without blocking.

3803

#

3804

# All rows yielded are consistent with each other -- if any part of

3805

# the read observes a transaction, all parts of the read see the

3806

# transaction. Boundedly stale reads are not repeatable: two stale

3807

# reads, even if they use the same staleness bound, can execute at

3808

# different timestamps and thus return inconsistent results.

3809

#

3810

# Boundedly stale reads execute in two phases: the first phase

3811

# negotiates a timestamp among all replicas needed to serve the

3812

# read. In the second phase, reads are executed at the negotiated

3813

# timestamp.

3814

#

3815

# As a result of the two phase execution, bounded staleness reads are

3816

# usually a little slower than comparable exact staleness

3817

# reads. However, they are typically able to return fresher

3818

# results, and are more likely to execute at the closest replica.

3819

#

3820

# Because the timestamp negotiation requires up-front knowledge of

3821

# which rows will be read, it can only be used with single-use

3822

# read-only transactions.

3823

#

3824

# See TransactionOptions.ReadOnly.max_staleness and

3825

# TransactionOptions.ReadOnly.min_read_timestamp.

3826

#

3827

# ### Old Read Timestamps and Garbage Collection

3828

#

3829

# Cloud Spanner continuously garbage collects deleted and overwritten data

3830

# in the background to reclaim storage space. This process is known

3831

# as "version GC". By default, version GC reclaims versions after they

3832

# are one hour old. Because of this, Cloud Spanner cannot perform reads

3833

# at read timestamps more than one hour in the past. This

3834

# restriction also applies to in-progress reads and/or SQL queries whose

3835

# timestamp become too old while executing. Reads and SQL queries with

3836

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3837

#

3838

# ## Partitioned DML Transactions

3839

#

3840

# Partitioned DML transactions are used to execute DML statements with a

3841

# different execution strategy that provides different, and often better,

3842

# scalability properties for large, table-wide operations than DML in a

3843

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

3844

# should prefer using ReadWrite transactions.

3845

#

3846

# Partitioned DML partitions the keyspace and runs the DML statement on each

3847

# partition in separate, internal transactions. These transactions commit

3848

# automatically when complete, and run independently from one another.

3849

#

3850

# To reduce lock contention, this execution strategy only acquires read locks

3851

# on rows that match the WHERE clause of the statement. Additionally, the

3852

# smaller per-partition transactions hold locks for less time.

3853

#

3854

# That said, Partitioned DML is not a drop-in replacement for standard DML used

3855

# in ReadWrite transactions.

3856

#

3857

# - The DML statement must be fully-partitionable. Specifically, the statement

3858

# must be expressible as the union of many statements which each access only

3859

# a single row of the table.

3860

#

3861

# - The statement is not applied atomically to all rows of the table. Rather,

3862

# the statement is applied atomically to partitions of the table, in

3863

# independent transactions. Secondary index rows are updated atomically

3864

# with the base table rows.

3865

#

3866

# - Partitioned DML does not guarantee exactly-once execution semantics

3867

# against a partition. The statement will be applied at least once to each

3868

# partition. It is strongly recommended that the DML statement should be

3869

# idempotent to avoid unexpected results. For instance, it is potentially

3870

# dangerous to run a statement such as

3871

# `UPDATE table SET column = column + 1` as it could be run multiple times

3872

# against some rows.

3873

#

3874

# - The partitions are committed automatically - there is no support for

3875

# Commit or Rollback. If the call returns an error, or if the client issuing

3876

# the ExecuteSql call dies, it is possible that some rows had the statement

3877

# executed on them successfully. It is also possible that statement was

3878

# never executed against other rows.

3879

#

3880

# - Partitioned DML transactions may only contain the execution of a single

3881

# DML statement via ExecuteSql or ExecuteStreamingSql.

3882

#

3883

# - If any error is encountered during the execution of the partitioned DML

3884

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

3885

# value that cannot be stored due to schema constraints), then the

3886

# operation is stopped at that point and an error is returned. It is

3887

# possible that at this point, some partitions have been committed (or even

3888

# committed multiple times), and other partitions have not been run at all.

3889

#

3890

# Given the above, Partitioned DML is good fit for large, database-wide,

3891

# operations that are idempotent, such as deleting old rows from a very large

3892

# table.

3893

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3894

#

3895

# Authorization to begin a read-write transaction requires

3896

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

3897

# on the `session` resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3898

# transaction type has no options.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3899

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3900

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3901

#

3902

# Authorization to begin a read-only transaction requires

3903

# `spanner.databases.beginReadOnlyTransaction` permission

3904

# on the `session` resource.

3905

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

3906

#

3907

# This is useful for requesting fresher data than some previous

3908

# read, or data that is fresh enough to observe the effects of some

3909

# previously committed transaction whose timestamp is known.

3910

#

3911

# Note that this option can only be used in single-use transactions.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3912

#

3913

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

3914

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3915

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

3916

# the Transaction message that describes the transaction.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3917

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

3918

# seconds. Guarantees that all writes that have committed more

3919

# than the specified number of seconds ago are visible. Because

3920

# Cloud Spanner chooses the exact timestamp, this mode works even if

3921

# the client's local clock is substantially skewed from Cloud Spanner

3922

# commit timestamps.

3923

#

3924

# Useful for reading the freshest data available at a nearby

3925

# replica, while bounding the possible staleness if the local

3926

# replica has fallen behind.

3927

#

3928

# Note that this option can only be used in single-use

3929

# transactions.

3930

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

3931

# old. The timestamp is chosen soon after the read is started.

3932

#

3933

# Guarantees that all writes that have committed more than the

3934

# specified number of seconds ago are visible. Because Cloud Spanner

3935

# chooses the exact timestamp, this mode works even if the client's

3936

# local clock is substantially skewed from Cloud Spanner commit

3937

# timestamps.

3938

#

3939

# Useful for reading at nearby replicas without the distributed

3940

# timestamp negotiation overhead of `max_staleness`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

3941

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

3942

# reads at a specific timestamp are repeatable; the same read at

3943

# the same timestamp always returns the same data. If the

3944

# timestamp is in the future, the read will block until the

3945

# specified timestamp, modulo the read's deadline.

3946

#

3947

# Useful for large scale consistent reads such as mapreduces, or

3948

# for coordinating many reads against a consistent snapshot of the

3949

# data.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3950

#

3951

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

3952

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3953

"strong": True or False, # Read at a timestamp where all previously committed transactions

3954

# are visible.

3955

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3956

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

3957

#

3958

# Authorization to begin a Partitioned DML transaction requires

3959

# `spanner.databases.beginPartitionedDmlTransaction` permission

3960

# on the `session` resource.

3961

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3962

},

3963

"id": "A String", # Execute the read or SQL query in a previously-started transaction.

3964

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3965

"seqno": "A String", # A per-transaction sequence number used to identify this request. This

3966

# makes each request idempotent such that if the request is received multiple

3967

# times, at most one will succeed.

3968

#

3969

# The sequence number must be monotonically increasing within the

3970

# transaction. If a request arrives for the first time with an out-of-order

3971

# sequence number, the transaction may be aborted. Replays of previously

3972

# handled requests will yield the same response as the first execution.

3973

#

3974

# Required for DML statements. Ignored for queries.

3975

"resumeToken": "A String", # If this request is resuming a previously interrupted SQL statement

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3976

# execution, `resume_token` should be copied from the last

3977

# PartialResultSet yielded before the interruption. Doing this

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3978

# enables the new SQL statement execution to resume where the last one left

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3979

# off. The rest of the request parameters must exactly match the

3980

# request that yielded this token.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3981

"partitionToken": "A String", # If present, results will be restricted to the specified partition

3982

# previously created using PartitionQuery(). There must be an exact

3983

# match for the values of fields common to this message and the

3984

# PartitionQueryRequest message used to create this partition_token.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3985

"paramTypes": { # It is not always possible for Cloud Spanner to infer the right SQL type

3986

# from a JSON value. For example, values of type `BYTES` and values

3987

# of type `STRING` both appear in params as JSON strings.

3988

#

3989

# In these cases, `param_types` can be used to specify the exact

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

3990

# SQL type for some or all of the SQL statement parameters. See the

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

3991

# definition of Type for more information

3992

# about SQL types.

3993

"a_key": { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a

3994

# table cell or returned from an SQL query.

3995

"structType": # Object with schema name: StructType # If code == STRUCT, then `struct_type`

3996

# provides type information for the struct's fields.

3997

"code": "A String", # Required. The TypeCode for this type.

3998

"arrayElementType": # Object with schema name: Type # If code == ARRAY, then `array_element_type`

3999

# is the type of the array elements.

4000

},

4001

},

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4002

"queryMode": "A String", # Used to control the amount of debugging information returned in

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4003

# ResultSetStats. If partition_token is set, query_mode can only

4004

# be set to QueryMode.NORMAL.

4005

"sql": "A String", # Required. The SQL string.

4006

"params": { # The SQL string can contain parameter placeholders. A parameter

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4007

# placeholder consists of `'@'` followed by the parameter

4008

# name. Parameter names consist of any combination of letters,

4009

# numbers, and underscores.

4010

#

4011

# Parameters can appear anywhere that a literal value is expected. The same

4012

# parameter name can be used more than once, for example:

4013

# `"WHERE id > @msg_id AND id < @msg_id + 100"`

4014

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4015

# It is an error to execute an SQL statement with unbound parameters.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4016

#

4017

# Parameter values are specified using `params`, which is a JSON

4018

# object whose keys are parameter names, and whose values are the

4019

# corresponding parameter values.

4020

"a_key": "", # Properties of the object.

},

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

4031

4032

{ # Partial results from a streaming read or SQL query. Streaming reads and

4033

# SQL queries better tolerate large result sets, large rows, and large

4034

# values, but are a little trickier to consume.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4035

"resumeToken": "A String", # Streaming calls might be interrupted for a variety of reasons, such

4036

# as TCP connection loss. If this occurs, the stream of results can

4037

# be resumed by re-sending the original request and including

4038

# `resume_token`. Note that executing any other transaction in the

4039

# same session invalidates the token.

4040

"chunkedValue": True or False, # If true, then the final value in values is chunked, and must

4041

# be combined with more values from subsequent `PartialResultSet`s

4042

# to obtain a complete field value.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4043

"values": [ # A streamed result set consists of a stream of values, which might

4044

# be split into many `PartialResultSet` messages to accommodate

4045

# large rows and/or large values. Every N complete values defines a

4046

# row, where N is equal to the number of entries in

4047

# metadata.row_type.fields.

4048

#

4049

# Most values are encoded based on type as described

4050

# here.

4051

#

4052

# It is possible that the last value in values is "chunked",

4053

# meaning that the rest of the value is sent in subsequent

4054

# `PartialResultSet`(s). This is denoted by the chunked_value

4055

# field. Two or more chunked values can be merged to form a

4056

# complete value as follows:

4057

#

4058

# * `bool/number/null`: cannot be chunked

4059

# * `string`: concatenate the strings

4060

# * `list`: concatenate the lists. If the last element in a list is a

4061

# `string`, `list`, or `object`, merge it with the first element in

4062

# the next list by applying these rules recursively.

4063

# * `object`: concatenate the (field name, field value) pairs. If a

4064

# field name is duplicated, then apply these rules recursively

4065

# to merge the field values.

4066

#

4067

# Some examples of merging:

4068

#

4069

# # Strings are concatenated.

4070

# "foo", "bar" => "foobar"

4071

#

4072

# # Lists of non-strings are concatenated.

4073

# [2, 3], [4] => [2, 3, 4]

4074

#

4075

# # Lists are concatenated, but the last and first elements are merged

4076

# # because they are strings.

4077

# ["a", "b"], ["c", "d"] => ["a", "bc", "d"]

4078

#

4079

# # Lists are concatenated, but the last and first elements are merged

4080

# # because they are lists. Recursively, the last and first elements

4081

# # of the inner lists are merged because they are strings.

4082

# ["a", ["b", "c"]], [["d"], "e"] => ["a", ["b", "cd"], "e"]

4083

#

4084

# # Non-overlapping object fields are combined.

4085

# {"a": "1"}, {"b": "2"} => {"a": "1", "b": 2"}

4086

#

4087

# # Overlapping object fields are merged.

4088

# {"a": "1"}, {"a": "2"} => {"a": "12"}

4089

#

4090

# # Examples of merging objects containing lists of strings.

4091

# {"a": ["1"]}, {"a": ["2"]} => {"a": ["12"]}

4092

#

4093

# For a more complete example, suppose a streaming SQL query is

4094

# yielding a result set whose rows contain a single string

4095

# field. The following `PartialResultSet`s might be yielded:

4096

#

4097

# {

4098

# "metadata": { ... }

4099

# "values": ["Hello", "W"]

4100

# "chunked_value": true

4101

# "resume_token": "Af65..."

# }

# {

# "values": ["orl"]

# "chunked_value": true

4106

# "resume_token": "Bqp2..."

# }

# {

# "values": ["d"]

# "resume_token": "Zx1B..."

4111

# }

4112

#

4113

# This sequence of `PartialResultSet`s encodes two rows, one

4114

# containing the field value `"Hello"`, and a second containing the

4115

# field value `"World" = "W" + "orl" + "d"`.

4116

"",

4117

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4118

"stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the statement that produced this

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4119

# streaming result set. These can be requested by setting

4120

# ExecuteSqlRequest.query_mode and are sent

4121

# only once with the last response in the stream.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4122

# This field will also be present in the last response for DML

4123

# statements.

4124

"rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it

4125

# returns a lower bound of the rows modified.

4126

"rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4127

"queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.

4128

"planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting

4129

# with the plan root. Each PlanNode's `id` corresponds to its index in

4130

# `plan_nodes`.

4131

{ # Node information for nodes appearing in a QueryPlan.plan_nodes.

4132

"index": 42, # The `PlanNode`'s index in node list.

4133

"kind": "A String", # Used to determine the type of node. May be needed for visualizing

4134

# different kinds of nodes differently. For example, If the node is a

4135

# SCALAR node, it will have a condensed representation

4136

# which can be used to directly embed a description of the node in its

4137

# parent.

4138

"displayName": "A String", # The display name for the node.

4139

"executionStats": { # The execution statistics associated with the node, contained in a group of

4140

# key-value pairs. Only present if the plan was returned as a result of a

4141

# profile query. For example, number of executions, number of rows/time per

4142

# execution etc.

4143

"a_key": "", # Properties of the object.

4144

},

4145

"childLinks": [ # List of child node `index`es and their relationship to this parent.

4146

{ # Metadata associated with a parent-child relationship appearing in a

4147

# PlanNode.

4148

"variable": "A String", # Only present if the child node is SCALAR and corresponds

4149

# to an output variable of the parent node. The field carries the name of

4150

# the output variable.

4151

# For example, a `TableScan` operator that reads rows from a table will

4152

# have child links to the `SCALAR` nodes representing the output variables

4153

# created for each column that is read by the operator. The corresponding

4154

# `variable` fields will be set to the variable names assigned to the

4155

# columns.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

4156

"childIndex": 42, # The node to which the link points.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4157

"type": "A String", # The type of the link. For example, in Hash Joins this could be used to

4158

# distinguish between the build child and the probe child, or in the case

4159

# of the child being an output variable, to represent the tag associated

4160

# with the output variable.

4161

},

4162

],

4163

"shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.

4164

# `SCALAR` PlanNode(s).

4165

"subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases

4166

# where the `description` string of this node references a `SCALAR`

4167

# subquery contained in the expression subtree rooted at this node. The

4168

# referenced `SCALAR` subquery may not necessarily be a direct child of

# this node.

"a_key": 42,

},

"description": "A String", # A string representation of the expression subtree rooted at this node.

4173

},

4174

"metadata": { # Attributes relevant to the node contained in a group of key-value pairs.

4175

# For example, a Parameter Reference node could have the following

4176

# information in its metadata:

4177

#

4178

# {

4179

# "parameter_reference": "param1",

4180

# "parameter_type": "array"

4181

# }

4182

"a_key": "", # Properties of the object.

},

},

],

},

"queryStats": { # Aggregated statistics from the execution of the query. Only present when

4188

# the query is profiled. For example, a query could return the statistics as

# follows:

#

# {

# "rows_returned": "3",

4193

# "elapsed_time": "1.22 secs",

4194

# "cpu_time": "1.19 secs"

4195

# }

4196

"a_key": "", # Properties of the object.

4197

},

4198

},

4199

"metadata": { # Metadata about a ResultSet or PartialResultSet. # Metadata about the result set, such as row type information.

4200

# Only present in the first response.

4201

"rowType": { # `StructType` defines the fields of a STRUCT type. # Indicates the field names and types for the rows in the result

4202

# set. For example, a SQL query like `"SELECT UserId, UserName FROM

4203

# Users"` could return a `row_type` value like:

4204

#

4205

# "fields": [

4206

# { "name": "UserId", "type": { "code": "INT64" } },

4207

# { "name": "UserName", "type": { "code": "STRING" } },

4208

# ]

4209

"fields": [ # The list of fields that make up this struct. Order is

4210

# significant, because values of this struct type are represented as

4211

# lists, where the order of field values matches the order of

4212

# fields in the StructType. In turn, the order of fields

4213

# matches the order of columns in a read request, or the order of

4214

# fields in the `SELECT` clause of a query.

4215

{ # Message representing a single field of a struct.

4216

"type": { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a # The type of the field.

4217

# table cell or returned from an SQL query.

4218

"structType": # Object with schema name: StructType # If code == STRUCT, then `struct_type`

4219

# provides type information for the struct's fields.

4220

"code": "A String", # Required. The TypeCode for this type.

4221

"arrayElementType": # Object with schema name: Type # If code == ARRAY, then `array_element_type`

4222

# is the type of the array elements.

4223

},

4224

"name": "A String", # The name of the field. For reads, this is the column name. For

4225

# SQL queries, it is the column alias (e.g., `"Word"` in the

4226

# query `"SELECT 'hello' AS Word"`), or the column name (e.g.,

4227

# `"ColName"` in the query `"SELECT ColName FROM Table"`). Some

4228

# columns might have an empty name (e.g., !"SELECT

4229

# UPPER(ColName)"`). Note that a query result can contain

4230

# multiple fields with the same name.

},

],

},

"transaction": { # A transaction. # If the read or SQL query began a transaction as a side-effect, the

4235

# information about the new transaction is yielded here.

4236

"readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen

4237

# for the transaction. Not returned by default: see

4238

# TransactionOptions.ReadOnly.return_read_timestamp.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4239

#

4240

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

4241

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

4242

"id": "A String", # `id` may be used to identify the transaction in subsequent

# Read,

# ExecuteSql,

# Commit, or

# Rollback calls.

#

# Single-use read-only transactions do not have IDs, because

4249

# single-use transactions do not support multiple requests.

},

},

}</pre>

</div>

<code class="details" id="get">get(name, x__xgafv=None)</code>

4257

<pre>Gets a session. Returns `NOT_FOUND` if the session does not exist.

4258

This is mainly useful for determining whether a session is still

alive.

Args:

name: string, Required. The name of the session to retrieve. (required)

4263

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

4270

4271

{ # A session in the Cloud Spanner API.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

4272

"labels": { # The labels for the session.

4273

#

4274

# * Label keys must be between 1 and 63 characters long and must conform to

4275

# the following regular expression: `[a-z]([-a-z0-9]*[a-z0-9])?`.

4276

# * Label values must be between 0 and 63 characters long and must conform

4277

# to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`.

4278

# * No more than 64 labels can be associated with a given session.

4279

#

4280

# See https://goo.gl/xmQnxf for more information on and examples of labels.

4281

"a_key": "A String",

4282

},

4283

"name": "A String", # The name of the session. This is always system-assigned; values provided

4284

# when creating a session are ignored.

4285

"approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is

4286

# typically earlier than the actual last use time.

4287

"createTime": "A String", # Output only. The timestamp when the session is created.

}</pre>

</div>

<code class="details" id="list">list(database, pageSize=None, filter=None, pageToken=None, x__xgafv=None)</code>

4293

<pre>Lists all sessions in a given database.

4294

4295

Args:

4296

database: string, Required. The database in which to list sessions. (required)

4297

pageSize: integer, Number of sessions to be returned in the response. If 0 or less, defaults

4298

to the server's maximum allowed page size.

4299

filter: string, An expression for filtering the results of the request. Filter rules are

4300

case insensitive. The fields eligible for filtering are:

4301

4302

* `labels.key` where key is the name of a label

4303

4304

Some examples of using filters are:

4305

4306

* `labels.env:*` --> The session has the label "env".

4307

* `labels.env:dev` --> The session has the label "env" and the value of

4308

the label contains the string "dev".

4309

pageToken: string, If non-empty, `page_token` should contain a

4310

next_page_token from a previous

4311

ListSessionsResponse.

4312

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

4319

4320

{ # The response for ListSessions.

4321

"nextPageToken": "A String", # `next_page_token` can be sent in a subsequent

4322

# ListSessions call to fetch more of the matching

4323

# sessions.

4324

"sessions": [ # The list of requested sessions.

4325

{ # A session in the Cloud Spanner API.

4326

"labels": { # The labels for the session.

4327

#

4328

# * Label keys must be between 1 and 63 characters long and must conform to

4329

# the following regular expression: `[a-z]([-a-z0-9]*[a-z0-9])?`.

4330

# * Label values must be between 0 and 63 characters long and must conform

4331

# to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`.

4332

# * No more than 64 labels can be associated with a given session.

4333

#

4334

# See https://goo.gl/xmQnxf for more information on and examples of labels.

4335

"a_key": "A String",

4336

},

4337

"name": "A String", # The name of the session. This is always system-assigned; values provided

4338

# when creating a session are ignored.

4339

"approximateLastUseTime": "A String", # Output only. The approximate timestamp when the session is last used. It is

4340

# typically earlier than the actual last use time.

4341

"createTime": "A String", # Output only. The timestamp when the session is created.

},

],

}</pre>

</div>

<code class="details" id="list_next">list_next(previous_request, previous_response)</code>

4349

<pre>Retrieves the next page of results.

4350

4351

Args:

4352

previous_request: The request for the previous page. (required)

4353

previous_response: The response from the request for the previous page. (required)

4354

4355

Returns:

4356

A request object that you can call 'execute()' on to request the next

4357

page. Returns None if there are no more items in the collection.

</pre>

</div>

<code class="details" id="partitionQuery">partitionQuery(session, body, x__xgafv=None)</code>

4363

<pre>Creates a set of partition tokens that can be used to execute a query

4364

operation in parallel. Each of the returned partition tokens can be used

4365

by ExecuteStreamingSql to specify a subset

4366

of the query result to read. The same session and read-only transaction

4367

must be used by the PartitionQueryRequest used to create the

4368

partition tokens and the ExecuteSqlRequests that use the partition tokens.

4369

4370

Partition tokens become invalid when the session used to create them

4371

is deleted, is idle for too long, begins a new transaction, or becomes too

4372

old. When any of these happen, it is not possible to resume the query, and

4373

the whole operation must be restarted from the beginning.

4374

4375

Args:

4376

session: string, Required. The session used to create the partitions. (required)

4377

body: object, The request body. (required)

4378

The object takes the form of:

4379

4380

{ # The request for PartitionQuery

4381

"paramTypes": { # It is not always possible for Cloud Spanner to infer the right SQL type

4382

# from a JSON value. For example, values of type `BYTES` and values

4383

# of type `STRING` both appear in params as JSON strings.

4384

#

4385

# In these cases, `param_types` can be used to specify the exact

4386

# SQL type for some or all of the SQL query parameters. See the

4387

# definition of Type for more information

4388

# about SQL types.

4389

"a_key": { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a

4390

# table cell or returned from an SQL query.

4391

"structType": # Object with schema name: StructType # If code == STRUCT, then `struct_type`

4392

# provides type information for the struct's fields.

4393

"code": "A String", # Required. The TypeCode for this type.

4394

"arrayElementType": # Object with schema name: Type # If code == ARRAY, then `array_element_type`

4395

# is the type of the array elements.

4396

},

4397

},

4398

"partitionOptions": { # Options for a PartitionQueryRequest and # Additional options that affect how many partitions are created.

4399

# PartitionReadRequest.

4400

"maxPartitions": "A String", # **Note:** This hint is currently ignored by PartitionQuery and

4401

# PartitionRead requests.

4402

#

4403

# The desired maximum number of partitions to return. For example, this may

4404

# be set to the number of workers available. The default for this option

4405

# is currently 10,000. The maximum value is currently 200,000. This is only

4406

# a hint. The actual number of partitions returned may be smaller or larger

4407

# than this maximum count request.

4408

"partitionSizeBytes": "A String", # **Note:** This hint is currently ignored by PartitionQuery and

4409

# PartitionRead requests.

4410

#

4411

# The desired data size for each partition generated. The default for this

4412

# option is currently 1 GiB. This is only a hint. The actual size of each

4413

# partition may be smaller or larger than this size request.

4414

},

4415

"transaction": { # This message is used to select the transaction in which a # Read only snapshot transactions are supported, read/write and single use

4416

# transactions are not.

4417

# Read or

4418

# ExecuteSql call runs.

4419

#

4420

# See TransactionOptions for more information about transactions.

4421

"begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in

4422

# it. The transaction ID of the new transaction is returned in

4423

# ResultSetMetadata.transaction, which is a Transaction.

4424

#

4425

#

4426

# Each session can have at most one active transaction at a time. After the

4427

# active transaction is completed, the session can immediately be

4428

# re-used for the next transaction. It is not necessary to create a

4429

# new session for each transaction.

4430

#

4431

# # Transaction Modes

4432

#

4433

# Cloud Spanner supports three transaction modes:

4434

#

4435

# 1. Locking read-write. This type of transaction is the only way

4436

# to write data into Cloud Spanner. These transactions rely on

4437

# pessimistic locking and, if necessary, two-phase commit.

4438

# Locking read-write transactions may abort, requiring the

4439

# application to retry.

4440

#

4441

# 2. Snapshot read-only. This transaction type provides guaranteed

4442

# consistency across several reads, but does not allow

4443

# writes. Snapshot read-only transactions can be configured to

4444

# read at timestamps in the past. Snapshot read-only

4445

# transactions do not need to be committed.

4446

#

4447

# 3. Partitioned DML. This type of transaction is used to execute

4448

# a single Partitioned DML statement. Partitioned DML partitions

4449

# the key space and runs the DML statement over each partition

4450

# in parallel using separate, internal transactions that commit

4451

# independently. Partitioned DML transactions do not need to be

4452

# committed.

4453

#

4454

# For transactions that only read, snapshot read-only transactions

4455

# provide simpler semantics and are almost always faster. In

4456

# particular, read-only transactions do not take locks, so they do

4457

# not conflict with read-write transactions. As a consequence of not

4458

# taking locks, they also do not abort, so retry loops are not needed.

4459

#

4460

# Transactions may only read/write data in a single database. They

4461

# may, however, read/write data in different tables within that

4462

# database.

4463

#

4464

# ## Locking Read-Write Transactions

4465

#

4466

# Locking transactions may be used to atomically read-modify-write

4467

# data anywhere in a database. This type of transaction is externally

4468

# consistent.

4469

#

4470

# Clients should attempt to minimize the amount of time a transaction

4471

# is active. Faster transactions commit with higher probability

4472

# and cause less contention. Cloud Spanner attempts to keep read locks

4473

# active as long as the transaction continues to do reads, and the

4474

# transaction has not been terminated by

4475

# Commit or

4476

# Rollback. Long periods of

4477

# inactivity at the client may cause Cloud Spanner to release a

4478

# transaction's locks and abort it.

4479

#

4480

# Conceptually, a read-write transaction consists of zero or more

4481

# reads or SQL statements followed by

4482

# Commit. At any time before

4483

# Commit, the client can send a

4484

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

4490

# are still valid at commit time, and it is able to acquire write

4491

# locks for all writes. Cloud Spanner can abort the transaction for any

4492

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

4493

# that the transaction has not modified any user data in Cloud Spanner.

4494

#

4495

# Unless the transaction commits, Cloud Spanner makes no guarantees about

4496

# how long the transaction's locks were held for. It is an error to

4497

# use Cloud Spanner locks for any sort of mutual exclusion other than

4498

# between Cloud Spanner transactions themselves.

4499

#

4500

# ### Retrying Aborted Transactions

4501

#

4502

# When a transaction aborts, the application can choose to retry the

4503

# whole transaction again. To maximize the chances of successfully

4504

# committing the retry, the client should execute the retry in the

4505

# same session as the original attempt. The original session's lock

4506

# priority increases with each consecutive abort, meaning that each

4507

# attempt has a slightly better chance of success than the previous.

4508

#

4509

# Under some circumstances (e.g., many transactions attempting to

4510

# modify the same row(s)), a transaction can abort many times in a

4511

# short period before successfully committing. Thus, it is not a good

4512

# idea to cap the number of retries a transaction can attempt;

4513

# instead, it is better to limit the total amount of wall time spent

4514

# retrying.

4515

#

4516

# ### Idle Transactions

4517

#

4518

# A transaction is considered idle if it has no outstanding reads or

4519

# SQL queries and has not started a read or SQL query within the last 10

4520

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

4521

# don't hold on to locks indefinitely. In that case, the commit will

4522

# fail with error `ABORTED`.

4523

#

4524

# If this behavior is undesirable, periodically executing a simple

4525

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

4526

# transaction from becoming idle.

4527

#

4528

# ## Snapshot Read-Only Transactions

4529

#

4530

# Snapshot read-only transactions provides a simpler method than

4531

# locking read-write transactions for doing several consistent

4532

# reads. However, this type of transaction does not support writes.

4533

#

4534

# Snapshot transactions do not take locks. Instead, they work by

4535

# choosing a Cloud Spanner timestamp, then executing all reads at that

4536

# timestamp. Since they do not acquire locks, they do not block

4537

# concurrent read-write transactions.

4538

#

4539

# Unlike locking read-write transactions, snapshot read-only

4540

# transactions never abort. They can fail if the chosen read

4541

# timestamp is garbage collected; however, the default garbage

4542

# collection policy is generous enough that most applications do not

4543

# need to worry about this in practice.

4544

#

4545

# Snapshot read-only transactions do not need to call

4546

# Commit or

4547

# Rollback (and in fact are not

4548

# permitted to do so).

4549

#

4550

# To execute a snapshot transaction, the client specifies a timestamp

4551

# bound, which tells Cloud Spanner how to choose a read timestamp.

4552

#

4553

# The types of timestamp bound are:

4554

#

4555

# - Strong (the default).

4556

# - Bounded staleness.

4557

# - Exact staleness.

4558

#

4559

# If the Cloud Spanner database to be read is geographically distributed,

4560

# stale read-only transactions can execute more quickly than strong

4561

# or read-write transaction, because they are able to execute far

4562

# from the leader replica.

4563

#

4564

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

4569

# that have committed before the start of the read. Furthermore, all

4570

# rows yielded by a single read are consistent with each other -- if

4571

# any part of the read observes a transaction, all parts of the read

4572

# see the transaction.

4573

#

4574

# Strong reads are not repeatable: two consecutive strong read-only

4575

# transactions might return inconsistent results if there are

4576

# concurrent writes. If consistency across reads is required, the

4577

# reads should be executed within a transaction or at an exact read

4578

# timestamp.

4579

#

4580

# See TransactionOptions.ReadOnly.strong.

4581

#

4582

# ### Exact Staleness

4583

#

4584

# These timestamp bounds execute reads at a user-specified

4585

# timestamp. Reads at a timestamp are guaranteed to see a consistent

4586

# prefix of the global transaction history: they observe

4587

# modifications done by all transactions with a commit timestamp <=

4588

# the read timestamp, and observe none of the modifications done by

4589

# transactions with a larger commit timestamp. They will block until

4590

# all conflicting transactions that may be assigned commit timestamps

4591

# <= the read timestamp have finished.

4592

#

4593

# The timestamp can either be expressed as an absolute Cloud Spanner commit

4594

# timestamp or a staleness relative to the current time.

4595

#

4596

# These modes do not require a "negotiation phase" to pick a

4597

# timestamp. As a result, they execute slightly faster than the

4598

# equivalent boundedly stale concurrency modes. On the other hand,

4599

# boundedly stale reads usually return fresher results.

4600

#

4601

# See TransactionOptions.ReadOnly.read_timestamp and

4602

# TransactionOptions.ReadOnly.exact_staleness.

4603

#

4604

# ### Bounded Staleness

4605

#

4606

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

4607

# subject to a user-provided staleness bound. Cloud Spanner chooses the

4608

# newest timestamp within the staleness bound that allows execution

4609

# of the reads at the closest available replica without blocking.

4610

#

4611

# All rows yielded are consistent with each other -- if any part of

4612

# the read observes a transaction, all parts of the read see the

4613

# transaction. Boundedly stale reads are not repeatable: two stale

4614

# reads, even if they use the same staleness bound, can execute at

4615

# different timestamps and thus return inconsistent results.

4616

#

4617

# Boundedly stale reads execute in two phases: the first phase

4618

# negotiates a timestamp among all replicas needed to serve the

4619

# read. In the second phase, reads are executed at the negotiated

4620

# timestamp.

4621

#

4622

# As a result of the two phase execution, bounded staleness reads are

4623

# usually a little slower than comparable exact staleness

4624

# reads. However, they are typically able to return fresher

4625

# results, and are more likely to execute at the closest replica.

4626

#

4627

# Because the timestamp negotiation requires up-front knowledge of

4628

# which rows will be read, it can only be used with single-use

4629

# read-only transactions.

4630

#

4631

# See TransactionOptions.ReadOnly.max_staleness and

4632

# TransactionOptions.ReadOnly.min_read_timestamp.

4633

#

4634

# ### Old Read Timestamps and Garbage Collection

4635

#

4636

# Cloud Spanner continuously garbage collects deleted and overwritten data

4637

# in the background to reclaim storage space. This process is known

4638

# as "version GC". By default, version GC reclaims versions after they

4639

# are one hour old. Because of this, Cloud Spanner cannot perform reads

4640

# at read timestamps more than one hour in the past. This

4641

# restriction also applies to in-progress reads and/or SQL queries whose

4642

# timestamp become too old while executing. Reads and SQL queries with

4643

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

4644

#

4645

# ## Partitioned DML Transactions

4646

#

4647

# Partitioned DML transactions are used to execute DML statements with a

4648

# different execution strategy that provides different, and often better,

4649

# scalability properties for large, table-wide operations than DML in a

4650

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

4651

# should prefer using ReadWrite transactions.

4652

#

4653

# Partitioned DML partitions the keyspace and runs the DML statement on each

4654

# partition in separate, internal transactions. These transactions commit

4655

# automatically when complete, and run independently from one another.

4656

#

4657

# To reduce lock contention, this execution strategy only acquires read locks

4658

# on rows that match the WHERE clause of the statement. Additionally, the

4659

# smaller per-partition transactions hold locks for less time.

4660

#

4661

# That said, Partitioned DML is not a drop-in replacement for standard DML used

4662

# in ReadWrite transactions.

4663

#

4664

# - The DML statement must be fully-partitionable. Specifically, the statement

4665

# must be expressible as the union of many statements which each access only

4666

# a single row of the table.

4667

#

4668

# - The statement is not applied atomically to all rows of the table. Rather,

4669

# the statement is applied atomically to partitions of the table, in

4670

# independent transactions. Secondary index rows are updated atomically

4671

# with the base table rows.

4672

#

4673

# - Partitioned DML does not guarantee exactly-once execution semantics

4674

# against a partition. The statement will be applied at least once to each

4675

# partition. It is strongly recommended that the DML statement should be

4676

# idempotent to avoid unexpected results. For instance, it is potentially

4677

# dangerous to run a statement such as

4678

# `UPDATE table SET column = column + 1` as it could be run multiple times

4679

# against some rows.

4680

#

4681

# - The partitions are committed automatically - there is no support for

4682

# Commit or Rollback. If the call returns an error, or if the client issuing

4683

# the ExecuteSql call dies, it is possible that some rows had the statement

4684

# executed on them successfully. It is also possible that statement was

4685

# never executed against other rows.

4686

#

4687

# - Partitioned DML transactions may only contain the execution of a single

4688

# DML statement via ExecuteSql or ExecuteStreamingSql.

4689

#

4690

# - If any error is encountered during the execution of the partitioned DML

4691

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

4692

# value that cannot be stored due to schema constraints), then the

4693

# operation is stopped at that point and an error is returned. It is

4694

# possible that at this point, some partitions have been committed (or even

4695

# committed multiple times), and other partitions have not been run at all.

4696

#

4697

# Given the above, Partitioned DML is good fit for large, database-wide,

4698

# operations that are idempotent, such as deleting old rows from a very large

4699

# table.

4700

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

4701

#

4702

# Authorization to begin a read-write transaction requires

4703

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

4704

# on the `session` resource.

4705

# transaction type has no options.

4706

},

4707

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

4708

#

4709

# Authorization to begin a read-only transaction requires

4710

# `spanner.databases.beginReadOnlyTransaction` permission

4711

# on the `session` resource.

4712

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

4713

#

4714

# This is useful for requesting fresher data than some previous

4715

# read, or data that is fresh enough to observe the effects of some

4716

# previously committed transaction whose timestamp is known.

4717

#

4718

# Note that this option can only be used in single-use transactions.

4719

#

4720

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

4721

# Example: `"2014-10-02T15:01:23.045123456Z"`.

4722

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

4723

# the Transaction message that describes the transaction.

4724

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

4725

# seconds. Guarantees that all writes that have committed more

4726

# than the specified number of seconds ago are visible. Because

4727

# Cloud Spanner chooses the exact timestamp, this mode works even if

4728

# the client's local clock is substantially skewed from Cloud Spanner

4729

# commit timestamps.

4730

#

4731

# Useful for reading the freshest data available at a nearby

4732

# replica, while bounding the possible staleness if the local

4733

# replica has fallen behind.

4734

#

4735

# Note that this option can only be used in single-use

4736

# transactions.

4737

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

4738

# old. The timestamp is chosen soon after the read is started.

4739

#

4740

# Guarantees that all writes that have committed more than the

4741

# specified number of seconds ago are visible. Because Cloud Spanner

4742

# chooses the exact timestamp, this mode works even if the client's

4743

# local clock is substantially skewed from Cloud Spanner commit

4744

# timestamps.

4745

#

4746

# Useful for reading at nearby replicas without the distributed

4747

# timestamp negotiation overhead of `max_staleness`.

4748

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

4749

# reads at a specific timestamp are repeatable; the same read at

4750

# the same timestamp always returns the same data. If the

4751

# timestamp is in the future, the read will block until the

4752

# specified timestamp, modulo the read's deadline.

4753

#

4754

# Useful for large scale consistent reads such as mapreduces, or

4755

# for coordinating many reads against a consistent snapshot of the

4756

# data.

4757

#

4758

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

4759

# Example: `"2014-10-02T15:01:23.045123456Z"`.

4760

"strong": True or False, # Read at a timestamp where all previously committed transactions

4761

# are visible.

4762

},

4763

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

4764

#

4765

# Authorization to begin a Partitioned DML transaction requires

4766

# `spanner.databases.beginPartitionedDmlTransaction` permission

4767

# on the `session` resource.

4768

},

4769

},

4770

"singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.

4771

# This is the most efficient way to execute a transaction that

4772

# consists of a single SQL query.

4773

#

4774

#

4775

# Each session can have at most one active transaction at a time. After the

4776

# active transaction is completed, the session can immediately be

4777

# re-used for the next transaction. It is not necessary to create a

4778

# new session for each transaction.

4779

#

4780

# # Transaction Modes

4781

#

4782

# Cloud Spanner supports three transaction modes:

4783

#

4784

# 1. Locking read-write. This type of transaction is the only way

4785

# to write data into Cloud Spanner. These transactions rely on

4786

# pessimistic locking and, if necessary, two-phase commit.

4787

# Locking read-write transactions may abort, requiring the

4788

# application to retry.

4789

#

4790

# 2. Snapshot read-only. This transaction type provides guaranteed

4791

# consistency across several reads, but does not allow

4792

# writes. Snapshot read-only transactions can be configured to

4793

# read at timestamps in the past. Snapshot read-only

4794

# transactions do not need to be committed.

4795

#

4796

# 3. Partitioned DML. This type of transaction is used to execute

4797

# a single Partitioned DML statement. Partitioned DML partitions

4798

# the key space and runs the DML statement over each partition

4799

# in parallel using separate, internal transactions that commit

4800

# independently. Partitioned DML transactions do not need to be

4801

# committed.

4802

#

4803

# For transactions that only read, snapshot read-only transactions

4804

# provide simpler semantics and are almost always faster. In

4805

# particular, read-only transactions do not take locks, so they do

4806

# not conflict with read-write transactions. As a consequence of not

4807

# taking locks, they also do not abort, so retry loops are not needed.

4808

#

4809

# Transactions may only read/write data in a single database. They

4810

# may, however, read/write data in different tables within that

4811

# database.

4812

#

4813

# ## Locking Read-Write Transactions

4814

#

4815

# Locking transactions may be used to atomically read-modify-write

4816

# data anywhere in a database. This type of transaction is externally

4817

# consistent.

4818

#

4819

# Clients should attempt to minimize the amount of time a transaction

4820

# is active. Faster transactions commit with higher probability

4821

# and cause less contention. Cloud Spanner attempts to keep read locks

4822

# active as long as the transaction continues to do reads, and the

4823

# transaction has not been terminated by

4824

# Commit or

4825

# Rollback. Long periods of

4826

# inactivity at the client may cause Cloud Spanner to release a

4827

# transaction's locks and abort it.

4828

#

4829

# Conceptually, a read-write transaction consists of zero or more

4830

# reads or SQL statements followed by

4831

# Commit. At any time before

4832

# Commit, the client can send a

4833

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

4839

# are still valid at commit time, and it is able to acquire write

4840

# locks for all writes. Cloud Spanner can abort the transaction for any

4841

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

4842

# that the transaction has not modified any user data in Cloud Spanner.

4843

#

4844

# Unless the transaction commits, Cloud Spanner makes no guarantees about

4845

# how long the transaction's locks were held for. It is an error to

4846

# use Cloud Spanner locks for any sort of mutual exclusion other than

4847

# between Cloud Spanner transactions themselves.

4848

#

4849

# ### Retrying Aborted Transactions

4850

#

4851

# When a transaction aborts, the application can choose to retry the

4852

# whole transaction again. To maximize the chances of successfully

4853

# committing the retry, the client should execute the retry in the

4854

# same session as the original attempt. The original session's lock

4855

# priority increases with each consecutive abort, meaning that each

4856

# attempt has a slightly better chance of success than the previous.

4857

#

4858

# Under some circumstances (e.g., many transactions attempting to

4859

# modify the same row(s)), a transaction can abort many times in a

4860

# short period before successfully committing. Thus, it is not a good

4861

# idea to cap the number of retries a transaction can attempt;

4862

# instead, it is better to limit the total amount of wall time spent

4863

# retrying.

4864

#

4865

# ### Idle Transactions

4866

#

4867

# A transaction is considered idle if it has no outstanding reads or

4868

# SQL queries and has not started a read or SQL query within the last 10

4869

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

4870

# don't hold on to locks indefinitely. In that case, the commit will

4871

# fail with error `ABORTED`.

4872

#

4873

# If this behavior is undesirable, periodically executing a simple

4874

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

4875

# transaction from becoming idle.

4876

#

4877

# ## Snapshot Read-Only Transactions

4878

#

4879

# Snapshot read-only transactions provides a simpler method than

4880

# locking read-write transactions for doing several consistent

4881

# reads. However, this type of transaction does not support writes.

4882

#

4883

# Snapshot transactions do not take locks. Instead, they work by

4884

# choosing a Cloud Spanner timestamp, then executing all reads at that

4885

# timestamp. Since they do not acquire locks, they do not block

4886

# concurrent read-write transactions.

4887

#

4888

# Unlike locking read-write transactions, snapshot read-only

4889

# transactions never abort. They can fail if the chosen read

4890

# timestamp is garbage collected; however, the default garbage

4891

# collection policy is generous enough that most applications do not

4892

# need to worry about this in practice.

4893

#

4894

# Snapshot read-only transactions do not need to call

4895

# Commit or

4896

# Rollback (and in fact are not

4897

# permitted to do so).

4898

#

4899

# To execute a snapshot transaction, the client specifies a timestamp

4900

# bound, which tells Cloud Spanner how to choose a read timestamp.

4901

#

4902

# The types of timestamp bound are:

4903

#

4904

# - Strong (the default).

4905

# - Bounded staleness.

4906

# - Exact staleness.

4907

#

4908

# If the Cloud Spanner database to be read is geographically distributed,

4909

# stale read-only transactions can execute more quickly than strong

4910

# or read-write transaction, because they are able to execute far

4911

# from the leader replica.

4912

#

4913

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

4918

# that have committed before the start of the read. Furthermore, all

4919

# rows yielded by a single read are consistent with each other -- if

4920

# any part of the read observes a transaction, all parts of the read

4921

# see the transaction.

4922

#

4923

# Strong reads are not repeatable: two consecutive strong read-only

4924

# transactions might return inconsistent results if there are

4925

# concurrent writes. If consistency across reads is required, the

4926

# reads should be executed within a transaction or at an exact read

4927

# timestamp.

4928

#

4929

# See TransactionOptions.ReadOnly.strong.

4930

#

4931

# ### Exact Staleness

4932

#

4933

# These timestamp bounds execute reads at a user-specified

4934

# timestamp. Reads at a timestamp are guaranteed to see a consistent

4935

# prefix of the global transaction history: they observe

4936

# modifications done by all transactions with a commit timestamp <=

4937

# the read timestamp, and observe none of the modifications done by

4938

# transactions with a larger commit timestamp. They will block until

4939

# all conflicting transactions that may be assigned commit timestamps

4940

# <= the read timestamp have finished.

4941

#

4942

# The timestamp can either be expressed as an absolute Cloud Spanner commit

4943

# timestamp or a staleness relative to the current time.

4944

#

4945

# These modes do not require a "negotiation phase" to pick a

4946

# timestamp. As a result, they execute slightly faster than the

4947

# equivalent boundedly stale concurrency modes. On the other hand,

4948

# boundedly stale reads usually return fresher results.

4949

#

4950

# See TransactionOptions.ReadOnly.read_timestamp and

4951

# TransactionOptions.ReadOnly.exact_staleness.

4952

#

4953

# ### Bounded Staleness

4954

#

4955

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

4956

# subject to a user-provided staleness bound. Cloud Spanner chooses the

4957

# newest timestamp within the staleness bound that allows execution

4958

# of the reads at the closest available replica without blocking.

4959

#

4960

# All rows yielded are consistent with each other -- if any part of

4961

# the read observes a transaction, all parts of the read see the

4962

# transaction. Boundedly stale reads are not repeatable: two stale

4963

# reads, even if they use the same staleness bound, can execute at

4964

# different timestamps and thus return inconsistent results.

4965

#

4966

# Boundedly stale reads execute in two phases: the first phase

4967

# negotiates a timestamp among all replicas needed to serve the

4968

# read. In the second phase, reads are executed at the negotiated

4969

# timestamp.

4970

#

4971

# As a result of the two phase execution, bounded staleness reads are

4972

# usually a little slower than comparable exact staleness

4973

# reads. However, they are typically able to return fresher

4974

# results, and are more likely to execute at the closest replica.

4975

#

4976

# Because the timestamp negotiation requires up-front knowledge of

4977

# which rows will be read, it can only be used with single-use

4978

# read-only transactions.

4979

#

4980

# See TransactionOptions.ReadOnly.max_staleness and

4981

# TransactionOptions.ReadOnly.min_read_timestamp.

4982

#

4983

# ### Old Read Timestamps and Garbage Collection

4984

#

4985

# Cloud Spanner continuously garbage collects deleted and overwritten data

4986

# in the background to reclaim storage space. This process is known

4987

# as "version GC". By default, version GC reclaims versions after they

4988

# are one hour old. Because of this, Cloud Spanner cannot perform reads

4989

# at read timestamps more than one hour in the past. This

4990

# restriction also applies to in-progress reads and/or SQL queries whose

4991

# timestamp become too old while executing. Reads and SQL queries with

4992

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

4993

#

4994

# ## Partitioned DML Transactions

4995

#

4996

# Partitioned DML transactions are used to execute DML statements with a

4997

# different execution strategy that provides different, and often better,

4998

# scalability properties for large, table-wide operations than DML in a

4999

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

5000

# should prefer using ReadWrite transactions.

5001

#

5002

# Partitioned DML partitions the keyspace and runs the DML statement on each

5003

# partition in separate, internal transactions. These transactions commit

5004

# automatically when complete, and run independently from one another.

5005

#

5006

# To reduce lock contention, this execution strategy only acquires read locks

5007

# on rows that match the WHERE clause of the statement. Additionally, the

5008

# smaller per-partition transactions hold locks for less time.

5009

#

5010

# That said, Partitioned DML is not a drop-in replacement for standard DML used

5011

# in ReadWrite transactions.

5012

#

5013

# - The DML statement must be fully-partitionable. Specifically, the statement

5014

# must be expressible as the union of many statements which each access only

5015

# a single row of the table.

5016

#

5017

# - The statement is not applied atomically to all rows of the table. Rather,

5018

# the statement is applied atomically to partitions of the table, in

5019

# independent transactions. Secondary index rows are updated atomically

5020

# with the base table rows.

5021

#

5022

# - Partitioned DML does not guarantee exactly-once execution semantics

5023

# against a partition. The statement will be applied at least once to each

5024

# partition. It is strongly recommended that the DML statement should be

5025

# idempotent to avoid unexpected results. For instance, it is potentially

5026

# dangerous to run a statement such as

5027

# `UPDATE table SET column = column + 1` as it could be run multiple times

5028

# against some rows.

5029

#

5030

# - The partitions are committed automatically - there is no support for

5031

# Commit or Rollback. If the call returns an error, or if the client issuing

5032

# the ExecuteSql call dies, it is possible that some rows had the statement

5033

# executed on them successfully. It is also possible that statement was

5034

# never executed against other rows.

5035

#

5036

# - Partitioned DML transactions may only contain the execution of a single

5037

# DML statement via ExecuteSql or ExecuteStreamingSql.

5038

#

5039

# - If any error is encountered during the execution of the partitioned DML

5040

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

5041

# value that cannot be stored due to schema constraints), then the

5042

# operation is stopped at that point and an error is returned. It is

5043

# possible that at this point, some partitions have been committed (or even

5044

# committed multiple times), and other partitions have not been run at all.

5045

#

5046

# Given the above, Partitioned DML is good fit for large, database-wide,

5047

# operations that are idempotent, such as deleting old rows from a very large

5048

# table.

5049

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

5050

#

5051

# Authorization to begin a read-write transaction requires

5052

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

5053

# on the `session` resource.

5054

# transaction type has no options.

5055

},

5056

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

5057

#

5058

# Authorization to begin a read-only transaction requires

5059

# `spanner.databases.beginReadOnlyTransaction` permission

5060

# on the `session` resource.

5061

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

5062

#

5063

# This is useful for requesting fresher data than some previous

5064

# read, or data that is fresh enough to observe the effects of some

5065

# previously committed transaction whose timestamp is known.

5066

#

5067

# Note that this option can only be used in single-use transactions.

5068

#

5069

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

5070

# Example: `"2014-10-02T15:01:23.045123456Z"`.

5071

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

5072

# the Transaction message that describes the transaction.

5073

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

5074

# seconds. Guarantees that all writes that have committed more

5075

# than the specified number of seconds ago are visible. Because

5076

# Cloud Spanner chooses the exact timestamp, this mode works even if

5077

# the client's local clock is substantially skewed from Cloud Spanner

5078

# commit timestamps.

5079

#

5080

# Useful for reading the freshest data available at a nearby

5081

# replica, while bounding the possible staleness if the local

5082

# replica has fallen behind.

5083

#

5084

# Note that this option can only be used in single-use

5085

# transactions.

5086

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

5087

# old. The timestamp is chosen soon after the read is started.

5088

#

5089

# Guarantees that all writes that have committed more than the

5090

# specified number of seconds ago are visible. Because Cloud Spanner

5091

# chooses the exact timestamp, this mode works even if the client's

5092

# local clock is substantially skewed from Cloud Spanner commit

5093

# timestamps.

5094

#

5095

# Useful for reading at nearby replicas without the distributed

5096

# timestamp negotiation overhead of `max_staleness`.

5097

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

5098

# reads at a specific timestamp are repeatable; the same read at

5099

# the same timestamp always returns the same data. If the

5100

# timestamp is in the future, the read will block until the

5101

# specified timestamp, modulo the read's deadline.

5102

#

5103

# Useful for large scale consistent reads such as mapreduces, or

5104

# for coordinating many reads against a consistent snapshot of the

5105

# data.

5106

#

5107

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

5108

# Example: `"2014-10-02T15:01:23.045123456Z"`.

5109

"strong": True or False, # Read at a timestamp where all previously committed transactions

5110

# are visible.

5111

},

5112

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

5113

#

5114

# Authorization to begin a Partitioned DML transaction requires

5115

# `spanner.databases.beginPartitionedDmlTransaction` permission

5116

# on the `session` resource.

5117

},

5118

},

5119

"id": "A String", # Execute the read or SQL query in a previously-started transaction.

5120

},

5121

"params": { # The SQL query string can contain parameter placeholders. A parameter

5122

# placeholder consists of `'@'` followed by the parameter

5123

# name. Parameter names consist of any combination of letters,

5124

# numbers, and underscores.

5125

#

5126

# Parameters can appear anywhere that a literal value is expected. The same

5127

# parameter name can be used more than once, for example:

5128

# `"WHERE id > @msg_id AND id < @msg_id + 100"`

5129

#

5130

# It is an error to execute an SQL query with unbound parameters.

5131

#

5132

# Parameter values are specified using `params`, which is a JSON

5133

# object whose keys are parameter names, and whose values are the

5134

# corresponding parameter values.

5135

"a_key": "", # Properties of the object.

5136

},

5137

"sql": "A String", # The query request to generate partitions for. The request will fail if

5138

# the query is not root partitionable. The query plan of a root

5139

# partitionable query has a single distributed union operator. A distributed

5140

# union operator conceptually divides one or more tables into multiple

5141

# splits, remotely evaluates a subquery independently on each split, and

5142

# then unions all results.

5143

#

5144

# This must not contain DML commands, such as INSERT, UPDATE, or

5145

# DELETE. Use ExecuteStreamingSql with a

5146

# PartitionedDml transaction for large, partition-friendly DML operations.

5147

}

5148

5149

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

5156

5157

{ # The response for PartitionQuery

5158

# or PartitionRead

5159

"transaction": { # A transaction. # Transaction created by this request.

5160

"readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen

5161

# for the transaction. Not returned by default: see

5162

# TransactionOptions.ReadOnly.return_read_timestamp.

5163

#

5164

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

5165

# Example: `"2014-10-02T15:01:23.045123456Z"`.

5166

"id": "A String", # `id` may be used to identify the transaction in subsequent

# Read,

# ExecuteSql,

# Commit, or

# Rollback calls.

#

# Single-use read-only transactions do not have IDs, because

5173

# single-use transactions do not support multiple requests.

5174

},

5175

"partitions": [ # Partitions created by this request.

5176

{ # Information returned for each partition returned in a

5177

# PartitionResponse.

5178

"partitionToken": "A String", # This token can be passed to Read, StreamingRead, ExecuteSql, or

5179

# ExecuteStreamingSql requests to restrict the results to those identified by

5180

# this partition token.

},

],

}</pre>

</div>

<code class="details" id="partitionRead">partitionRead(session, body, x__xgafv=None)</code>

5188

<pre>Creates a set of partition tokens that can be used to execute a read

5189

operation in parallel. Each of the returned partition tokens can be used

5190

by StreamingRead to specify a subset of the read

5191

result to read. The same session and read-only transaction must be used by

5192

the PartitionReadRequest used to create the partition tokens and the

5193

ReadRequests that use the partition tokens. There are no ordering

5194

guarantees on rows returned among the returned partition tokens, or even

5195

within each individual StreamingRead call issued with a partition_token.

5196

5197

Partition tokens become invalid when the session used to create them

5198

is deleted, is idle for too long, begins a new transaction, or becomes too

5199

old. When any of these happen, it is not possible to resume the read, and

5200

the whole operation must be restarted from the beginning.

5201

5202

Args:

5203

session: string, Required. The session used to create the partitions. (required)

5204

body: object, The request body. (required)

5205

The object takes the form of:

5206

5207

{ # The request for PartitionRead

5208

"index": "A String", # If non-empty, the name of an index on table. This index is

5209

# used instead of the table primary key when interpreting key_set

5210

# and sorting result rows. See key_set for further information.

5211

"transaction": { # This message is used to select the transaction in which a # Read only snapshot transactions are supported, read/write and single use

5212

# transactions are not.

5213

# Read or

5214

# ExecuteSql call runs.

5215

#

5216

# See TransactionOptions for more information about transactions.

5217

"begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in

5218

# it. The transaction ID of the new transaction is returned in

5219

# ResultSetMetadata.transaction, which is a Transaction.

5220

#

5221

#

5222

# Each session can have at most one active transaction at a time. After the

5223

# active transaction is completed, the session can immediately be

5224

# re-used for the next transaction. It is not necessary to create a

5225

# new session for each transaction.

5226

#

5227

# # Transaction Modes

5228

#

5229

# Cloud Spanner supports three transaction modes:

5230

#

5231

# 1. Locking read-write. This type of transaction is the only way

5232

# to write data into Cloud Spanner. These transactions rely on

5233

# pessimistic locking and, if necessary, two-phase commit.

5234

# Locking read-write transactions may abort, requiring the

5235

# application to retry.

5236

#

5237

# 2. Snapshot read-only. This transaction type provides guaranteed

5238

# consistency across several reads, but does not allow

5239

# writes. Snapshot read-only transactions can be configured to

5240

# read at timestamps in the past. Snapshot read-only

5241

# transactions do not need to be committed.

5242

#

5243

# 3. Partitioned DML. This type of transaction is used to execute

5244

# a single Partitioned DML statement. Partitioned DML partitions

5245

# the key space and runs the DML statement over each partition

5246

# in parallel using separate, internal transactions that commit

5247

# independently. Partitioned DML transactions do not need to be

5248

# committed.

5249

#

5250

# For transactions that only read, snapshot read-only transactions

5251

# provide simpler semantics and are almost always faster. In

5252

# particular, read-only transactions do not take locks, so they do

5253

# not conflict with read-write transactions. As a consequence of not

5254

# taking locks, they also do not abort, so retry loops are not needed.

5255

#

5256

# Transactions may only read/write data in a single database. They

5257

# may, however, read/write data in different tables within that

5258

# database.

5259

#

5260

# ## Locking Read-Write Transactions

5261

#

5262

# Locking transactions may be used to atomically read-modify-write

5263

# data anywhere in a database. This type of transaction is externally

5264

# consistent.

5265

#

5266

# Clients should attempt to minimize the amount of time a transaction

5267

# is active. Faster transactions commit with higher probability

5268

# and cause less contention. Cloud Spanner attempts to keep read locks

5269

# active as long as the transaction continues to do reads, and the

5270

# transaction has not been terminated by

5271

# Commit or

5272

# Rollback. Long periods of

5273

# inactivity at the client may cause Cloud Spanner to release a

5274

# transaction's locks and abort it.

5275

#

5276

# Conceptually, a read-write transaction consists of zero or more

5277

# reads or SQL statements followed by

5278

# Commit. At any time before

5279

# Commit, the client can send a

5280

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

5286

# are still valid at commit time, and it is able to acquire write

5287

# locks for all writes. Cloud Spanner can abort the transaction for any

5288

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

5289

# that the transaction has not modified any user data in Cloud Spanner.

5290

#

5291

# Unless the transaction commits, Cloud Spanner makes no guarantees about

5292

# how long the transaction's locks were held for. It is an error to

5293

# use Cloud Spanner locks for any sort of mutual exclusion other than

5294

# between Cloud Spanner transactions themselves.

5295

#

5296

# ### Retrying Aborted Transactions

5297

#

5298

# When a transaction aborts, the application can choose to retry the

5299

# whole transaction again. To maximize the chances of successfully

5300

# committing the retry, the client should execute the retry in the

5301

# same session as the original attempt. The original session's lock

5302

# priority increases with each consecutive abort, meaning that each

5303

# attempt has a slightly better chance of success than the previous.

5304

#

5305

# Under some circumstances (e.g., many transactions attempting to

5306

# modify the same row(s)), a transaction can abort many times in a

5307

# short period before successfully committing. Thus, it is not a good

5308

# idea to cap the number of retries a transaction can attempt;

5309

# instead, it is better to limit the total amount of wall time spent

5310

# retrying.

5311

#

5312

# ### Idle Transactions

5313

#

5314

# A transaction is considered idle if it has no outstanding reads or

5315

# SQL queries and has not started a read or SQL query within the last 10

5316

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

5317

# don't hold on to locks indefinitely. In that case, the commit will

5318

# fail with error `ABORTED`.

5319

#

5320

# If this behavior is undesirable, periodically executing a simple

5321

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

5322

# transaction from becoming idle.

5323

#

5324

# ## Snapshot Read-Only Transactions

5325

#

5326

# Snapshot read-only transactions provides a simpler method than

5327

# locking read-write transactions for doing several consistent

5328

# reads. However, this type of transaction does not support writes.

5329

#

5330

# Snapshot transactions do not take locks. Instead, they work by

5331

# choosing a Cloud Spanner timestamp, then executing all reads at that

5332

# timestamp. Since they do not acquire locks, they do not block

5333

# concurrent read-write transactions.

5334

#

5335

# Unlike locking read-write transactions, snapshot read-only

5336

# transactions never abort. They can fail if the chosen read

5337

# timestamp is garbage collected; however, the default garbage

5338

# collection policy is generous enough that most applications do not

5339

# need to worry about this in practice.

5340

#

5341

# Snapshot read-only transactions do not need to call

5342

# Commit or

5343

# Rollback (and in fact are not

5344

# permitted to do so).

5345

#

5346

# To execute a snapshot transaction, the client specifies a timestamp

5347

# bound, which tells Cloud Spanner how to choose a read timestamp.

5348

#

5349

# The types of timestamp bound are:

5350

#

5351

# - Strong (the default).

5352

# - Bounded staleness.

5353

# - Exact staleness.

5354

#

5355

# If the Cloud Spanner database to be read is geographically distributed,

5356

# stale read-only transactions can execute more quickly than strong

5357

# or read-write transaction, because they are able to execute far

5358

# from the leader replica.

5359

#

5360

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

5365

# that have committed before the start of the read. Furthermore, all

5366

# rows yielded by a single read are consistent with each other -- if

5367

# any part of the read observes a transaction, all parts of the read

5368

# see the transaction.

5369

#

5370

# Strong reads are not repeatable: two consecutive strong read-only

5371

# transactions might return inconsistent results if there are

5372

# concurrent writes. If consistency across reads is required, the

5373

# reads should be executed within a transaction or at an exact read

5374

# timestamp.

5375

#

5376

# See TransactionOptions.ReadOnly.strong.

5377

#

5378

# ### Exact Staleness

5379

#

5380

# These timestamp bounds execute reads at a user-specified

5381

# timestamp. Reads at a timestamp are guaranteed to see a consistent

5382

# prefix of the global transaction history: they observe

5383

# modifications done by all transactions with a commit timestamp <=

5384

# the read timestamp, and observe none of the modifications done by

5385

# transactions with a larger commit timestamp. They will block until

5386

# all conflicting transactions that may be assigned commit timestamps

5387

# <= the read timestamp have finished.

5388

#

5389

# The timestamp can either be expressed as an absolute Cloud Spanner commit

5390

# timestamp or a staleness relative to the current time.

5391

#

5392

# These modes do not require a "negotiation phase" to pick a

5393

# timestamp. As a result, they execute slightly faster than the

5394

# equivalent boundedly stale concurrency modes. On the other hand,

5395

# boundedly stale reads usually return fresher results.

5396

#

5397

# See TransactionOptions.ReadOnly.read_timestamp and

5398

# TransactionOptions.ReadOnly.exact_staleness.

5399

#

5400

# ### Bounded Staleness

5401

#

5402

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

5403

# subject to a user-provided staleness bound. Cloud Spanner chooses the

5404

# newest timestamp within the staleness bound that allows execution

5405

# of the reads at the closest available replica without blocking.

5406

#

5407

# All rows yielded are consistent with each other -- if any part of

5408

# the read observes a transaction, all parts of the read see the

5409

# transaction. Boundedly stale reads are not repeatable: two stale

5410

# reads, even if they use the same staleness bound, can execute at

5411

# different timestamps and thus return inconsistent results.

5412

#

5413

# Boundedly stale reads execute in two phases: the first phase

5414

# negotiates a timestamp among all replicas needed to serve the

5415

# read. In the second phase, reads are executed at the negotiated

5416

# timestamp.

5417

#

5418

# As a result of the two phase execution, bounded staleness reads are

5419

# usually a little slower than comparable exact staleness

5420

# reads. However, they are typically able to return fresher

5421

# results, and are more likely to execute at the closest replica.

5422

#

5423

# Because the timestamp negotiation requires up-front knowledge of

5424

# which rows will be read, it can only be used with single-use

5425

# read-only transactions.

5426

#

5427

# See TransactionOptions.ReadOnly.max_staleness and

5428

# TransactionOptions.ReadOnly.min_read_timestamp.

5429

#

5430

# ### Old Read Timestamps and Garbage Collection

5431

#

5432

# Cloud Spanner continuously garbage collects deleted and overwritten data

5433

# in the background to reclaim storage space. This process is known

5434

# as "version GC". By default, version GC reclaims versions after they

5435

# are one hour old. Because of this, Cloud Spanner cannot perform reads

5436

# at read timestamps more than one hour in the past. This

5437

# restriction also applies to in-progress reads and/or SQL queries whose

5438

# timestamp become too old while executing. Reads and SQL queries with

5439

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

5440

#

5441

# ## Partitioned DML Transactions

5442

#

5443

# Partitioned DML transactions are used to execute DML statements with a

5444

# different execution strategy that provides different, and often better,

5445

# scalability properties for large, table-wide operations than DML in a

5446

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

5447

# should prefer using ReadWrite transactions.

5448

#

5449

# Partitioned DML partitions the keyspace and runs the DML statement on each

5450

# partition in separate, internal transactions. These transactions commit

5451

# automatically when complete, and run independently from one another.

5452

#

5453

# To reduce lock contention, this execution strategy only acquires read locks

5454

# on rows that match the WHERE clause of the statement. Additionally, the

5455

# smaller per-partition transactions hold locks for less time.

5456

#

5457

# That said, Partitioned DML is not a drop-in replacement for standard DML used

5458

# in ReadWrite transactions.

5459

#

5460

# - The DML statement must be fully-partitionable. Specifically, the statement

5461

# must be expressible as the union of many statements which each access only

5462

# a single row of the table.

5463

#

5464

# - The statement is not applied atomically to all rows of the table. Rather,

5465

# the statement is applied atomically to partitions of the table, in

5466

# independent transactions. Secondary index rows are updated atomically

5467

# with the base table rows.

5468

#

5469

# - Partitioned DML does not guarantee exactly-once execution semantics

5470

# against a partition. The statement will be applied at least once to each

5471

# partition. It is strongly recommended that the DML statement should be

5472

# idempotent to avoid unexpected results. For instance, it is potentially

5473

# dangerous to run a statement such as

5474

# `UPDATE table SET column = column + 1` as it could be run multiple times

5475

# against some rows.

5476

#

5477

# - The partitions are committed automatically - there is no support for

5478

# Commit or Rollback. If the call returns an error, or if the client issuing

5479

# the ExecuteSql call dies, it is possible that some rows had the statement

5480

# executed on them successfully. It is also possible that statement was

5481

# never executed against other rows.

5482

#

5483

# - Partitioned DML transactions may only contain the execution of a single

5484

# DML statement via ExecuteSql or ExecuteStreamingSql.

5485

#

5486

# - If any error is encountered during the execution of the partitioned DML

5487

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

5488

# value that cannot be stored due to schema constraints), then the

5489

# operation is stopped at that point and an error is returned. It is

5490

# possible that at this point, some partitions have been committed (or even

5491

# committed multiple times), and other partitions have not been run at all.

5492

#

5493

# Given the above, Partitioned DML is good fit for large, database-wide,

5494

# operations that are idempotent, such as deleting old rows from a very large

5495

# table.

5496

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

5497

#

5498

# Authorization to begin a read-write transaction requires

5499

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

5500

# on the `session` resource.

5501

# transaction type has no options.

5502

},

5503

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

5504

#

5505

# Authorization to begin a read-only transaction requires

5506

# `spanner.databases.beginReadOnlyTransaction` permission

5507

# on the `session` resource.

5508

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

5509

#

5510

# This is useful for requesting fresher data than some previous

5511

# read, or data that is fresh enough to observe the effects of some

5512

# previously committed transaction whose timestamp is known.

5513

#

5514

# Note that this option can only be used in single-use transactions.

5515

#

5516

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

5517

# Example: `"2014-10-02T15:01:23.045123456Z"`.

5518

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

5519

# the Transaction message that describes the transaction.

5520

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

5521

# seconds. Guarantees that all writes that have committed more

5522

# than the specified number of seconds ago are visible. Because

5523

# Cloud Spanner chooses the exact timestamp, this mode works even if

5524

# the client's local clock is substantially skewed from Cloud Spanner

5525

# commit timestamps.

5526

#

5527

# Useful for reading the freshest data available at a nearby

5528

# replica, while bounding the possible staleness if the local

5529

# replica has fallen behind.

5530

#

5531

# Note that this option can only be used in single-use

5532

# transactions.

5533

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

5534

# old. The timestamp is chosen soon after the read is started.

5535

#

5536

# Guarantees that all writes that have committed more than the

5537

# specified number of seconds ago are visible. Because Cloud Spanner

5538

# chooses the exact timestamp, this mode works even if the client's

5539

# local clock is substantially skewed from Cloud Spanner commit

5540

# timestamps.

5541

#

5542

# Useful for reading at nearby replicas without the distributed

5543

# timestamp negotiation overhead of `max_staleness`.

5544

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

5545

# reads at a specific timestamp are repeatable; the same read at

5546

# the same timestamp always returns the same data. If the

5547

# timestamp is in the future, the read will block until the

5548

# specified timestamp, modulo the read's deadline.

5549

#

5550

# Useful for large scale consistent reads such as mapreduces, or

5551

# for coordinating many reads against a consistent snapshot of the

5552

# data.

5553

#

5554

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

5555

# Example: `"2014-10-02T15:01:23.045123456Z"`.

5556

"strong": True or False, # Read at a timestamp where all previously committed transactions

5557

# are visible.

5558

},

5559

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

5560

#

5561

# Authorization to begin a Partitioned DML transaction requires

5562

# `spanner.databases.beginPartitionedDmlTransaction` permission

5563

# on the `session` resource.

5564

},

5565

},

5566

"singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.

5567

# This is the most efficient way to execute a transaction that

5568

# consists of a single SQL query.

5569

#

5570

#

5571

# Each session can have at most one active transaction at a time. After the

5572

# active transaction is completed, the session can immediately be

5573

# re-used for the next transaction. It is not necessary to create a

5574

# new session for each transaction.

5575

#

5576

# # Transaction Modes

5577

#

5578

# Cloud Spanner supports three transaction modes:

5579

#

5580

# 1. Locking read-write. This type of transaction is the only way

5581

# to write data into Cloud Spanner. These transactions rely on

5582

# pessimistic locking and, if necessary, two-phase commit.

5583

# Locking read-write transactions may abort, requiring the

5584

# application to retry.

5585

#

5586

# 2. Snapshot read-only. This transaction type provides guaranteed

5587

# consistency across several reads, but does not allow

5588

# writes. Snapshot read-only transactions can be configured to

5589

# read at timestamps in the past. Snapshot read-only

5590

# transactions do not need to be committed.

5591

#

5592

# 3. Partitioned DML. This type of transaction is used to execute

5593

# a single Partitioned DML statement. Partitioned DML partitions

5594

# the key space and runs the DML statement over each partition

5595

# in parallel using separate, internal transactions that commit

5596

# independently. Partitioned DML transactions do not need to be

5597

# committed.

5598

#

5599

# For transactions that only read, snapshot read-only transactions

5600

# provide simpler semantics and are almost always faster. In

5601

# particular, read-only transactions do not take locks, so they do

5602

# not conflict with read-write transactions. As a consequence of not

5603

# taking locks, they also do not abort, so retry loops are not needed.

5604

#

5605

# Transactions may only read/write data in a single database. They

5606

# may, however, read/write data in different tables within that

5607

# database.

5608

#

5609

# ## Locking Read-Write Transactions

5610

#

5611

# Locking transactions may be used to atomically read-modify-write

5612

# data anywhere in a database. This type of transaction is externally

5613

# consistent.

5614

#

5615

# Clients should attempt to minimize the amount of time a transaction

5616

# is active. Faster transactions commit with higher probability

5617

# and cause less contention. Cloud Spanner attempts to keep read locks

5618

# active as long as the transaction continues to do reads, and the

5619

# transaction has not been terminated by

5620

# Commit or

5621

# Rollback. Long periods of

5622

# inactivity at the client may cause Cloud Spanner to release a

5623

# transaction's locks and abort it.

5624

#

5625

# Conceptually, a read-write transaction consists of zero or more

5626

# reads or SQL statements followed by

5627

# Commit. At any time before

5628

# Commit, the client can send a

5629

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

5635

# are still valid at commit time, and it is able to acquire write

5636

# locks for all writes. Cloud Spanner can abort the transaction for any

5637

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

5638

# that the transaction has not modified any user data in Cloud Spanner.

5639

#

5640

# Unless the transaction commits, Cloud Spanner makes no guarantees about

5641

# how long the transaction's locks were held for. It is an error to

5642

# use Cloud Spanner locks for any sort of mutual exclusion other than

5643

# between Cloud Spanner transactions themselves.

5644

#

5645

# ### Retrying Aborted Transactions

5646

#

5647

# When a transaction aborts, the application can choose to retry the

5648

# whole transaction again. To maximize the chances of successfully

5649

# committing the retry, the client should execute the retry in the

5650

# same session as the original attempt. The original session's lock

5651

# priority increases with each consecutive abort, meaning that each

5652

# attempt has a slightly better chance of success than the previous.

5653

#

5654

# Under some circumstances (e.g., many transactions attempting to

5655

# modify the same row(s)), a transaction can abort many times in a

5656

# short period before successfully committing. Thus, it is not a good

5657

# idea to cap the number of retries a transaction can attempt;

5658

# instead, it is better to limit the total amount of wall time spent

5659

# retrying.

5660

#

5661

# ### Idle Transactions

5662

#

5663

# A transaction is considered idle if it has no outstanding reads or

5664

# SQL queries and has not started a read or SQL query within the last 10

5665

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

5666

# don't hold on to locks indefinitely. In that case, the commit will

5667

# fail with error `ABORTED`.

5668

#

5669

# If this behavior is undesirable, periodically executing a simple

5670

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

5671

# transaction from becoming idle.

5672

#

5673

# ## Snapshot Read-Only Transactions

5674

#

5675

# Snapshot read-only transactions provides a simpler method than

5676

# locking read-write transactions for doing several consistent

5677

# reads. However, this type of transaction does not support writes.

5678

#

5679

# Snapshot transactions do not take locks. Instead, they work by

5680

# choosing a Cloud Spanner timestamp, then executing all reads at that

5681

# timestamp. Since they do not acquire locks, they do not block

5682

# concurrent read-write transactions.

5683

#

5684

# Unlike locking read-write transactions, snapshot read-only

5685

# transactions never abort. They can fail if the chosen read

5686

# timestamp is garbage collected; however, the default garbage

5687

# collection policy is generous enough that most applications do not

5688

# need to worry about this in practice.

5689

#

5690

# Snapshot read-only transactions do not need to call

5691

# Commit or

5692

# Rollback (and in fact are not

5693

# permitted to do so).

5694

#

5695

# To execute a snapshot transaction, the client specifies a timestamp

5696

# bound, which tells Cloud Spanner how to choose a read timestamp.

5697

#

5698

# The types of timestamp bound are:

5699

#

5700

# - Strong (the default).

5701

# - Bounded staleness.

5702

# - Exact staleness.

5703

#

5704

# If the Cloud Spanner database to be read is geographically distributed,

5705

# stale read-only transactions can execute more quickly than strong

5706

# or read-write transaction, because they are able to execute far

5707

# from the leader replica.

5708

#

5709

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

5714

# that have committed before the start of the read. Furthermore, all

5715

# rows yielded by a single read are consistent with each other -- if

5716

# any part of the read observes a transaction, all parts of the read

5717

# see the transaction.

5718

#

5719

# Strong reads are not repeatable: two consecutive strong read-only

5720

# transactions might return inconsistent results if there are

5721

# concurrent writes. If consistency across reads is required, the

5722

# reads should be executed within a transaction or at an exact read

5723

# timestamp.

5724

#

5725

# See TransactionOptions.ReadOnly.strong.

5726

#

5727

# ### Exact Staleness

5728

#

5729

# These timestamp bounds execute reads at a user-specified

5730

# timestamp. Reads at a timestamp are guaranteed to see a consistent

5731

# prefix of the global transaction history: they observe

5732

# modifications done by all transactions with a commit timestamp <=

5733

# the read timestamp, and observe none of the modifications done by

5734

# transactions with a larger commit timestamp. They will block until

5735

# all conflicting transactions that may be assigned commit timestamps

5736

# <= the read timestamp have finished.

5737

#

5738

# The timestamp can either be expressed as an absolute Cloud Spanner commit

5739

# timestamp or a staleness relative to the current time.

5740

#

5741

# These modes do not require a "negotiation phase" to pick a

5742

# timestamp. As a result, they execute slightly faster than the

5743

# equivalent boundedly stale concurrency modes. On the other hand,

5744

# boundedly stale reads usually return fresher results.

5745

#

5746

# See TransactionOptions.ReadOnly.read_timestamp and

5747

# TransactionOptions.ReadOnly.exact_staleness.

5748

#

5749

# ### Bounded Staleness

5750

#

5751

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

5752

# subject to a user-provided staleness bound. Cloud Spanner chooses the

5753

# newest timestamp within the staleness bound that allows execution

5754

# of the reads at the closest available replica without blocking.

5755

#

5756

# All rows yielded are consistent with each other -- if any part of

5757

# the read observes a transaction, all parts of the read see the

5758

# transaction. Boundedly stale reads are not repeatable: two stale

5759

# reads, even if they use the same staleness bound, can execute at

5760

# different timestamps and thus return inconsistent results.

5761

#

5762

# Boundedly stale reads execute in two phases: the first phase

5763

# negotiates a timestamp among all replicas needed to serve the

5764

# read. In the second phase, reads are executed at the negotiated

5765

# timestamp.

5766

#

5767

# As a result of the two phase execution, bounded staleness reads are

5768

# usually a little slower than comparable exact staleness

5769

# reads. However, they are typically able to return fresher

5770

# results, and are more likely to execute at the closest replica.

5771

#

5772

# Because the timestamp negotiation requires up-front knowledge of

5773

# which rows will be read, it can only be used with single-use

5774

# read-only transactions.

5775

#

5776

# See TransactionOptions.ReadOnly.max_staleness and

5777

# TransactionOptions.ReadOnly.min_read_timestamp.

5778

#

5779

# ### Old Read Timestamps and Garbage Collection

5780

#

5781

# Cloud Spanner continuously garbage collects deleted and overwritten data

5782

# in the background to reclaim storage space. This process is known

5783

# as "version GC". By default, version GC reclaims versions after they

5784

# are one hour old. Because of this, Cloud Spanner cannot perform reads

5785

# at read timestamps more than one hour in the past. This

5786

# restriction also applies to in-progress reads and/or SQL queries whose

5787

# timestamp become too old while executing. Reads and SQL queries with

5788

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

5789

#

5790

# ## Partitioned DML Transactions

5791

#

5792

# Partitioned DML transactions are used to execute DML statements with a

5793

# different execution strategy that provides different, and often better,

5794

# scalability properties for large, table-wide operations than DML in a

5795

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

5796

# should prefer using ReadWrite transactions.

5797

#

5798

# Partitioned DML partitions the keyspace and runs the DML statement on each

5799

# partition in separate, internal transactions. These transactions commit

5800

# automatically when complete, and run independently from one another.

5801

#

5802

# To reduce lock contention, this execution strategy only acquires read locks

5803

# on rows that match the WHERE clause of the statement. Additionally, the

5804

# smaller per-partition transactions hold locks for less time.

5805

#

5806

# That said, Partitioned DML is not a drop-in replacement for standard DML used

5807

# in ReadWrite transactions.

5808

#

5809

# - The DML statement must be fully-partitionable. Specifically, the statement

5810

# must be expressible as the union of many statements which each access only

5811

# a single row of the table.

5812

#

5813

# - The statement is not applied atomically to all rows of the table. Rather,

5814

# the statement is applied atomically to partitions of the table, in

5815

# independent transactions. Secondary index rows are updated atomically

5816

# with the base table rows.

5817

#

5818

# - Partitioned DML does not guarantee exactly-once execution semantics

5819

# against a partition. The statement will be applied at least once to each

5820

# partition. It is strongly recommended that the DML statement should be

5821

# idempotent to avoid unexpected results. For instance, it is potentially

5822

# dangerous to run a statement such as

5823

# `UPDATE table SET column = column + 1` as it could be run multiple times

5824

# against some rows.

5825

#

5826

# - The partitions are committed automatically - there is no support for

5827

# Commit or Rollback. If the call returns an error, or if the client issuing

5828

# the ExecuteSql call dies, it is possible that some rows had the statement

5829

# executed on them successfully. It is also possible that statement was

5830

# never executed against other rows.

5831

#

5832

# - Partitioned DML transactions may only contain the execution of a single

5833

# DML statement via ExecuteSql or ExecuteStreamingSql.

5834

#

5835

# - If any error is encountered during the execution of the partitioned DML

5836

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

5837

# value that cannot be stored due to schema constraints), then the

5838

# operation is stopped at that point and an error is returned. It is

5839

# possible that at this point, some partitions have been committed (or even

5840

# committed multiple times), and other partitions have not been run at all.

5841

#

5842

# Given the above, Partitioned DML is good fit for large, database-wide,

5843

# operations that are idempotent, such as deleting old rows from a very large

5844

# table.

5845

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

5846

#

5847

# Authorization to begin a read-write transaction requires

5848

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

5849

# on the `session` resource.

5850

# transaction type has no options.

5851

},

5852

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

5853

#

5854

# Authorization to begin a read-only transaction requires

5855

# `spanner.databases.beginReadOnlyTransaction` permission

5856

# on the `session` resource.

5857

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

5858

#

5859

# This is useful for requesting fresher data than some previous

5860

# read, or data that is fresh enough to observe the effects of some

5861

# previously committed transaction whose timestamp is known.

5862

#

5863

# Note that this option can only be used in single-use transactions.

5864

#

5865

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

5866

# Example: `"2014-10-02T15:01:23.045123456Z"`.

5867

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

5868

# the Transaction message that describes the transaction.

5869

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

5870

# seconds. Guarantees that all writes that have committed more

5871

# than the specified number of seconds ago are visible. Because

5872

# Cloud Spanner chooses the exact timestamp, this mode works even if

5873

# the client's local clock is substantially skewed from Cloud Spanner

5874

# commit timestamps.

5875

#

5876

# Useful for reading the freshest data available at a nearby

5877

# replica, while bounding the possible staleness if the local

5878

# replica has fallen behind.

5879

#

5880

# Note that this option can only be used in single-use

5881

# transactions.

5882

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

5883

# old. The timestamp is chosen soon after the read is started.

5884

#

5885

# Guarantees that all writes that have committed more than the

5886

# specified number of seconds ago are visible. Because Cloud Spanner

5887

# chooses the exact timestamp, this mode works even if the client's

5888

# local clock is substantially skewed from Cloud Spanner commit

5889

# timestamps.

5890

#

5891

# Useful for reading at nearby replicas without the distributed

5892

# timestamp negotiation overhead of `max_staleness`.

5893

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

5894

# reads at a specific timestamp are repeatable; the same read at

5895

# the same timestamp always returns the same data. If the

5896

# timestamp is in the future, the read will block until the

5897

# specified timestamp, modulo the read's deadline.

5898

#

5899

# Useful for large scale consistent reads such as mapreduces, or

5900

# for coordinating many reads against a consistent snapshot of the

5901

# data.

5902

#

5903

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

5904

# Example: `"2014-10-02T15:01:23.045123456Z"`.

5905

"strong": True or False, # Read at a timestamp where all previously committed transactions

5906

# are visible.

5907

},

5908

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

5909

#

5910

# Authorization to begin a Partitioned DML transaction requires

5911

# `spanner.databases.beginPartitionedDmlTransaction` permission

5912

# on the `session` resource.

5913

},

5914

},

5915

"id": "A String", # Execute the read or SQL query in a previously-started transaction.

5916

},

5917

"keySet": { # `KeySet` defines a collection of Cloud Spanner keys and/or key ranges. All # Required. `key_set` identifies the rows to be yielded. `key_set` names the

5918

# primary keys of the rows in table to be yielded, unless index

5919

# is present. If index is present, then key_set instead names

5920

# index keys in index.

5921

#

5922

# It is not an error for the `key_set` to name rows that do not

5923

# exist in the database. Read yields nothing for nonexistent rows.

5924

# the keys are expected to be in the same table or index. The keys need

5925

# not be sorted in any particular way.

5926

#

5927

# If the same key is specified multiple times in the set (for example

5928

# if two ranges, two keys, or a key and a range overlap), Cloud Spanner

5929

# behaves as if the key were only specified once.

5930

"ranges": [ # A list of key ranges. See KeyRange for more information about

5931

# key range specifications.

5932

{ # KeyRange represents a range of rows in a table or index.

5933

#

5934

# A range has a start key and an end key. These keys can be open or

5935

# closed, indicating if the range includes rows with that key.

5936

#

5937

# Keys are represented by lists, where the ith value in the list

5938

# corresponds to the ith component of the table or index primary key.

5939

# Individual values are encoded as described

5940

# here.

5941

#

5942

# For example, consider the following table definition:

5943

#

5944

# CREATE TABLE UserEvents (

5945

# UserName STRING(MAX),

5946

# EventDate STRING(10)

5947

# ) PRIMARY KEY(UserName, EventDate);

5948

#

5949

# The following keys name rows in this table:

5950

#

5951

# "Bob", "2014-09-23"

5952

#

5953

# Since the `UserEvents` table's `PRIMARY KEY` clause names two

5954

# columns, each `UserEvents` key has two elements; the first is the

5955

# `UserName`, and the second is the `EventDate`.

5956

#

5957

# Key ranges with multiple components are interpreted

5958

# lexicographically by component using the table or index key's declared

5959

# sort order. For example, the following range returns all events for

5960

# user `"Bob"` that occurred in the year 2015:

5961

#

5962

# "start_closed": ["Bob", "2015-01-01"]

5963

# "end_closed": ["Bob", "2015-12-31"]

5964

#

5965

# Start and end keys can omit trailing key components. This affects the

5966

# inclusion and exclusion of rows that exactly match the provided key

5967

# components: if the key is closed, then rows that exactly match the

5968

# provided components are included; if the key is open, then rows

5969

# that exactly match are not included.

5970

#

5971

# For example, the following range includes all events for `"Bob"` that

5972

# occurred during and after the year 2000:

5973

#

5974

# "start_closed": ["Bob", "2000-01-01"]

5975

# "end_closed": ["Bob"]

5976

#

5977

# The next example retrieves all events for `"Bob"`:

5978

#

5979

# "start_closed": ["Bob"]

5980

# "end_closed": ["Bob"]

5981

#

5982

# To retrieve events before the year 2000:

5983

#

5984

# "start_closed": ["Bob"]

5985

# "end_open": ["Bob", "2000-01-01"]

5986

#

5987

# The following range includes all rows in the table:

#

# "start_closed": []

# "end_closed": []

#

# This range returns all users whose `UserName` begins with any

5993

# character from A to C:

5994

#

5995

# "start_closed": ["A"]

5996

# "end_open": ["D"]

5997

#

5998

# This range returns all users whose `UserName` begins with B:

5999

#

6000

# "start_closed": ["B"]

6001

# "end_open": ["C"]

6002

#

6003

# Key ranges honor column sort order. For example, suppose a table is

6004

# defined as follows:

6005

#

6006

# CREATE TABLE DescendingSortedTable {

6007

# Key INT64,

6008

# ...

6009

# ) PRIMARY KEY(Key DESC);

6010

#

6011

# The following range retrieves all rows with key values between 1

6012

# and 100 inclusive:

6013

#

6014

# "start_closed": ["100"]

6015

# "end_closed": ["1"]

6016

#

6017

# Note that 100 is passed as the start, and 1 is passed as the end,

6018

# because `Key` is a descending column in the schema.

6019

"endOpen": [ # If the end is open, then the range excludes rows whose first

6020

# `len(end_open)` key columns exactly match `end_open`.

6021

"",

6022

],

6023

"startOpen": [ # If the start is open, then the range excludes rows whose first

6024

# `len(start_open)` key columns exactly match `start_open`.

6025

"",

6026

],

6027

"endClosed": [ # If the end is closed, then the range includes all rows whose

6028

# first `len(end_closed)` key columns exactly match `end_closed`.

6029

"",

6030

],

6031

"startClosed": [ # If the start is closed, then the range includes all rows whose

6032

# first `len(start_closed)` key columns exactly match `start_closed`.

"",

],

},

],

"keys": [ # A list of specific keys. Entries in `keys` should have exactly as

6038

# many elements as there are columns in the primary or index key

6039

# with which this `KeySet` is used. Individual key values are

6040

# encoded as described here.

[

"",

],

],

"all": True or False, # For convenience `all` can be set to `true` to indicate that this

6046

# `KeySet` matches all keys in the table or index. Note that any keys

6047

# specified in `keys` or `ranges` are only yielded once.

6048

},

6049

"partitionOptions": { # Options for a PartitionQueryRequest and # Additional options that affect how many partitions are created.

6050

# PartitionReadRequest.

6051

"maxPartitions": "A String", # **Note:** This hint is currently ignored by PartitionQuery and

6052

# PartitionRead requests.

6053

#

6054

# The desired maximum number of partitions to return. For example, this may

6055

# be set to the number of workers available. The default for this option

6056

# is currently 10,000. The maximum value is currently 200,000. This is only

6057

# a hint. The actual number of partitions returned may be smaller or larger

6058

# than this maximum count request.

6059

"partitionSizeBytes": "A String", # **Note:** This hint is currently ignored by PartitionQuery and

6060

# PartitionRead requests.

6061

#

6062

# The desired data size for each partition generated. The default for this

6063

# option is currently 1 GiB. This is only a hint. The actual size of each

6064

# partition may be smaller or larger than this size request.

6065

},

6066

"table": "A String", # Required. The name of the table in the database to be read.

6067

"columns": [ # The columns of table to be returned for each row matching

# this request.

"A String",

],

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

6080

6081

{ # The response for PartitionQuery

6082

# or PartitionRead

6083

"transaction": { # A transaction. # Transaction created by this request.

6084

"readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen

6085

# for the transaction. Not returned by default: see

6086

# TransactionOptions.ReadOnly.return_read_timestamp.

6087

#

6088

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

6089

# Example: `"2014-10-02T15:01:23.045123456Z"`.

6090

"id": "A String", # `id` may be used to identify the transaction in subsequent

# Read,

# ExecuteSql,

# Commit, or

# Rollback calls.

#

# Single-use read-only transactions do not have IDs, because

6097

# single-use transactions do not support multiple requests.

6098

},

6099

"partitions": [ # Partitions created by this request.

6100

{ # Information returned for each partition returned in a

6101

# PartitionResponse.

6102

"partitionToken": "A String", # This token can be passed to Read, StreamingRead, ExecuteSql, or

6103

# ExecuteStreamingSql requests to restrict the results to those identified by

6104

# this partition token.

6105

},

6106

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

}</pre>

</div>

<code class="details" id="read">read(session, body, x__xgafv=None)</code>

6112

<pre>Reads rows from the database using key lookups and scans, as a

6113

simple key/value style alternative to

6114

ExecuteSql. This method cannot be used to

6115

return a result set larger than 10 MiB; if the read matches more

6116

data than that, the read fails with a `FAILED_PRECONDITION`

6117

error.

6118

6119

Reads inside read-write transactions might return `ABORTED`. If

6120

this occurs, the application should restart the transaction from

6121

the beginning. See Transaction for more details.

6122

6123

Larger result sets can be yielded in streaming fashion by calling

6124

StreamingRead instead.

6125

6126

Args:

6127

session: string, Required. The session in which the read should be performed. (required)

6128

body: object, The request body. (required)

6129

The object takes the form of:

6130

6131

{ # The request for Read and

6132

# StreamingRead.

6133

"index": "A String", # If non-empty, the name of an index on table. This index is

6134

# used instead of the table primary key when interpreting key_set

6135

# and sorting result rows. See key_set for further information.

6136

"transaction": { # This message is used to select the transaction in which a # The transaction to use. If none is provided, the default is a

6137

# temporary read-only transaction with strong concurrency.

6138

# Read or

6139

# ExecuteSql call runs.

6140

#

6141

# See TransactionOptions for more information about transactions.

6142

"begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in

6143

# it. The transaction ID of the new transaction is returned in

6144

# ResultSetMetadata.transaction, which is a Transaction.

6145

#

6146

#

6147

# Each session can have at most one active transaction at a time. After the

6148

# active transaction is completed, the session can immediately be

6149

# re-used for the next transaction. It is not necessary to create a

6150

# new session for each transaction.

6151

#

6152

# # Transaction Modes

6153

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6154

# Cloud Spanner supports three transaction modes:

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6155

#

6156

# 1. Locking read-write. This type of transaction is the only way

6157

# to write data into Cloud Spanner. These transactions rely on

6158

# pessimistic locking and, if necessary, two-phase commit.

6159

# Locking read-write transactions may abort, requiring the

6160

# application to retry.

6161

#

6162

# 2. Snapshot read-only. This transaction type provides guaranteed

6163

# consistency across several reads, but does not allow

6164

# writes. Snapshot read-only transactions can be configured to

6165

# read at timestamps in the past. Snapshot read-only

6166

# transactions do not need to be committed.

6167

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6168

# 3. Partitioned DML. This type of transaction is used to execute

6169

# a single Partitioned DML statement. Partitioned DML partitions

6170

# the key space and runs the DML statement over each partition

6171

# in parallel using separate, internal transactions that commit

6172

# independently. Partitioned DML transactions do not need to be

6173

# committed.

6174

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6175

# For transactions that only read, snapshot read-only transactions

6176

# provide simpler semantics and are almost always faster. In

6177

# particular, read-only transactions do not take locks, so they do

6178

# not conflict with read-write transactions. As a consequence of not

6179

# taking locks, they also do not abort, so retry loops are not needed.

6180

#

6181

# Transactions may only read/write data in a single database. They

6182

# may, however, read/write data in different tables within that

6183

# database.

6184

#

6185

# ## Locking Read-Write Transactions

6186

#

6187

# Locking transactions may be used to atomically read-modify-write

6188

# data anywhere in a database. This type of transaction is externally

6189

# consistent.

6190

#

6191

# Clients should attempt to minimize the amount of time a transaction

6192

# is active. Faster transactions commit with higher probability

6193

# and cause less contention. Cloud Spanner attempts to keep read locks

6194

# active as long as the transaction continues to do reads, and the

6195

# transaction has not been terminated by

6196

# Commit or

6197

# Rollback. Long periods of

6198

# inactivity at the client may cause Cloud Spanner to release a

6199

# transaction's locks and abort it.

6200

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6201

# Conceptually, a read-write transaction consists of zero or more

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6202

# reads or SQL statements followed by

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6203

# Commit. At any time before

6204

# Commit, the client can send a

6205

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

6211

# are still valid at commit time, and it is able to acquire write

6212

# locks for all writes. Cloud Spanner can abort the transaction for any

6213

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

6214

# that the transaction has not modified any user data in Cloud Spanner.

6215

#

6216

# Unless the transaction commits, Cloud Spanner makes no guarantees about

6217

# how long the transaction's locks were held for. It is an error to

6218

# use Cloud Spanner locks for any sort of mutual exclusion other than

6219

# between Cloud Spanner transactions themselves.

6220

#

6221

# ### Retrying Aborted Transactions

6222

#

6223

# When a transaction aborts, the application can choose to retry the

6224

# whole transaction again. To maximize the chances of successfully

6225

# committing the retry, the client should execute the retry in the

6226

# same session as the original attempt. The original session's lock

6227

# priority increases with each consecutive abort, meaning that each

6228

# attempt has a slightly better chance of success than the previous.

6229

#

6230

# Under some circumstances (e.g., many transactions attempting to

6231

# modify the same row(s)), a transaction can abort many times in a

6232

# short period before successfully committing. Thus, it is not a good

6233

# idea to cap the number of retries a transaction can attempt;

6234

# instead, it is better to limit the total amount of wall time spent

6235

# retrying.

6236

#

6237

# ### Idle Transactions

6238

#

6239

# A transaction is considered idle if it has no outstanding reads or

6240

# SQL queries and has not started a read or SQL query within the last 10

6241

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

6242

# don't hold on to locks indefinitely. In that case, the commit will

6243

# fail with error `ABORTED`.

6244

#

6245

# If this behavior is undesirable, periodically executing a simple

6246

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

6247

# transaction from becoming idle.

6248

#

6249

# ## Snapshot Read-Only Transactions

6250

#

6251

# Snapshot read-only transactions provides a simpler method than

6252

# locking read-write transactions for doing several consistent

6253

# reads. However, this type of transaction does not support writes.

6254

#

6255

# Snapshot transactions do not take locks. Instead, they work by

6256

# choosing a Cloud Spanner timestamp, then executing all reads at that

6257

# timestamp. Since they do not acquire locks, they do not block

6258

# concurrent read-write transactions.

6259

#

6260

# Unlike locking read-write transactions, snapshot read-only

6261

# transactions never abort. They can fail if the chosen read

6262

# timestamp is garbage collected; however, the default garbage

6263

# collection policy is generous enough that most applications do not

6264

# need to worry about this in practice.

6265

#

6266

# Snapshot read-only transactions do not need to call

6267

# Commit or

6268

# Rollback (and in fact are not

6269

# permitted to do so).

6270

#

6271

# To execute a snapshot transaction, the client specifies a timestamp

6272

# bound, which tells Cloud Spanner how to choose a read timestamp.

6273

#

6274

# The types of timestamp bound are:

6275

#

6276

# - Strong (the default).

6277

# - Bounded staleness.

6278

# - Exact staleness.

6279

#

6280

# If the Cloud Spanner database to be read is geographically distributed,

6281

# stale read-only transactions can execute more quickly than strong

6282

# or read-write transaction, because they are able to execute far

6283

# from the leader replica.

6284

#

6285

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

6290

# that have committed before the start of the read. Furthermore, all

6291

# rows yielded by a single read are consistent with each other -- if

6292

# any part of the read observes a transaction, all parts of the read

6293

# see the transaction.

6294

#

6295

# Strong reads are not repeatable: two consecutive strong read-only

6296

# transactions might return inconsistent results if there are

6297

# concurrent writes. If consistency across reads is required, the

6298

# reads should be executed within a transaction or at an exact read

6299

# timestamp.

6300

#

6301

# See TransactionOptions.ReadOnly.strong.

6302

#

6303

# ### Exact Staleness

6304

#

6305

# These timestamp bounds execute reads at a user-specified

6306

# timestamp. Reads at a timestamp are guaranteed to see a consistent

6307

# prefix of the global transaction history: they observe

6308

# modifications done by all transactions with a commit timestamp <=

6309

# the read timestamp, and observe none of the modifications done by

6310

# transactions with a larger commit timestamp. They will block until

6311

# all conflicting transactions that may be assigned commit timestamps

6312

# <= the read timestamp have finished.

6313

#

6314

# The timestamp can either be expressed as an absolute Cloud Spanner commit

6315

# timestamp or a staleness relative to the current time.

6316

#

6317

# These modes do not require a "negotiation phase" to pick a

6318

# timestamp. As a result, they execute slightly faster than the

6319

# equivalent boundedly stale concurrency modes. On the other hand,

6320

# boundedly stale reads usually return fresher results.

6321

#

6322

# See TransactionOptions.ReadOnly.read_timestamp and

6323

# TransactionOptions.ReadOnly.exact_staleness.

6324

#

6325

# ### Bounded Staleness

6326

#

6327

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

6328

# subject to a user-provided staleness bound. Cloud Spanner chooses the

6329

# newest timestamp within the staleness bound that allows execution

6330

# of the reads at the closest available replica without blocking.

6331

#

6332

# All rows yielded are consistent with each other -- if any part of

6333

# the read observes a transaction, all parts of the read see the

6334

# transaction. Boundedly stale reads are not repeatable: two stale

6335

# reads, even if they use the same staleness bound, can execute at

6336

# different timestamps and thus return inconsistent results.

6337

#

6338

# Boundedly stale reads execute in two phases: the first phase

6339

# negotiates a timestamp among all replicas needed to serve the

6340

# read. In the second phase, reads are executed at the negotiated

6341

# timestamp.

6342

#

6343

# As a result of the two phase execution, bounded staleness reads are

6344

# usually a little slower than comparable exact staleness

6345

# reads. However, they are typically able to return fresher

6346

# results, and are more likely to execute at the closest replica.

6347

#

6348

# Because the timestamp negotiation requires up-front knowledge of

6349

# which rows will be read, it can only be used with single-use

6350

# read-only transactions.

6351

#

6352

# See TransactionOptions.ReadOnly.max_staleness and

6353

# TransactionOptions.ReadOnly.min_read_timestamp.

6354

#

6355

# ### Old Read Timestamps and Garbage Collection

6356

#

6357

# Cloud Spanner continuously garbage collects deleted and overwritten data

6358

# in the background to reclaim storage space. This process is known

6359

# as "version GC". By default, version GC reclaims versions after they

6360

# are one hour old. Because of this, Cloud Spanner cannot perform reads

6361

# at read timestamps more than one hour in the past. This

6362

# restriction also applies to in-progress reads and/or SQL queries whose

6363

# timestamp become too old while executing. Reads and SQL queries with

6364

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6365

#

6366

# ## Partitioned DML Transactions

6367

#

6368

# Partitioned DML transactions are used to execute DML statements with a

6369

# different execution strategy that provides different, and often better,

6370

# scalability properties for large, table-wide operations than DML in a

6371

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

6372

# should prefer using ReadWrite transactions.

6373

#

6374

# Partitioned DML partitions the keyspace and runs the DML statement on each

6375

# partition in separate, internal transactions. These transactions commit

6376

# automatically when complete, and run independently from one another.

6377

#

6378

# To reduce lock contention, this execution strategy only acquires read locks

6379

# on rows that match the WHERE clause of the statement. Additionally, the

6380

# smaller per-partition transactions hold locks for less time.

6381

#

6382

# That said, Partitioned DML is not a drop-in replacement for standard DML used

6383

# in ReadWrite transactions.

6384

#

6385

# - The DML statement must be fully-partitionable. Specifically, the statement

6386

# must be expressible as the union of many statements which each access only

6387

# a single row of the table.

6388

#

6389

# - The statement is not applied atomically to all rows of the table. Rather,

6390

# the statement is applied atomically to partitions of the table, in

6391

# independent transactions. Secondary index rows are updated atomically

6392

# with the base table rows.

6393

#

6394

# - Partitioned DML does not guarantee exactly-once execution semantics

6395

# against a partition. The statement will be applied at least once to each

6396

# partition. It is strongly recommended that the DML statement should be

6397

# idempotent to avoid unexpected results. For instance, it is potentially

6398

# dangerous to run a statement such as

6399

# `UPDATE table SET column = column + 1` as it could be run multiple times

6400

# against some rows.

6401

#

6402

# - The partitions are committed automatically - there is no support for

6403

# Commit or Rollback. If the call returns an error, or if the client issuing

6404

# the ExecuteSql call dies, it is possible that some rows had the statement

6405

# executed on them successfully. It is also possible that statement was

6406

# never executed against other rows.

6407

#

6408

# - Partitioned DML transactions may only contain the execution of a single

6409

# DML statement via ExecuteSql or ExecuteStreamingSql.

6410

#

6411

# - If any error is encountered during the execution of the partitioned DML

6412

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

6413

# value that cannot be stored due to schema constraints), then the

6414

# operation is stopped at that point and an error is returned. It is

6415

# possible that at this point, some partitions have been committed (or even

6416

# committed multiple times), and other partitions have not been run at all.

6417

#

6418

# Given the above, Partitioned DML is good fit for large, database-wide,

6419

# operations that are idempotent, such as deleting old rows from a very large

6420

# table.

6421

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6422

#

6423

# Authorization to begin a read-write transaction requires

6424

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

6425

# on the `session` resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6426

# transaction type has no options.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6427

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6428

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6429

#

6430

# Authorization to begin a read-only transaction requires

6431

# `spanner.databases.beginReadOnlyTransaction` permission

6432

# on the `session` resource.

6433

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

6434

#

6435

# This is useful for requesting fresher data than some previous

6436

# read, or data that is fresh enough to observe the effects of some

6437

# previously committed transaction whose timestamp is known.

6438

#

6439

# Note that this option can only be used in single-use transactions.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6440

#

6441

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

6442

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6443

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

6444

# the Transaction message that describes the transaction.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6445

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

6446

# seconds. Guarantees that all writes that have committed more

6447

# than the specified number of seconds ago are visible. Because

6448

# Cloud Spanner chooses the exact timestamp, this mode works even if

6449

# the client's local clock is substantially skewed from Cloud Spanner

6450

# commit timestamps.

6451

#

6452

# Useful for reading the freshest data available at a nearby

6453

# replica, while bounding the possible staleness if the local

6454

# replica has fallen behind.

6455

#

6456

# Note that this option can only be used in single-use

6457

# transactions.

6458

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

6459

# old. The timestamp is chosen soon after the read is started.

6460

#

6461

# Guarantees that all writes that have committed more than the

6462

# specified number of seconds ago are visible. Because Cloud Spanner

6463

# chooses the exact timestamp, this mode works even if the client's

6464

# local clock is substantially skewed from Cloud Spanner commit

6465

# timestamps.

6466

#

6467

# Useful for reading at nearby replicas without the distributed

6468

# timestamp negotiation overhead of `max_staleness`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6469

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

6470

# reads at a specific timestamp are repeatable; the same read at

6471

# the same timestamp always returns the same data. If the

6472

# timestamp is in the future, the read will block until the

6473

# specified timestamp, modulo the read's deadline.

6474

#

6475

# Useful for large scale consistent reads such as mapreduces, or

6476

# for coordinating many reads against a consistent snapshot of the

6477

# data.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6478

#

6479

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

6480

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6481

"strong": True or False, # Read at a timestamp where all previously committed transactions

6482

# are visible.

6483

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6484

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

6485

#

6486

# Authorization to begin a Partitioned DML transaction requires

6487

# `spanner.databases.beginPartitionedDmlTransaction` permission

6488

# on the `session` resource.

6489

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6490

},

6491

"singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.

6492

# This is the most efficient way to execute a transaction that

6493

# consists of a single SQL query.

6494

#

6495

#

6496

# Each session can have at most one active transaction at a time. After the

6497

# active transaction is completed, the session can immediately be

6498

# re-used for the next transaction. It is not necessary to create a

6499

# new session for each transaction.

6500

#

6501

# # Transaction Modes

6502

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6503

# Cloud Spanner supports three transaction modes:

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6504

#

6505

# 1. Locking read-write. This type of transaction is the only way

6506

# to write data into Cloud Spanner. These transactions rely on

6507

# pessimistic locking and, if necessary, two-phase commit.

6508

# Locking read-write transactions may abort, requiring the

6509

# application to retry.

6510

#

6511

# 2. Snapshot read-only. This transaction type provides guaranteed

6512

# consistency across several reads, but does not allow

6513

# writes. Snapshot read-only transactions can be configured to

6514

# read at timestamps in the past. Snapshot read-only

6515

# transactions do not need to be committed.

6516

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6517

# 3. Partitioned DML. This type of transaction is used to execute

6518

# a single Partitioned DML statement. Partitioned DML partitions

6519

# the key space and runs the DML statement over each partition

6520

# in parallel using separate, internal transactions that commit

6521

# independently. Partitioned DML transactions do not need to be

6522

# committed.

6523

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6524

# For transactions that only read, snapshot read-only transactions

6525

# provide simpler semantics and are almost always faster. In

6526

# particular, read-only transactions do not take locks, so they do

6527

# not conflict with read-write transactions. As a consequence of not

6528

# taking locks, they also do not abort, so retry loops are not needed.

6529

#

6530

# Transactions may only read/write data in a single database. They

6531

# may, however, read/write data in different tables within that

6532

# database.

6533

#

6534

# ## Locking Read-Write Transactions

6535

#

6536

# Locking transactions may be used to atomically read-modify-write

6537

# data anywhere in a database. This type of transaction is externally

6538

# consistent.

6539

#

6540

# Clients should attempt to minimize the amount of time a transaction

6541

# is active. Faster transactions commit with higher probability

6542

# and cause less contention. Cloud Spanner attempts to keep read locks

6543

# active as long as the transaction continues to do reads, and the

6544

# transaction has not been terminated by

6545

# Commit or

6546

# Rollback. Long periods of

6547

# inactivity at the client may cause Cloud Spanner to release a

6548

# transaction's locks and abort it.

6549

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6550

# Conceptually, a read-write transaction consists of zero or more

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6551

# reads or SQL statements followed by

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6552

# Commit. At any time before

6553

# Commit, the client can send a

6554

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

6560

# are still valid at commit time, and it is able to acquire write

6561

# locks for all writes. Cloud Spanner can abort the transaction for any

6562

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

6563

# that the transaction has not modified any user data in Cloud Spanner.

6564

#

6565

# Unless the transaction commits, Cloud Spanner makes no guarantees about

6566

# how long the transaction's locks were held for. It is an error to

6567

# use Cloud Spanner locks for any sort of mutual exclusion other than

6568

# between Cloud Spanner transactions themselves.

6569

#

6570

# ### Retrying Aborted Transactions

6571

#

6572

# When a transaction aborts, the application can choose to retry the

6573

# whole transaction again. To maximize the chances of successfully

6574

# committing the retry, the client should execute the retry in the

6575

# same session as the original attempt. The original session's lock

6576

# priority increases with each consecutive abort, meaning that each

6577

# attempt has a slightly better chance of success than the previous.

6578

#

6579

# Under some circumstances (e.g., many transactions attempting to

6580

# modify the same row(s)), a transaction can abort many times in a

6581

# short period before successfully committing. Thus, it is not a good

6582

# idea to cap the number of retries a transaction can attempt;

6583

# instead, it is better to limit the total amount of wall time spent

6584

# retrying.

6585

#

6586

# ### Idle Transactions

6587

#

6588

# A transaction is considered idle if it has no outstanding reads or

6589

# SQL queries and has not started a read or SQL query within the last 10

6590

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

6591

# don't hold on to locks indefinitely. In that case, the commit will

6592

# fail with error `ABORTED`.

6593

#

6594

# If this behavior is undesirable, periodically executing a simple

6595

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

6596

# transaction from becoming idle.

6597

#

6598

# ## Snapshot Read-Only Transactions

6599

#

6600

# Snapshot read-only transactions provides a simpler method than

6601

# locking read-write transactions for doing several consistent

6602

# reads. However, this type of transaction does not support writes.

6603

#

6604

# Snapshot transactions do not take locks. Instead, they work by

6605

# choosing a Cloud Spanner timestamp, then executing all reads at that

6606

# timestamp. Since they do not acquire locks, they do not block

6607

# concurrent read-write transactions.

6608

#

6609

# Unlike locking read-write transactions, snapshot read-only

6610

# transactions never abort. They can fail if the chosen read

6611

# timestamp is garbage collected; however, the default garbage

6612

# collection policy is generous enough that most applications do not

6613

# need to worry about this in practice.

6614

#

6615

# Snapshot read-only transactions do not need to call

6616

# Commit or

6617

# Rollback (and in fact are not

6618

# permitted to do so).

6619

#

6620

# To execute a snapshot transaction, the client specifies a timestamp

6621

# bound, which tells Cloud Spanner how to choose a read timestamp.

6622

#

6623

# The types of timestamp bound are:

6624

#

6625

# - Strong (the default).

6626

# - Bounded staleness.

6627

# - Exact staleness.

6628

#

6629

# If the Cloud Spanner database to be read is geographically distributed,

6630

# stale read-only transactions can execute more quickly than strong

6631

# or read-write transaction, because they are able to execute far

6632

# from the leader replica.

6633

#

6634

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

6639

# that have committed before the start of the read. Furthermore, all

6640

# rows yielded by a single read are consistent with each other -- if

6641

# any part of the read observes a transaction, all parts of the read

6642

# see the transaction.

6643

#

6644

# Strong reads are not repeatable: two consecutive strong read-only

6645

# transactions might return inconsistent results if there are

6646

# concurrent writes. If consistency across reads is required, the

6647

# reads should be executed within a transaction or at an exact read

6648

# timestamp.

6649

#

6650

# See TransactionOptions.ReadOnly.strong.

6651

#

6652

# ### Exact Staleness

6653

#

6654

# These timestamp bounds execute reads at a user-specified

6655

# timestamp. Reads at a timestamp are guaranteed to see a consistent

6656

# prefix of the global transaction history: they observe

6657

# modifications done by all transactions with a commit timestamp <=

6658

# the read timestamp, and observe none of the modifications done by

6659

# transactions with a larger commit timestamp. They will block until

6660

# all conflicting transactions that may be assigned commit timestamps

6661

# <= the read timestamp have finished.

6662

#

6663

# The timestamp can either be expressed as an absolute Cloud Spanner commit

6664

# timestamp or a staleness relative to the current time.

6665

#

6666

# These modes do not require a "negotiation phase" to pick a

6667

# timestamp. As a result, they execute slightly faster than the

6668

# equivalent boundedly stale concurrency modes. On the other hand,

6669

# boundedly stale reads usually return fresher results.

6670

#

6671

# See TransactionOptions.ReadOnly.read_timestamp and

6672

# TransactionOptions.ReadOnly.exact_staleness.

6673

#

6674

# ### Bounded Staleness

6675

#

6676

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

6677

# subject to a user-provided staleness bound. Cloud Spanner chooses the

6678

# newest timestamp within the staleness bound that allows execution

6679

# of the reads at the closest available replica without blocking.

6680

#

6681

# All rows yielded are consistent with each other -- if any part of

6682

# the read observes a transaction, all parts of the read see the

6683

# transaction. Boundedly stale reads are not repeatable: two stale

6684

# reads, even if they use the same staleness bound, can execute at

6685

# different timestamps and thus return inconsistent results.

6686

#

6687

# Boundedly stale reads execute in two phases: the first phase

6688

# negotiates a timestamp among all replicas needed to serve the

6689

# read. In the second phase, reads are executed at the negotiated

6690

# timestamp.

6691

#

6692

# As a result of the two phase execution, bounded staleness reads are

6693

# usually a little slower than comparable exact staleness

6694

# reads. However, they are typically able to return fresher

6695

# results, and are more likely to execute at the closest replica.

6696

#

6697

# Because the timestamp negotiation requires up-front knowledge of

6698

# which rows will be read, it can only be used with single-use

6699

# read-only transactions.

6700

#

6701

# See TransactionOptions.ReadOnly.max_staleness and

6702

# TransactionOptions.ReadOnly.min_read_timestamp.

6703

#

6704

# ### Old Read Timestamps and Garbage Collection

6705

#

6706

# Cloud Spanner continuously garbage collects deleted and overwritten data

6707

# in the background to reclaim storage space. This process is known

6708

# as "version GC". By default, version GC reclaims versions after they

6709

# are one hour old. Because of this, Cloud Spanner cannot perform reads

6710

# at read timestamps more than one hour in the past. This

6711

# restriction also applies to in-progress reads and/or SQL queries whose

6712

# timestamp become too old while executing. Reads and SQL queries with

6713

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6714

#

6715

# ## Partitioned DML Transactions

6716

#

6717

# Partitioned DML transactions are used to execute DML statements with a

6718

# different execution strategy that provides different, and often better,

6719

# scalability properties for large, table-wide operations than DML in a

6720

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

6721

# should prefer using ReadWrite transactions.

6722

#

6723

# Partitioned DML partitions the keyspace and runs the DML statement on each

6724

# partition in separate, internal transactions. These transactions commit

6725

# automatically when complete, and run independently from one another.

6726

#

6727

# To reduce lock contention, this execution strategy only acquires read locks

6728

# on rows that match the WHERE clause of the statement. Additionally, the

6729

# smaller per-partition transactions hold locks for less time.

6730

#

6731

# That said, Partitioned DML is not a drop-in replacement for standard DML used

6732

# in ReadWrite transactions.

6733

#

6734

# - The DML statement must be fully-partitionable. Specifically, the statement

6735

# must be expressible as the union of many statements which each access only

6736

# a single row of the table.

6737

#

6738

# - The statement is not applied atomically to all rows of the table. Rather,

6739

# the statement is applied atomically to partitions of the table, in

6740

# independent transactions. Secondary index rows are updated atomically

6741

# with the base table rows.

6742

#

6743

# - Partitioned DML does not guarantee exactly-once execution semantics

6744

# against a partition. The statement will be applied at least once to each

6745

# partition. It is strongly recommended that the DML statement should be

6746

# idempotent to avoid unexpected results. For instance, it is potentially

6747

# dangerous to run a statement such as

6748

# `UPDATE table SET column = column + 1` as it could be run multiple times

6749

# against some rows.

6750

#

6751

# - The partitions are committed automatically - there is no support for

6752

# Commit or Rollback. If the call returns an error, or if the client issuing

6753

# the ExecuteSql call dies, it is possible that some rows had the statement

6754

# executed on them successfully. It is also possible that statement was

6755

# never executed against other rows.

6756

#

6757

# - Partitioned DML transactions may only contain the execution of a single

6758

# DML statement via ExecuteSql or ExecuteStreamingSql.

6759

#

6760

# - If any error is encountered during the execution of the partitioned DML

6761

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

6762

# value that cannot be stored due to schema constraints), then the

6763

# operation is stopped at that point and an error is returned. It is

6764

# possible that at this point, some partitions have been committed (or even

6765

# committed multiple times), and other partitions have not been run at all.

6766

#

6767

# Given the above, Partitioned DML is good fit for large, database-wide,

6768

# operations that are idempotent, such as deleting old rows from a very large

6769

# table.

6770

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6771

#

6772

# Authorization to begin a read-write transaction requires

6773

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

6774

# on the `session` resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6775

# transaction type has no options.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6776

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6777

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6778

#

6779

# Authorization to begin a read-only transaction requires

6780

# `spanner.databases.beginReadOnlyTransaction` permission

6781

# on the `session` resource.

6782

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

6783

#

6784

# This is useful for requesting fresher data than some previous

6785

# read, or data that is fresh enough to observe the effects of some

6786

# previously committed transaction whose timestamp is known.

6787

#

6788

# Note that this option can only be used in single-use transactions.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6789

#

6790

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

6791

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6792

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

6793

# the Transaction message that describes the transaction.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6794

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

6795

# seconds. Guarantees that all writes that have committed more

6796

# than the specified number of seconds ago are visible. Because

6797

# Cloud Spanner chooses the exact timestamp, this mode works even if

6798

# the client's local clock is substantially skewed from Cloud Spanner

6799

# commit timestamps.

6800

#

6801

# Useful for reading the freshest data available at a nearby

6802

# replica, while bounding the possible staleness if the local

6803

# replica has fallen behind.

6804

#

6805

# Note that this option can only be used in single-use

6806

# transactions.

6807

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

6808

# old. The timestamp is chosen soon after the read is started.

6809

#

6810

# Guarantees that all writes that have committed more than the

6811

# specified number of seconds ago are visible. Because Cloud Spanner

6812

# chooses the exact timestamp, this mode works even if the client's

6813

# local clock is substantially skewed from Cloud Spanner commit

6814

# timestamps.

6815

#

6816

# Useful for reading at nearby replicas without the distributed

6817

# timestamp negotiation overhead of `max_staleness`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

6818

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

6819

# reads at a specific timestamp are repeatable; the same read at

6820

# the same timestamp always returns the same data. If the

6821

# timestamp is in the future, the read will block until the

6822

# specified timestamp, modulo the read's deadline.

6823

#

6824

# Useful for large scale consistent reads such as mapreduces, or

6825

# for coordinating many reads against a consistent snapshot of the

6826

# data.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6827

#

6828

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

6829

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6830

"strong": True or False, # Read at a timestamp where all previously committed transactions

6831

# are visible.

6832

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6833

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

6834

#

6835

# Authorization to begin a Partitioned DML transaction requires

6836

# `spanner.databases.beginPartitionedDmlTransaction` permission

6837

# on the `session` resource.

6838

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6839

},

6840

"id": "A String", # Execute the read or SQL query in a previously-started transaction.

6841

},

6842

"resumeToken": "A String", # If this request is resuming a previously interrupted read,

6843

# `resume_token` should be copied from the last

6844

# PartialResultSet yielded before the interruption. Doing this

6845

# enables the new read to resume where the last read left off. The

6846

# rest of the request parameters must exactly match the request

6847

# that yielded this token.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6848

"partitionToken": "A String", # If present, results will be restricted to the specified partition

6849

# previously created using PartitionRead(). There must be an exact

6850

# match for the values of fields common to this message and the

6851

# PartitionReadRequest message used to create this partition_token.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6852

"keySet": { # `KeySet` defines a collection of Cloud Spanner keys and/or key ranges. All # Required. `key_set` identifies the rows to be yielded. `key_set` names the

6853

# primary keys of the rows in table to be yielded, unless index

6854

# is present. If index is present, then key_set instead names

6855

# index keys in index.

6856

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6857

# If the partition_token field is empty, rows are yielded

6858

# in table primary key order (if index is empty) or index key order

6859

# (if index is non-empty). If the partition_token field is not

6860

# empty, rows will be yielded in an unspecified order.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6861

#

6862

# It is not an error for the `key_set` to name rows that do not

6863

# exist in the database. Read yields nothing for nonexistent rows.

6864

# the keys are expected to be in the same table or index. The keys need

6865

# not be sorted in any particular way.

6866

#

6867

# If the same key is specified multiple times in the set (for example

6868

# if two ranges, two keys, or a key and a range overlap), Cloud Spanner

6869

# behaves as if the key were only specified once.

6870

"ranges": [ # A list of key ranges. See KeyRange for more information about

6871

# key range specifications.

6872

{ # KeyRange represents a range of rows in a table or index.

6873

#

6874

# A range has a start key and an end key. These keys can be open or

6875

# closed, indicating if the range includes rows with that key.

6876

#

6877

# Keys are represented by lists, where the ith value in the list

6878

# corresponds to the ith component of the table or index primary key.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6879

# Individual values are encoded as described

6880

# here.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6881

#

6882

# For example, consider the following table definition:

6883

#

6884

# CREATE TABLE UserEvents (

6885

# UserName STRING(MAX),

6886

# EventDate STRING(10)

6887

# ) PRIMARY KEY(UserName, EventDate);

6888

#

6889

# The following keys name rows in this table:

6890

#

6891

# "Bob", "2014-09-23"

6892

#

6893

# Since the `UserEvents` table's `PRIMARY KEY` clause names two

6894

# columns, each `UserEvents` key has two elements; the first is the

6895

# `UserName`, and the second is the `EventDate`.

6896

#

6897

# Key ranges with multiple components are interpreted

6898

# lexicographically by component using the table or index key's declared

6899

# sort order. For example, the following range returns all events for

6900

# user `"Bob"` that occurred in the year 2015:

6901

#

6902

# "start_closed": ["Bob", "2015-01-01"]

6903

# "end_closed": ["Bob", "2015-12-31"]

6904

#

6905

# Start and end keys can omit trailing key components. This affects the

6906

# inclusion and exclusion of rows that exactly match the provided key

6907

# components: if the key is closed, then rows that exactly match the

6908

# provided components are included; if the key is open, then rows

6909

# that exactly match are not included.

6910

#

6911

# For example, the following range includes all events for `"Bob"` that

6912

# occurred during and after the year 2000:

6913

#

6914

# "start_closed": ["Bob", "2000-01-01"]

6915

# "end_closed": ["Bob"]

6916

#

6917

# The next example retrieves all events for `"Bob"`:

6918

#

6919

# "start_closed": ["Bob"]

6920

# "end_closed": ["Bob"]

6921

#

6922

# To retrieve events before the year 2000:

6923

#

6924

# "start_closed": ["Bob"]

6925

# "end_open": ["Bob", "2000-01-01"]

6926

#

6927

# The following range includes all rows in the table:

#

# "start_closed": []

# "end_closed": []

#

# This range returns all users whose `UserName` begins with any

6933

# character from A to C:

6934

#

6935

# "start_closed": ["A"]

6936

# "end_open": ["D"]

6937

#

6938

# This range returns all users whose `UserName` begins with B:

6939

#

6940

# "start_closed": ["B"]

6941

# "end_open": ["C"]

6942

#

6943

# Key ranges honor column sort order. For example, suppose a table is

6944

# defined as follows:

6945

#

6946

# CREATE TABLE DescendingSortedTable {

6947

# Key INT64,

6948

# ...

6949

# ) PRIMARY KEY(Key DESC);

6950

#

6951

# The following range retrieves all rows with key values between 1

6952

# and 100 inclusive:

6953

#

6954

# "start_closed": ["100"]

6955

# "end_closed": ["1"]

6956

#

6957

# Note that 100 is passed as the start, and 1 is passed as the end,

6958

# because `Key` is a descending column in the schema.

6959

"endOpen": [ # If the end is open, then the range excludes rows whose first

6960

# `len(end_open)` key columns exactly match `end_open`.

6961

"",

6962

],

6963

"startOpen": [ # If the start is open, then the range excludes rows whose first

6964

# `len(start_open)` key columns exactly match `start_open`.

6965

"",

6966

],

6967

"endClosed": [ # If the end is closed, then the range includes all rows whose

6968

# first `len(end_closed)` key columns exactly match `end_closed`.

6969

"",

6970

],

6971

"startClosed": [ # If the start is closed, then the range includes all rows whose

6972

# first `len(start_closed)` key columns exactly match `start_closed`.

"",

],

},

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

6977

"keys": [ # A list of specific keys. Entries in `keys` should have exactly as

6978

# many elements as there are columns in the primary or index key

6979

# with which this `KeySet` is used. Individual key values are

6980

# encoded as described here.

[

"",

],

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6985

"all": True or False, # For convenience `all` can be set to `true` to indicate that this

6986

# `KeySet` matches all keys in the table or index. Note that any keys

6987

# specified in `keys` or `ranges` are only yielded once.

6988

},

6989

"limit": "A String", # If greater than zero, only the first `limit` rows are yielded. If `limit`

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

6990

# is zero, the default is no limit. A limit cannot be specified if

6991

# `partition_token` is set.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

6992

"table": "A String", # Required. The name of the table in the database to be read.

6993

"columns": [ # The columns of table to be returned for each row matching

# this request.

"A String",

],

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

7006

7007

{ # Results from Read or

7008

# ExecuteSql.

7009

"rows": [ # Each element in `rows` is a row whose format is defined by

7010

# metadata.row_type. The ith element

7011

# in each row matches the ith field in

7012

# metadata.row_type. Elements are

7013

# encoded based on type as described

# here.

[

"",

],

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7019

"stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the SQL statement that

7020

# produced this result set. These can be requested by setting

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7021

# ExecuteSqlRequest.query_mode.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7022

# DML statements always produce stats containing the number of rows

7023

# modified, unless executed using the

7024

# ExecuteSqlRequest.QueryMode.PLAN ExecuteSqlRequest.query_mode.

7025

# Other fields may or may not be populated, based on the

7026

# ExecuteSqlRequest.query_mode.

7027

"rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it

7028

# returns a lower bound of the rows modified.

7029

"rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7030

"queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.

7031

"planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting

7032

# with the plan root. Each PlanNode's `id` corresponds to its index in

7033

# `plan_nodes`.

7034

{ # Node information for nodes appearing in a QueryPlan.plan_nodes.

7035

"index": 42, # The `PlanNode`'s index in node list.

7036

"kind": "A String", # Used to determine the type of node. May be needed for visualizing

7037

# different kinds of nodes differently. For example, If the node is a

7038

# SCALAR node, it will have a condensed representation

7039

# which can be used to directly embed a description of the node in its

7040

# parent.

7041

"displayName": "A String", # The display name for the node.

7042

"executionStats": { # The execution statistics associated with the node, contained in a group of

7043

# key-value pairs. Only present if the plan was returned as a result of a

7044

# profile query. For example, number of executions, number of rows/time per

7045

# execution etc.

7046

"a_key": "", # Properties of the object.

7047

},

7048

"childLinks": [ # List of child node `index`es and their relationship to this parent.

7049

{ # Metadata associated with a parent-child relationship appearing in a

7050

# PlanNode.

7051

"variable": "A String", # Only present if the child node is SCALAR and corresponds

7052

# to an output variable of the parent node. The field carries the name of

7053

# the output variable.

7054

# For example, a `TableScan` operator that reads rows from a table will

7055

# have child links to the `SCALAR` nodes representing the output variables

7056

# created for each column that is read by the operator. The corresponding

7057

# `variable` fields will be set to the variable names assigned to the

7058

# columns.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

7059

"childIndex": 42, # The node to which the link points.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7060

"type": "A String", # The type of the link. For example, in Hash Joins this could be used to

7061

# distinguish between the build child and the probe child, or in the case

7062

# of the child being an output variable, to represent the tag associated

7063

# with the output variable.

7064

},

7065

],

7066

"shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.

7067

# `SCALAR` PlanNode(s).

7068

"subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases

7069

# where the `description` string of this node references a `SCALAR`

7070

# subquery contained in the expression subtree rooted at this node. The

7071

# referenced `SCALAR` subquery may not necessarily be a direct child of

# this node.

"a_key": 42,

},

"description": "A String", # A string representation of the expression subtree rooted at this node.

7076

},

7077

"metadata": { # Attributes relevant to the node contained in a group of key-value pairs.

7078

# For example, a Parameter Reference node could have the following

7079

# information in its metadata:

7080

#

7081

# {

7082

# "parameter_reference": "param1",

7083

# "parameter_type": "array"

7084

# }

7085

"a_key": "", # Properties of the object.

},

},

],

},

"queryStats": { # Aggregated statistics from the execution of the query. Only present when

7091

# the query is profiled. For example, a query could return the statistics as

# follows:

#

# {

# "rows_returned": "3",

7096

# "elapsed_time": "1.22 secs",

7097

# "cpu_time": "1.19 secs"

7098

# }

7099

"a_key": "", # Properties of the object.

7100

},

7101

},

7102

"metadata": { # Metadata about a ResultSet or PartialResultSet. # Metadata about the result set, such as row type information.

7103

"rowType": { # `StructType` defines the fields of a STRUCT type. # Indicates the field names and types for the rows in the result

7104

# set. For example, a SQL query like `"SELECT UserId, UserName FROM

7105

# Users"` could return a `row_type` value like:

7106

#

7107

# "fields": [

7108

# { "name": "UserId", "type": { "code": "INT64" } },

7109

# { "name": "UserName", "type": { "code": "STRING" } },

7110

# ]

7111

"fields": [ # The list of fields that make up this struct. Order is

7112

# significant, because values of this struct type are represented as

7113

# lists, where the order of field values matches the order of

7114

# fields in the StructType. In turn, the order of fields

7115

# matches the order of columns in a read request, or the order of

7116

# fields in the `SELECT` clause of a query.

7117

{ # Message representing a single field of a struct.

7118

"type": { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a # The type of the field.

7119

# table cell or returned from an SQL query.

7120

"structType": # Object with schema name: StructType # If code == STRUCT, then `struct_type`

7121

# provides type information for the struct's fields.

7122

"code": "A String", # Required. The TypeCode for this type.

7123

"arrayElementType": # Object with schema name: Type # If code == ARRAY, then `array_element_type`

7124

# is the type of the array elements.

7125

},

7126

"name": "A String", # The name of the field. For reads, this is the column name. For

7127

# SQL queries, it is the column alias (e.g., `"Word"` in the

7128

# query `"SELECT 'hello' AS Word"`), or the column name (e.g.,

7129

# `"ColName"` in the query `"SELECT ColName FROM Table"`). Some

7130

# columns might have an empty name (e.g., !"SELECT

7131

# UPPER(ColName)"`). Note that a query result can contain

7132

# multiple fields with the same name.

},

],

},

"transaction": { # A transaction. # If the read or SQL query began a transaction as a side-effect, the

7137

# information about the new transaction is yielded here.

7138

"readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen

7139

# for the transaction. Not returned by default: see

7140

# TransactionOptions.ReadOnly.return_read_timestamp.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7141

#

7142

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

7143

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7144

"id": "A String", # `id` may be used to identify the transaction in subsequent

# Read,

# ExecuteSql,

# Commit, or

# Rollback calls.

#

# Single-use read-only transactions do not have IDs, because

7151

# single-use transactions do not support multiple requests.

},

},

}</pre>

</div>

<code class="details" id="rollback">rollback(session, body, x__xgafv=None)</code>

7159

<pre>Rolls back a transaction, releasing any locks it holds. It is a good

7160

idea to call this for any transaction that includes one or more

7161

Read or ExecuteSql requests and

7162

ultimately decides not to commit.

7163

7164

`Rollback` returns `OK` if it successfully aborts the transaction, the

7165

transaction was already aborted, or the transaction is not

7166

found. `Rollback` never returns `ABORTED`.

7167

7168

Args:

7169

session: string, Required. The session in which the transaction to roll back is running. (required)

7170

body: object, The request body. (required)

7171

The object takes the form of:

7172

7173

{ # The request for Rollback.

7174

"transactionId": "A String", # Required. The transaction to roll back.

7175

}

7176

7177

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

7184

7185

{ # A generic empty message that you can re-use to avoid defining duplicated

7186

# empty messages in your APIs. A typical example is to use it as the request

7187

# or the response type of an API method. For instance:

7188

#

7189

# service Foo {

7190

# rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);

7191

# }

7192

#

7193

# The JSON representation for `Empty` is empty JSON object `{}`.

}</pre>

</div>

<code class="details" id="streamingRead">streamingRead(session, body, x__xgafv=None)</code>

7199

<pre>Like Read, except returns the result set as a

7200

stream. Unlike Read, there is no limit on the

7201

size of the returned result set. However, no individual row in

7202

the result set can exceed 100 MiB, and no column value can exceed

10 MiB.

Args:

session: string, Required. The session in which the read should be performed. (required)

7207

body: object, The request body. (required)

7208

The object takes the form of:

7209

7210

{ # The request for Read and

7211

# StreamingRead.

7212

"index": "A String", # If non-empty, the name of an index on table. This index is

7213

# used instead of the table primary key when interpreting key_set

7214

# and sorting result rows. See key_set for further information.

7215

"transaction": { # This message is used to select the transaction in which a # The transaction to use. If none is provided, the default is a

7216

# temporary read-only transaction with strong concurrency.

7217

# Read or

7218

# ExecuteSql call runs.

7219

#

7220

# See TransactionOptions for more information about transactions.

7221

"begin": { # # Transactions # Begin a new transaction and execute this read or SQL query in

7222

# it. The transaction ID of the new transaction is returned in

7223

# ResultSetMetadata.transaction, which is a Transaction.

7224

#

7225

#

7226

# Each session can have at most one active transaction at a time. After the

7227

# active transaction is completed, the session can immediately be

7228

# re-used for the next transaction. It is not necessary to create a

7229

# new session for each transaction.

7230

#

7231

# # Transaction Modes

7232

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7233

# Cloud Spanner supports three transaction modes:

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7234

#

7235

# 1. Locking read-write. This type of transaction is the only way

7236

# to write data into Cloud Spanner. These transactions rely on

7237

# pessimistic locking and, if necessary, two-phase commit.

7238

# Locking read-write transactions may abort, requiring the

7239

# application to retry.

7240

#

7241

# 2. Snapshot read-only. This transaction type provides guaranteed

7242

# consistency across several reads, but does not allow

7243

# writes. Snapshot read-only transactions can be configured to

7244

# read at timestamps in the past. Snapshot read-only

7245

# transactions do not need to be committed.

7246

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7247

# 3. Partitioned DML. This type of transaction is used to execute

7248

# a single Partitioned DML statement. Partitioned DML partitions

7249

# the key space and runs the DML statement over each partition

7250

# in parallel using separate, internal transactions that commit

7251

# independently. Partitioned DML transactions do not need to be

7252

# committed.

7253

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7254

# For transactions that only read, snapshot read-only transactions

7255

# provide simpler semantics and are almost always faster. In

7256

# particular, read-only transactions do not take locks, so they do

7257

# not conflict with read-write transactions. As a consequence of not

7258

# taking locks, they also do not abort, so retry loops are not needed.

7259

#

7260

# Transactions may only read/write data in a single database. They

7261

# may, however, read/write data in different tables within that

7262

# database.

7263

#

7264

# ## Locking Read-Write Transactions

7265

#

7266

# Locking transactions may be used to atomically read-modify-write

7267

# data anywhere in a database. This type of transaction is externally

7268

# consistent.

7269

#

7270

# Clients should attempt to minimize the amount of time a transaction

7271

# is active. Faster transactions commit with higher probability

7272

# and cause less contention. Cloud Spanner attempts to keep read locks

7273

# active as long as the transaction continues to do reads, and the

7274

# transaction has not been terminated by

7275

# Commit or

7276

# Rollback. Long periods of

7277

# inactivity at the client may cause Cloud Spanner to release a

7278

# transaction's locks and abort it.

7279

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7280

# Conceptually, a read-write transaction consists of zero or more

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7281

# reads or SQL statements followed by

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7282

# Commit. At any time before

7283

# Commit, the client can send a

7284

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

7290

# are still valid at commit time, and it is able to acquire write

7291

# locks for all writes. Cloud Spanner can abort the transaction for any

7292

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

7293

# that the transaction has not modified any user data in Cloud Spanner.

7294

#

7295

# Unless the transaction commits, Cloud Spanner makes no guarantees about

7296

# how long the transaction's locks were held for. It is an error to

7297

# use Cloud Spanner locks for any sort of mutual exclusion other than

7298

# between Cloud Spanner transactions themselves.

7299

#

7300

# ### Retrying Aborted Transactions

7301

#

7302

# When a transaction aborts, the application can choose to retry the

7303

# whole transaction again. To maximize the chances of successfully

7304

# committing the retry, the client should execute the retry in the

7305

# same session as the original attempt. The original session's lock

7306

# priority increases with each consecutive abort, meaning that each

7307

# attempt has a slightly better chance of success than the previous.

7308

#

7309

# Under some circumstances (e.g., many transactions attempting to

7310

# modify the same row(s)), a transaction can abort many times in a

7311

# short period before successfully committing. Thus, it is not a good

7312

# idea to cap the number of retries a transaction can attempt;

7313

# instead, it is better to limit the total amount of wall time spent

7314

# retrying.

7315

#

7316

# ### Idle Transactions

7317

#

7318

# A transaction is considered idle if it has no outstanding reads or

7319

# SQL queries and has not started a read or SQL query within the last 10

7320

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

7321

# don't hold on to locks indefinitely. In that case, the commit will

7322

# fail with error `ABORTED`.

7323

#

7324

# If this behavior is undesirable, periodically executing a simple

7325

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

7326

# transaction from becoming idle.

7327

#

7328

# ## Snapshot Read-Only Transactions

7329

#

7330

# Snapshot read-only transactions provides a simpler method than

7331

# locking read-write transactions for doing several consistent

7332

# reads. However, this type of transaction does not support writes.

7333

#

7334

# Snapshot transactions do not take locks. Instead, they work by

7335

# choosing a Cloud Spanner timestamp, then executing all reads at that

7336

# timestamp. Since they do not acquire locks, they do not block

7337

# concurrent read-write transactions.

7338

#

7339

# Unlike locking read-write transactions, snapshot read-only

7340

# transactions never abort. They can fail if the chosen read

7341

# timestamp is garbage collected; however, the default garbage

7342

# collection policy is generous enough that most applications do not

7343

# need to worry about this in practice.

7344

#

7345

# Snapshot read-only transactions do not need to call

7346

# Commit or

7347

# Rollback (and in fact are not

7348

# permitted to do so).

7349

#

7350

# To execute a snapshot transaction, the client specifies a timestamp

7351

# bound, which tells Cloud Spanner how to choose a read timestamp.

7352

#

7353

# The types of timestamp bound are:

7354

#

7355

# - Strong (the default).

7356

# - Bounded staleness.

7357

# - Exact staleness.

7358

#

7359

# If the Cloud Spanner database to be read is geographically distributed,

7360

# stale read-only transactions can execute more quickly than strong

7361

# or read-write transaction, because they are able to execute far

7362

# from the leader replica.

7363

#

7364

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

7369

# that have committed before the start of the read. Furthermore, all

7370

# rows yielded by a single read are consistent with each other -- if

7371

# any part of the read observes a transaction, all parts of the read

7372

# see the transaction.

7373

#

7374

# Strong reads are not repeatable: two consecutive strong read-only

7375

# transactions might return inconsistent results if there are

7376

# concurrent writes. If consistency across reads is required, the

7377

# reads should be executed within a transaction or at an exact read

7378

# timestamp.

7379

#

7380

# See TransactionOptions.ReadOnly.strong.

7381

#

7382

# ### Exact Staleness

7383

#

7384

# These timestamp bounds execute reads at a user-specified

7385

# timestamp. Reads at a timestamp are guaranteed to see a consistent

7386

# prefix of the global transaction history: they observe

7387

# modifications done by all transactions with a commit timestamp <=

7388

# the read timestamp, and observe none of the modifications done by

7389

# transactions with a larger commit timestamp. They will block until

7390

# all conflicting transactions that may be assigned commit timestamps

7391

# <= the read timestamp have finished.

7392

#

7393

# The timestamp can either be expressed as an absolute Cloud Spanner commit

7394

# timestamp or a staleness relative to the current time.

7395

#

7396

# These modes do not require a "negotiation phase" to pick a

7397

# timestamp. As a result, they execute slightly faster than the

7398

# equivalent boundedly stale concurrency modes. On the other hand,

7399

# boundedly stale reads usually return fresher results.

7400

#

7401

# See TransactionOptions.ReadOnly.read_timestamp and

7402

# TransactionOptions.ReadOnly.exact_staleness.

7403

#

7404

# ### Bounded Staleness

7405

#

7406

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

7407

# subject to a user-provided staleness bound. Cloud Spanner chooses the

7408

# newest timestamp within the staleness bound that allows execution

7409

# of the reads at the closest available replica without blocking.

7410

#

7411

# All rows yielded are consistent with each other -- if any part of

7412

# the read observes a transaction, all parts of the read see the

7413

# transaction. Boundedly stale reads are not repeatable: two stale

7414

# reads, even if they use the same staleness bound, can execute at

7415

# different timestamps and thus return inconsistent results.

7416

#

7417

# Boundedly stale reads execute in two phases: the first phase

7418

# negotiates a timestamp among all replicas needed to serve the

7419

# read. In the second phase, reads are executed at the negotiated

7420

# timestamp.

7421

#

7422

# As a result of the two phase execution, bounded staleness reads are

7423

# usually a little slower than comparable exact staleness

7424

# reads. However, they are typically able to return fresher

7425

# results, and are more likely to execute at the closest replica.

7426

#

7427

# Because the timestamp negotiation requires up-front knowledge of

7428

# which rows will be read, it can only be used with single-use

7429

# read-only transactions.

7430

#

7431

# See TransactionOptions.ReadOnly.max_staleness and

7432

# TransactionOptions.ReadOnly.min_read_timestamp.

7433

#

7434

# ### Old Read Timestamps and Garbage Collection

7435

#

7436

# Cloud Spanner continuously garbage collects deleted and overwritten data

7437

# in the background to reclaim storage space. This process is known

7438

# as "version GC". By default, version GC reclaims versions after they

7439

# are one hour old. Because of this, Cloud Spanner cannot perform reads

7440

# at read timestamps more than one hour in the past. This

7441

# restriction also applies to in-progress reads and/or SQL queries whose

7442

# timestamp become too old while executing. Reads and SQL queries with

7443

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7444

#

7445

# ## Partitioned DML Transactions

7446

#

7447

# Partitioned DML transactions are used to execute DML statements with a

7448

# different execution strategy that provides different, and often better,

7449

# scalability properties for large, table-wide operations than DML in a

7450

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

7451

# should prefer using ReadWrite transactions.

7452

#

7453

# Partitioned DML partitions the keyspace and runs the DML statement on each

7454

# partition in separate, internal transactions. These transactions commit

7455

# automatically when complete, and run independently from one another.

7456

#

7457

# To reduce lock contention, this execution strategy only acquires read locks

7458

# on rows that match the WHERE clause of the statement. Additionally, the

7459

# smaller per-partition transactions hold locks for less time.

7460

#

7461

# That said, Partitioned DML is not a drop-in replacement for standard DML used

7462

# in ReadWrite transactions.

7463

#

7464

# - The DML statement must be fully-partitionable. Specifically, the statement

7465

# must be expressible as the union of many statements which each access only

7466

# a single row of the table.

7467

#

7468

# - The statement is not applied atomically to all rows of the table. Rather,

7469

# the statement is applied atomically to partitions of the table, in

7470

# independent transactions. Secondary index rows are updated atomically

7471

# with the base table rows.

7472

#

7473

# - Partitioned DML does not guarantee exactly-once execution semantics

7474

# against a partition. The statement will be applied at least once to each

7475

# partition. It is strongly recommended that the DML statement should be

7476

# idempotent to avoid unexpected results. For instance, it is potentially

7477

# dangerous to run a statement such as

7478

# `UPDATE table SET column = column + 1` as it could be run multiple times

7479

# against some rows.

7480

#

7481

# - The partitions are committed automatically - there is no support for

7482

# Commit or Rollback. If the call returns an error, or if the client issuing

7483

# the ExecuteSql call dies, it is possible that some rows had the statement

7484

# executed on them successfully. It is also possible that statement was

7485

# never executed against other rows.

7486

#

7487

# - Partitioned DML transactions may only contain the execution of a single

7488

# DML statement via ExecuteSql or ExecuteStreamingSql.

7489

#

7490

# - If any error is encountered during the execution of the partitioned DML

7491

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

7492

# value that cannot be stored due to schema constraints), then the

7493

# operation is stopped at that point and an error is returned. It is

7494

# possible that at this point, some partitions have been committed (or even

7495

# committed multiple times), and other partitions have not been run at all.

7496

#

7497

# Given the above, Partitioned DML is good fit for large, database-wide,

7498

# operations that are idempotent, such as deleting old rows from a very large

7499

# table.

7500

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7501

#

7502

# Authorization to begin a read-write transaction requires

7503

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

7504

# on the `session` resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7505

# transaction type has no options.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7506

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7507

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7508

#

7509

# Authorization to begin a read-only transaction requires

7510

# `spanner.databases.beginReadOnlyTransaction` permission

7511

# on the `session` resource.

7512

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

7513

#

7514

# This is useful for requesting fresher data than some previous

7515

# read, or data that is fresh enough to observe the effects of some

7516

# previously committed transaction whose timestamp is known.

7517

#

7518

# Note that this option can only be used in single-use transactions.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7519

#

7520

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

7521

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

7522

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

7523

# the Transaction message that describes the transaction.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7524

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

7525

# seconds. Guarantees that all writes that have committed more

7526

# than the specified number of seconds ago are visible. Because

7527

# Cloud Spanner chooses the exact timestamp, this mode works even if

7528

# the client's local clock is substantially skewed from Cloud Spanner

7529

# commit timestamps.

7530

#

7531

# Useful for reading the freshest data available at a nearby

7532

# replica, while bounding the possible staleness if the local

7533

# replica has fallen behind.

7534

#

7535

# Note that this option can only be used in single-use

7536

# transactions.

7537

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

7538

# old. The timestamp is chosen soon after the read is started.

7539

#

7540

# Guarantees that all writes that have committed more than the

7541

# specified number of seconds ago are visible. Because Cloud Spanner

7542

# chooses the exact timestamp, this mode works even if the client's

7543

# local clock is substantially skewed from Cloud Spanner commit

7544

# timestamps.

7545

#

7546

# Useful for reading at nearby replicas without the distributed

7547

# timestamp negotiation overhead of `max_staleness`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

7548

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

7549

# reads at a specific timestamp are repeatable; the same read at

7550

# the same timestamp always returns the same data. If the

7551

# timestamp is in the future, the read will block until the

7552

# specified timestamp, modulo the read's deadline.

7553

#

7554

# Useful for large scale consistent reads such as mapreduces, or

7555

# for coordinating many reads against a consistent snapshot of the

7556

# data.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7557

#

7558

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

7559

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7560

"strong": True or False, # Read at a timestamp where all previously committed transactions

7561

# are visible.

7562

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7563

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

7564

#

7565

# Authorization to begin a Partitioned DML transaction requires

7566

# `spanner.databases.beginPartitionedDmlTransaction` permission

7567

# on the `session` resource.

7568

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7569

},

7570

"singleUse": { # # Transactions # Execute the read or SQL query in a temporary transaction.

7571

# This is the most efficient way to execute a transaction that

7572

# consists of a single SQL query.

7573

#

7574

#

7575

# Each session can have at most one active transaction at a time. After the

7576

# active transaction is completed, the session can immediately be

7577

# re-used for the next transaction. It is not necessary to create a

7578

# new session for each transaction.

7579

#

7580

# # Transaction Modes

7581

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7582

# Cloud Spanner supports three transaction modes:

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7583

#

7584

# 1. Locking read-write. This type of transaction is the only way

7585

# to write data into Cloud Spanner. These transactions rely on

7586

# pessimistic locking and, if necessary, two-phase commit.

7587

# Locking read-write transactions may abort, requiring the

7588

# application to retry.

7589

#

7590

# 2. Snapshot read-only. This transaction type provides guaranteed

7591

# consistency across several reads, but does not allow

7592

# writes. Snapshot read-only transactions can be configured to

7593

# read at timestamps in the past. Snapshot read-only

7594

# transactions do not need to be committed.

7595

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7596

# 3. Partitioned DML. This type of transaction is used to execute

7597

# a single Partitioned DML statement. Partitioned DML partitions

7598

# the key space and runs the DML statement over each partition

7599

# in parallel using separate, internal transactions that commit

7600

# independently. Partitioned DML transactions do not need to be

7601

# committed.

7602

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7603

# For transactions that only read, snapshot read-only transactions

7604

# provide simpler semantics and are almost always faster. In

7605

# particular, read-only transactions do not take locks, so they do

7606

# not conflict with read-write transactions. As a consequence of not

7607

# taking locks, they also do not abort, so retry loops are not needed.

7608

#

7609

# Transactions may only read/write data in a single database. They

7610

# may, however, read/write data in different tables within that

7611

# database.

7612

#

7613

# ## Locking Read-Write Transactions

7614

#

7615

# Locking transactions may be used to atomically read-modify-write

7616

# data anywhere in a database. This type of transaction is externally

7617

# consistent.

7618

#

7619

# Clients should attempt to minimize the amount of time a transaction

7620

# is active. Faster transactions commit with higher probability

7621

# and cause less contention. Cloud Spanner attempts to keep read locks

7622

# active as long as the transaction continues to do reads, and the

7623

# transaction has not been terminated by

7624

# Commit or

7625

# Rollback. Long periods of

7626

# inactivity at the client may cause Cloud Spanner to release a

7627

# transaction's locks and abort it.

7628

#

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7629

# Conceptually, a read-write transaction consists of zero or more

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7630

# reads or SQL statements followed by

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7631

# Commit. At any time before

7632

# Commit, the client can send a

7633

# Rollback request to abort the

# transaction.

#

# ### Semantics

#

# Cloud Spanner can commit the transaction if all read locks it acquired

7639

# are still valid at commit time, and it is able to acquire write

7640

# locks for all writes. Cloud Spanner can abort the transaction for any

7641

# reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees

7642

# that the transaction has not modified any user data in Cloud Spanner.

7643

#

7644

# Unless the transaction commits, Cloud Spanner makes no guarantees about

7645

# how long the transaction's locks were held for. It is an error to

7646

# use Cloud Spanner locks for any sort of mutual exclusion other than

7647

# between Cloud Spanner transactions themselves.

7648

#

7649

# ### Retrying Aborted Transactions

7650

#

7651

# When a transaction aborts, the application can choose to retry the

7652

# whole transaction again. To maximize the chances of successfully

7653

# committing the retry, the client should execute the retry in the

7654

# same session as the original attempt. The original session's lock

7655

# priority increases with each consecutive abort, meaning that each

7656

# attempt has a slightly better chance of success than the previous.

7657

#

7658

# Under some circumstances (e.g., many transactions attempting to

7659

# modify the same row(s)), a transaction can abort many times in a

7660

# short period before successfully committing. Thus, it is not a good

7661

# idea to cap the number of retries a transaction can attempt;

7662

# instead, it is better to limit the total amount of wall time spent

7663

# retrying.

7664

#

7665

# ### Idle Transactions

7666

#

7667

# A transaction is considered idle if it has no outstanding reads or

7668

# SQL queries and has not started a read or SQL query within the last 10

7669

# seconds. Idle transactions can be aborted by Cloud Spanner so that they

7670

# don't hold on to locks indefinitely. In that case, the commit will

7671

# fail with error `ABORTED`.

7672

#

7673

# If this behavior is undesirable, periodically executing a simple

7674

# SQL query in the transaction (e.g., `SELECT 1`) prevents the

7675

# transaction from becoming idle.

7676

#

7677

# ## Snapshot Read-Only Transactions

7678

#

7679

# Snapshot read-only transactions provides a simpler method than

7680

# locking read-write transactions for doing several consistent

7681

# reads. However, this type of transaction does not support writes.

7682

#

7683

# Snapshot transactions do not take locks. Instead, they work by

7684

# choosing a Cloud Spanner timestamp, then executing all reads at that

7685

# timestamp. Since they do not acquire locks, they do not block

7686

# concurrent read-write transactions.

7687

#

7688

# Unlike locking read-write transactions, snapshot read-only

7689

# transactions never abort. They can fail if the chosen read

7690

# timestamp is garbage collected; however, the default garbage

7691

# collection policy is generous enough that most applications do not

7692

# need to worry about this in practice.

7693

#

7694

# Snapshot read-only transactions do not need to call

7695

# Commit or

7696

# Rollback (and in fact are not

7697

# permitted to do so).

7698

#

7699

# To execute a snapshot transaction, the client specifies a timestamp

7700

# bound, which tells Cloud Spanner how to choose a read timestamp.

7701

#

7702

# The types of timestamp bound are:

7703

#

7704

# - Strong (the default).

7705

# - Bounded staleness.

7706

# - Exact staleness.

7707

#

7708

# If the Cloud Spanner database to be read is geographically distributed,

7709

# stale read-only transactions can execute more quickly than strong

7710

# or read-write transaction, because they are able to execute far

7711

# from the leader replica.

7712

#

7713

# Each type of timestamp bound is discussed in detail below.

#

# ### Strong

#

# Strong reads are guaranteed to see the effects of all transactions

7718

# that have committed before the start of the read. Furthermore, all

7719

# rows yielded by a single read are consistent with each other -- if

7720

# any part of the read observes a transaction, all parts of the read

7721

# see the transaction.

7722

#

7723

# Strong reads are not repeatable: two consecutive strong read-only

7724

# transactions might return inconsistent results if there are

7725

# concurrent writes. If consistency across reads is required, the

7726

# reads should be executed within a transaction or at an exact read

7727

# timestamp.

7728

#

7729

# See TransactionOptions.ReadOnly.strong.

7730

#

7731

# ### Exact Staleness

7732

#

7733

# These timestamp bounds execute reads at a user-specified

7734

# timestamp. Reads at a timestamp are guaranteed to see a consistent

7735

# prefix of the global transaction history: they observe

7736

# modifications done by all transactions with a commit timestamp <=

7737

# the read timestamp, and observe none of the modifications done by

7738

# transactions with a larger commit timestamp. They will block until

7739

# all conflicting transactions that may be assigned commit timestamps

7740

# <= the read timestamp have finished.

7741

#

7742

# The timestamp can either be expressed as an absolute Cloud Spanner commit

7743

# timestamp or a staleness relative to the current time.

7744

#

7745

# These modes do not require a "negotiation phase" to pick a

7746

# timestamp. As a result, they execute slightly faster than the

7747

# equivalent boundedly stale concurrency modes. On the other hand,

7748

# boundedly stale reads usually return fresher results.

7749

#

7750

# See TransactionOptions.ReadOnly.read_timestamp and

7751

# TransactionOptions.ReadOnly.exact_staleness.

7752

#

7753

# ### Bounded Staleness

7754

#

7755

# Bounded staleness modes allow Cloud Spanner to pick the read timestamp,

7756

# subject to a user-provided staleness bound. Cloud Spanner chooses the

7757

# newest timestamp within the staleness bound that allows execution

7758

# of the reads at the closest available replica without blocking.

7759

#

7760

# All rows yielded are consistent with each other -- if any part of

7761

# the read observes a transaction, all parts of the read see the

7762

# transaction. Boundedly stale reads are not repeatable: two stale

7763

# reads, even if they use the same staleness bound, can execute at

7764

# different timestamps and thus return inconsistent results.

7765

#

7766

# Boundedly stale reads execute in two phases: the first phase

7767

# negotiates a timestamp among all replicas needed to serve the

7768

# read. In the second phase, reads are executed at the negotiated

7769

# timestamp.

7770

#

7771

# As a result of the two phase execution, bounded staleness reads are

7772

# usually a little slower than comparable exact staleness

7773

# reads. However, they are typically able to return fresher

7774

# results, and are more likely to execute at the closest replica.

7775

#

7776

# Because the timestamp negotiation requires up-front knowledge of

7777

# which rows will be read, it can only be used with single-use

7778

# read-only transactions.

7779

#

7780

# See TransactionOptions.ReadOnly.max_staleness and

7781

# TransactionOptions.ReadOnly.min_read_timestamp.

7782

#

7783

# ### Old Read Timestamps and Garbage Collection

7784

#

7785

# Cloud Spanner continuously garbage collects deleted and overwritten data

7786

# in the background to reclaim storage space. This process is known

7787

# as "version GC". By default, version GC reclaims versions after they

7788

# are one hour old. Because of this, Cloud Spanner cannot perform reads

7789

# at read timestamps more than one hour in the past. This

7790

# restriction also applies to in-progress reads and/or SQL queries whose

7791

# timestamp become too old while executing. Reads and SQL queries with

7792

# too-old read timestamps fail with the error `FAILED_PRECONDITION`.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7793

#

7794

# ## Partitioned DML Transactions

7795

#

7796

# Partitioned DML transactions are used to execute DML statements with a

7797

# different execution strategy that provides different, and often better,

7798

# scalability properties for large, table-wide operations than DML in a

7799

# ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,

7800

# should prefer using ReadWrite transactions.

7801

#

7802

# Partitioned DML partitions the keyspace and runs the DML statement on each

7803

# partition in separate, internal transactions. These transactions commit

7804

# automatically when complete, and run independently from one another.

7805

#

7806

# To reduce lock contention, this execution strategy only acquires read locks

7807

# on rows that match the WHERE clause of the statement. Additionally, the

7808

# smaller per-partition transactions hold locks for less time.

7809

#

7810

# That said, Partitioned DML is not a drop-in replacement for standard DML used

7811

# in ReadWrite transactions.

7812

#

7813

# - The DML statement must be fully-partitionable. Specifically, the statement

7814

# must be expressible as the union of many statements which each access only

7815

# a single row of the table.

7816

#

7817

# - The statement is not applied atomically to all rows of the table. Rather,

7818

# the statement is applied atomically to partitions of the table, in

7819

# independent transactions. Secondary index rows are updated atomically

7820

# with the base table rows.

7821

#

7822

# - Partitioned DML does not guarantee exactly-once execution semantics

7823

# against a partition. The statement will be applied at least once to each

7824

# partition. It is strongly recommended that the DML statement should be

7825

# idempotent to avoid unexpected results. For instance, it is potentially

7826

# dangerous to run a statement such as

7827

# `UPDATE table SET column = column + 1` as it could be run multiple times

7828

# against some rows.

7829

#

7830

# - The partitions are committed automatically - there is no support for

7831

# Commit or Rollback. If the call returns an error, or if the client issuing

7832

# the ExecuteSql call dies, it is possible that some rows had the statement

7833

# executed on them successfully. It is also possible that statement was

7834

# never executed against other rows.

7835

#

7836

# - Partitioned DML transactions may only contain the execution of a single

7837

# DML statement via ExecuteSql or ExecuteStreamingSql.

7838

#

7839

# - If any error is encountered during the execution of the partitioned DML

7840

# operation (for instance, a UNIQUE INDEX violation, division by zero, or a

7841

# value that cannot be stored due to schema constraints), then the

7842

# operation is stopped at that point and an error is returned. It is

7843

# possible that at this point, some partitions have been committed (or even

7844

# committed multiple times), and other partitions have not been run at all.

7845

#

7846

# Given the above, Partitioned DML is good fit for large, database-wide,

7847

# operations that are idempotent, such as deleting old rows from a very large

7848

# table.

7849

"readWrite": { # Message type to initiate a read-write transaction. Currently this # Transaction may write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7850

#

7851

# Authorization to begin a read-write transaction requires

7852

# `spanner.databases.beginOrRollbackReadWriteTransaction` permission

7853

# on the `session` resource.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7854

# transaction type has no options.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7855

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7856

"readOnly": { # Message type to initiate a read-only transaction. # Transaction will not write.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7857

#

7858

# Authorization to begin a read-only transaction requires

7859

# `spanner.databases.beginReadOnlyTransaction` permission

7860

# on the `session` resource.

7861

"minReadTimestamp": "A String", # Executes all reads at a timestamp >= `min_read_timestamp`.

7862

#

7863

# This is useful for requesting fresher data than some previous

7864

# read, or data that is fresh enough to observe the effects of some

7865

# previously committed transaction whose timestamp is known.

7866

#

7867

# Note that this option can only be used in single-use transactions.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7868

#

7869

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

7870

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

7871

"returnReadTimestamp": True or False, # If true, the Cloud Spanner-selected read timestamp is included in

7872

# the Transaction message that describes the transaction.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7873

"maxStaleness": "A String", # Read data at a timestamp >= `NOW - max_staleness`

7874

# seconds. Guarantees that all writes that have committed more

7875

# than the specified number of seconds ago are visible. Because

7876

# Cloud Spanner chooses the exact timestamp, this mode works even if

7877

# the client's local clock is substantially skewed from Cloud Spanner

7878

# commit timestamps.

7879

#

7880

# Useful for reading the freshest data available at a nearby

7881

# replica, while bounding the possible staleness if the local

7882

# replica has fallen behind.

7883

#

7884

# Note that this option can only be used in single-use

7885

# transactions.

7886

"exactStaleness": "A String", # Executes all reads at a timestamp that is `exact_staleness`

7887

# old. The timestamp is chosen soon after the read is started.

7888

#

7889

# Guarantees that all writes that have committed more than the

7890

# specified number of seconds ago are visible. Because Cloud Spanner

7891

# chooses the exact timestamp, this mode works even if the client's

7892

# local clock is substantially skewed from Cloud Spanner commit

7893

# timestamps.

7894

#

7895

# Useful for reading at nearby replicas without the distributed

7896

# timestamp negotiation overhead of `max_staleness`.

Thomas Coffee

2017-03-27 10:39:26 -0700

[diff] [blame]

7897

"readTimestamp": "A String", # Executes all reads at the given timestamp. Unlike other modes,

7898

# reads at a specific timestamp are repeatable; the same read at

7899

# the same timestamp always returns the same data. If the

7900

# timestamp is in the future, the read will block until the

7901

# specified timestamp, modulo the read's deadline.

7902

#

7903

# Useful for large scale consistent reads such as mapreduces, or

7904

# for coordinating many reads against a consistent snapshot of the

7905

# data.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7906

#

7907

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

7908

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7909

"strong": True or False, # Read at a timestamp where all previously committed transactions

7910

# are visible.

7911

},

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7912

"partitionedDml": { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.

7913

#

7914

# Authorization to begin a Partitioned DML transaction requires

7915

# `spanner.databases.beginPartitionedDmlTransaction` permission

7916

# on the `session` resource.

7917

},

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7918

},

7919

"id": "A String", # Execute the read or SQL query in a previously-started transaction.

7920

},

7921

"resumeToken": "A String", # If this request is resuming a previously interrupted read,

7922

# `resume_token` should be copied from the last

7923

# PartialResultSet yielded before the interruption. Doing this

7924

# enables the new read to resume where the last read left off. The

7925

# rest of the request parameters must exactly match the request

7926

# that yielded this token.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7927

"partitionToken": "A String", # If present, results will be restricted to the specified partition

7928

# previously created using PartitionRead(). There must be an exact

7929

# match for the values of fields common to this message and the

7930

# PartitionReadRequest message used to create this partition_token.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7931

"keySet": { # `KeySet` defines a collection of Cloud Spanner keys and/or key ranges. All # Required. `key_set` identifies the rows to be yielded. `key_set` names the

7932

# primary keys of the rows in table to be yielded, unless index

7933

# is present. If index is present, then key_set instead names

7934

# index keys in index.

7935

#

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7936

# If the partition_token field is empty, rows are yielded

7937

# in table primary key order (if index is empty) or index key order

7938

# (if index is non-empty). If the partition_token field is not

7939

# empty, rows will be yielded in an unspecified order.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7940

#

7941

# It is not an error for the `key_set` to name rows that do not

7942

# exist in the database. Read yields nothing for nonexistent rows.

7943

# the keys are expected to be in the same table or index. The keys need

7944

# not be sorted in any particular way.

7945

#

7946

# If the same key is specified multiple times in the set (for example

7947

# if two ranges, two keys, or a key and a range overlap), Cloud Spanner

7948

# behaves as if the key were only specified once.

7949

"ranges": [ # A list of key ranges. See KeyRange for more information about

7950

# key range specifications.

7951

{ # KeyRange represents a range of rows in a table or index.

7952

#

7953

# A range has a start key and an end key. These keys can be open or

7954

# closed, indicating if the range includes rows with that key.

7955

#

7956

# Keys are represented by lists, where the ith value in the list

7957

# corresponds to the ith component of the table or index primary key.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

7958

# Individual values are encoded as described

7959

# here.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

7960

#

7961

# For example, consider the following table definition:

7962

#

7963

# CREATE TABLE UserEvents (

7964

# UserName STRING(MAX),

7965

# EventDate STRING(10)

7966

# ) PRIMARY KEY(UserName, EventDate);

7967

#

7968

# The following keys name rows in this table:

7969

#

7970

# "Bob", "2014-09-23"

7971

#

7972

# Since the `UserEvents` table's `PRIMARY KEY` clause names two

7973

# columns, each `UserEvents` key has two elements; the first is the

7974

# `UserName`, and the second is the `EventDate`.

7975

#

7976

# Key ranges with multiple components are interpreted

7977

# lexicographically by component using the table or index key's declared

7978

# sort order. For example, the following range returns all events for

7979

# user `"Bob"` that occurred in the year 2015:

7980

#

7981

# "start_closed": ["Bob", "2015-01-01"]

7982

# "end_closed": ["Bob", "2015-12-31"]

7983

#

7984

# Start and end keys can omit trailing key components. This affects the

7985

# inclusion and exclusion of rows that exactly match the provided key

7986

# components: if the key is closed, then rows that exactly match the

7987

# provided components are included; if the key is open, then rows

7988

# that exactly match are not included.

7989

#

7990

# For example, the following range includes all events for `"Bob"` that

7991

# occurred during and after the year 2000:

7992

#

7993

# "start_closed": ["Bob", "2000-01-01"]

7994

# "end_closed": ["Bob"]

7995

#

7996

# The next example retrieves all events for `"Bob"`:

7997

#

7998

# "start_closed": ["Bob"]

7999

# "end_closed": ["Bob"]

8000

#

8001

# To retrieve events before the year 2000:

8002

#

8003

# "start_closed": ["Bob"]

8004

# "end_open": ["Bob", "2000-01-01"]

8005

#

8006

# The following range includes all rows in the table:

#

# "start_closed": []

# "end_closed": []

#

# This range returns all users whose `UserName` begins with any

8012

# character from A to C:

8013

#

8014

# "start_closed": ["A"]

8015

# "end_open": ["D"]

8016

#

8017

# This range returns all users whose `UserName` begins with B:

8018

#

8019

# "start_closed": ["B"]

8020

# "end_open": ["C"]

8021

#

8022

# Key ranges honor column sort order. For example, suppose a table is

8023

# defined as follows:

8024

#

8025

# CREATE TABLE DescendingSortedTable {

8026

# Key INT64,

8027

# ...

8028

# ) PRIMARY KEY(Key DESC);

8029

#

8030

# The following range retrieves all rows with key values between 1

8031

# and 100 inclusive:

8032

#

8033

# "start_closed": ["100"]

8034

# "end_closed": ["1"]

8035

#

8036

# Note that 100 is passed as the start, and 1 is passed as the end,

8037

# because `Key` is a descending column in the schema.

8038

"endOpen": [ # If the end is open, then the range excludes rows whose first

8039

# `len(end_open)` key columns exactly match `end_open`.

8040

"",

8041

],

8042

"startOpen": [ # If the start is open, then the range excludes rows whose first

8043

# `len(start_open)` key columns exactly match `start_open`.

8044

"",

8045

],

8046

"endClosed": [ # If the end is closed, then the range includes all rows whose

8047

# first `len(end_closed)` key columns exactly match `end_closed`.

8048

"",

8049

],

8050

"startClosed": [ # If the start is closed, then the range includes all rows whose

8051

# first `len(start_closed)` key columns exactly match `start_closed`.

"",

],

},

],

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

8056

"keys": [ # A list of specific keys. Entries in `keys` should have exactly as

8057

# many elements as there are columns in the primary or index key

8058

# with which this `KeySet` is used. Individual key values are

8059

# encoded as described here.

[

"",

],

],

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

8064

"all": True or False, # For convenience `all` can be set to `true` to indicate that this

8065

# `KeySet` matches all keys in the table or index. Note that any keys

8066

# specified in `keys` or `ranges` are only yielded once.

8067

},

8068

"limit": "A String", # If greater than zero, only the first `limit` rows are yielded. If `limit`

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

8069

# is zero, the default is no limit. A limit cannot be specified if

8070

# `partition_token` is set.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

8071

"table": "A String", # Required. The name of the table in the database to be read.

8072

"columns": [ # The columns of table to be returned for each row matching

# this request.

"A String",

],

}

x__xgafv: string, V1 error format.

Allowed values

1 - v1 error format

2 - v2 error format

Returns:

An object of the form:

8085

8086

{ # Partial results from a streaming read or SQL query. Streaming reads and

8087

# SQL queries better tolerate large result sets, large rows, and large

8088

# values, but are a little trickier to consume.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

8089

"resumeToken": "A String", # Streaming calls might be interrupted for a variety of reasons, such

8090

# as TCP connection loss. If this occurs, the stream of results can

8091

# be resumed by re-sending the original request and including

8092

# `resume_token`. Note that executing any other transaction in the

8093

# same session invalidates the token.

8094

"chunkedValue": True or False, # If true, then the final value in values is chunked, and must

8095

# be combined with more values from subsequent `PartialResultSet`s

8096

# to obtain a complete field value.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

8097

"values": [ # A streamed result set consists of a stream of values, which might

8098

# be split into many `PartialResultSet` messages to accommodate

8099

# large rows and/or large values. Every N complete values defines a

8100

# row, where N is equal to the number of entries in

8101

# metadata.row_type.fields.

8102

#

8103

# Most values are encoded based on type as described

8104

# here.

8105

#

8106

# It is possible that the last value in values is "chunked",

8107

# meaning that the rest of the value is sent in subsequent

8108

# `PartialResultSet`(s). This is denoted by the chunked_value

8109

# field. Two or more chunked values can be merged to form a

8110

# complete value as follows:

8111

#

8112

# * `bool/number/null`: cannot be chunked

8113

# * `string`: concatenate the strings

8114

# * `list`: concatenate the lists. If the last element in a list is a

8115

# `string`, `list`, or `object`, merge it with the first element in

8116

# the next list by applying these rules recursively.

8117

# * `object`: concatenate the (field name, field value) pairs. If a

8118

# field name is duplicated, then apply these rules recursively

8119

# to merge the field values.

8120

#

8121

# Some examples of merging:

8122

#

8123

# # Strings are concatenated.

8124

# "foo", "bar" => "foobar"

8125

#

8126

# # Lists of non-strings are concatenated.

8127

# [2, 3], [4] => [2, 3, 4]

8128

#

8129

# # Lists are concatenated, but the last and first elements are merged

8130

# # because they are strings.

8131

# ["a", "b"], ["c", "d"] => ["a", "bc", "d"]

8132

#

8133

# # Lists are concatenated, but the last and first elements are merged

8134

# # because they are lists. Recursively, the last and first elements

8135

# # of the inner lists are merged because they are strings.

8136

# ["a", ["b", "c"]], [["d"], "e"] => ["a", ["b", "cd"], "e"]

8137

#

8138

# # Non-overlapping object fields are combined.

8139

# {"a": "1"}, {"b": "2"} => {"a": "1", "b": 2"}

8140

#

8141

# # Overlapping object fields are merged.

8142

# {"a": "1"}, {"a": "2"} => {"a": "12"}

8143

#

8144

# # Examples of merging objects containing lists of strings.

8145

# {"a": ["1"]}, {"a": ["2"]} => {"a": ["12"]}

8146

#

8147

# For a more complete example, suppose a streaming SQL query is

8148

# yielding a result set whose rows contain a single string

8149

# field. The following `PartialResultSet`s might be yielded:

8150

#

8151

# {

8152

# "metadata": { ... }

8153

# "values": ["Hello", "W"]

8154

# "chunked_value": true

8155

# "resume_token": "Af65..."

# }

# {

# "values": ["orl"]

# "chunked_value": true

8160

# "resume_token": "Bqp2..."

# }

# {

# "values": ["d"]

# "resume_token": "Zx1B..."

8165

# }

8166

#

8167

# This sequence of `PartialResultSet`s encodes two rows, one

8168

# containing the field value `"Hello"`, and a second containing the

8169

# field value `"World" = "W" + "orl" + "d"`.

8170

"",

8171

],

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

8172

"stats": { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the statement that produced this

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

8173

# streaming result set. These can be requested by setting

8174

# ExecuteSqlRequest.query_mode and are sent

8175

# only once with the last response in the stream.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

8176

# This field will also be present in the last response for DML

8177

# statements.

8178

"rowCountLowerBound": "A String", # Partitioned DML does not offer exactly-once semantics, so it

8179

# returns a lower bound of the rows modified.

8180

"rowCountExact": "A String", # Standard DML returns an exact count of rows that were modified.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

8181

"queryPlan": { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.

8182

"planNodes": [ # The nodes in the query plan. Plan nodes are returned in pre-order starting

8183

# with the plan root. Each PlanNode's `id` corresponds to its index in

8184

# `plan_nodes`.

8185

{ # Node information for nodes appearing in a QueryPlan.plan_nodes.

8186

"index": 42, # The `PlanNode`'s index in node list.

8187

"kind": "A String", # Used to determine the type of node. May be needed for visualizing

8188

# different kinds of nodes differently. For example, If the node is a

8189

# SCALAR node, it will have a condensed representation

8190

# which can be used to directly embed a description of the node in its

8191

# parent.

8192

"displayName": "A String", # The display name for the node.

8193

"executionStats": { # The execution statistics associated with the node, contained in a group of

8194

# key-value pairs. Only present if the plan was returned as a result of a

8195

# profile query. For example, number of executions, number of rows/time per

8196

# execution etc.

8197

"a_key": "", # Properties of the object.

8198

},

8199

"childLinks": [ # List of child node `index`es and their relationship to this parent.

8200

{ # Metadata associated with a parent-child relationship appearing in a

8201

# PlanNode.

8202

"variable": "A String", # Only present if the child node is SCALAR and corresponds

8203

# to an output variable of the parent node. The field carries the name of

8204

# the output variable.

8205

# For example, a `TableScan` operator that reads rows from a table will

8206

# have child links to the `SCALAR` nodes representing the output variables

8207

# created for each column that is read by the operator. The corresponding

8208

# `variable` fields will be set to the variable names assigned to the

8209

# columns.

Sai Cheemalapati

2017-06-06 18:46:08 -0400

[diff] [blame]

8210

"childIndex": 42, # The node to which the link points.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

8211

"type": "A String", # The type of the link. For example, in Hash Joins this could be used to

8212

# distinguish between the build child and the probe child, or in the case

8213

# of the child being an output variable, to represent the tag associated

8214

# with the output variable.

Sai Cheemalapati

2017-03-13 12:12:03 -0400

[diff] [blame]

8215

},

8216

],

8217

"shortRepresentation": { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.

8218

# `SCALAR` PlanNode(s).

8219

"subqueries": { # A mapping of (subquery variable name) -> (subquery node id) for cases

8220

# where the `description` string of this node references a `SCALAR`

8221

# subquery contained in the expression subtree rooted at this node. The

8222

# referenced `SCALAR` subquery may not necessarily be a direct child of

# this node.

"a_key": 42,

},

"description": "A String", # A string representation of the expression subtree rooted at this node.

8227

},

8228

"metadata": { # Attributes relevant to the node contained in a group of key-value pairs.

8229

# For example, a Parameter Reference node could have the following

8230

# information in its metadata:

8231

#

8232

# {

8233

# "parameter_reference": "param1",

8234

# "parameter_type": "array"

8235

# }

8236

"a_key": "", # Properties of the object.

},

},

],

},

"queryStats": { # Aggregated statistics from the execution of the query. Only present when

8242

# the query is profiled. For example, a query could return the statistics as

# follows:

#

# {

# "rows_returned": "3",

8247

# "elapsed_time": "1.22 secs",

8248

# "cpu_time": "1.19 secs"

8249

# }

8250

"a_key": "", # Properties of the object.

8251

},

8252

},

8253

"metadata": { # Metadata about a ResultSet or PartialResultSet. # Metadata about the result set, such as row type information.

8254

# Only present in the first response.

8255

"rowType": { # `StructType` defines the fields of a STRUCT type. # Indicates the field names and types for the rows in the result

8256

# set. For example, a SQL query like `"SELECT UserId, UserName FROM

8257

# Users"` could return a `row_type` value like:

8258

#

8259

# "fields": [

8260

# { "name": "UserId", "type": { "code": "INT64" } },

8261

# { "name": "UserName", "type": { "code": "STRING" } },

8262

# ]

8263

"fields": [ # The list of fields that make up this struct. Order is

8264

# significant, because values of this struct type are represented as

8265

# lists, where the order of field values matches the order of

8266

# fields in the StructType. In turn, the order of fields

8267

# matches the order of columns in a read request, or the order of

8268

# fields in the `SELECT` clause of a query.

8269

{ # Message representing a single field of a struct.

8270

"type": { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a # The type of the field.

8271

# table cell or returned from an SQL query.

8272

"structType": # Object with schema name: StructType # If code == STRUCT, then `struct_type`

8273

# provides type information for the struct's fields.

8274

"code": "A String", # Required. The TypeCode for this type.

8275

"arrayElementType": # Object with schema name: Type # If code == ARRAY, then `array_element_type`

8276

# is the type of the array elements.

8277

},

8278

"name": "A String", # The name of the field. For reads, this is the column name. For

8279

# SQL queries, it is the column alias (e.g., `"Word"` in the

8280

# query `"SELECT 'hello' AS Word"`), or the column name (e.g.,

8281

# `"ColName"` in the query `"SELECT ColName FROM Table"`). Some

8282

# columns might have an empty name (e.g., !"SELECT

8283

# UPPER(ColName)"`). Note that a query result can contain

8284

# multiple fields with the same name.

},

],

},

"transaction": { # A transaction. # If the read or SQL query began a transaction as a side-effect, the

8289

# information about the new transaction is yielded here.

8290

"readTimestamp": "A String", # For snapshot read-only transactions, the read timestamp chosen

8291

# for the transaction. Not returned by default: see

8292

# TransactionOptions.ReadOnly.return_read_timestamp.

Bu Sun Kim

2019-06-14 16:50:42 -0700

[diff] [blame]

8293

#

8294

# A timestamp in RFC3339 UTC \"Zulu\" format, accurate to nanoseconds.

8295

# Example: `"2014-10-02T15:01:23.045123456Z"`.

Sai Cheemalapati