Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / google-api-python-client / 650209194f8080f37a5f20846931790f4c70ed46 / . / docs / dyn / spanner_v1.projects.instances.databases.sessions.html
blob: 1632d4113789679fc744c080e76140a8e3533472 [file] [log] [blame]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1<html><body>
2<style>
3
4body, h1, h2, h3, div, span, p, pre, a {
5 margin: 0;
6 padding: 0;
7 border: 0;
8 font-weight: inherit;
9 font-style: inherit;
10 font-size: 100%;
11 font-family: inherit;
12 vertical-align: baseline;
13}
14
15body {
16 font-size: 13px;
17 padding: 1em;
18}
19
20h1 {
21 font-size: 26px;
22 margin-bottom: 1em;
23}
24
25h2 {
26 font-size: 24px;
27 margin-bottom: 1em;
28}
29
30h3 {
31 font-size: 20px;
32 margin-bottom: 1em;
33 margin-top: 1em;
34}
35
36pre, code {
37 line-height: 1.5;
38 font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace;
39}
40
41pre {
42 margin-top: 0.5em;
43}
44
45h1, h2, h3, p {
46 font-family: Arial, sans serif;
47}
48
49h1, h2, h3 {
50 border-bottom: solid #CCC 1px;
51}
52
53.toc_element {
54 margin-top: 0.5em;
55}
56
57.firstline {
58 margin-left: 2 em;
59}
60
61.method {
62 margin-top: 1em;
63 border: solid 1px #CCC;
64 padding: 1em;
65 background: #EEE;
66}
67
68.details {
69 font-weight: bold;
70 font-size: 14px;
71}
72
73</style>
74
75<h1><a href="spanner_v1.html">Cloud Spanner API</a> . <a href="spanner_v1.projects.html">projects</a> . <a href="spanner_v1.projects.instances.html">instances</a> . <a href="spanner_v1.projects.instances.databases.html">databases</a> . <a href="spanner_v1.projects.instances.databases.sessions.html">sessions</a></h1>
76<h2>Instance Methods</h2>
77<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]78 <code><a href="#batchCreate">batchCreate(database, body=None, x__xgafv=None)</a></code></p>
79<p class="firstline">Creates multiple new sessions.</p>
80<p class="toc_element">
81 <code><a href="#beginTransaction">beginTransaction(session, body=None, x__xgafv=None)</a></code></p>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]82<p class="firstline">Begins a new transaction. This step can often be skipped:</p>
83<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]84 <code><a href="#commit">commit(session, body=None, x__xgafv=None)</a></code></p>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]85<p class="firstline">Commits a transaction. The request includes the mutations to be</p>
86<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]87 <code><a href="#create">create(database, body=None, x__xgafv=None)</a></code></p>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]88<p class="firstline">Creates a new session. A session can be used to perform</p>
89<p class="toc_element">
90 <code><a href="#delete">delete(name, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]91<p class="firstline">Ends a session, releasing server resources associated with it. This will</p>
92<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]93 <code><a href="#executeBatchDml">executeBatchDml(session, body=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]94<p class="firstline">Executes a batch of SQL DML statements. This method allows many statements</p>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]95<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]96 <code><a href="#executeSql">executeSql(session, body=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]97<p class="firstline">Executes an SQL statement, returning all results in a single reply. This</p>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]98<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]99 <code><a href="#executeStreamingSql">executeStreamingSql(session, body=None, x__xgafv=None)</a></code></p>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]100<p class="firstline">Like ExecuteSql, except returns the result</p>
101<p class="toc_element">
102 <code><a href="#get">get(name, x__xgafv=None)</a></code></p>
103<p class="firstline">Gets a session. Returns `NOT_FOUND` if the session does not exist.</p>
104<p class="toc_element">
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]105 <code><a href="#list">list(database, filter=None, pageToken=None, pageSize=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]106<p class="firstline">Lists all sessions in a given database.</p>
107<p class="toc_element">
108 <code><a href="#list_next">list_next(previous_request, previous_response)</a></code></p>
109<p class="firstline">Retrieves the next page of results.</p>
110<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]111 <code><a href="#partitionQuery">partitionQuery(session, body=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]112<p class="firstline">Creates a set of partition tokens that can be used to execute a query</p>
113<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]114 <code><a href="#partitionRead">partitionRead(session, body=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]115<p class="firstline">Creates a set of partition tokens that can be used to execute a read</p>
116<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]117 <code><a href="#read">read(session, body=None, x__xgafv=None)</a></code></p>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]118<p class="firstline">Reads rows from the database using key lookups and scans, as a</p>
119<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]120 <code><a href="#rollback">rollback(session, body=None, x__xgafv=None)</a></code></p>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]121<p class="firstline">Rolls back a transaction, releasing any locks it holds. It is a good</p>
122<p class="toc_element">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]123 <code><a href="#streamingRead">streamingRead(session, body=None, x__xgafv=None)</a></code></p>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]124<p class="firstline">Like Read, except returns the result set as a</p>
125<h3>Method Details</h3>
126<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]127 <code class="details" id="batchCreate">batchCreate(database, body=None, x__xgafv=None)</code>
128 <pre>Creates multiple new sessions.
129
130This API can be used to initialize a session cache on the clients.
131See https://goo.gl/TgSFN2 for best practices on session cache management.
132
133Args:
134 database: string, Required. The database in which the new sessions are created. (required)
135 body: object, The request body.
136 The object takes the form of:
137
138{ # The request for BatchCreateSessions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]139 &quot;sessionTemplate&quot;: { # A session in the Cloud Spanner API. # Parameters to be applied to each created session.
140 &quot;approximateLastUseTime&quot;: &quot;A String&quot;, # Output only. The approximate timestamp when the session is last used. It is
141 # typically earlier than the actual last use time.
142 &quot;name&quot;: &quot;A String&quot;, # The name of the session. This is always system-assigned; values provided
143 # when creating a session are ignored.
144 &quot;createTime&quot;: &quot;A String&quot;, # Output only. The timestamp when the session is created.
145 &quot;labels&quot;: { # The labels for the session.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]146 #
147 # * Label keys must be between 1 and 63 characters long and must conform to
148 # the following regular expression: `[a-z]([-a-z0-9]*[a-z0-9])?`.
149 # * Label values must be between 0 and 63 characters long and must conform
150 # to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`.
151 # * No more than 64 labels can be associated with a given session.
152 #
153 # See https://goo.gl/xmQnxf for more information on and examples of labels.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]154 &quot;a_key&quot;: &quot;A String&quot;,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]155 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]156 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]157 &quot;sessionCount&quot;: 42, # Required. The number of sessions to be created in this batch call.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]158 # The API may return fewer than the requested number of sessions. If a
159 # specific number of sessions are desired, the client can make additional
160 # calls to BatchCreateSessions (adjusting
161 # session_count as necessary).
162 }
163
164 x__xgafv: string, V1 error format.
165 Allowed values
166 1 - v1 error format
167 2 - v2 error format
168
169Returns:
170 An object of the form:
171
172 { # The response for BatchCreateSessions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]173 &quot;session&quot;: [ # The freshly created sessions.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]174 { # A session in the Cloud Spanner API.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]175 &quot;approximateLastUseTime&quot;: &quot;A String&quot;, # Output only. The approximate timestamp when the session is last used. It is
176 # typically earlier than the actual last use time.
177 &quot;name&quot;: &quot;A String&quot;, # The name of the session. This is always system-assigned; values provided
178 # when creating a session are ignored.
179 &quot;createTime&quot;: &quot;A String&quot;, # Output only. The timestamp when the session is created.
180 &quot;labels&quot;: { # The labels for the session.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]181 #
182 # * Label keys must be between 1 and 63 characters long and must conform to
183 # the following regular expression: `[a-z]([-a-z0-9]*[a-z0-9])?`.
184 # * Label values must be between 0 and 63 characters long and must conform
185 # to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`.
186 # * No more than 64 labels can be associated with a given session.
187 #
188 # See https://goo.gl/xmQnxf for more information on and examples of labels.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]189 &quot;a_key&quot;: &quot;A String&quot;,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]190 },
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]191 },
192 ],
193 }</pre>
194</div>
195
196<div class="method">
197 <code class="details" id="beginTransaction">beginTransaction(session, body=None, x__xgafv=None)</code>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]198 <pre>Begins a new transaction. This step can often be skipped:
199Read, ExecuteSql and
200Commit can begin a new transaction as a
201side-effect.
202
203Args:
204 session: string, Required. The session in which the transaction runs. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]205 body: object, The request body.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]206 The object takes the form of:
207
208{ # The request for BeginTransaction.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]209 &quot;options&quot;: { # # Transactions # Required. Options for the new transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]210 #
211 #
212 # Each session can have at most one active transaction at a time. After the
213 # active transaction is completed, the session can immediately be
214 # re-used for the next transaction. It is not necessary to create a
215 # new session for each transaction.
216 #
217 # # Transaction Modes
218 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]219 # Cloud Spanner supports three transaction modes:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]220 #
221 # 1. Locking read-write. This type of transaction is the only way
222 # to write data into Cloud Spanner. These transactions rely on
223 # pessimistic locking and, if necessary, two-phase commit.
224 # Locking read-write transactions may abort, requiring the
225 # application to retry.
226 #
227 # 2. Snapshot read-only. This transaction type provides guaranteed
228 # consistency across several reads, but does not allow
229 # writes. Snapshot read-only transactions can be configured to
230 # read at timestamps in the past. Snapshot read-only
231 # transactions do not need to be committed.
232 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]233 # 3. Partitioned DML. This type of transaction is used to execute
234 # a single Partitioned DML statement. Partitioned DML partitions
235 # the key space and runs the DML statement over each partition
236 # in parallel using separate, internal transactions that commit
237 # independently. Partitioned DML transactions do not need to be
238 # committed.
239 #
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]240 # For transactions that only read, snapshot read-only transactions
241 # provide simpler semantics and are almost always faster. In
242 # particular, read-only transactions do not take locks, so they do
243 # not conflict with read-write transactions. As a consequence of not
244 # taking locks, they also do not abort, so retry loops are not needed.
245 #
246 # Transactions may only read/write data in a single database. They
247 # may, however, read/write data in different tables within that
248 # database.
249 #
250 # ## Locking Read-Write Transactions
251 #
252 # Locking transactions may be used to atomically read-modify-write
253 # data anywhere in a database. This type of transaction is externally
254 # consistent.
255 #
256 # Clients should attempt to minimize the amount of time a transaction
257 # is active. Faster transactions commit with higher probability
258 # and cause less contention. Cloud Spanner attempts to keep read locks
259 # active as long as the transaction continues to do reads, and the
260 # transaction has not been terminated by
261 # Commit or
262 # Rollback. Long periods of
263 # inactivity at the client may cause Cloud Spanner to release a
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]264 # transaction&#x27;s locks and abort it.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]265 #
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]266 # Conceptually, a read-write transaction consists of zero or more
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]267 # reads or SQL statements followed by
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]268 # Commit. At any time before
269 # Commit, the client can send a
270 # Rollback request to abort the
271 # transaction.
272 #
273 # ### Semantics
274 #
275 # Cloud Spanner can commit the transaction if all read locks it acquired
276 # are still valid at commit time, and it is able to acquire write
277 # locks for all writes. Cloud Spanner can abort the transaction for any
278 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
279 # that the transaction has not modified any user data in Cloud Spanner.
280 #
281 # Unless the transaction commits, Cloud Spanner makes no guarantees about
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]282 # how long the transaction&#x27;s locks were held for. It is an error to
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]283 # use Cloud Spanner locks for any sort of mutual exclusion other than
284 # between Cloud Spanner transactions themselves.
285 #
286 # ### Retrying Aborted Transactions
287 #
288 # When a transaction aborts, the application can choose to retry the
289 # whole transaction again. To maximize the chances of successfully
290 # committing the retry, the client should execute the retry in the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]291 # same session as the original attempt. The original session&#x27;s lock
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]292 # priority increases with each consecutive abort, meaning that each
293 # attempt has a slightly better chance of success than the previous.
294 #
295 # Under some circumstances (e.g., many transactions attempting to
296 # modify the same row(s)), a transaction can abort many times in a
297 # short period before successfully committing. Thus, it is not a good
298 # idea to cap the number of retries a transaction can attempt;
299 # instead, it is better to limit the total amount of wall time spent
300 # retrying.
301 #
302 # ### Idle Transactions
303 #
304 # A transaction is considered idle if it has no outstanding reads or
305 # SQL queries and has not started a read or SQL query within the last 10
306 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]307 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]308 # fail with error `ABORTED`.
309 #
310 # If this behavior is undesirable, periodically executing a simple
311 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
312 # transaction from becoming idle.
313 #
314 # ## Snapshot Read-Only Transactions
315 #
316 # Snapshot read-only transactions provides a simpler method than
317 # locking read-write transactions for doing several consistent
318 # reads. However, this type of transaction does not support writes.
319 #
320 # Snapshot transactions do not take locks. Instead, they work by
321 # choosing a Cloud Spanner timestamp, then executing all reads at that
322 # timestamp. Since they do not acquire locks, they do not block
323 # concurrent read-write transactions.
324 #
325 # Unlike locking read-write transactions, snapshot read-only
326 # transactions never abort. They can fail if the chosen read
327 # timestamp is garbage collected; however, the default garbage
328 # collection policy is generous enough that most applications do not
329 # need to worry about this in practice.
330 #
331 # Snapshot read-only transactions do not need to call
332 # Commit or
333 # Rollback (and in fact are not
334 # permitted to do so).
335 #
336 # To execute a snapshot transaction, the client specifies a timestamp
337 # bound, which tells Cloud Spanner how to choose a read timestamp.
338 #
339 # The types of timestamp bound are:
340 #
341 # - Strong (the default).
342 # - Bounded staleness.
343 # - Exact staleness.
344 #
345 # If the Cloud Spanner database to be read is geographically distributed,
346 # stale read-only transactions can execute more quickly than strong
347 # or read-write transaction, because they are able to execute far
348 # from the leader replica.
349 #
350 # Each type of timestamp bound is discussed in detail below.
351 #
352 # ### Strong
353 #
354 # Strong reads are guaranteed to see the effects of all transactions
355 # that have committed before the start of the read. Furthermore, all
356 # rows yielded by a single read are consistent with each other -- if
357 # any part of the read observes a transaction, all parts of the read
358 # see the transaction.
359 #
360 # Strong reads are not repeatable: two consecutive strong read-only
361 # transactions might return inconsistent results if there are
362 # concurrent writes. If consistency across reads is required, the
363 # reads should be executed within a transaction or at an exact read
364 # timestamp.
365 #
366 # See TransactionOptions.ReadOnly.strong.
367 #
368 # ### Exact Staleness
369 #
370 # These timestamp bounds execute reads at a user-specified
371 # timestamp. Reads at a timestamp are guaranteed to see a consistent
372 # prefix of the global transaction history: they observe
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]373 # modifications done by all transactions with a commit timestamp &lt;=
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]374 # the read timestamp, and observe none of the modifications done by
375 # transactions with a larger commit timestamp. They will block until
376 # all conflicting transactions that may be assigned commit timestamps
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]377 # &lt;= the read timestamp have finished.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]378 #
379 # The timestamp can either be expressed as an absolute Cloud Spanner commit
380 # timestamp or a staleness relative to the current time.
381 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]382 # These modes do not require a &quot;negotiation phase&quot; to pick a
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]383 # timestamp. As a result, they execute slightly faster than the
384 # equivalent boundedly stale concurrency modes. On the other hand,
385 # boundedly stale reads usually return fresher results.
386 #
387 # See TransactionOptions.ReadOnly.read_timestamp and
388 # TransactionOptions.ReadOnly.exact_staleness.
389 #
390 # ### Bounded Staleness
391 #
392 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
393 # subject to a user-provided staleness bound. Cloud Spanner chooses the
394 # newest timestamp within the staleness bound that allows execution
395 # of the reads at the closest available replica without blocking.
396 #
397 # All rows yielded are consistent with each other -- if any part of
398 # the read observes a transaction, all parts of the read see the
399 # transaction. Boundedly stale reads are not repeatable: two stale
400 # reads, even if they use the same staleness bound, can execute at
401 # different timestamps and thus return inconsistent results.
402 #
403 # Boundedly stale reads execute in two phases: the first phase
404 # negotiates a timestamp among all replicas needed to serve the
405 # read. In the second phase, reads are executed at the negotiated
406 # timestamp.
407 #
408 # As a result of the two phase execution, bounded staleness reads are
409 # usually a little slower than comparable exact staleness
410 # reads. However, they are typically able to return fresher
411 # results, and are more likely to execute at the closest replica.
412 #
413 # Because the timestamp negotiation requires up-front knowledge of
414 # which rows will be read, it can only be used with single-use
415 # read-only transactions.
416 #
417 # See TransactionOptions.ReadOnly.max_staleness and
418 # TransactionOptions.ReadOnly.min_read_timestamp.
419 #
420 # ### Old Read Timestamps and Garbage Collection
421 #
422 # Cloud Spanner continuously garbage collects deleted and overwritten data
423 # in the background to reclaim storage space. This process is known
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]424 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]425 # are one hour old. Because of this, Cloud Spanner cannot perform reads
426 # at read timestamps more than one hour in the past. This
427 # restriction also applies to in-progress reads and/or SQL queries whose
428 # timestamp become too old while executing. Reads and SQL queries with
429 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]430 #
431 # ## Partitioned DML Transactions
432 #
433 # Partitioned DML transactions are used to execute DML statements with a
434 # different execution strategy that provides different, and often better,
435 # scalability properties for large, table-wide operations than DML in a
436 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
437 # should prefer using ReadWrite transactions.
438 #
439 # Partitioned DML partitions the keyspace and runs the DML statement on each
440 # partition in separate, internal transactions. These transactions commit
441 # automatically when complete, and run independently from one another.
442 #
443 # To reduce lock contention, this execution strategy only acquires read locks
444 # on rows that match the WHERE clause of the statement. Additionally, the
445 # smaller per-partition transactions hold locks for less time.
446 #
447 # That said, Partitioned DML is not a drop-in replacement for standard DML used
448 # in ReadWrite transactions.
449 #
450 # - The DML statement must be fully-partitionable. Specifically, the statement
451 # must be expressible as the union of many statements which each access only
452 # a single row of the table.
453 #
454 # - The statement is not applied atomically to all rows of the table. Rather,
455 # the statement is applied atomically to partitions of the table, in
456 # independent transactions. Secondary index rows are updated atomically
457 # with the base table rows.
458 #
459 # - Partitioned DML does not guarantee exactly-once execution semantics
460 # against a partition. The statement will be applied at least once to each
461 # partition. It is strongly recommended that the DML statement should be
462 # idempotent to avoid unexpected results. For instance, it is potentially
463 # dangerous to run a statement such as
464 # `UPDATE table SET column = column + 1` as it could be run multiple times
465 # against some rows.
466 #
467 # - The partitions are committed automatically - there is no support for
468 # Commit or Rollback. If the call returns an error, or if the client issuing
469 # the ExecuteSql call dies, it is possible that some rows had the statement
470 # executed on them successfully. It is also possible that statement was
471 # never executed against other rows.
472 #
473 # - Partitioned DML transactions may only contain the execution of a single
474 # DML statement via ExecuteSql or ExecuteStreamingSql.
475 #
476 # - If any error is encountered during the execution of the partitioned DML
477 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
478 # value that cannot be stored due to schema constraints), then the
479 # operation is stopped at that point and an error is returned. It is
480 # possible that at this point, some partitions have been committed (or even
481 # committed multiple times), and other partitions have not been run at all.
482 #
483 # Given the above, Partitioned DML is good fit for large, database-wide,
484 # operations that are idempotent, such as deleting old rows from a very large
485 # table.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]486 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]487 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]488 # Authorization to begin a Partitioned DML transaction requires
489 # `spanner.databases.beginPartitionedDmlTransaction` permission
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]490 # on the `session` resource.
491 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]492 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]493 #
494 # Authorization to begin a read-only transaction requires
495 # `spanner.databases.beginReadOnlyTransaction` permission
496 # on the `session` resource.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]497 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]498 #
499 # This is useful for requesting fresher data than some previous
500 # read, or data that is fresh enough to observe the effects of some
501 # previously committed transaction whose timestamp is known.
502 #
503 # Note that this option can only be used in single-use transactions.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]504 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]505 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
506 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
507 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]508 # reads at a specific timestamp are repeatable; the same read at
509 # the same timestamp always returns the same data. If the
510 # timestamp is in the future, the read will block until the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]511 # specified timestamp, modulo the read&#x27;s deadline.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]512 #
513 # Useful for large scale consistent reads such as mapreduces, or
514 # for coordinating many reads against a consistent snapshot of the
515 # data.
516 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]517 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
518 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
519 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]520 # seconds. Guarantees that all writes that have committed more
521 # than the specified number of seconds ago are visible. Because
522 # Cloud Spanner chooses the exact timestamp, this mode works even if
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]523 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]524 # commit timestamps.
525 #
526 # Useful for reading the freshest data available at a nearby
527 # replica, while bounding the possible staleness if the local
528 # replica has fallen behind.
529 #
530 # Note that this option can only be used in single-use
531 # transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]532 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
533 # the Transaction message that describes the transaction.
534 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]535 # old. The timestamp is chosen soon after the read is started.
536 #
537 # Guarantees that all writes that have committed more than the
538 # specified number of seconds ago are visible. Because Cloud Spanner
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]539 # chooses the exact timestamp, this mode works even if the client&#x27;s
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]540 # local clock is substantially skewed from Cloud Spanner commit
541 # timestamps.
542 #
543 # Useful for reading at nearby replicas without the distributed
544 # timestamp negotiation overhead of `max_staleness`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]545 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]546 # are visible.
547 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]548 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]549 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]550 # Authorization to begin a read-write transaction requires
551 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]552 # on the `session` resource.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]553 # transaction type has no options.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]554 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]555 },
556 }
557
558 x__xgafv: string, V1 error format.
559 Allowed values
560 1 - v1 error format
561 2 - v2 error format
562
563Returns:
564 An object of the form:
565
566 { # A transaction.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]567 &quot;id&quot;: &quot;A String&quot;, # `id` may be used to identify the transaction in subsequent
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]568 # Read,
569 # ExecuteSql,
570 # Commit, or
571 # Rollback calls.
572 #
573 # Single-use read-only transactions do not have IDs, because
574 # single-use transactions do not support multiple requests.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]575 &quot;readTimestamp&quot;: &quot;A String&quot;, # For snapshot read-only transactions, the read timestamp chosen
576 # for the transaction. Not returned by default: see
577 # TransactionOptions.ReadOnly.return_read_timestamp.
578 #
579 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
580 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]581 }</pre>
582</div>
583
584<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]585 <code class="details" id="commit">commit(session, body=None, x__xgafv=None)</code>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]586 <pre>Commits a transaction. The request includes the mutations to be
587applied to rows in the database.
588
589`Commit` might return an `ABORTED` error. This can occur at any time;
590commonly, the cause is conflicts with concurrent
591transactions. However, it can also happen for a variety of other
592reasons. If `Commit` returns `ABORTED`, the caller should re-attempt
593the transaction from the beginning, re-using the same session.
594
595Args:
596 session: string, Required. The session in which the transaction to be committed is running. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]597 body: object, The request body.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]598 The object takes the form of:
599
600{ # The request for Commit.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]601 &quot;mutations&quot;: [ # The mutations to be executed when this transaction commits. All
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]602 # mutations are applied atomically, in the order they appear in
603 # this list.
604 { # A modification to one or more Cloud Spanner rows. Mutations can be
605 # applied to a Cloud Spanner database by sending them in a
606 # Commit call.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]607 &quot;replace&quot;: { # Arguments to insert, update, insert_or_update, and # Like insert, except that if the row already exists, it is
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]608 # deleted, and the column values provided are inserted
609 # instead. Unlike insert_or_update, this means any values not
610 # explicitly written become `NULL`.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]611 #
612 # In an interleaved table, if you create the child table with the
613 # `ON DELETE CASCADE` annotation, then replacing a parent row
614 # also deletes the child rows. Otherwise, you must delete the
615 # child rows before you replace the parent row.
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]616 # replace operations.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]617 &quot;table&quot;: &quot;A String&quot;, # Required. The table whose rows will be written.
618 &quot;values&quot;: [ # The values to be written. `values` can contain more than one
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]619 # list of values. If it does, then multiple rows are written, one
620 # for each entry in `values`. Each list in `values` must have
621 # exactly as many entries as there are entries in columns
622 # above. Sending multiple lists is equivalent to sending multiple
623 # `Mutation`s, each containing one `values` entry and repeating
624 # table and columns. Individual values in each list are
625 # encoded as described here.
626 [
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]627 &quot;&quot;,
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]628 ],
629 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]630 &quot;columns&quot;: [ # The names of the columns in table to be written.
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]631 #
632 # The list of columns must contain enough columns to allow
633 # Cloud Spanner to derive values for all primary key columns in the
634 # row(s) to be modified.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]635 &quot;A String&quot;,
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]636 ],
637 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]638 &quot;delete&quot;: { # Arguments to delete operations. # Delete rows from a table. Succeeds whether or not the named
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]639 # rows were present.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]640 &quot;keySet&quot;: { # `KeySet` defines a collection of Cloud Spanner keys and/or key ranges. All # Required. The primary keys of the rows within table to delete. The
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]641 # primary keys must be specified in the order in which they appear in the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]642 # `PRIMARY KEY()` clause of the table&#x27;s equivalent DDL statement (the DDL
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]643 # statement used to create the table).
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]644 # Delete is idempotent. The transaction will succeed even if some or all
645 # rows do not exist.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]646 # the keys are expected to be in the same table or index. The keys need
647 # not be sorted in any particular way.
648 #
649 # If the same key is specified multiple times in the set (for example
650 # if two ranges, two keys, or a key and a range overlap), Cloud Spanner
651 # behaves as if the key were only specified once.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]652 &quot;ranges&quot;: [ # A list of key ranges. See KeyRange for more information about
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]653 # key range specifications.
654 { # KeyRange represents a range of rows in a table or index.
655 #
656 # A range has a start key and an end key. These keys can be open or
657 # closed, indicating if the range includes rows with that key.
658 #
659 # Keys are represented by lists, where the ith value in the list
660 # corresponds to the ith component of the table or index primary key.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]661 # Individual values are encoded as described
662 # here.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]663 #
664 # For example, consider the following table definition:
665 #
666 # CREATE TABLE UserEvents (
667 # UserName STRING(MAX),
668 # EventDate STRING(10)
669 # ) PRIMARY KEY(UserName, EventDate);
670 #
671 # The following keys name rows in this table:
672 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]673 # &quot;Bob&quot;, &quot;2014-09-23&quot;
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]674 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]675 # Since the `UserEvents` table&#x27;s `PRIMARY KEY` clause names two
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]676 # columns, each `UserEvents` key has two elements; the first is the
677 # `UserName`, and the second is the `EventDate`.
678 #
679 # Key ranges with multiple components are interpreted
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]680 # lexicographically by component using the table or index key&#x27;s declared
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]681 # sort order. For example, the following range returns all events for
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]682 # user `&quot;Bob&quot;` that occurred in the year 2015:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]683 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]684 # &quot;start_closed&quot;: [&quot;Bob&quot;, &quot;2015-01-01&quot;]
685 # &quot;end_closed&quot;: [&quot;Bob&quot;, &quot;2015-12-31&quot;]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]686 #
687 # Start and end keys can omit trailing key components. This affects the
688 # inclusion and exclusion of rows that exactly match the provided key
689 # components: if the key is closed, then rows that exactly match the
690 # provided components are included; if the key is open, then rows
691 # that exactly match are not included.
692 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]693 # For example, the following range includes all events for `&quot;Bob&quot;` that
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]694 # occurred during and after the year 2000:
695 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]696 # &quot;start_closed&quot;: [&quot;Bob&quot;, &quot;2000-01-01&quot;]
697 # &quot;end_closed&quot;: [&quot;Bob&quot;]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]698 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]699 # The next example retrieves all events for `&quot;Bob&quot;`:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]700 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]701 # &quot;start_closed&quot;: [&quot;Bob&quot;]
702 # &quot;end_closed&quot;: [&quot;Bob&quot;]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]703 #
704 # To retrieve events before the year 2000:
705 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]706 # &quot;start_closed&quot;: [&quot;Bob&quot;]
707 # &quot;end_open&quot;: [&quot;Bob&quot;, &quot;2000-01-01&quot;]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]708 #
709 # The following range includes all rows in the table:
710 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]711 # &quot;start_closed&quot;: []
712 # &quot;end_closed&quot;: []
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]713 #
714 # This range returns all users whose `UserName` begins with any
715 # character from A to C:
716 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]717 # &quot;start_closed&quot;: [&quot;A&quot;]
718 # &quot;end_open&quot;: [&quot;D&quot;]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]719 #
720 # This range returns all users whose `UserName` begins with B:
721 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]722 # &quot;start_closed&quot;: [&quot;B&quot;]
723 # &quot;end_open&quot;: [&quot;C&quot;]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]724 #
725 # Key ranges honor column sort order. For example, suppose a table is
726 # defined as follows:
727 #
728 # CREATE TABLE DescendingSortedTable {
729 # Key INT64,
730 # ...
731 # ) PRIMARY KEY(Key DESC);
732 #
733 # The following range retrieves all rows with key values between 1
734 # and 100 inclusive:
735 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]736 # &quot;start_closed&quot;: [&quot;100&quot;]
737 # &quot;end_closed&quot;: [&quot;1&quot;]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]738 #
739 # Note that 100 is passed as the start, and 1 is passed as the end,
740 # because `Key` is a descending column in the schema.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]741 &quot;endOpen&quot;: [ # If the end is open, then the range excludes rows whose first
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]742 # `len(end_open)` key columns exactly match `end_open`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]743 &quot;&quot;,
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]744 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]745 &quot;endClosed&quot;: [ # If the end is closed, then the range includes all rows whose
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]746 # first `len(end_closed)` key columns exactly match `end_closed`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]747 &quot;&quot;,
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]748 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]749 &quot;startOpen&quot;: [ # If the start is open, then the range excludes rows whose first
750 # `len(start_open)` key columns exactly match `start_open`.
751 &quot;&quot;,
752 ],
753 &quot;startClosed&quot;: [ # If the start is closed, then the range includes all rows whose
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]754 # first `len(start_closed)` key columns exactly match `start_closed`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]755 &quot;&quot;,
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]756 ],
757 },
758 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]759 &quot;all&quot;: True or False, # For convenience `all` can be set to `true` to indicate that this
760 # `KeySet` matches all keys in the table or index. Note that any keys
761 # specified in `keys` or `ranges` are only yielded once.
762 &quot;keys&quot;: [ # A list of specific keys. Entries in `keys` should have exactly as
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]763 # many elements as there are columns in the primary or index key
764 # with which this `KeySet` is used. Individual key values are
765 # encoded as described here.
766 [
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]767 &quot;&quot;,
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]768 ],
769 ],
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]770 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]771 &quot;table&quot;: &quot;A String&quot;, # Required. The table whose rows will be deleted.
772 },
773 &quot;insertOrUpdate&quot;: { # Arguments to insert, update, insert_or_update, and # Like insert, except that if the row already exists, then
774 # its column values are overwritten with the ones provided. Any
775 # column values not explicitly written are preserved.
776 #
777 # When using insert_or_update, just as when using insert, all `NOT
778 # NULL` columns in the table must be given a value. This holds true
779 # even when the row already exists and will therefore actually be updated.
780 # replace operations.
781 &quot;table&quot;: &quot;A String&quot;, # Required. The table whose rows will be written.
782 &quot;values&quot;: [ # The values to be written. `values` can contain more than one
783 # list of values. If it does, then multiple rows are written, one
784 # for each entry in `values`. Each list in `values` must have
785 # exactly as many entries as there are entries in columns
786 # above. Sending multiple lists is equivalent to sending multiple
787 # `Mutation`s, each containing one `values` entry and repeating
788 # table and columns. Individual values in each list are
789 # encoded as described here.
790 [
791 &quot;&quot;,
792 ],
793 ],
794 &quot;columns&quot;: [ # The names of the columns in table to be written.
795 #
796 # The list of columns must contain enough columns to allow
797 # Cloud Spanner to derive values for all primary key columns in the
798 # row(s) to be modified.
799 &quot;A String&quot;,
800 ],
801 },
802 &quot;insert&quot;: { # Arguments to insert, update, insert_or_update, and # Insert new rows in a table. If any of the rows already exist,
803 # the write or transaction fails with error `ALREADY_EXISTS`.
804 # replace operations.
805 &quot;table&quot;: &quot;A String&quot;, # Required. The table whose rows will be written.
806 &quot;values&quot;: [ # The values to be written. `values` can contain more than one
807 # list of values. If it does, then multiple rows are written, one
808 # for each entry in `values`. Each list in `values` must have
809 # exactly as many entries as there are entries in columns
810 # above. Sending multiple lists is equivalent to sending multiple
811 # `Mutation`s, each containing one `values` entry and repeating
812 # table and columns. Individual values in each list are
813 # encoded as described here.
814 [
815 &quot;&quot;,
816 ],
817 ],
818 &quot;columns&quot;: [ # The names of the columns in table to be written.
819 #
820 # The list of columns must contain enough columns to allow
821 # Cloud Spanner to derive values for all primary key columns in the
822 # row(s) to be modified.
823 &quot;A String&quot;,
824 ],
825 },
826 &quot;update&quot;: { # Arguments to insert, update, insert_or_update, and # Update existing rows in a table. If any of the rows does not
827 # already exist, the transaction fails with error `NOT_FOUND`.
828 # replace operations.
829 &quot;table&quot;: &quot;A String&quot;, # Required. The table whose rows will be written.
830 &quot;values&quot;: [ # The values to be written. `values` can contain more than one
831 # list of values. If it does, then multiple rows are written, one
832 # for each entry in `values`. Each list in `values` must have
833 # exactly as many entries as there are entries in columns
834 # above. Sending multiple lists is equivalent to sending multiple
835 # `Mutation`s, each containing one `values` entry and repeating
836 # table and columns. Individual values in each list are
837 # encoded as described here.
838 [
839 &quot;&quot;,
840 ],
841 ],
842 &quot;columns&quot;: [ # The names of the columns in table to be written.
843 #
844 # The list of columns must contain enough columns to allow
845 # Cloud Spanner to derive values for all primary key columns in the
846 # row(s) to be modified.
847 &quot;A String&quot;,
848 ],
Thomas Coffee2f245372017-03-27 10:39:26 -0700[diff] [blame]849 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]850 },
851 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]852 &quot;singleUseTransaction&quot;: { # # Transactions # Execute mutations in a temporary transaction. Note that unlike
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]853 # commit of a previously-started transaction, commit with a
854 # temporary transaction is non-idempotent. That is, if the
855 # `CommitRequest` is sent to Cloud Spanner more than once (for
856 # instance, due to retries in the application, or in the
857 # transport library), it is possible that the mutations are
858 # executed more than once. If this is undesirable, use
859 # BeginTransaction and
860 # Commit instead.
861 #
862 #
863 # Each session can have at most one active transaction at a time. After the
864 # active transaction is completed, the session can immediately be
865 # re-used for the next transaction. It is not necessary to create a
866 # new session for each transaction.
867 #
868 # # Transaction Modes
869 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]870 # Cloud Spanner supports three transaction modes:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]871 #
872 # 1. Locking read-write. This type of transaction is the only way
873 # to write data into Cloud Spanner. These transactions rely on
874 # pessimistic locking and, if necessary, two-phase commit.
875 # Locking read-write transactions may abort, requiring the
876 # application to retry.
877 #
878 # 2. Snapshot read-only. This transaction type provides guaranteed
879 # consistency across several reads, but does not allow
880 # writes. Snapshot read-only transactions can be configured to
881 # read at timestamps in the past. Snapshot read-only
882 # transactions do not need to be committed.
883 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]884 # 3. Partitioned DML. This type of transaction is used to execute
885 # a single Partitioned DML statement. Partitioned DML partitions
886 # the key space and runs the DML statement over each partition
887 # in parallel using separate, internal transactions that commit
888 # independently. Partitioned DML transactions do not need to be
889 # committed.
890 #
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]891 # For transactions that only read, snapshot read-only transactions
892 # provide simpler semantics and are almost always faster. In
893 # particular, read-only transactions do not take locks, so they do
894 # not conflict with read-write transactions. As a consequence of not
895 # taking locks, they also do not abort, so retry loops are not needed.
896 #
897 # Transactions may only read/write data in a single database. They
898 # may, however, read/write data in different tables within that
899 # database.
900 #
901 # ## Locking Read-Write Transactions
902 #
903 # Locking transactions may be used to atomically read-modify-write
904 # data anywhere in a database. This type of transaction is externally
905 # consistent.
906 #
907 # Clients should attempt to minimize the amount of time a transaction
908 # is active. Faster transactions commit with higher probability
909 # and cause less contention. Cloud Spanner attempts to keep read locks
910 # active as long as the transaction continues to do reads, and the
911 # transaction has not been terminated by
912 # Commit or
913 # Rollback. Long periods of
914 # inactivity at the client may cause Cloud Spanner to release a
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]915 # transaction&#x27;s locks and abort it.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]916 #
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]917 # Conceptually, a read-write transaction consists of zero or more
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]918 # reads or SQL statements followed by
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]919 # Commit. At any time before
920 # Commit, the client can send a
921 # Rollback request to abort the
922 # transaction.
923 #
924 # ### Semantics
925 #
926 # Cloud Spanner can commit the transaction if all read locks it acquired
927 # are still valid at commit time, and it is able to acquire write
928 # locks for all writes. Cloud Spanner can abort the transaction for any
929 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
930 # that the transaction has not modified any user data in Cloud Spanner.
931 #
932 # Unless the transaction commits, Cloud Spanner makes no guarantees about
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]933 # how long the transaction&#x27;s locks were held for. It is an error to
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]934 # use Cloud Spanner locks for any sort of mutual exclusion other than
935 # between Cloud Spanner transactions themselves.
936 #
937 # ### Retrying Aborted Transactions
938 #
939 # When a transaction aborts, the application can choose to retry the
940 # whole transaction again. To maximize the chances of successfully
941 # committing the retry, the client should execute the retry in the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]942 # same session as the original attempt. The original session&#x27;s lock
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]943 # priority increases with each consecutive abort, meaning that each
944 # attempt has a slightly better chance of success than the previous.
945 #
946 # Under some circumstances (e.g., many transactions attempting to
947 # modify the same row(s)), a transaction can abort many times in a
948 # short period before successfully committing. Thus, it is not a good
949 # idea to cap the number of retries a transaction can attempt;
950 # instead, it is better to limit the total amount of wall time spent
951 # retrying.
952 #
953 # ### Idle Transactions
954 #
955 # A transaction is considered idle if it has no outstanding reads or
956 # SQL queries and has not started a read or SQL query within the last 10
957 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]958 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]959 # fail with error `ABORTED`.
960 #
961 # If this behavior is undesirable, periodically executing a simple
962 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
963 # transaction from becoming idle.
964 #
965 # ## Snapshot Read-Only Transactions
966 #
967 # Snapshot read-only transactions provides a simpler method than
968 # locking read-write transactions for doing several consistent
969 # reads. However, this type of transaction does not support writes.
970 #
971 # Snapshot transactions do not take locks. Instead, they work by
972 # choosing a Cloud Spanner timestamp, then executing all reads at that
973 # timestamp. Since they do not acquire locks, they do not block
974 # concurrent read-write transactions.
975 #
976 # Unlike locking read-write transactions, snapshot read-only
977 # transactions never abort. They can fail if the chosen read
978 # timestamp is garbage collected; however, the default garbage
979 # collection policy is generous enough that most applications do not
980 # need to worry about this in practice.
981 #
982 # Snapshot read-only transactions do not need to call
983 # Commit or
984 # Rollback (and in fact are not
985 # permitted to do so).
986 #
987 # To execute a snapshot transaction, the client specifies a timestamp
988 # bound, which tells Cloud Spanner how to choose a read timestamp.
989 #
990 # The types of timestamp bound are:
991 #
992 # - Strong (the default).
993 # - Bounded staleness.
994 # - Exact staleness.
995 #
996 # If the Cloud Spanner database to be read is geographically distributed,
997 # stale read-only transactions can execute more quickly than strong
998 # or read-write transaction, because they are able to execute far
999 # from the leader replica.
1000 #
1001 # Each type of timestamp bound is discussed in detail below.
1002 #
1003 # ### Strong
1004 #
1005 # Strong reads are guaranteed to see the effects of all transactions
1006 # that have committed before the start of the read. Furthermore, all
1007 # rows yielded by a single read are consistent with each other -- if
1008 # any part of the read observes a transaction, all parts of the read
1009 # see the transaction.
1010 #
1011 # Strong reads are not repeatable: two consecutive strong read-only
1012 # transactions might return inconsistent results if there are
1013 # concurrent writes. If consistency across reads is required, the
1014 # reads should be executed within a transaction or at an exact read
1015 # timestamp.
1016 #
1017 # See TransactionOptions.ReadOnly.strong.
1018 #
1019 # ### Exact Staleness
1020 #
1021 # These timestamp bounds execute reads at a user-specified
1022 # timestamp. Reads at a timestamp are guaranteed to see a consistent
1023 # prefix of the global transaction history: they observe
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1024 # modifications done by all transactions with a commit timestamp &lt;=
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1025 # the read timestamp, and observe none of the modifications done by
1026 # transactions with a larger commit timestamp. They will block until
1027 # all conflicting transactions that may be assigned commit timestamps
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1028 # &lt;= the read timestamp have finished.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1029 #
1030 # The timestamp can either be expressed as an absolute Cloud Spanner commit
1031 # timestamp or a staleness relative to the current time.
1032 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1033 # These modes do not require a &quot;negotiation phase&quot; to pick a
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1034 # timestamp. As a result, they execute slightly faster than the
1035 # equivalent boundedly stale concurrency modes. On the other hand,
1036 # boundedly stale reads usually return fresher results.
1037 #
1038 # See TransactionOptions.ReadOnly.read_timestamp and
1039 # TransactionOptions.ReadOnly.exact_staleness.
1040 #
1041 # ### Bounded Staleness
1042 #
1043 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
1044 # subject to a user-provided staleness bound. Cloud Spanner chooses the
1045 # newest timestamp within the staleness bound that allows execution
1046 # of the reads at the closest available replica without blocking.
1047 #
1048 # All rows yielded are consistent with each other -- if any part of
1049 # the read observes a transaction, all parts of the read see the
1050 # transaction. Boundedly stale reads are not repeatable: two stale
1051 # reads, even if they use the same staleness bound, can execute at
1052 # different timestamps and thus return inconsistent results.
1053 #
1054 # Boundedly stale reads execute in two phases: the first phase
1055 # negotiates a timestamp among all replicas needed to serve the
1056 # read. In the second phase, reads are executed at the negotiated
1057 # timestamp.
1058 #
1059 # As a result of the two phase execution, bounded staleness reads are
1060 # usually a little slower than comparable exact staleness
1061 # reads. However, they are typically able to return fresher
1062 # results, and are more likely to execute at the closest replica.
1063 #
1064 # Because the timestamp negotiation requires up-front knowledge of
1065 # which rows will be read, it can only be used with single-use
1066 # read-only transactions.
1067 #
1068 # See TransactionOptions.ReadOnly.max_staleness and
1069 # TransactionOptions.ReadOnly.min_read_timestamp.
1070 #
1071 # ### Old Read Timestamps and Garbage Collection
1072 #
1073 # Cloud Spanner continuously garbage collects deleted and overwritten data
1074 # in the background to reclaim storage space. This process is known
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1075 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1076 # are one hour old. Because of this, Cloud Spanner cannot perform reads
1077 # at read timestamps more than one hour in the past. This
1078 # restriction also applies to in-progress reads and/or SQL queries whose
1079 # timestamp become too old while executing. Reads and SQL queries with
1080 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1081 #
1082 # ## Partitioned DML Transactions
1083 #
1084 # Partitioned DML transactions are used to execute DML statements with a
1085 # different execution strategy that provides different, and often better,
1086 # scalability properties for large, table-wide operations than DML in a
1087 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
1088 # should prefer using ReadWrite transactions.
1089 #
1090 # Partitioned DML partitions the keyspace and runs the DML statement on each
1091 # partition in separate, internal transactions. These transactions commit
1092 # automatically when complete, and run independently from one another.
1093 #
1094 # To reduce lock contention, this execution strategy only acquires read locks
1095 # on rows that match the WHERE clause of the statement. Additionally, the
1096 # smaller per-partition transactions hold locks for less time.
1097 #
1098 # That said, Partitioned DML is not a drop-in replacement for standard DML used
1099 # in ReadWrite transactions.
1100 #
1101 # - The DML statement must be fully-partitionable. Specifically, the statement
1102 # must be expressible as the union of many statements which each access only
1103 # a single row of the table.
1104 #
1105 # - The statement is not applied atomically to all rows of the table. Rather,
1106 # the statement is applied atomically to partitions of the table, in
1107 # independent transactions. Secondary index rows are updated atomically
1108 # with the base table rows.
1109 #
1110 # - Partitioned DML does not guarantee exactly-once execution semantics
1111 # against a partition. The statement will be applied at least once to each
1112 # partition. It is strongly recommended that the DML statement should be
1113 # idempotent to avoid unexpected results. For instance, it is potentially
1114 # dangerous to run a statement such as
1115 # `UPDATE table SET column = column + 1` as it could be run multiple times
1116 # against some rows.
1117 #
1118 # - The partitions are committed automatically - there is no support for
1119 # Commit or Rollback. If the call returns an error, or if the client issuing
1120 # the ExecuteSql call dies, it is possible that some rows had the statement
1121 # executed on them successfully. It is also possible that statement was
1122 # never executed against other rows.
1123 #
1124 # - Partitioned DML transactions may only contain the execution of a single
1125 # DML statement via ExecuteSql or ExecuteStreamingSql.
1126 #
1127 # - If any error is encountered during the execution of the partitioned DML
1128 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
1129 # value that cannot be stored due to schema constraints), then the
1130 # operation is stopped at that point and an error is returned. It is
1131 # possible that at this point, some partitions have been committed (or even
1132 # committed multiple times), and other partitions have not been run at all.
1133 #
1134 # Given the above, Partitioned DML is good fit for large, database-wide,
1135 # operations that are idempotent, such as deleting old rows from a very large
1136 # table.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1137 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1138 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1139 # Authorization to begin a Partitioned DML transaction requires
1140 # `spanner.databases.beginPartitionedDmlTransaction` permission
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1141 # on the `session` resource.
1142 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1143 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1144 #
1145 # Authorization to begin a read-only transaction requires
1146 # `spanner.databases.beginReadOnlyTransaction` permission
1147 # on the `session` resource.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1148 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1149 #
1150 # This is useful for requesting fresher data than some previous
1151 # read, or data that is fresh enough to observe the effects of some
1152 # previously committed transaction whose timestamp is known.
1153 #
1154 # Note that this option can only be used in single-use transactions.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1155 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1156 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
1157 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
1158 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1159 # reads at a specific timestamp are repeatable; the same read at
1160 # the same timestamp always returns the same data. If the
1161 # timestamp is in the future, the read will block until the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1162 # specified timestamp, modulo the read&#x27;s deadline.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1163 #
1164 # Useful for large scale consistent reads such as mapreduces, or
1165 # for coordinating many reads against a consistent snapshot of the
1166 # data.
1167 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1168 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
1169 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
1170 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1171 # seconds. Guarantees that all writes that have committed more
1172 # than the specified number of seconds ago are visible. Because
1173 # Cloud Spanner chooses the exact timestamp, this mode works even if
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1174 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1175 # commit timestamps.
1176 #
1177 # Useful for reading the freshest data available at a nearby
1178 # replica, while bounding the possible staleness if the local
1179 # replica has fallen behind.
1180 #
1181 # Note that this option can only be used in single-use
1182 # transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1183 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
1184 # the Transaction message that describes the transaction.
1185 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1186 # old. The timestamp is chosen soon after the read is started.
1187 #
1188 # Guarantees that all writes that have committed more than the
1189 # specified number of seconds ago are visible. Because Cloud Spanner
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1190 # chooses the exact timestamp, this mode works even if the client&#x27;s
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1191 # local clock is substantially skewed from Cloud Spanner commit
1192 # timestamps.
1193 #
1194 # Useful for reading at nearby replicas without the distributed
1195 # timestamp negotiation overhead of `max_staleness`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1196 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1197 # are visible.
1198 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1199 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1200 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1201 # Authorization to begin a read-write transaction requires
1202 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1203 # on the `session` resource.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1204 # transaction type has no options.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1205 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1206 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1207 &quot;transactionId&quot;: &quot;A String&quot;, # Commit a previously-started transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1208 }
1209
1210 x__xgafv: string, V1 error format.
1211 Allowed values
1212 1 - v1 error format
1213 2 - v2 error format
1214
1215Returns:
1216 An object of the form:
1217
1218 { # The response for Commit.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1219 &quot;commitTimestamp&quot;: &quot;A String&quot;, # The Cloud Spanner timestamp at which the transaction committed.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1220 }</pre>
1221</div>
1222
1223<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1224 <code class="details" id="create">create(database, body=None, x__xgafv=None)</code>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1225 <pre>Creates a new session. A session can be used to perform
1226transactions that read and/or modify data in a Cloud Spanner database.
1227Sessions are meant to be reused for many consecutive
1228transactions.
1229
1230Sessions can only execute one transaction at a time. To execute
1231multiple concurrent read-write/write-only transactions, create
1232multiple sessions. Note that standalone reads and queries use a
1233transaction internally, and count toward the one transaction
1234limit.
1235
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1236Active sessions use additional server resources, so it is a good idea to
1237delete idle and unneeded sessions.
1238Aside from explicit deletes, Cloud Spanner may delete sessions for which no
Sai Cheemalapatie833b792017-03-24 15:06:46 -0700[diff] [blame]1239operations are sent for more than an hour. If a session is deleted,
1240requests to it return `NOT_FOUND`.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1241
1242Idle sessions can be kept alive by sending a trivial SQL query
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1243periodically, e.g., `&quot;SELECT 1&quot;`.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1244
1245Args:
1246 database: string, Required. The database in which the new session is created. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1247 body: object, The request body.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1248 The object takes the form of:
1249
1250{ # The request for CreateSession.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1251 &quot;session&quot;: { # A session in the Cloud Spanner API. # The session to create.
1252 &quot;approximateLastUseTime&quot;: &quot;A String&quot;, # Output only. The approximate timestamp when the session is last used. It is
1253 # typically earlier than the actual last use time.
1254 &quot;name&quot;: &quot;A String&quot;, # The name of the session. This is always system-assigned; values provided
1255 # when creating a session are ignored.
1256 &quot;createTime&quot;: &quot;A String&quot;, # Output only. The timestamp when the session is created.
1257 &quot;labels&quot;: { # The labels for the session.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1258 #
1259 # * Label keys must be between 1 and 63 characters long and must conform to
1260 # the following regular expression: `[a-z]([-a-z0-9]*[a-z0-9])?`.
1261 # * Label values must be between 0 and 63 characters long and must conform
1262 # to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`.
1263 # * No more than 64 labels can be associated with a given session.
1264 #
1265 # See https://goo.gl/xmQnxf for more information on and examples of labels.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1266 &quot;a_key&quot;: &quot;A String&quot;,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1267 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1268 },
1269 }
1270
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1271 x__xgafv: string, V1 error format.
1272 Allowed values
1273 1 - v1 error format
1274 2 - v2 error format
1275
1276Returns:
1277 An object of the form:
1278
1279 { # A session in the Cloud Spanner API.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1280 &quot;approximateLastUseTime&quot;: &quot;A String&quot;, # Output only. The approximate timestamp when the session is last used. It is
1281 # typically earlier than the actual last use time.
1282 &quot;name&quot;: &quot;A String&quot;, # The name of the session. This is always system-assigned; values provided
1283 # when creating a session are ignored.
1284 &quot;createTime&quot;: &quot;A String&quot;, # Output only. The timestamp when the session is created.
1285 &quot;labels&quot;: { # The labels for the session.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1286 #
1287 # * Label keys must be between 1 and 63 characters long and must conform to
1288 # the following regular expression: `[a-z]([-a-z0-9]*[a-z0-9])?`.
1289 # * Label values must be between 0 and 63 characters long and must conform
1290 # to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`.
1291 # * No more than 64 labels can be associated with a given session.
1292 #
1293 # See https://goo.gl/xmQnxf for more information on and examples of labels.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1294 &quot;a_key&quot;: &quot;A String&quot;,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1295 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1296 }</pre>
1297</div>
1298
1299<div class="method">
1300 <code class="details" id="delete">delete(name, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1301 <pre>Ends a session, releasing server resources associated with it. This will
1302asynchronously trigger cancellation of any operations that are running with
1303this session.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1304
1305Args:
1306 name: string, Required. The name of the session to delete. (required)
1307 x__xgafv: string, V1 error format.
1308 Allowed values
1309 1 - v1 error format
1310 2 - v2 error format
1311
1312Returns:
1313 An object of the form:
1314
1315 { # A generic empty message that you can re-use to avoid defining duplicated
1316 # empty messages in your APIs. A typical example is to use it as the request
1317 # or the response type of an API method. For instance:
1318 #
1319 # service Foo {
1320 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
1321 # }
1322 #
1323 # The JSON representation for `Empty` is empty JSON object `{}`.
1324 }</pre>
1325</div>
1326
1327<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1328 <code class="details" id="executeBatchDml">executeBatchDml(session, body=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1329 <pre>Executes a batch of SQL DML statements. This method allows many statements
1330to be run with lower latency than submitting them sequentially with
1331ExecuteSql.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1332
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1333Statements are executed in sequential order. A request can succeed even if
1334a statement fails. The ExecuteBatchDmlResponse.status field in the
1335response provides information about the statement that failed. Clients must
1336inspect this field to determine whether an error occurred.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1337
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1338Execution stops after the first failed statement; the remaining statements
1339are not executed.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1340
1341Args:
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1342 session: string, Required. The session in which the DML statements should be performed. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1343 body: object, The request body.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1344 The object takes the form of:
1345
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1346{ # The request for ExecuteBatchDml.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1347 &quot;transaction&quot;: { # This message is used to select the transaction in which a # Required. The transaction to use. Must be a read-write transaction.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1348 #
1349 # To protect against replays, single-use transactions are not supported. The
1350 # caller must either supply an existing transaction ID or begin a new
1351 # transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1352 # Read or
1353 # ExecuteSql call runs.
1354 #
1355 # See TransactionOptions for more information about transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1356 &quot;singleUse&quot;: { # # Transactions # Execute the read or SQL query in a temporary transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1357 # This is the most efficient way to execute a transaction that
1358 # consists of a single SQL query.
1359 #
1360 #
1361 # Each session can have at most one active transaction at a time. After the
1362 # active transaction is completed, the session can immediately be
1363 # re-used for the next transaction. It is not necessary to create a
1364 # new session for each transaction.
1365 #
1366 # # Transaction Modes
1367 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1368 # Cloud Spanner supports three transaction modes:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1369 #
1370 # 1. Locking read-write. This type of transaction is the only way
1371 # to write data into Cloud Spanner. These transactions rely on
1372 # pessimistic locking and, if necessary, two-phase commit.
1373 # Locking read-write transactions may abort, requiring the
1374 # application to retry.
1375 #
1376 # 2. Snapshot read-only. This transaction type provides guaranteed
1377 # consistency across several reads, but does not allow
1378 # writes. Snapshot read-only transactions can be configured to
1379 # read at timestamps in the past. Snapshot read-only
1380 # transactions do not need to be committed.
1381 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1382 # 3. Partitioned DML. This type of transaction is used to execute
1383 # a single Partitioned DML statement. Partitioned DML partitions
1384 # the key space and runs the DML statement over each partition
1385 # in parallel using separate, internal transactions that commit
1386 # independently. Partitioned DML transactions do not need to be
1387 # committed.
1388 #
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1389 # For transactions that only read, snapshot read-only transactions
1390 # provide simpler semantics and are almost always faster. In
1391 # particular, read-only transactions do not take locks, so they do
1392 # not conflict with read-write transactions. As a consequence of not
1393 # taking locks, they also do not abort, so retry loops are not needed.
1394 #
1395 # Transactions may only read/write data in a single database. They
1396 # may, however, read/write data in different tables within that
1397 # database.
1398 #
1399 # ## Locking Read-Write Transactions
1400 #
1401 # Locking transactions may be used to atomically read-modify-write
1402 # data anywhere in a database. This type of transaction is externally
1403 # consistent.
1404 #
1405 # Clients should attempt to minimize the amount of time a transaction
1406 # is active. Faster transactions commit with higher probability
1407 # and cause less contention. Cloud Spanner attempts to keep read locks
1408 # active as long as the transaction continues to do reads, and the
1409 # transaction has not been terminated by
1410 # Commit or
1411 # Rollback. Long periods of
1412 # inactivity at the client may cause Cloud Spanner to release a
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1413 # transaction&#x27;s locks and abort it.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1414 #
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1415 # Conceptually, a read-write transaction consists of zero or more
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1416 # reads or SQL statements followed by
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1417 # Commit. At any time before
1418 # Commit, the client can send a
1419 # Rollback request to abort the
1420 # transaction.
1421 #
1422 # ### Semantics
1423 #
1424 # Cloud Spanner can commit the transaction if all read locks it acquired
1425 # are still valid at commit time, and it is able to acquire write
1426 # locks for all writes. Cloud Spanner can abort the transaction for any
1427 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
1428 # that the transaction has not modified any user data in Cloud Spanner.
1429 #
1430 # Unless the transaction commits, Cloud Spanner makes no guarantees about
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1431 # how long the transaction&#x27;s locks were held for. It is an error to
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1432 # use Cloud Spanner locks for any sort of mutual exclusion other than
1433 # between Cloud Spanner transactions themselves.
1434 #
1435 # ### Retrying Aborted Transactions
1436 #
1437 # When a transaction aborts, the application can choose to retry the
1438 # whole transaction again. To maximize the chances of successfully
1439 # committing the retry, the client should execute the retry in the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1440 # same session as the original attempt. The original session&#x27;s lock
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1441 # priority increases with each consecutive abort, meaning that each
1442 # attempt has a slightly better chance of success than the previous.
1443 #
1444 # Under some circumstances (e.g., many transactions attempting to
1445 # modify the same row(s)), a transaction can abort many times in a
1446 # short period before successfully committing. Thus, it is not a good
1447 # idea to cap the number of retries a transaction can attempt;
1448 # instead, it is better to limit the total amount of wall time spent
1449 # retrying.
1450 #
1451 # ### Idle Transactions
1452 #
1453 # A transaction is considered idle if it has no outstanding reads or
1454 # SQL queries and has not started a read or SQL query within the last 10
1455 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1456 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1457 # fail with error `ABORTED`.
1458 #
1459 # If this behavior is undesirable, periodically executing a simple
1460 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
1461 # transaction from becoming idle.
1462 #
1463 # ## Snapshot Read-Only Transactions
1464 #
1465 # Snapshot read-only transactions provides a simpler method than
1466 # locking read-write transactions for doing several consistent
1467 # reads. However, this type of transaction does not support writes.
1468 #
1469 # Snapshot transactions do not take locks. Instead, they work by
1470 # choosing a Cloud Spanner timestamp, then executing all reads at that
1471 # timestamp. Since they do not acquire locks, they do not block
1472 # concurrent read-write transactions.
1473 #
1474 # Unlike locking read-write transactions, snapshot read-only
1475 # transactions never abort. They can fail if the chosen read
1476 # timestamp is garbage collected; however, the default garbage
1477 # collection policy is generous enough that most applications do not
1478 # need to worry about this in practice.
1479 #
1480 # Snapshot read-only transactions do not need to call
1481 # Commit or
1482 # Rollback (and in fact are not
1483 # permitted to do so).
1484 #
1485 # To execute a snapshot transaction, the client specifies a timestamp
1486 # bound, which tells Cloud Spanner how to choose a read timestamp.
1487 #
1488 # The types of timestamp bound are:
1489 #
1490 # - Strong (the default).
1491 # - Bounded staleness.
1492 # - Exact staleness.
1493 #
1494 # If the Cloud Spanner database to be read is geographically distributed,
1495 # stale read-only transactions can execute more quickly than strong
1496 # or read-write transaction, because they are able to execute far
1497 # from the leader replica.
1498 #
1499 # Each type of timestamp bound is discussed in detail below.
1500 #
1501 # ### Strong
1502 #
1503 # Strong reads are guaranteed to see the effects of all transactions
1504 # that have committed before the start of the read. Furthermore, all
1505 # rows yielded by a single read are consistent with each other -- if
1506 # any part of the read observes a transaction, all parts of the read
1507 # see the transaction.
1508 #
1509 # Strong reads are not repeatable: two consecutive strong read-only
1510 # transactions might return inconsistent results if there are
1511 # concurrent writes. If consistency across reads is required, the
1512 # reads should be executed within a transaction or at an exact read
1513 # timestamp.
1514 #
1515 # See TransactionOptions.ReadOnly.strong.
1516 #
1517 # ### Exact Staleness
1518 #
1519 # These timestamp bounds execute reads at a user-specified
1520 # timestamp. Reads at a timestamp are guaranteed to see a consistent
1521 # prefix of the global transaction history: they observe
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1522 # modifications done by all transactions with a commit timestamp &lt;=
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1523 # the read timestamp, and observe none of the modifications done by
1524 # transactions with a larger commit timestamp. They will block until
1525 # all conflicting transactions that may be assigned commit timestamps
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1526 # &lt;= the read timestamp have finished.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1527 #
1528 # The timestamp can either be expressed as an absolute Cloud Spanner commit
1529 # timestamp or a staleness relative to the current time.
1530 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1531 # These modes do not require a &quot;negotiation phase&quot; to pick a
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1532 # timestamp. As a result, they execute slightly faster than the
1533 # equivalent boundedly stale concurrency modes. On the other hand,
1534 # boundedly stale reads usually return fresher results.
1535 #
1536 # See TransactionOptions.ReadOnly.read_timestamp and
1537 # TransactionOptions.ReadOnly.exact_staleness.
1538 #
1539 # ### Bounded Staleness
1540 #
1541 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
1542 # subject to a user-provided staleness bound. Cloud Spanner chooses the
1543 # newest timestamp within the staleness bound that allows execution
1544 # of the reads at the closest available replica without blocking.
1545 #
1546 # All rows yielded are consistent with each other -- if any part of
1547 # the read observes a transaction, all parts of the read see the
1548 # transaction. Boundedly stale reads are not repeatable: two stale
1549 # reads, even if they use the same staleness bound, can execute at
1550 # different timestamps and thus return inconsistent results.
1551 #
1552 # Boundedly stale reads execute in two phases: the first phase
1553 # negotiates a timestamp among all replicas needed to serve the
1554 # read. In the second phase, reads are executed at the negotiated
1555 # timestamp.
1556 #
1557 # As a result of the two phase execution, bounded staleness reads are
1558 # usually a little slower than comparable exact staleness
1559 # reads. However, they are typically able to return fresher
1560 # results, and are more likely to execute at the closest replica.
1561 #
1562 # Because the timestamp negotiation requires up-front knowledge of
1563 # which rows will be read, it can only be used with single-use
1564 # read-only transactions.
1565 #
1566 # See TransactionOptions.ReadOnly.max_staleness and
1567 # TransactionOptions.ReadOnly.min_read_timestamp.
1568 #
1569 # ### Old Read Timestamps and Garbage Collection
1570 #
1571 # Cloud Spanner continuously garbage collects deleted and overwritten data
1572 # in the background to reclaim storage space. This process is known
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1573 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1574 # are one hour old. Because of this, Cloud Spanner cannot perform reads
1575 # at read timestamps more than one hour in the past. This
1576 # restriction also applies to in-progress reads and/or SQL queries whose
1577 # timestamp become too old while executing. Reads and SQL queries with
1578 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1579 #
1580 # ## Partitioned DML Transactions
1581 #
1582 # Partitioned DML transactions are used to execute DML statements with a
1583 # different execution strategy that provides different, and often better,
1584 # scalability properties for large, table-wide operations than DML in a
1585 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
1586 # should prefer using ReadWrite transactions.
1587 #
1588 # Partitioned DML partitions the keyspace and runs the DML statement on each
1589 # partition in separate, internal transactions. These transactions commit
1590 # automatically when complete, and run independently from one another.
1591 #
1592 # To reduce lock contention, this execution strategy only acquires read locks
1593 # on rows that match the WHERE clause of the statement. Additionally, the
1594 # smaller per-partition transactions hold locks for less time.
1595 #
1596 # That said, Partitioned DML is not a drop-in replacement for standard DML used
1597 # in ReadWrite transactions.
1598 #
1599 # - The DML statement must be fully-partitionable. Specifically, the statement
1600 # must be expressible as the union of many statements which each access only
1601 # a single row of the table.
1602 #
1603 # - The statement is not applied atomically to all rows of the table. Rather,
1604 # the statement is applied atomically to partitions of the table, in
1605 # independent transactions. Secondary index rows are updated atomically
1606 # with the base table rows.
1607 #
1608 # - Partitioned DML does not guarantee exactly-once execution semantics
1609 # against a partition. The statement will be applied at least once to each
1610 # partition. It is strongly recommended that the DML statement should be
1611 # idempotent to avoid unexpected results. For instance, it is potentially
1612 # dangerous to run a statement such as
1613 # `UPDATE table SET column = column + 1` as it could be run multiple times
1614 # against some rows.
1615 #
1616 # - The partitions are committed automatically - there is no support for
1617 # Commit or Rollback. If the call returns an error, or if the client issuing
1618 # the ExecuteSql call dies, it is possible that some rows had the statement
1619 # executed on them successfully. It is also possible that statement was
1620 # never executed against other rows.
1621 #
1622 # - Partitioned DML transactions may only contain the execution of a single
1623 # DML statement via ExecuteSql or ExecuteStreamingSql.
1624 #
1625 # - If any error is encountered during the execution of the partitioned DML
1626 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
1627 # value that cannot be stored due to schema constraints), then the
1628 # operation is stopped at that point and an error is returned. It is
1629 # possible that at this point, some partitions have been committed (or even
1630 # committed multiple times), and other partitions have not been run at all.
1631 #
1632 # Given the above, Partitioned DML is good fit for large, database-wide,
1633 # operations that are idempotent, such as deleting old rows from a very large
1634 # table.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1635 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1636 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1637 # Authorization to begin a Partitioned DML transaction requires
1638 # `spanner.databases.beginPartitionedDmlTransaction` permission
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1639 # on the `session` resource.
1640 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1641 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1642 #
1643 # Authorization to begin a read-only transaction requires
1644 # `spanner.databases.beginReadOnlyTransaction` permission
1645 # on the `session` resource.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1646 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1647 #
1648 # This is useful for requesting fresher data than some previous
1649 # read, or data that is fresh enough to observe the effects of some
1650 # previously committed transaction whose timestamp is known.
1651 #
1652 # Note that this option can only be used in single-use transactions.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1653 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1654 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
1655 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
1656 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1657 # reads at a specific timestamp are repeatable; the same read at
1658 # the same timestamp always returns the same data. If the
1659 # timestamp is in the future, the read will block until the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1660 # specified timestamp, modulo the read&#x27;s deadline.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]1661 #
1662 # Useful for large scale consistent reads such as mapreduces, or
1663 # for coordinating many reads against a consistent snapshot of the
1664 # data.
1665 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1666 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
1667 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
1668 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1669 # seconds. Guarantees that all writes that have committed more
1670 # than the specified number of seconds ago are visible. Because
1671 # Cloud Spanner chooses the exact timestamp, this mode works even if
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1672 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1673 # commit timestamps.
1674 #
1675 # Useful for reading the freshest data available at a nearby
1676 # replica, while bounding the possible staleness if the local
1677 # replica has fallen behind.
1678 #
1679 # Note that this option can only be used in single-use
1680 # transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1681 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
1682 # the Transaction message that describes the transaction.
1683 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1684 # old. The timestamp is chosen soon after the read is started.
1685 #
1686 # Guarantees that all writes that have committed more than the
1687 # specified number of seconds ago are visible. Because Cloud Spanner
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1688 # chooses the exact timestamp, this mode works even if the client&#x27;s
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1689 # local clock is substantially skewed from Cloud Spanner commit
1690 # timestamps.
1691 #
1692 # Useful for reading at nearby replicas without the distributed
1693 # timestamp negotiation overhead of `max_staleness`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1694 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]1695 # are visible.
1696 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1697 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
1698 #
1699 # Authorization to begin a read-write transaction requires
1700 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
1701 # on the `session` resource.
1702 # transaction type has no options.
1703 },
1704 },
1705 &quot;begin&quot;: { # # Transactions # Begin a new transaction and execute this read or SQL query in
1706 # it. The transaction ID of the new transaction is returned in
1707 # ResultSetMetadata.transaction, which is a Transaction.
1708 #
1709 #
1710 # Each session can have at most one active transaction at a time. After the
1711 # active transaction is completed, the session can immediately be
1712 # re-used for the next transaction. It is not necessary to create a
1713 # new session for each transaction.
1714 #
1715 # # Transaction Modes
1716 #
1717 # Cloud Spanner supports three transaction modes:
1718 #
1719 # 1. Locking read-write. This type of transaction is the only way
1720 # to write data into Cloud Spanner. These transactions rely on
1721 # pessimistic locking and, if necessary, two-phase commit.
1722 # Locking read-write transactions may abort, requiring the
1723 # application to retry.
1724 #
1725 # 2. Snapshot read-only. This transaction type provides guaranteed
1726 # consistency across several reads, but does not allow
1727 # writes. Snapshot read-only transactions can be configured to
1728 # read at timestamps in the past. Snapshot read-only
1729 # transactions do not need to be committed.
1730 #
1731 # 3. Partitioned DML. This type of transaction is used to execute
1732 # a single Partitioned DML statement. Partitioned DML partitions
1733 # the key space and runs the DML statement over each partition
1734 # in parallel using separate, internal transactions that commit
1735 # independently. Partitioned DML transactions do not need to be
1736 # committed.
1737 #
1738 # For transactions that only read, snapshot read-only transactions
1739 # provide simpler semantics and are almost always faster. In
1740 # particular, read-only transactions do not take locks, so they do
1741 # not conflict with read-write transactions. As a consequence of not
1742 # taking locks, they also do not abort, so retry loops are not needed.
1743 #
1744 # Transactions may only read/write data in a single database. They
1745 # may, however, read/write data in different tables within that
1746 # database.
1747 #
1748 # ## Locking Read-Write Transactions
1749 #
1750 # Locking transactions may be used to atomically read-modify-write
1751 # data anywhere in a database. This type of transaction is externally
1752 # consistent.
1753 #
1754 # Clients should attempt to minimize the amount of time a transaction
1755 # is active. Faster transactions commit with higher probability
1756 # and cause less contention. Cloud Spanner attempts to keep read locks
1757 # active as long as the transaction continues to do reads, and the
1758 # transaction has not been terminated by
1759 # Commit or
1760 # Rollback. Long periods of
1761 # inactivity at the client may cause Cloud Spanner to release a
1762 # transaction&#x27;s locks and abort it.
1763 #
1764 # Conceptually, a read-write transaction consists of zero or more
1765 # reads or SQL statements followed by
1766 # Commit. At any time before
1767 # Commit, the client can send a
1768 # Rollback request to abort the
1769 # transaction.
1770 #
1771 # ### Semantics
1772 #
1773 # Cloud Spanner can commit the transaction if all read locks it acquired
1774 # are still valid at commit time, and it is able to acquire write
1775 # locks for all writes. Cloud Spanner can abort the transaction for any
1776 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
1777 # that the transaction has not modified any user data in Cloud Spanner.
1778 #
1779 # Unless the transaction commits, Cloud Spanner makes no guarantees about
1780 # how long the transaction&#x27;s locks were held for. It is an error to
1781 # use Cloud Spanner locks for any sort of mutual exclusion other than
1782 # between Cloud Spanner transactions themselves.
1783 #
1784 # ### Retrying Aborted Transactions
1785 #
1786 # When a transaction aborts, the application can choose to retry the
1787 # whole transaction again. To maximize the chances of successfully
1788 # committing the retry, the client should execute the retry in the
1789 # same session as the original attempt. The original session&#x27;s lock
1790 # priority increases with each consecutive abort, meaning that each
1791 # attempt has a slightly better chance of success than the previous.
1792 #
1793 # Under some circumstances (e.g., many transactions attempting to
1794 # modify the same row(s)), a transaction can abort many times in a
1795 # short period before successfully committing. Thus, it is not a good
1796 # idea to cap the number of retries a transaction can attempt;
1797 # instead, it is better to limit the total amount of wall time spent
1798 # retrying.
1799 #
1800 # ### Idle Transactions
1801 #
1802 # A transaction is considered idle if it has no outstanding reads or
1803 # SQL queries and has not started a read or SQL query within the last 10
1804 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
1805 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
1806 # fail with error `ABORTED`.
1807 #
1808 # If this behavior is undesirable, periodically executing a simple
1809 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
1810 # transaction from becoming idle.
1811 #
1812 # ## Snapshot Read-Only Transactions
1813 #
1814 # Snapshot read-only transactions provides a simpler method than
1815 # locking read-write transactions for doing several consistent
1816 # reads. However, this type of transaction does not support writes.
1817 #
1818 # Snapshot transactions do not take locks. Instead, they work by
1819 # choosing a Cloud Spanner timestamp, then executing all reads at that
1820 # timestamp. Since they do not acquire locks, they do not block
1821 # concurrent read-write transactions.
1822 #
1823 # Unlike locking read-write transactions, snapshot read-only
1824 # transactions never abort. They can fail if the chosen read
1825 # timestamp is garbage collected; however, the default garbage
1826 # collection policy is generous enough that most applications do not
1827 # need to worry about this in practice.
1828 #
1829 # Snapshot read-only transactions do not need to call
1830 # Commit or
1831 # Rollback (and in fact are not
1832 # permitted to do so).
1833 #
1834 # To execute a snapshot transaction, the client specifies a timestamp
1835 # bound, which tells Cloud Spanner how to choose a read timestamp.
1836 #
1837 # The types of timestamp bound are:
1838 #
1839 # - Strong (the default).
1840 # - Bounded staleness.
1841 # - Exact staleness.
1842 #
1843 # If the Cloud Spanner database to be read is geographically distributed,
1844 # stale read-only transactions can execute more quickly than strong
1845 # or read-write transaction, because they are able to execute far
1846 # from the leader replica.
1847 #
1848 # Each type of timestamp bound is discussed in detail below.
1849 #
1850 # ### Strong
1851 #
1852 # Strong reads are guaranteed to see the effects of all transactions
1853 # that have committed before the start of the read. Furthermore, all
1854 # rows yielded by a single read are consistent with each other -- if
1855 # any part of the read observes a transaction, all parts of the read
1856 # see the transaction.
1857 #
1858 # Strong reads are not repeatable: two consecutive strong read-only
1859 # transactions might return inconsistent results if there are
1860 # concurrent writes. If consistency across reads is required, the
1861 # reads should be executed within a transaction or at an exact read
1862 # timestamp.
1863 #
1864 # See TransactionOptions.ReadOnly.strong.
1865 #
1866 # ### Exact Staleness
1867 #
1868 # These timestamp bounds execute reads at a user-specified
1869 # timestamp. Reads at a timestamp are guaranteed to see a consistent
1870 # prefix of the global transaction history: they observe
1871 # modifications done by all transactions with a commit timestamp &lt;=
1872 # the read timestamp, and observe none of the modifications done by
1873 # transactions with a larger commit timestamp. They will block until
1874 # all conflicting transactions that may be assigned commit timestamps
1875 # &lt;= the read timestamp have finished.
1876 #
1877 # The timestamp can either be expressed as an absolute Cloud Spanner commit
1878 # timestamp or a staleness relative to the current time.
1879 #
1880 # These modes do not require a &quot;negotiation phase&quot; to pick a
1881 # timestamp. As a result, they execute slightly faster than the
1882 # equivalent boundedly stale concurrency modes. On the other hand,
1883 # boundedly stale reads usually return fresher results.
1884 #
1885 # See TransactionOptions.ReadOnly.read_timestamp and
1886 # TransactionOptions.ReadOnly.exact_staleness.
1887 #
1888 # ### Bounded Staleness
1889 #
1890 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
1891 # subject to a user-provided staleness bound. Cloud Spanner chooses the
1892 # newest timestamp within the staleness bound that allows execution
1893 # of the reads at the closest available replica without blocking.
1894 #
1895 # All rows yielded are consistent with each other -- if any part of
1896 # the read observes a transaction, all parts of the read see the
1897 # transaction. Boundedly stale reads are not repeatable: two stale
1898 # reads, even if they use the same staleness bound, can execute at
1899 # different timestamps and thus return inconsistent results.
1900 #
1901 # Boundedly stale reads execute in two phases: the first phase
1902 # negotiates a timestamp among all replicas needed to serve the
1903 # read. In the second phase, reads are executed at the negotiated
1904 # timestamp.
1905 #
1906 # As a result of the two phase execution, bounded staleness reads are
1907 # usually a little slower than comparable exact staleness
1908 # reads. However, they are typically able to return fresher
1909 # results, and are more likely to execute at the closest replica.
1910 #
1911 # Because the timestamp negotiation requires up-front knowledge of
1912 # which rows will be read, it can only be used with single-use
1913 # read-only transactions.
1914 #
1915 # See TransactionOptions.ReadOnly.max_staleness and
1916 # TransactionOptions.ReadOnly.min_read_timestamp.
1917 #
1918 # ### Old Read Timestamps and Garbage Collection
1919 #
1920 # Cloud Spanner continuously garbage collects deleted and overwritten data
1921 # in the background to reclaim storage space. This process is known
1922 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
1923 # are one hour old. Because of this, Cloud Spanner cannot perform reads
1924 # at read timestamps more than one hour in the past. This
1925 # restriction also applies to in-progress reads and/or SQL queries whose
1926 # timestamp become too old while executing. Reads and SQL queries with
1927 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
1928 #
1929 # ## Partitioned DML Transactions
1930 #
1931 # Partitioned DML transactions are used to execute DML statements with a
1932 # different execution strategy that provides different, and often better,
1933 # scalability properties for large, table-wide operations than DML in a
1934 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
1935 # should prefer using ReadWrite transactions.
1936 #
1937 # Partitioned DML partitions the keyspace and runs the DML statement on each
1938 # partition in separate, internal transactions. These transactions commit
1939 # automatically when complete, and run independently from one another.
1940 #
1941 # To reduce lock contention, this execution strategy only acquires read locks
1942 # on rows that match the WHERE clause of the statement. Additionally, the
1943 # smaller per-partition transactions hold locks for less time.
1944 #
1945 # That said, Partitioned DML is not a drop-in replacement for standard DML used
1946 # in ReadWrite transactions.
1947 #
1948 # - The DML statement must be fully-partitionable. Specifically, the statement
1949 # must be expressible as the union of many statements which each access only
1950 # a single row of the table.
1951 #
1952 # - The statement is not applied atomically to all rows of the table. Rather,
1953 # the statement is applied atomically to partitions of the table, in
1954 # independent transactions. Secondary index rows are updated atomically
1955 # with the base table rows.
1956 #
1957 # - Partitioned DML does not guarantee exactly-once execution semantics
1958 # against a partition. The statement will be applied at least once to each
1959 # partition. It is strongly recommended that the DML statement should be
1960 # idempotent to avoid unexpected results. For instance, it is potentially
1961 # dangerous to run a statement such as
1962 # `UPDATE table SET column = column + 1` as it could be run multiple times
1963 # against some rows.
1964 #
1965 # - The partitions are committed automatically - there is no support for
1966 # Commit or Rollback. If the call returns an error, or if the client issuing
1967 # the ExecuteSql call dies, it is possible that some rows had the statement
1968 # executed on them successfully. It is also possible that statement was
1969 # never executed against other rows.
1970 #
1971 # - Partitioned DML transactions may only contain the execution of a single
1972 # DML statement via ExecuteSql or ExecuteStreamingSql.
1973 #
1974 # - If any error is encountered during the execution of the partitioned DML
1975 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
1976 # value that cannot be stored due to schema constraints), then the
1977 # operation is stopped at that point and an error is returned. It is
1978 # possible that at this point, some partitions have been committed (or even
1979 # committed multiple times), and other partitions have not been run at all.
1980 #
1981 # Given the above, Partitioned DML is good fit for large, database-wide,
1982 # operations that are idempotent, such as deleting old rows from a very large
1983 # table.
1984 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1985 #
1986 # Authorization to begin a Partitioned DML transaction requires
1987 # `spanner.databases.beginPartitionedDmlTransaction` permission
1988 # on the `session` resource.
1989 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]1990 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
1991 #
1992 # Authorization to begin a read-only transaction requires
1993 # `spanner.databases.beginReadOnlyTransaction` permission
1994 # on the `session` resource.
1995 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
1996 #
1997 # This is useful for requesting fresher data than some previous
1998 # read, or data that is fresh enough to observe the effects of some
1999 # previously committed transaction whose timestamp is known.
2000 #
2001 # Note that this option can only be used in single-use transactions.
2002 #
2003 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
2004 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
2005 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
2006 # reads at a specific timestamp are repeatable; the same read at
2007 # the same timestamp always returns the same data. If the
2008 # timestamp is in the future, the read will block until the
2009 # specified timestamp, modulo the read&#x27;s deadline.
2010 #
2011 # Useful for large scale consistent reads such as mapreduces, or
2012 # for coordinating many reads against a consistent snapshot of the
2013 # data.
2014 #
2015 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
2016 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
2017 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
2018 # seconds. Guarantees that all writes that have committed more
2019 # than the specified number of seconds ago are visible. Because
2020 # Cloud Spanner chooses the exact timestamp, this mode works even if
2021 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
2022 # commit timestamps.
2023 #
2024 # Useful for reading the freshest data available at a nearby
2025 # replica, while bounding the possible staleness if the local
2026 # replica has fallen behind.
2027 #
2028 # Note that this option can only be used in single-use
2029 # transactions.
2030 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
2031 # the Transaction message that describes the transaction.
2032 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
2033 # old. The timestamp is chosen soon after the read is started.
2034 #
2035 # Guarantees that all writes that have committed more than the
2036 # specified number of seconds ago are visible. Because Cloud Spanner
2037 # chooses the exact timestamp, this mode works even if the client&#x27;s
2038 # local clock is substantially skewed from Cloud Spanner commit
2039 # timestamps.
2040 #
2041 # Useful for reading at nearby replicas without the distributed
2042 # timestamp negotiation overhead of `max_staleness`.
2043 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
2044 # are visible.
2045 },
2046 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
2047 #
2048 # Authorization to begin a read-write transaction requires
2049 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
2050 # on the `session` resource.
2051 # transaction type has no options.
2052 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]2053 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2054 &quot;id&quot;: &quot;A String&quot;, # Execute the read or SQL query in a previously-started transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]2055 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2056 &quot;seqno&quot;: &quot;A String&quot;, # Required. A per-transaction sequence number used to identify this request. This field
2057 # makes each request idempotent such that if the request is received multiple
2058 # times, at most one will succeed.
2059 #
2060 # The sequence number must be monotonically increasing within the
2061 # transaction. If a request arrives for the first time with an out-of-order
2062 # sequence number, the transaction may be aborted. Replays of previously
2063 # handled requests will yield the same response as the first execution.
2064 &quot;statements&quot;: [ # Required. The list of statements to execute in this batch. Statements are executed
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2065 # serially, such that the effects of statement `i` are visible to statement
2066 # `i+1`. Each statement must be a DML statement. Execution stops at the
2067 # first failed statement; the remaining statements are not executed.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2068 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2069 # Callers must provide at least one statement.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2070 { # A single DML statement.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2071 &quot;paramTypes&quot;: { # It is not always possible for Cloud Spanner to infer the right SQL type
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2072 # from a JSON value. For example, values of type `BYTES` and values
2073 # of type `STRING` both appear in params as JSON strings.
2074 #
2075 # In these cases, `param_types` can be used to specify the exact
2076 # SQL type for some or all of the SQL statement parameters. See the
2077 # definition of Type for more information
2078 # about SQL types.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2079 &quot;a_key&quot;: { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2080 # table cell or returned from an SQL query.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2081 &quot;arrayElementType&quot;: # Object with schema name: Type # If code == ARRAY, then `array_element_type`
2082 # is the type of the array elements.
2083 &quot;code&quot;: &quot;A String&quot;, # Required. The TypeCode for this type.
2084 &quot;structType&quot;: { # `StructType` defines the fields of a STRUCT type. # If code == STRUCT, then `struct_type`
2085 # provides type information for the struct&#x27;s fields.
2086 &quot;fields&quot;: [ # The list of fields that make up this struct. Order is
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2087 # significant, because values of this struct type are represented as
2088 # lists, where the order of field values matches the order of
2089 # fields in the StructType. In turn, the order of fields
2090 # matches the order of columns in a read request, or the order of
2091 # fields in the `SELECT` clause of a query.
2092 { # Message representing a single field of a struct.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2093 &quot;name&quot;: &quot;A String&quot;, # The name of the field. For reads, this is the column name. For
2094 # SQL queries, it is the column alias (e.g., `&quot;Word&quot;` in the
2095 # query `&quot;SELECT &#x27;hello&#x27; AS Word&quot;`), or the column name (e.g.,
2096 # `&quot;ColName&quot;` in the query `&quot;SELECT ColName FROM Table&quot;`). Some
2097 # columns might have an empty name (e.g., !&quot;SELECT
2098 # UPPER(ColName)&quot;`). Note that a query result can contain
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2099 # multiple fields with the same name.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2100 &quot;type&quot;: # Object with schema name: Type # The type of the field.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2101 },
2102 ],
2103 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2104 },
2105 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2106 &quot;sql&quot;: &quot;A String&quot;, # Required. The DML string.
2107 &quot;params&quot;: { # Parameter names and values that bind to placeholders in the DML string.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2108 #
2109 # A parameter placeholder consists of the `@` character followed by the
2110 # parameter name (for example, `@firstName`). Parameter names can contain
2111 # letters, numbers, and underscores.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2112 #
2113 # Parameters can appear anywhere that a literal value is expected. The
2114 # same parameter name can be used more than once, for example:
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2115 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2116 # `&quot;WHERE id &gt; @msg_id AND id &lt; @msg_id + 100&quot;`
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2117 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2118 # It is an error to execute a SQL statement with unbound parameters.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2119 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2120 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2121 },
2122 ],
2123 }
2124
2125 x__xgafv: string, V1 error format.
2126 Allowed values
2127 1 - v1 error format
2128 2 - v2 error format
2129
2130Returns:
2131 An object of the form:
2132
2133 { # The response for ExecuteBatchDml. Contains a list
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2134 # of ResultSet messages, one for each DML statement that has successfully
2135 # executed, in the same order as the statements in the request. If a statement
2136 # fails, the status in the response body identifies the cause of the failure.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2137 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2138 # To check for DML statements that failed, use the following approach:
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2139 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2140 # 1. Check the status in the response message. The google.rpc.Code enum
2141 # value `OK` indicates that all statements were executed successfully.
2142 # 2. If the status was not `OK`, check the number of result sets in the
2143 # response. If the response contains `N` ResultSet messages, then
2144 # statement `N+1` in the request failed.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2145 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2146 # Example 1:
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2147 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2148 # * Request: 5 DML statements, all executed successfully.
2149 # * Response: 5 ResultSet messages, with the status `OK`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2150 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2151 # Example 2:
2152 #
2153 # * Request: 5 DML statements. The third statement has a syntax error.
2154 # * Response: 2 ResultSet messages, and a syntax error (`INVALID_ARGUMENT`)
2155 # status. The number of ResultSet messages indicates that the third
2156 # statement failed, and the fourth and fifth statements were not executed.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2157 &quot;status&quot;: { # The `Status` type defines a logical error model that is suitable for # If all DML statements are executed successfully, the status is `OK`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2158 # Otherwise, the error status of the first failed statement.
2159 # different programming environments, including REST APIs and RPC APIs. It is
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2160 # used by [gRPC](https://github.com/grpc). Each `Status` message contains
2161 # three pieces of data: error code, error message, and error details.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2162 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2163 # You can find out more about this error model and how to work with it in the
2164 # [API Design Guide](https://cloud.google.com/apis/design/errors).
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2165 &quot;code&quot;: 42, # The status code, which should be an enum value of google.rpc.Code.
2166 &quot;message&quot;: &quot;A String&quot;, # A developer-facing error message, which should be in English. Any
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2167 # user-facing error message should be localized and sent in the
2168 # google.rpc.Status.details field, or localized by the client.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2169 &quot;details&quot;: [ # A list of messages that carry the error details. There is a common set of
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2170 # message types for APIs to use.
2171 {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2172 &quot;a_key&quot;: &quot;&quot;, # Properties of the object. Contains field @type with type URL.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2173 },
2174 ],
2175 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2176 &quot;resultSets&quot;: [ # One ResultSet for each statement in the request that ran successfully,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2177 # in the same order as the statements in the request. Each ResultSet does
2178 # not contain any rows. The ResultSetStats in each ResultSet contain
2179 # the number of rows modified by the statement.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2180 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2181 # Only the first ResultSet in the response contains valid
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2182 # ResultSetMetadata.
2183 { # Results from Read or
2184 # ExecuteSql.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2185 &quot;stats&quot;: { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the SQL statement that
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2186 # produced this result set. These can be requested by setting
2187 # ExecuteSqlRequest.query_mode.
2188 # DML statements always produce stats containing the number of rows
2189 # modified, unless executed using the
2190 # ExecuteSqlRequest.QueryMode.PLAN ExecuteSqlRequest.query_mode.
2191 # Other fields may or may not be populated, based on the
2192 # ExecuteSqlRequest.query_mode.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2193 &quot;rowCountExact&quot;: &quot;A String&quot;, # Standard DML returns an exact count of rows that were modified.
2194 &quot;queryStats&quot;: { # Aggregated statistics from the execution of the query. Only present when
2195 # the query is profiled. For example, a query could return the statistics as
2196 # follows:
2197 #
2198 # {
2199 # &quot;rows_returned&quot;: &quot;3&quot;,
2200 # &quot;elapsed_time&quot;: &quot;1.22 secs&quot;,
2201 # &quot;cpu_time&quot;: &quot;1.19 secs&quot;
2202 # }
2203 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
2204 },
2205 &quot;rowCountLowerBound&quot;: &quot;A String&quot;, # Partitioned DML does not offer exactly-once semantics, so it
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2206 # returns a lower bound of the rows modified.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2207 &quot;queryPlan&quot;: { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
2208 &quot;planNodes&quot;: [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
2209 # with the plan root. Each PlanNode&#x27;s `id` corresponds to its index in
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2210 # `plan_nodes`.
2211 { # Node information for nodes appearing in a QueryPlan.plan_nodes.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2212 &quot;metadata&quot;: { # Attributes relevant to the node contained in a group of key-value pairs.
2213 # For example, a Parameter Reference node could have the following
2214 # information in its metadata:
2215 #
2216 # {
2217 # &quot;parameter_reference&quot;: &quot;param1&quot;,
2218 # &quot;parameter_type&quot;: &quot;array&quot;
2219 # }
2220 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
2221 },
2222 &quot;executionStats&quot;: { # The execution statistics associated with the node, contained in a group of
2223 # key-value pairs. Only present if the plan was returned as a result of a
2224 # profile query. For example, number of executions, number of rows/time per
2225 # execution etc.
2226 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
2227 },
2228 &quot;shortRepresentation&quot;: { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
2229 # `SCALAR` PlanNode(s).
2230 &quot;description&quot;: &quot;A String&quot;, # A string representation of the expression subtree rooted at this node.
2231 &quot;subqueries&quot;: { # A mapping of (subquery variable name) -&gt; (subquery node id) for cases
2232 # where the `description` string of this node references a `SCALAR`
2233 # subquery contained in the expression subtree rooted at this node. The
2234 # referenced `SCALAR` subquery may not necessarily be a direct child of
2235 # this node.
2236 &quot;a_key&quot;: 42,
2237 },
2238 },
2239 &quot;index&quot;: 42, # The `PlanNode`&#x27;s index in node list.
2240 &quot;kind&quot;: &quot;A String&quot;, # Used to determine the type of node. May be needed for visualizing
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2241 # different kinds of nodes differently. For example, If the node is a
2242 # SCALAR node, it will have a condensed representation
2243 # which can be used to directly embed a description of the node in its
2244 # parent.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2245 &quot;displayName&quot;: &quot;A String&quot;, # The display name for the node.
2246 &quot;childLinks&quot;: [ # List of child node `index`es and their relationship to this parent.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2247 { # Metadata associated with a parent-child relationship appearing in a
2248 # PlanNode.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2249 &quot;variable&quot;: &quot;A String&quot;, # Only present if the child node is SCALAR and corresponds
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2250 # to an output variable of the parent node. The field carries the name of
2251 # the output variable.
2252 # For example, a `TableScan` operator that reads rows from a table will
2253 # have child links to the `SCALAR` nodes representing the output variables
2254 # created for each column that is read by the operator. The corresponding
2255 # `variable` fields will be set to the variable names assigned to the
2256 # columns.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2257 &quot;childIndex&quot;: 42, # The node to which the link points.
2258 &quot;type&quot;: &quot;A String&quot;, # The type of the link. For example, in Hash Joins this could be used to
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2259 # distinguish between the build child and the probe child, or in the case
2260 # of the child being an output variable, to represent the tag associated
2261 # with the output variable.
2262 },
2263 ],
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2264 },
2265 ],
2266 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2267 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2268 &quot;rows&quot;: [ # Each element in `rows` is a row whose format is defined by
2269 # metadata.row_type. The ith element
2270 # in each row matches the ith field in
2271 # metadata.row_type. Elements are
2272 # encoded based on type as described
2273 # here.
2274 [
2275 &quot;&quot;,
2276 ],
2277 ],
2278 &quot;metadata&quot;: { # Metadata about a ResultSet or PartialResultSet. # Metadata about the result set, such as row type information.
2279 &quot;rowType&quot;: { # `StructType` defines the fields of a STRUCT type. # Indicates the field names and types for the rows in the result
2280 # set. For example, a SQL query like `&quot;SELECT UserId, UserName FROM
2281 # Users&quot;` could return a `row_type` value like:
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2282 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2283 # &quot;fields&quot;: [
2284 # { &quot;name&quot;: &quot;UserId&quot;, &quot;type&quot;: { &quot;code&quot;: &quot;INT64&quot; } },
2285 # { &quot;name&quot;: &quot;UserName&quot;, &quot;type&quot;: { &quot;code&quot;: &quot;STRING&quot; } },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2286 # ]
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2287 &quot;fields&quot;: [ # The list of fields that make up this struct. Order is
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2288 # significant, because values of this struct type are represented as
2289 # lists, where the order of field values matches the order of
2290 # fields in the StructType. In turn, the order of fields
2291 # matches the order of columns in a read request, or the order of
2292 # fields in the `SELECT` clause of a query.
2293 { # Message representing a single field of a struct.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2294 &quot;name&quot;: &quot;A String&quot;, # The name of the field. For reads, this is the column name. For
2295 # SQL queries, it is the column alias (e.g., `&quot;Word&quot;` in the
2296 # query `&quot;SELECT &#x27;hello&#x27; AS Word&quot;`), or the column name (e.g.,
2297 # `&quot;ColName&quot;` in the query `&quot;SELECT ColName FROM Table&quot;`). Some
2298 # columns might have an empty name (e.g., !&quot;SELECT
2299 # UPPER(ColName)&quot;`). Note that a query result can contain
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2300 # multiple fields with the same name.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2301 &quot;type&quot;: # Object with schema name: Type # The type of the field.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2302 },
2303 ],
2304 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2305 &quot;transaction&quot;: { # A transaction. # If the read or SQL query began a transaction as a side-effect, the
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2306 # information about the new transaction is yielded here.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2307 &quot;id&quot;: &quot;A String&quot;, # `id` may be used to identify the transaction in subsequent
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2308 # Read,
2309 # ExecuteSql,
2310 # Commit, or
2311 # Rollback calls.
2312 #
2313 # Single-use read-only transactions do not have IDs, because
2314 # single-use transactions do not support multiple requests.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2315 &quot;readTimestamp&quot;: &quot;A String&quot;, # For snapshot read-only transactions, the read timestamp chosen
2316 # for the transaction. Not returned by default: see
2317 # TransactionOptions.ReadOnly.return_read_timestamp.
2318 #
2319 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
2320 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2321 },
2322 },
2323 },
2324 ],
2325 }</pre>
2326</div>
2327
2328<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2329 <code class="details" id="executeSql">executeSql(session, body=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2330 <pre>Executes an SQL statement, returning all results in a single reply. This
2331method cannot be used to return a result set larger than 10 MiB;
2332if the query yields more data than that, the query fails with
2333a `FAILED_PRECONDITION` error.
2334
2335Operations inside read-write transactions might return `ABORTED`. If
2336this occurs, the application should restart the transaction from
2337the beginning. See Transaction for more details.
2338
2339Larger result sets can be fetched in streaming fashion by calling
2340ExecuteStreamingSql instead.
2341
2342Args:
2343 session: string, Required. The session in which the SQL query should be performed. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2344 body: object, The request body.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2345 The object takes the form of:
2346
2347{ # The request for ExecuteSql and
2348 # ExecuteStreamingSql.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2349 &quot;queryMode&quot;: &quot;A String&quot;, # Used to control the amount of debugging information returned in
2350 # ResultSetStats. If partition_token is set, query_mode can only
2351 # be set to QueryMode.NORMAL.
2352 &quot;transaction&quot;: { # This message is used to select the transaction in which a # The transaction to use.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2353 #
2354 # For queries, if none is provided, the default is a temporary read-only
2355 # transaction with strong concurrency.
2356 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2357 # Standard DML statements require a read-write transaction. To protect
2358 # against replays, single-use transactions are not supported. The caller
2359 # must either supply an existing transaction ID or begin a new transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2360 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2361 # Partitioned DML requires an existing Partitioned DML transaction ID.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2362 # Read or
2363 # ExecuteSql call runs.
2364 #
2365 # See TransactionOptions for more information about transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2366 &quot;singleUse&quot;: { # # Transactions # Execute the read or SQL query in a temporary transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2367 # This is the most efficient way to execute a transaction that
2368 # consists of a single SQL query.
2369 #
2370 #
2371 # Each session can have at most one active transaction at a time. After the
2372 # active transaction is completed, the session can immediately be
2373 # re-used for the next transaction. It is not necessary to create a
2374 # new session for each transaction.
2375 #
2376 # # Transaction Modes
2377 #
2378 # Cloud Spanner supports three transaction modes:
2379 #
2380 # 1. Locking read-write. This type of transaction is the only way
2381 # to write data into Cloud Spanner. These transactions rely on
2382 # pessimistic locking and, if necessary, two-phase commit.
2383 # Locking read-write transactions may abort, requiring the
2384 # application to retry.
2385 #
2386 # 2. Snapshot read-only. This transaction type provides guaranteed
2387 # consistency across several reads, but does not allow
2388 # writes. Snapshot read-only transactions can be configured to
2389 # read at timestamps in the past. Snapshot read-only
2390 # transactions do not need to be committed.
2391 #
2392 # 3. Partitioned DML. This type of transaction is used to execute
2393 # a single Partitioned DML statement. Partitioned DML partitions
2394 # the key space and runs the DML statement over each partition
2395 # in parallel using separate, internal transactions that commit
2396 # independently. Partitioned DML transactions do not need to be
2397 # committed.
2398 #
2399 # For transactions that only read, snapshot read-only transactions
2400 # provide simpler semantics and are almost always faster. In
2401 # particular, read-only transactions do not take locks, so they do
2402 # not conflict with read-write transactions. As a consequence of not
2403 # taking locks, they also do not abort, so retry loops are not needed.
2404 #
2405 # Transactions may only read/write data in a single database. They
2406 # may, however, read/write data in different tables within that
2407 # database.
2408 #
2409 # ## Locking Read-Write Transactions
2410 #
2411 # Locking transactions may be used to atomically read-modify-write
2412 # data anywhere in a database. This type of transaction is externally
2413 # consistent.
2414 #
2415 # Clients should attempt to minimize the amount of time a transaction
2416 # is active. Faster transactions commit with higher probability
2417 # and cause less contention. Cloud Spanner attempts to keep read locks
2418 # active as long as the transaction continues to do reads, and the
2419 # transaction has not been terminated by
2420 # Commit or
2421 # Rollback. Long periods of
2422 # inactivity at the client may cause Cloud Spanner to release a
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2423 # transaction&#x27;s locks and abort it.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2424 #
2425 # Conceptually, a read-write transaction consists of zero or more
2426 # reads or SQL statements followed by
2427 # Commit. At any time before
2428 # Commit, the client can send a
2429 # Rollback request to abort the
2430 # transaction.
2431 #
2432 # ### Semantics
2433 #
2434 # Cloud Spanner can commit the transaction if all read locks it acquired
2435 # are still valid at commit time, and it is able to acquire write
2436 # locks for all writes. Cloud Spanner can abort the transaction for any
2437 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
2438 # that the transaction has not modified any user data in Cloud Spanner.
2439 #
2440 # Unless the transaction commits, Cloud Spanner makes no guarantees about
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2441 # how long the transaction&#x27;s locks were held for. It is an error to
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2442 # use Cloud Spanner locks for any sort of mutual exclusion other than
2443 # between Cloud Spanner transactions themselves.
2444 #
2445 # ### Retrying Aborted Transactions
2446 #
2447 # When a transaction aborts, the application can choose to retry the
2448 # whole transaction again. To maximize the chances of successfully
2449 # committing the retry, the client should execute the retry in the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2450 # same session as the original attempt. The original session&#x27;s lock
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2451 # priority increases with each consecutive abort, meaning that each
2452 # attempt has a slightly better chance of success than the previous.
2453 #
2454 # Under some circumstances (e.g., many transactions attempting to
2455 # modify the same row(s)), a transaction can abort many times in a
2456 # short period before successfully committing. Thus, it is not a good
2457 # idea to cap the number of retries a transaction can attempt;
2458 # instead, it is better to limit the total amount of wall time spent
2459 # retrying.
2460 #
2461 # ### Idle Transactions
2462 #
2463 # A transaction is considered idle if it has no outstanding reads or
2464 # SQL queries and has not started a read or SQL query within the last 10
2465 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2466 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2467 # fail with error `ABORTED`.
2468 #
2469 # If this behavior is undesirable, periodically executing a simple
2470 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
2471 # transaction from becoming idle.
2472 #
2473 # ## Snapshot Read-Only Transactions
2474 #
2475 # Snapshot read-only transactions provides a simpler method than
2476 # locking read-write transactions for doing several consistent
2477 # reads. However, this type of transaction does not support writes.
2478 #
2479 # Snapshot transactions do not take locks. Instead, they work by
2480 # choosing a Cloud Spanner timestamp, then executing all reads at that
2481 # timestamp. Since they do not acquire locks, they do not block
2482 # concurrent read-write transactions.
2483 #
2484 # Unlike locking read-write transactions, snapshot read-only
2485 # transactions never abort. They can fail if the chosen read
2486 # timestamp is garbage collected; however, the default garbage
2487 # collection policy is generous enough that most applications do not
2488 # need to worry about this in practice.
2489 #
2490 # Snapshot read-only transactions do not need to call
2491 # Commit or
2492 # Rollback (and in fact are not
2493 # permitted to do so).
2494 #
2495 # To execute a snapshot transaction, the client specifies a timestamp
2496 # bound, which tells Cloud Spanner how to choose a read timestamp.
2497 #
2498 # The types of timestamp bound are:
2499 #
2500 # - Strong (the default).
2501 # - Bounded staleness.
2502 # - Exact staleness.
2503 #
2504 # If the Cloud Spanner database to be read is geographically distributed,
2505 # stale read-only transactions can execute more quickly than strong
2506 # or read-write transaction, because they are able to execute far
2507 # from the leader replica.
2508 #
2509 # Each type of timestamp bound is discussed in detail below.
2510 #
2511 # ### Strong
2512 #
2513 # Strong reads are guaranteed to see the effects of all transactions
2514 # that have committed before the start of the read. Furthermore, all
2515 # rows yielded by a single read are consistent with each other -- if
2516 # any part of the read observes a transaction, all parts of the read
2517 # see the transaction.
2518 #
2519 # Strong reads are not repeatable: two consecutive strong read-only
2520 # transactions might return inconsistent results if there are
2521 # concurrent writes. If consistency across reads is required, the
2522 # reads should be executed within a transaction or at an exact read
2523 # timestamp.
2524 #
2525 # See TransactionOptions.ReadOnly.strong.
2526 #
2527 # ### Exact Staleness
2528 #
2529 # These timestamp bounds execute reads at a user-specified
2530 # timestamp. Reads at a timestamp are guaranteed to see a consistent
2531 # prefix of the global transaction history: they observe
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2532 # modifications done by all transactions with a commit timestamp &lt;=
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2533 # the read timestamp, and observe none of the modifications done by
2534 # transactions with a larger commit timestamp. They will block until
2535 # all conflicting transactions that may be assigned commit timestamps
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2536 # &lt;= the read timestamp have finished.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2537 #
2538 # The timestamp can either be expressed as an absolute Cloud Spanner commit
2539 # timestamp or a staleness relative to the current time.
2540 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2541 # These modes do not require a &quot;negotiation phase&quot; to pick a
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2542 # timestamp. As a result, they execute slightly faster than the
2543 # equivalent boundedly stale concurrency modes. On the other hand,
2544 # boundedly stale reads usually return fresher results.
2545 #
2546 # See TransactionOptions.ReadOnly.read_timestamp and
2547 # TransactionOptions.ReadOnly.exact_staleness.
2548 #
2549 # ### Bounded Staleness
2550 #
2551 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
2552 # subject to a user-provided staleness bound. Cloud Spanner chooses the
2553 # newest timestamp within the staleness bound that allows execution
2554 # of the reads at the closest available replica without blocking.
2555 #
2556 # All rows yielded are consistent with each other -- if any part of
2557 # the read observes a transaction, all parts of the read see the
2558 # transaction. Boundedly stale reads are not repeatable: two stale
2559 # reads, even if they use the same staleness bound, can execute at
2560 # different timestamps and thus return inconsistent results.
2561 #
2562 # Boundedly stale reads execute in two phases: the first phase
2563 # negotiates a timestamp among all replicas needed to serve the
2564 # read. In the second phase, reads are executed at the negotiated
2565 # timestamp.
2566 #
2567 # As a result of the two phase execution, bounded staleness reads are
2568 # usually a little slower than comparable exact staleness
2569 # reads. However, they are typically able to return fresher
2570 # results, and are more likely to execute at the closest replica.
2571 #
2572 # Because the timestamp negotiation requires up-front knowledge of
2573 # which rows will be read, it can only be used with single-use
2574 # read-only transactions.
2575 #
2576 # See TransactionOptions.ReadOnly.max_staleness and
2577 # TransactionOptions.ReadOnly.min_read_timestamp.
2578 #
2579 # ### Old Read Timestamps and Garbage Collection
2580 #
2581 # Cloud Spanner continuously garbage collects deleted and overwritten data
2582 # in the background to reclaim storage space. This process is known
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2583 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2584 # are one hour old. Because of this, Cloud Spanner cannot perform reads
2585 # at read timestamps more than one hour in the past. This
2586 # restriction also applies to in-progress reads and/or SQL queries whose
2587 # timestamp become too old while executing. Reads and SQL queries with
2588 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
2589 #
2590 # ## Partitioned DML Transactions
2591 #
2592 # Partitioned DML transactions are used to execute DML statements with a
2593 # different execution strategy that provides different, and often better,
2594 # scalability properties for large, table-wide operations than DML in a
2595 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
2596 # should prefer using ReadWrite transactions.
2597 #
2598 # Partitioned DML partitions the keyspace and runs the DML statement on each
2599 # partition in separate, internal transactions. These transactions commit
2600 # automatically when complete, and run independently from one another.
2601 #
2602 # To reduce lock contention, this execution strategy only acquires read locks
2603 # on rows that match the WHERE clause of the statement. Additionally, the
2604 # smaller per-partition transactions hold locks for less time.
2605 #
2606 # That said, Partitioned DML is not a drop-in replacement for standard DML used
2607 # in ReadWrite transactions.
2608 #
2609 # - The DML statement must be fully-partitionable. Specifically, the statement
2610 # must be expressible as the union of many statements which each access only
2611 # a single row of the table.
2612 #
2613 # - The statement is not applied atomically to all rows of the table. Rather,
2614 # the statement is applied atomically to partitions of the table, in
2615 # independent transactions. Secondary index rows are updated atomically
2616 # with the base table rows.
2617 #
2618 # - Partitioned DML does not guarantee exactly-once execution semantics
2619 # against a partition. The statement will be applied at least once to each
2620 # partition. It is strongly recommended that the DML statement should be
2621 # idempotent to avoid unexpected results. For instance, it is potentially
2622 # dangerous to run a statement such as
2623 # `UPDATE table SET column = column + 1` as it could be run multiple times
2624 # against some rows.
2625 #
2626 # - The partitions are committed automatically - there is no support for
2627 # Commit or Rollback. If the call returns an error, or if the client issuing
2628 # the ExecuteSql call dies, it is possible that some rows had the statement
2629 # executed on them successfully. It is also possible that statement was
2630 # never executed against other rows.
2631 #
2632 # - Partitioned DML transactions may only contain the execution of a single
2633 # DML statement via ExecuteSql or ExecuteStreamingSql.
2634 #
2635 # - If any error is encountered during the execution of the partitioned DML
2636 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
2637 # value that cannot be stored due to schema constraints), then the
2638 # operation is stopped at that point and an error is returned. It is
2639 # possible that at this point, some partitions have been committed (or even
2640 # committed multiple times), and other partitions have not been run at all.
2641 #
2642 # Given the above, Partitioned DML is good fit for large, database-wide,
2643 # operations that are idempotent, such as deleting old rows from a very large
2644 # table.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2645 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2646 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2647 # Authorization to begin a Partitioned DML transaction requires
2648 # `spanner.databases.beginPartitionedDmlTransaction` permission
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2649 # on the `session` resource.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2650 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2651 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2652 #
2653 # Authorization to begin a read-only transaction requires
2654 # `spanner.databases.beginReadOnlyTransaction` permission
2655 # on the `session` resource.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2656 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2657 #
2658 # This is useful for requesting fresher data than some previous
2659 # read, or data that is fresh enough to observe the effects of some
2660 # previously committed transaction whose timestamp is known.
2661 #
2662 # Note that this option can only be used in single-use transactions.
2663 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2664 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
2665 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
2666 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2667 # reads at a specific timestamp are repeatable; the same read at
2668 # the same timestamp always returns the same data. If the
2669 # timestamp is in the future, the read will block until the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2670 # specified timestamp, modulo the read&#x27;s deadline.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]2671 #
2672 # Useful for large scale consistent reads such as mapreduces, or
2673 # for coordinating many reads against a consistent snapshot of the
2674 # data.
2675 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2676 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
2677 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
2678 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2679 # seconds. Guarantees that all writes that have committed more
2680 # than the specified number of seconds ago are visible. Because
2681 # Cloud Spanner chooses the exact timestamp, this mode works even if
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2682 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2683 # commit timestamps.
2684 #
2685 # Useful for reading the freshest data available at a nearby
2686 # replica, while bounding the possible staleness if the local
2687 # replica has fallen behind.
2688 #
2689 # Note that this option can only be used in single-use
2690 # transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2691 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
2692 # the Transaction message that describes the transaction.
2693 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2694 # old. The timestamp is chosen soon after the read is started.
2695 #
2696 # Guarantees that all writes that have committed more than the
2697 # specified number of seconds ago are visible. Because Cloud Spanner
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2698 # chooses the exact timestamp, this mode works even if the client&#x27;s
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2699 # local clock is substantially skewed from Cloud Spanner commit
2700 # timestamps.
2701 #
2702 # Useful for reading at nearby replicas without the distributed
2703 # timestamp negotiation overhead of `max_staleness`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2704 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2705 # are visible.
2706 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]2707 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
2708 #
2709 # Authorization to begin a read-write transaction requires
2710 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
2711 # on the `session` resource.
2712 # transaction type has no options.
2713 },
2714 },
2715 &quot;begin&quot;: { # # Transactions # Begin a new transaction and execute this read or SQL query in
2716 # it. The transaction ID of the new transaction is returned in
2717 # ResultSetMetadata.transaction, which is a Transaction.
2718 #
2719 #
2720 # Each session can have at most one active transaction at a time. After the
2721 # active transaction is completed, the session can immediately be
2722 # re-used for the next transaction. It is not necessary to create a
2723 # new session for each transaction.
2724 #
2725 # # Transaction Modes
2726 #
2727 # Cloud Spanner supports three transaction modes:
2728 #
2729 # 1. Locking read-write. This type of transaction is the only way
2730 # to write data into Cloud Spanner. These transactions rely on
2731 # pessimistic locking and, if necessary, two-phase commit.
2732 # Locking read-write transactions may abort, requiring the
2733 # application to retry.
2734 #
2735 # 2. Snapshot read-only. This transaction type provides guaranteed
2736 # consistency across several reads, but does not allow
2737 # writes. Snapshot read-only transactions can be configured to
2738 # read at timestamps in the past. Snapshot read-only
2739 # transactions do not need to be committed.
2740 #
2741 # 3. Partitioned DML. This type of transaction is used to execute
2742 # a single Partitioned DML statement. Partitioned DML partitions
2743 # the key space and runs the DML statement over each partition
2744 # in parallel using separate, internal transactions that commit
2745 # independently. Partitioned DML transactions do not need to be
2746 # committed.
2747 #
2748 # For transactions that only read, snapshot read-only transactions
2749 # provide simpler semantics and are almost always faster. In
2750 # particular, read-only transactions do not take locks, so they do
2751 # not conflict with read-write transactions. As a consequence of not
2752 # taking locks, they also do not abort, so retry loops are not needed.
2753 #
2754 # Transactions may only read/write data in a single database. They
2755 # may, however, read/write data in different tables within that
2756 # database.
2757 #
2758 # ## Locking Read-Write Transactions
2759 #
2760 # Locking transactions may be used to atomically read-modify-write
2761 # data anywhere in a database. This type of transaction is externally
2762 # consistent.
2763 #
2764 # Clients should attempt to minimize the amount of time a transaction
2765 # is active. Faster transactions commit with higher probability
2766 # and cause less contention. Cloud Spanner attempts to keep read locks
2767 # active as long as the transaction continues to do reads, and the
2768 # transaction has not been terminated by
2769 # Commit or
2770 # Rollback. Long periods of
2771 # inactivity at the client may cause Cloud Spanner to release a
2772 # transaction&#x27;s locks and abort it.
2773 #
2774 # Conceptually, a read-write transaction consists of zero or more
2775 # reads or SQL statements followed by
2776 # Commit. At any time before
2777 # Commit, the client can send a
2778 # Rollback request to abort the
2779 # transaction.
2780 #
2781 # ### Semantics
2782 #
2783 # Cloud Spanner can commit the transaction if all read locks it acquired
2784 # are still valid at commit time, and it is able to acquire write
2785 # locks for all writes. Cloud Spanner can abort the transaction for any
2786 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
2787 # that the transaction has not modified any user data in Cloud Spanner.
2788 #
2789 # Unless the transaction commits, Cloud Spanner makes no guarantees about
2790 # how long the transaction&#x27;s locks were held for. It is an error to
2791 # use Cloud Spanner locks for any sort of mutual exclusion other than
2792 # between Cloud Spanner transactions themselves.
2793 #
2794 # ### Retrying Aborted Transactions
2795 #
2796 # When a transaction aborts, the application can choose to retry the
2797 # whole transaction again. To maximize the chances of successfully
2798 # committing the retry, the client should execute the retry in the
2799 # same session as the original attempt. The original session&#x27;s lock
2800 # priority increases with each consecutive abort, meaning that each
2801 # attempt has a slightly better chance of success than the previous.
2802 #
2803 # Under some circumstances (e.g., many transactions attempting to
2804 # modify the same row(s)), a transaction can abort many times in a
2805 # short period before successfully committing. Thus, it is not a good
2806 # idea to cap the number of retries a transaction can attempt;
2807 # instead, it is better to limit the total amount of wall time spent
2808 # retrying.
2809 #
2810 # ### Idle Transactions
2811 #
2812 # A transaction is considered idle if it has no outstanding reads or
2813 # SQL queries and has not started a read or SQL query within the last 10
2814 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
2815 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
2816 # fail with error `ABORTED`.
2817 #
2818 # If this behavior is undesirable, periodically executing a simple
2819 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
2820 # transaction from becoming idle.
2821 #
2822 # ## Snapshot Read-Only Transactions
2823 #
2824 # Snapshot read-only transactions provides a simpler method than
2825 # locking read-write transactions for doing several consistent
2826 # reads. However, this type of transaction does not support writes.
2827 #
2828 # Snapshot transactions do not take locks. Instead, they work by
2829 # choosing a Cloud Spanner timestamp, then executing all reads at that
2830 # timestamp. Since they do not acquire locks, they do not block
2831 # concurrent read-write transactions.
2832 #
2833 # Unlike locking read-write transactions, snapshot read-only
2834 # transactions never abort. They can fail if the chosen read
2835 # timestamp is garbage collected; however, the default garbage
2836 # collection policy is generous enough that most applications do not
2837 # need to worry about this in practice.
2838 #
2839 # Snapshot read-only transactions do not need to call
2840 # Commit or
2841 # Rollback (and in fact are not
2842 # permitted to do so).
2843 #
2844 # To execute a snapshot transaction, the client specifies a timestamp
2845 # bound, which tells Cloud Spanner how to choose a read timestamp.
2846 #
2847 # The types of timestamp bound are:
2848 #
2849 # - Strong (the default).
2850 # - Bounded staleness.
2851 # - Exact staleness.
2852 #
2853 # If the Cloud Spanner database to be read is geographically distributed,
2854 # stale read-only transactions can execute more quickly than strong
2855 # or read-write transaction, because they are able to execute far
2856 # from the leader replica.
2857 #
2858 # Each type of timestamp bound is discussed in detail below.
2859 #
2860 # ### Strong
2861 #
2862 # Strong reads are guaranteed to see the effects of all transactions
2863 # that have committed before the start of the read. Furthermore, all
2864 # rows yielded by a single read are consistent with each other -- if
2865 # any part of the read observes a transaction, all parts of the read
2866 # see the transaction.
2867 #
2868 # Strong reads are not repeatable: two consecutive strong read-only
2869 # transactions might return inconsistent results if there are
2870 # concurrent writes. If consistency across reads is required, the
2871 # reads should be executed within a transaction or at an exact read
2872 # timestamp.
2873 #
2874 # See TransactionOptions.ReadOnly.strong.
2875 #
2876 # ### Exact Staleness
2877 #
2878 # These timestamp bounds execute reads at a user-specified
2879 # timestamp. Reads at a timestamp are guaranteed to see a consistent
2880 # prefix of the global transaction history: they observe
2881 # modifications done by all transactions with a commit timestamp &lt;=
2882 # the read timestamp, and observe none of the modifications done by
2883 # transactions with a larger commit timestamp. They will block until
2884 # all conflicting transactions that may be assigned commit timestamps
2885 # &lt;= the read timestamp have finished.
2886 #
2887 # The timestamp can either be expressed as an absolute Cloud Spanner commit
2888 # timestamp or a staleness relative to the current time.
2889 #
2890 # These modes do not require a &quot;negotiation phase&quot; to pick a
2891 # timestamp. As a result, they execute slightly faster than the
2892 # equivalent boundedly stale concurrency modes. On the other hand,
2893 # boundedly stale reads usually return fresher results.
2894 #
2895 # See TransactionOptions.ReadOnly.read_timestamp and
2896 # TransactionOptions.ReadOnly.exact_staleness.
2897 #
2898 # ### Bounded Staleness
2899 #
2900 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
2901 # subject to a user-provided staleness bound. Cloud Spanner chooses the
2902 # newest timestamp within the staleness bound that allows execution
2903 # of the reads at the closest available replica without blocking.
2904 #
2905 # All rows yielded are consistent with each other -- if any part of
2906 # the read observes a transaction, all parts of the read see the
2907 # transaction. Boundedly stale reads are not repeatable: two stale
2908 # reads, even if they use the same staleness bound, can execute at
2909 # different timestamps and thus return inconsistent results.
2910 #
2911 # Boundedly stale reads execute in two phases: the first phase
2912 # negotiates a timestamp among all replicas needed to serve the
2913 # read. In the second phase, reads are executed at the negotiated
2914 # timestamp.
2915 #
2916 # As a result of the two phase execution, bounded staleness reads are
2917 # usually a little slower than comparable exact staleness
2918 # reads. However, they are typically able to return fresher
2919 # results, and are more likely to execute at the closest replica.
2920 #
2921 # Because the timestamp negotiation requires up-front knowledge of
2922 # which rows will be read, it can only be used with single-use
2923 # read-only transactions.
2924 #
2925 # See TransactionOptions.ReadOnly.max_staleness and
2926 # TransactionOptions.ReadOnly.min_read_timestamp.
2927 #
2928 # ### Old Read Timestamps and Garbage Collection
2929 #
2930 # Cloud Spanner continuously garbage collects deleted and overwritten data
2931 # in the background to reclaim storage space. This process is known
2932 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
2933 # are one hour old. Because of this, Cloud Spanner cannot perform reads
2934 # at read timestamps more than one hour in the past. This
2935 # restriction also applies to in-progress reads and/or SQL queries whose
2936 # timestamp become too old while executing. Reads and SQL queries with
2937 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
2938 #
2939 # ## Partitioned DML Transactions
2940 #
2941 # Partitioned DML transactions are used to execute DML statements with a
2942 # different execution strategy that provides different, and often better,
2943 # scalability properties for large, table-wide operations than DML in a
2944 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
2945 # should prefer using ReadWrite transactions.
2946 #
2947 # Partitioned DML partitions the keyspace and runs the DML statement on each
2948 # partition in separate, internal transactions. These transactions commit
2949 # automatically when complete, and run independently from one another.
2950 #
2951 # To reduce lock contention, this execution strategy only acquires read locks
2952 # on rows that match the WHERE clause of the statement. Additionally, the
2953 # smaller per-partition transactions hold locks for less time.
2954 #
2955 # That said, Partitioned DML is not a drop-in replacement for standard DML used
2956 # in ReadWrite transactions.
2957 #
2958 # - The DML statement must be fully-partitionable. Specifically, the statement
2959 # must be expressible as the union of many statements which each access only
2960 # a single row of the table.
2961 #
2962 # - The statement is not applied atomically to all rows of the table. Rather,
2963 # the statement is applied atomically to partitions of the table, in
2964 # independent transactions. Secondary index rows are updated atomically
2965 # with the base table rows.
2966 #
2967 # - Partitioned DML does not guarantee exactly-once execution semantics
2968 # against a partition. The statement will be applied at least once to each
2969 # partition. It is strongly recommended that the DML statement should be
2970 # idempotent to avoid unexpected results. For instance, it is potentially
2971 # dangerous to run a statement such as
2972 # `UPDATE table SET column = column + 1` as it could be run multiple times
2973 # against some rows.
2974 #
2975 # - The partitions are committed automatically - there is no support for
2976 # Commit or Rollback. If the call returns an error, or if the client issuing
2977 # the ExecuteSql call dies, it is possible that some rows had the statement
2978 # executed on them successfully. It is also possible that statement was
2979 # never executed against other rows.
2980 #
2981 # - Partitioned DML transactions may only contain the execution of a single
2982 # DML statement via ExecuteSql or ExecuteStreamingSql.
2983 #
2984 # - If any error is encountered during the execution of the partitioned DML
2985 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
2986 # value that cannot be stored due to schema constraints), then the
2987 # operation is stopped at that point and an error is returned. It is
2988 # possible that at this point, some partitions have been committed (or even
2989 # committed multiple times), and other partitions have not been run at all.
2990 #
2991 # Given the above, Partitioned DML is good fit for large, database-wide,
2992 # operations that are idempotent, such as deleting old rows from a very large
2993 # table.
2994 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]2995 #
2996 # Authorization to begin a Partitioned DML transaction requires
2997 # `spanner.databases.beginPartitionedDmlTransaction` permission
2998 # on the `session` resource.
2999 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3000 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
3001 #
3002 # Authorization to begin a read-only transaction requires
3003 # `spanner.databases.beginReadOnlyTransaction` permission
3004 # on the `session` resource.
3005 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
3006 #
3007 # This is useful for requesting fresher data than some previous
3008 # read, or data that is fresh enough to observe the effects of some
3009 # previously committed transaction whose timestamp is known.
3010 #
3011 # Note that this option can only be used in single-use transactions.
3012 #
3013 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
3014 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
3015 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
3016 # reads at a specific timestamp are repeatable; the same read at
3017 # the same timestamp always returns the same data. If the
3018 # timestamp is in the future, the read will block until the
3019 # specified timestamp, modulo the read&#x27;s deadline.
3020 #
3021 # Useful for large scale consistent reads such as mapreduces, or
3022 # for coordinating many reads against a consistent snapshot of the
3023 # data.
3024 #
3025 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
3026 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
3027 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
3028 # seconds. Guarantees that all writes that have committed more
3029 # than the specified number of seconds ago are visible. Because
3030 # Cloud Spanner chooses the exact timestamp, this mode works even if
3031 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
3032 # commit timestamps.
3033 #
3034 # Useful for reading the freshest data available at a nearby
3035 # replica, while bounding the possible staleness if the local
3036 # replica has fallen behind.
3037 #
3038 # Note that this option can only be used in single-use
3039 # transactions.
3040 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
3041 # the Transaction message that describes the transaction.
3042 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
3043 # old. The timestamp is chosen soon after the read is started.
3044 #
3045 # Guarantees that all writes that have committed more than the
3046 # specified number of seconds ago are visible. Because Cloud Spanner
3047 # chooses the exact timestamp, this mode works even if the client&#x27;s
3048 # local clock is substantially skewed from Cloud Spanner commit
3049 # timestamps.
3050 #
3051 # Useful for reading at nearby replicas without the distributed
3052 # timestamp negotiation overhead of `max_staleness`.
3053 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
3054 # are visible.
3055 },
3056 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
3057 #
3058 # Authorization to begin a read-write transaction requires
3059 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
3060 # on the `session` resource.
3061 # transaction type has no options.
3062 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3063 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3064 &quot;id&quot;: &quot;A String&quot;, # Execute the read or SQL query in a previously-started transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3065 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3066 &quot;resumeToken&quot;: &quot;A String&quot;, # If this request is resuming a previously interrupted SQL statement
3067 # execution, `resume_token` should be copied from the last
3068 # PartialResultSet yielded before the interruption. Doing this
3069 # enables the new SQL statement execution to resume where the last one left
3070 # off. The rest of the request parameters must exactly match the
3071 # request that yielded this token.
3072 &quot;partitionToken&quot;: &quot;A String&quot;, # If present, results will be restricted to the specified partition
3073 # previously created using PartitionQuery(). There must be an exact
3074 # match for the values of fields common to this message and the
3075 # PartitionQueryRequest message used to create this partition_token.
3076 &quot;seqno&quot;: &quot;A String&quot;, # A per-transaction sequence number used to identify this request. This field
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3077 # makes each request idempotent such that if the request is received multiple
3078 # times, at most one will succeed.
3079 #
3080 # The sequence number must be monotonically increasing within the
3081 # transaction. If a request arrives for the first time with an out-of-order
3082 # sequence number, the transaction may be aborted. Replays of previously
3083 # handled requests will yield the same response as the first execution.
3084 #
3085 # Required for DML statements. Ignored for queries.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3086 &quot;paramTypes&quot;: { # It is not always possible for Cloud Spanner to infer the right SQL type
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3087 # from a JSON value. For example, values of type `BYTES` and values
3088 # of type `STRING` both appear in params as JSON strings.
3089 #
3090 # In these cases, `param_types` can be used to specify the exact
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3091 # SQL type for some or all of the SQL statement parameters. See the
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3092 # definition of Type for more information
3093 # about SQL types.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3094 &quot;a_key&quot;: { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3095 # table cell or returned from an SQL query.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3096 &quot;arrayElementType&quot;: # Object with schema name: Type # If code == ARRAY, then `array_element_type`
3097 # is the type of the array elements.
3098 &quot;code&quot;: &quot;A String&quot;, # Required. The TypeCode for this type.
3099 &quot;structType&quot;: { # `StructType` defines the fields of a STRUCT type. # If code == STRUCT, then `struct_type`
3100 # provides type information for the struct&#x27;s fields.
3101 &quot;fields&quot;: [ # The list of fields that make up this struct. Order is
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]3102 # significant, because values of this struct type are represented as
3103 # lists, where the order of field values matches the order of
3104 # fields in the StructType. In turn, the order of fields
3105 # matches the order of columns in a read request, or the order of
3106 # fields in the `SELECT` clause of a query.
3107 { # Message representing a single field of a struct.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3108 &quot;name&quot;: &quot;A String&quot;, # The name of the field. For reads, this is the column name. For
3109 # SQL queries, it is the column alias (e.g., `&quot;Word&quot;` in the
3110 # query `&quot;SELECT &#x27;hello&#x27; AS Word&quot;`), or the column name (e.g.,
3111 # `&quot;ColName&quot;` in the query `&quot;SELECT ColName FROM Table&quot;`). Some
3112 # columns might have an empty name (e.g., !&quot;SELECT
3113 # UPPER(ColName)&quot;`). Note that a query result can contain
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]3114 # multiple fields with the same name.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3115 &quot;type&quot;: # Object with schema name: Type # The type of the field.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]3116 },
3117 ],
3118 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3119 },
3120 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3121 &quot;sql&quot;: &quot;A String&quot;, # Required. The SQL string.
3122 &quot;params&quot;: { # Parameter names and values that bind to placeholders in the SQL string.
3123 #
3124 # A parameter placeholder consists of the `@` character followed by the
3125 # parameter name (for example, `@firstName`). Parameter names can contain
3126 # letters, numbers, and underscores.
3127 #
3128 # Parameters can appear anywhere that a literal value is expected. The same
3129 # parameter name can be used more than once, for example:
3130 #
3131 # `&quot;WHERE id &gt; @msg_id AND id &lt; @msg_id + 100&quot;`
3132 #
3133 # It is an error to execute a SQL statement with unbound parameters.
3134 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
3135 },
3136 &quot;queryOptions&quot;: { # Query optimizer configuration. # Query optimizer configuration to use for the given query.
3137 &quot;optimizerVersion&quot;: &quot;A String&quot;, # An option to control the selection of optimizer version.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]3138 #
3139 # This parameter allows individual queries to pick different query
3140 # optimizer versions.
3141 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3142 # Specifying &quot;latest&quot; as a value instructs Cloud Spanner to use the
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]3143 # latest supported query optimizer version. If not specified, Cloud Spanner
3144 # uses optimizer version set at the database level options. Any other
3145 # positive integer (from the list of supported optimizer versions)
3146 # overrides the default optimizer version for query execution.
3147 # The list of supported optimizer versions can be queried from
3148 # SPANNER_SYS.SUPPORTED_OPTIMIZER_VERSIONS. Executing a SQL statement
3149 # with an invalid optimizer version will fail with a syntax error
3150 # (`INVALID_ARGUMENT`) status.
3151 #
3152 # The `optimizer_version` statement hint has precedence over this setting.
3153 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3154 }
3155
3156 x__xgafv: string, V1 error format.
3157 Allowed values
3158 1 - v1 error format
3159 2 - v2 error format
3160
3161Returns:
3162 An object of the form:
3163
3164 { # Results from Read or
3165 # ExecuteSql.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3166 &quot;stats&quot;: { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the SQL statement that
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3167 # produced this result set. These can be requested by setting
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3168 # ExecuteSqlRequest.query_mode.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3169 # DML statements always produce stats containing the number of rows
3170 # modified, unless executed using the
3171 # ExecuteSqlRequest.QueryMode.PLAN ExecuteSqlRequest.query_mode.
3172 # Other fields may or may not be populated, based on the
3173 # ExecuteSqlRequest.query_mode.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3174 &quot;rowCountExact&quot;: &quot;A String&quot;, # Standard DML returns an exact count of rows that were modified.
3175 &quot;queryStats&quot;: { # Aggregated statistics from the execution of the query. Only present when
3176 # the query is profiled. For example, a query could return the statistics as
3177 # follows:
3178 #
3179 # {
3180 # &quot;rows_returned&quot;: &quot;3&quot;,
3181 # &quot;elapsed_time&quot;: &quot;1.22 secs&quot;,
3182 # &quot;cpu_time&quot;: &quot;1.19 secs&quot;
3183 # }
3184 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
3185 },
3186 &quot;rowCountLowerBound&quot;: &quot;A String&quot;, # Partitioned DML does not offer exactly-once semantics, so it
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3187 # returns a lower bound of the rows modified.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3188 &quot;queryPlan&quot;: { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
3189 &quot;planNodes&quot;: [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
3190 # with the plan root. Each PlanNode&#x27;s `id` corresponds to its index in
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3191 # `plan_nodes`.
3192 { # Node information for nodes appearing in a QueryPlan.plan_nodes.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3193 &quot;metadata&quot;: { # Attributes relevant to the node contained in a group of key-value pairs.
3194 # For example, a Parameter Reference node could have the following
3195 # information in its metadata:
3196 #
3197 # {
3198 # &quot;parameter_reference&quot;: &quot;param1&quot;,
3199 # &quot;parameter_type&quot;: &quot;array&quot;
3200 # }
3201 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
3202 },
3203 &quot;executionStats&quot;: { # The execution statistics associated with the node, contained in a group of
3204 # key-value pairs. Only present if the plan was returned as a result of a
3205 # profile query. For example, number of executions, number of rows/time per
3206 # execution etc.
3207 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
3208 },
3209 &quot;shortRepresentation&quot;: { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
3210 # `SCALAR` PlanNode(s).
3211 &quot;description&quot;: &quot;A String&quot;, # A string representation of the expression subtree rooted at this node.
3212 &quot;subqueries&quot;: { # A mapping of (subquery variable name) -&gt; (subquery node id) for cases
3213 # where the `description` string of this node references a `SCALAR`
3214 # subquery contained in the expression subtree rooted at this node. The
3215 # referenced `SCALAR` subquery may not necessarily be a direct child of
3216 # this node.
3217 &quot;a_key&quot;: 42,
3218 },
3219 },
3220 &quot;index&quot;: 42, # The `PlanNode`&#x27;s index in node list.
3221 &quot;kind&quot;: &quot;A String&quot;, # Used to determine the type of node. May be needed for visualizing
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3222 # different kinds of nodes differently. For example, If the node is a
3223 # SCALAR node, it will have a condensed representation
3224 # which can be used to directly embed a description of the node in its
3225 # parent.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3226 &quot;displayName&quot;: &quot;A String&quot;, # The display name for the node.
3227 &quot;childLinks&quot;: [ # List of child node `index`es and their relationship to this parent.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3228 { # Metadata associated with a parent-child relationship appearing in a
3229 # PlanNode.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3230 &quot;variable&quot;: &quot;A String&quot;, # Only present if the child node is SCALAR and corresponds
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3231 # to an output variable of the parent node. The field carries the name of
3232 # the output variable.
3233 # For example, a `TableScan` operator that reads rows from a table will
3234 # have child links to the `SCALAR` nodes representing the output variables
3235 # created for each column that is read by the operator. The corresponding
3236 # `variable` fields will be set to the variable names assigned to the
3237 # columns.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3238 &quot;childIndex&quot;: 42, # The node to which the link points.
3239 &quot;type&quot;: &quot;A String&quot;, # The type of the link. For example, in Hash Joins this could be used to
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3240 # distinguish between the build child and the probe child, or in the case
3241 # of the child being an output variable, to represent the tag associated
3242 # with the output variable.
3243 },
3244 ],
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3245 },
3246 ],
3247 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3248 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3249 &quot;rows&quot;: [ # Each element in `rows` is a row whose format is defined by
3250 # metadata.row_type. The ith element
3251 # in each row matches the ith field in
3252 # metadata.row_type. Elements are
3253 # encoded based on type as described
3254 # here.
3255 [
3256 &quot;&quot;,
3257 ],
3258 ],
3259 &quot;metadata&quot;: { # Metadata about a ResultSet or PartialResultSet. # Metadata about the result set, such as row type information.
3260 &quot;rowType&quot;: { # `StructType` defines the fields of a STRUCT type. # Indicates the field names and types for the rows in the result
3261 # set. For example, a SQL query like `&quot;SELECT UserId, UserName FROM
3262 # Users&quot;` could return a `row_type` value like:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3263 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3264 # &quot;fields&quot;: [
3265 # { &quot;name&quot;: &quot;UserId&quot;, &quot;type&quot;: { &quot;code&quot;: &quot;INT64&quot; } },
3266 # { &quot;name&quot;: &quot;UserName&quot;, &quot;type&quot;: { &quot;code&quot;: &quot;STRING&quot; } },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3267 # ]
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3268 &quot;fields&quot;: [ # The list of fields that make up this struct. Order is
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3269 # significant, because values of this struct type are represented as
3270 # lists, where the order of field values matches the order of
3271 # fields in the StructType. In turn, the order of fields
3272 # matches the order of columns in a read request, or the order of
3273 # fields in the `SELECT` clause of a query.
3274 { # Message representing a single field of a struct.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3275 &quot;name&quot;: &quot;A String&quot;, # The name of the field. For reads, this is the column name. For
3276 # SQL queries, it is the column alias (e.g., `&quot;Word&quot;` in the
3277 # query `&quot;SELECT &#x27;hello&#x27; AS Word&quot;`), or the column name (e.g.,
3278 # `&quot;ColName&quot;` in the query `&quot;SELECT ColName FROM Table&quot;`). Some
3279 # columns might have an empty name (e.g., !&quot;SELECT
3280 # UPPER(ColName)&quot;`). Note that a query result can contain
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3281 # multiple fields with the same name.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3282 &quot;type&quot;: # Object with schema name: Type # The type of the field.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3283 },
3284 ],
3285 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3286 &quot;transaction&quot;: { # A transaction. # If the read or SQL query began a transaction as a side-effect, the
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3287 # information about the new transaction is yielded here.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3288 &quot;id&quot;: &quot;A String&quot;, # `id` may be used to identify the transaction in subsequent
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3289 # Read,
3290 # ExecuteSql,
3291 # Commit, or
3292 # Rollback calls.
3293 #
3294 # Single-use read-only transactions do not have IDs, because
3295 # single-use transactions do not support multiple requests.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3296 &quot;readTimestamp&quot;: &quot;A String&quot;, # For snapshot read-only transactions, the read timestamp chosen
3297 # for the transaction. Not returned by default: see
3298 # TransactionOptions.ReadOnly.return_read_timestamp.
3299 #
3300 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
3301 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3302 },
3303 },
3304 }</pre>
3305</div>
3306
3307<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]3308 <code class="details" id="executeStreamingSql">executeStreamingSql(session, body=None, x__xgafv=None)</code>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3309 <pre>Like ExecuteSql, except returns the result
3310set as a stream. Unlike ExecuteSql, there
3311is no limit on the size of the returned result set. However, no
3312individual row in the result set can exceed 100 MiB, and no
3313column value can exceed 10 MiB.
3314
3315Args:
3316 session: string, Required. The session in which the SQL query should be performed. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]3317 body: object, The request body.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3318 The object takes the form of:
3319
3320{ # The request for ExecuteSql and
3321 # ExecuteStreamingSql.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3322 &quot;queryMode&quot;: &quot;A String&quot;, # Used to control the amount of debugging information returned in
3323 # ResultSetStats. If partition_token is set, query_mode can only
3324 # be set to QueryMode.NORMAL.
3325 &quot;transaction&quot;: { # This message is used to select the transaction in which a # The transaction to use.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3326 #
3327 # For queries, if none is provided, the default is a temporary read-only
3328 # transaction with strong concurrency.
3329 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]3330 # Standard DML statements require a read-write transaction. To protect
3331 # against replays, single-use transactions are not supported. The caller
3332 # must either supply an existing transaction ID or begin a new transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3333 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]3334 # Partitioned DML requires an existing Partitioned DML transaction ID.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3335 # Read or
3336 # ExecuteSql call runs.
3337 #
3338 # See TransactionOptions for more information about transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3339 &quot;singleUse&quot;: { # # Transactions # Execute the read or SQL query in a temporary transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3340 # This is the most efficient way to execute a transaction that
3341 # consists of a single SQL query.
3342 #
3343 #
3344 # Each session can have at most one active transaction at a time. After the
3345 # active transaction is completed, the session can immediately be
3346 # re-used for the next transaction. It is not necessary to create a
3347 # new session for each transaction.
3348 #
3349 # # Transaction Modes
3350 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3351 # Cloud Spanner supports three transaction modes:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3352 #
3353 # 1. Locking read-write. This type of transaction is the only way
3354 # to write data into Cloud Spanner. These transactions rely on
3355 # pessimistic locking and, if necessary, two-phase commit.
3356 # Locking read-write transactions may abort, requiring the
3357 # application to retry.
3358 #
3359 # 2. Snapshot read-only. This transaction type provides guaranteed
3360 # consistency across several reads, but does not allow
3361 # writes. Snapshot read-only transactions can be configured to
3362 # read at timestamps in the past. Snapshot read-only
3363 # transactions do not need to be committed.
3364 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3365 # 3. Partitioned DML. This type of transaction is used to execute
3366 # a single Partitioned DML statement. Partitioned DML partitions
3367 # the key space and runs the DML statement over each partition
3368 # in parallel using separate, internal transactions that commit
3369 # independently. Partitioned DML transactions do not need to be
3370 # committed.
3371 #
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3372 # For transactions that only read, snapshot read-only transactions
3373 # provide simpler semantics and are almost always faster. In
3374 # particular, read-only transactions do not take locks, so they do
3375 # not conflict with read-write transactions. As a consequence of not
3376 # taking locks, they also do not abort, so retry loops are not needed.
3377 #
3378 # Transactions may only read/write data in a single database. They
3379 # may, however, read/write data in different tables within that
3380 # database.
3381 #
3382 # ## Locking Read-Write Transactions
3383 #
3384 # Locking transactions may be used to atomically read-modify-write
3385 # data anywhere in a database. This type of transaction is externally
3386 # consistent.
3387 #
3388 # Clients should attempt to minimize the amount of time a transaction
3389 # is active. Faster transactions commit with higher probability
3390 # and cause less contention. Cloud Spanner attempts to keep read locks
3391 # active as long as the transaction continues to do reads, and the
3392 # transaction has not been terminated by
3393 # Commit or
3394 # Rollback. Long periods of
3395 # inactivity at the client may cause Cloud Spanner to release a
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3396 # transaction&#x27;s locks and abort it.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3397 #
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3398 # Conceptually, a read-write transaction consists of zero or more
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3399 # reads or SQL statements followed by
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3400 # Commit. At any time before
3401 # Commit, the client can send a
3402 # Rollback request to abort the
3403 # transaction.
3404 #
3405 # ### Semantics
3406 #
3407 # Cloud Spanner can commit the transaction if all read locks it acquired
3408 # are still valid at commit time, and it is able to acquire write
3409 # locks for all writes. Cloud Spanner can abort the transaction for any
3410 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
3411 # that the transaction has not modified any user data in Cloud Spanner.
3412 #
3413 # Unless the transaction commits, Cloud Spanner makes no guarantees about
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3414 # how long the transaction&#x27;s locks were held for. It is an error to
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3415 # use Cloud Spanner locks for any sort of mutual exclusion other than
3416 # between Cloud Spanner transactions themselves.
3417 #
3418 # ### Retrying Aborted Transactions
3419 #
3420 # When a transaction aborts, the application can choose to retry the
3421 # whole transaction again. To maximize the chances of successfully
3422 # committing the retry, the client should execute the retry in the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3423 # same session as the original attempt. The original session&#x27;s lock
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3424 # priority increases with each consecutive abort, meaning that each
3425 # attempt has a slightly better chance of success than the previous.
3426 #
3427 # Under some circumstances (e.g., many transactions attempting to
3428 # modify the same row(s)), a transaction can abort many times in a
3429 # short period before successfully committing. Thus, it is not a good
3430 # idea to cap the number of retries a transaction can attempt;
3431 # instead, it is better to limit the total amount of wall time spent
3432 # retrying.
3433 #
3434 # ### Idle Transactions
3435 #
3436 # A transaction is considered idle if it has no outstanding reads or
3437 # SQL queries and has not started a read or SQL query within the last 10
3438 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3439 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3440 # fail with error `ABORTED`.
3441 #
3442 # If this behavior is undesirable, periodically executing a simple
3443 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
3444 # transaction from becoming idle.
3445 #
3446 # ## Snapshot Read-Only Transactions
3447 #
3448 # Snapshot read-only transactions provides a simpler method than
3449 # locking read-write transactions for doing several consistent
3450 # reads. However, this type of transaction does not support writes.
3451 #
3452 # Snapshot transactions do not take locks. Instead, they work by
3453 # choosing a Cloud Spanner timestamp, then executing all reads at that
3454 # timestamp. Since they do not acquire locks, they do not block
3455 # concurrent read-write transactions.
3456 #
3457 # Unlike locking read-write transactions, snapshot read-only
3458 # transactions never abort. They can fail if the chosen read
3459 # timestamp is garbage collected; however, the default garbage
3460 # collection policy is generous enough that most applications do not
3461 # need to worry about this in practice.
3462 #
3463 # Snapshot read-only transactions do not need to call
3464 # Commit or
3465 # Rollback (and in fact are not
3466 # permitted to do so).
3467 #
3468 # To execute a snapshot transaction, the client specifies a timestamp
3469 # bound, which tells Cloud Spanner how to choose a read timestamp.
3470 #
3471 # The types of timestamp bound are:
3472 #
3473 # - Strong (the default).
3474 # - Bounded staleness.
3475 # - Exact staleness.
3476 #
3477 # If the Cloud Spanner database to be read is geographically distributed,
3478 # stale read-only transactions can execute more quickly than strong
3479 # or read-write transaction, because they are able to execute far
3480 # from the leader replica.
3481 #
3482 # Each type of timestamp bound is discussed in detail below.
3483 #
3484 # ### Strong
3485 #
3486 # Strong reads are guaranteed to see the effects of all transactions
3487 # that have committed before the start of the read. Furthermore, all
3488 # rows yielded by a single read are consistent with each other -- if
3489 # any part of the read observes a transaction, all parts of the read
3490 # see the transaction.
3491 #
3492 # Strong reads are not repeatable: two consecutive strong read-only
3493 # transactions might return inconsistent results if there are
3494 # concurrent writes. If consistency across reads is required, the
3495 # reads should be executed within a transaction or at an exact read
3496 # timestamp.
3497 #
3498 # See TransactionOptions.ReadOnly.strong.
3499 #
3500 # ### Exact Staleness
3501 #
3502 # These timestamp bounds execute reads at a user-specified
3503 # timestamp. Reads at a timestamp are guaranteed to see a consistent
3504 # prefix of the global transaction history: they observe
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]3505 # modifications done by all transactions with a commit timestamp &lt;=
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3506 # the read timestamp, and observe none of the modifications done by
3507 # transactions with a larger commit timestamp. They will block until
3508 # all conflicting transactions that may be assigned commit timestamps
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]3509 # &lt;= the read timestamp have finished.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3510 #
3511 # The timestamp can either be expressed as an absolute Cloud Spanner commit
3512 # timestamp or a staleness relative to the current time.
3513 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3514 # These modes do not require a &quot;negotiation phase&quot; to pick a
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3515 # timestamp. As a result, they execute slightly faster than the
3516 # equivalent boundedly stale concurrency modes. On the other hand,
3517 # boundedly stale reads usually return fresher results.
3518 #
3519 # See TransactionOptions.ReadOnly.read_timestamp and
3520 # TransactionOptions.ReadOnly.exact_staleness.
3521 #
3522 # ### Bounded Staleness
3523 #
3524 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
3525 # subject to a user-provided staleness bound. Cloud Spanner chooses the
3526 # newest timestamp within the staleness bound that allows execution
3527 # of the reads at the closest available replica without blocking.
3528 #
3529 # All rows yielded are consistent with each other -- if any part of
3530 # the read observes a transaction, all parts of the read see the
3531 # transaction. Boundedly stale reads are not repeatable: two stale
3532 # reads, even if they use the same staleness bound, can execute at
3533 # different timestamps and thus return inconsistent results.
3534 #
3535 # Boundedly stale reads execute in two phases: the first phase
3536 # negotiates a timestamp among all replicas needed to serve the
3537 # read. In the second phase, reads are executed at the negotiated
3538 # timestamp.
3539 #
3540 # As a result of the two phase execution, bounded staleness reads are
3541 # usually a little slower than comparable exact staleness
3542 # reads. However, they are typically able to return fresher
3543 # results, and are more likely to execute at the closest replica.
3544 #
3545 # Because the timestamp negotiation requires up-front knowledge of
3546 # which rows will be read, it can only be used with single-use
3547 # read-only transactions.
3548 #
3549 # See TransactionOptions.ReadOnly.max_staleness and
3550 # TransactionOptions.ReadOnly.min_read_timestamp.
3551 #
3552 # ### Old Read Timestamps and Garbage Collection
3553 #
3554 # Cloud Spanner continuously garbage collects deleted and overwritten data
3555 # in the background to reclaim storage space. This process is known
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3556 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3557 # are one hour old. Because of this, Cloud Spanner cannot perform reads
3558 # at read timestamps more than one hour in the past. This
3559 # restriction also applies to in-progress reads and/or SQL queries whose
3560 # timestamp become too old while executing. Reads and SQL queries with
3561 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3562 #
3563 # ## Partitioned DML Transactions
3564 #
3565 # Partitioned DML transactions are used to execute DML statements with a
3566 # different execution strategy that provides different, and often better,
3567 # scalability properties for large, table-wide operations than DML in a
3568 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
3569 # should prefer using ReadWrite transactions.
3570 #
3571 # Partitioned DML partitions the keyspace and runs the DML statement on each
3572 # partition in separate, internal transactions. These transactions commit
3573 # automatically when complete, and run independently from one another.
3574 #
3575 # To reduce lock contention, this execution strategy only acquires read locks
3576 # on rows that match the WHERE clause of the statement. Additionally, the
3577 # smaller per-partition transactions hold locks for less time.
3578 #
3579 # That said, Partitioned DML is not a drop-in replacement for standard DML used
3580 # in ReadWrite transactions.
3581 #
3582 # - The DML statement must be fully-partitionable. Specifically, the statement
3583 # must be expressible as the union of many statements which each access only
3584 # a single row of the table.
3585 #
3586 # - The statement is not applied atomically to all rows of the table. Rather,
3587 # the statement is applied atomically to partitions of the table, in
3588 # independent transactions. Secondary index rows are updated atomically
3589 # with the base table rows.
3590 #
3591 # - Partitioned DML does not guarantee exactly-once execution semantics
3592 # against a partition. The statement will be applied at least once to each
3593 # partition. It is strongly recommended that the DML statement should be
3594 # idempotent to avoid unexpected results. For instance, it is potentially
3595 # dangerous to run a statement such as
3596 # `UPDATE table SET column = column + 1` as it could be run multiple times
3597 # against some rows.
3598 #
3599 # - The partitions are committed automatically - there is no support for
3600 # Commit or Rollback. If the call returns an error, or if the client issuing
3601 # the ExecuteSql call dies, it is possible that some rows had the statement
3602 # executed on them successfully. It is also possible that statement was
3603 # never executed against other rows.
3604 #
3605 # - Partitioned DML transactions may only contain the execution of a single
3606 # DML statement via ExecuteSql or ExecuteStreamingSql.
3607 #
3608 # - If any error is encountered during the execution of the partitioned DML
3609 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
3610 # value that cannot be stored due to schema constraints), then the
3611 # operation is stopped at that point and an error is returned. It is
3612 # possible that at this point, some partitions have been committed (or even
3613 # committed multiple times), and other partitions have not been run at all.
3614 #
3615 # Given the above, Partitioned DML is good fit for large, database-wide,
3616 # operations that are idempotent, such as deleting old rows from a very large
3617 # table.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3618 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3619 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3620 # Authorization to begin a Partitioned DML transaction requires
3621 # `spanner.databases.beginPartitionedDmlTransaction` permission
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3622 # on the `session` resource.
3623 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3624 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3625 #
3626 # Authorization to begin a read-only transaction requires
3627 # `spanner.databases.beginReadOnlyTransaction` permission
3628 # on the `session` resource.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3629 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3630 #
3631 # This is useful for requesting fresher data than some previous
3632 # read, or data that is fresh enough to observe the effects of some
3633 # previously committed transaction whose timestamp is known.
3634 #
3635 # Note that this option can only be used in single-use transactions.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3636 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3637 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
3638 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
3639 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]3640 # reads at a specific timestamp are repeatable; the same read at
3641 # the same timestamp always returns the same data. If the
3642 # timestamp is in the future, the read will block until the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3643 # specified timestamp, modulo the read&#x27;s deadline.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]3644 #
3645 # Useful for large scale consistent reads such as mapreduces, or
3646 # for coordinating many reads against a consistent snapshot of the
3647 # data.
3648 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3649 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
3650 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
3651 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3652 # seconds. Guarantees that all writes that have committed more
3653 # than the specified number of seconds ago are visible. Because
3654 # Cloud Spanner chooses the exact timestamp, this mode works even if
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3655 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3656 # commit timestamps.
3657 #
3658 # Useful for reading the freshest data available at a nearby
3659 # replica, while bounding the possible staleness if the local
3660 # replica has fallen behind.
3661 #
3662 # Note that this option can only be used in single-use
3663 # transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3664 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
3665 # the Transaction message that describes the transaction.
3666 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3667 # old. The timestamp is chosen soon after the read is started.
3668 #
3669 # Guarantees that all writes that have committed more than the
3670 # specified number of seconds ago are visible. Because Cloud Spanner
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3671 # chooses the exact timestamp, this mode works even if the client&#x27;s
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3672 # local clock is substantially skewed from Cloud Spanner commit
3673 # timestamps.
3674 #
3675 # Useful for reading at nearby replicas without the distributed
3676 # timestamp negotiation overhead of `max_staleness`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3677 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]3678 # are visible.
3679 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3680 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
3681 #
3682 # Authorization to begin a read-write transaction requires
3683 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
3684 # on the `session` resource.
3685 # transaction type has no options.
3686 },
3687 },
3688 &quot;begin&quot;: { # # Transactions # Begin a new transaction and execute this read or SQL query in
3689 # it. The transaction ID of the new transaction is returned in
3690 # ResultSetMetadata.transaction, which is a Transaction.
3691 #
3692 #
3693 # Each session can have at most one active transaction at a time. After the
3694 # active transaction is completed, the session can immediately be
3695 # re-used for the next transaction. It is not necessary to create a
3696 # new session for each transaction.
3697 #
3698 # # Transaction Modes
3699 #
3700 # Cloud Spanner supports three transaction modes:
3701 #
3702 # 1. Locking read-write. This type of transaction is the only way
3703 # to write data into Cloud Spanner. These transactions rely on
3704 # pessimistic locking and, if necessary, two-phase commit.
3705 # Locking read-write transactions may abort, requiring the
3706 # application to retry.
3707 #
3708 # 2. Snapshot read-only. This transaction type provides guaranteed
3709 # consistency across several reads, but does not allow
3710 # writes. Snapshot read-only transactions can be configured to
3711 # read at timestamps in the past. Snapshot read-only
3712 # transactions do not need to be committed.
3713 #
3714 # 3. Partitioned DML. This type of transaction is used to execute
3715 # a single Partitioned DML statement. Partitioned DML partitions
3716 # the key space and runs the DML statement over each partition
3717 # in parallel using separate, internal transactions that commit
3718 # independently. Partitioned DML transactions do not need to be
3719 # committed.
3720 #
3721 # For transactions that only read, snapshot read-only transactions
3722 # provide simpler semantics and are almost always faster. In
3723 # particular, read-only transactions do not take locks, so they do
3724 # not conflict with read-write transactions. As a consequence of not
3725 # taking locks, they also do not abort, so retry loops are not needed.
3726 #
3727 # Transactions may only read/write data in a single database. They
3728 # may, however, read/write data in different tables within that
3729 # database.
3730 #
3731 # ## Locking Read-Write Transactions
3732 #
3733 # Locking transactions may be used to atomically read-modify-write
3734 # data anywhere in a database. This type of transaction is externally
3735 # consistent.
3736 #
3737 # Clients should attempt to minimize the amount of time a transaction
3738 # is active. Faster transactions commit with higher probability
3739 # and cause less contention. Cloud Spanner attempts to keep read locks
3740 # active as long as the transaction continues to do reads, and the
3741 # transaction has not been terminated by
3742 # Commit or
3743 # Rollback. Long periods of
3744 # inactivity at the client may cause Cloud Spanner to release a
3745 # transaction&#x27;s locks and abort it.
3746 #
3747 # Conceptually, a read-write transaction consists of zero or more
3748 # reads or SQL statements followed by
3749 # Commit. At any time before
3750 # Commit, the client can send a
3751 # Rollback request to abort the
3752 # transaction.
3753 #
3754 # ### Semantics
3755 #
3756 # Cloud Spanner can commit the transaction if all read locks it acquired
3757 # are still valid at commit time, and it is able to acquire write
3758 # locks for all writes. Cloud Spanner can abort the transaction for any
3759 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
3760 # that the transaction has not modified any user data in Cloud Spanner.
3761 #
3762 # Unless the transaction commits, Cloud Spanner makes no guarantees about
3763 # how long the transaction&#x27;s locks were held for. It is an error to
3764 # use Cloud Spanner locks for any sort of mutual exclusion other than
3765 # between Cloud Spanner transactions themselves.
3766 #
3767 # ### Retrying Aborted Transactions
3768 #
3769 # When a transaction aborts, the application can choose to retry the
3770 # whole transaction again. To maximize the chances of successfully
3771 # committing the retry, the client should execute the retry in the
3772 # same session as the original attempt. The original session&#x27;s lock
3773 # priority increases with each consecutive abort, meaning that each
3774 # attempt has a slightly better chance of success than the previous.
3775 #
3776 # Under some circumstances (e.g., many transactions attempting to
3777 # modify the same row(s)), a transaction can abort many times in a
3778 # short period before successfully committing. Thus, it is not a good
3779 # idea to cap the number of retries a transaction can attempt;
3780 # instead, it is better to limit the total amount of wall time spent
3781 # retrying.
3782 #
3783 # ### Idle Transactions
3784 #
3785 # A transaction is considered idle if it has no outstanding reads or
3786 # SQL queries and has not started a read or SQL query within the last 10
3787 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
3788 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
3789 # fail with error `ABORTED`.
3790 #
3791 # If this behavior is undesirable, periodically executing a simple
3792 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
3793 # transaction from becoming idle.
3794 #
3795 # ## Snapshot Read-Only Transactions
3796 #
3797 # Snapshot read-only transactions provides a simpler method than
3798 # locking read-write transactions for doing several consistent
3799 # reads. However, this type of transaction does not support writes.
3800 #
3801 # Snapshot transactions do not take locks. Instead, they work by
3802 # choosing a Cloud Spanner timestamp, then executing all reads at that
3803 # timestamp. Since they do not acquire locks, they do not block
3804 # concurrent read-write transactions.
3805 #
3806 # Unlike locking read-write transactions, snapshot read-only
3807 # transactions never abort. They can fail if the chosen read
3808 # timestamp is garbage collected; however, the default garbage
3809 # collection policy is generous enough that most applications do not
3810 # need to worry about this in practice.
3811 #
3812 # Snapshot read-only transactions do not need to call
3813 # Commit or
3814 # Rollback (and in fact are not
3815 # permitted to do so).
3816 #
3817 # To execute a snapshot transaction, the client specifies a timestamp
3818 # bound, which tells Cloud Spanner how to choose a read timestamp.
3819 #
3820 # The types of timestamp bound are:
3821 #
3822 # - Strong (the default).
3823 # - Bounded staleness.
3824 # - Exact staleness.
3825 #
3826 # If the Cloud Spanner database to be read is geographically distributed,
3827 # stale read-only transactions can execute more quickly than strong
3828 # or read-write transaction, because they are able to execute far
3829 # from the leader replica.
3830 #
3831 # Each type of timestamp bound is discussed in detail below.
3832 #
3833 # ### Strong
3834 #
3835 # Strong reads are guaranteed to see the effects of all transactions
3836 # that have committed before the start of the read. Furthermore, all
3837 # rows yielded by a single read are consistent with each other -- if
3838 # any part of the read observes a transaction, all parts of the read
3839 # see the transaction.
3840 #
3841 # Strong reads are not repeatable: two consecutive strong read-only
3842 # transactions might return inconsistent results if there are
3843 # concurrent writes. If consistency across reads is required, the
3844 # reads should be executed within a transaction or at an exact read
3845 # timestamp.
3846 #
3847 # See TransactionOptions.ReadOnly.strong.
3848 #
3849 # ### Exact Staleness
3850 #
3851 # These timestamp bounds execute reads at a user-specified
3852 # timestamp. Reads at a timestamp are guaranteed to see a consistent
3853 # prefix of the global transaction history: they observe
3854 # modifications done by all transactions with a commit timestamp &lt;=
3855 # the read timestamp, and observe none of the modifications done by
3856 # transactions with a larger commit timestamp. They will block until
3857 # all conflicting transactions that may be assigned commit timestamps
3858 # &lt;= the read timestamp have finished.
3859 #
3860 # The timestamp can either be expressed as an absolute Cloud Spanner commit
3861 # timestamp or a staleness relative to the current time.
3862 #
3863 # These modes do not require a &quot;negotiation phase&quot; to pick a
3864 # timestamp. As a result, they execute slightly faster than the
3865 # equivalent boundedly stale concurrency modes. On the other hand,
3866 # boundedly stale reads usually return fresher results.
3867 #
3868 # See TransactionOptions.ReadOnly.read_timestamp and
3869 # TransactionOptions.ReadOnly.exact_staleness.
3870 #
3871 # ### Bounded Staleness
3872 #
3873 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
3874 # subject to a user-provided staleness bound. Cloud Spanner chooses the
3875 # newest timestamp within the staleness bound that allows execution
3876 # of the reads at the closest available replica without blocking.
3877 #
3878 # All rows yielded are consistent with each other -- if any part of
3879 # the read observes a transaction, all parts of the read see the
3880 # transaction. Boundedly stale reads are not repeatable: two stale
3881 # reads, even if they use the same staleness bound, can execute at
3882 # different timestamps and thus return inconsistent results.
3883 #
3884 # Boundedly stale reads execute in two phases: the first phase
3885 # negotiates a timestamp among all replicas needed to serve the
3886 # read. In the second phase, reads are executed at the negotiated
3887 # timestamp.
3888 #
3889 # As a result of the two phase execution, bounded staleness reads are
3890 # usually a little slower than comparable exact staleness
3891 # reads. However, they are typically able to return fresher
3892 # results, and are more likely to execute at the closest replica.
3893 #
3894 # Because the timestamp negotiation requires up-front knowledge of
3895 # which rows will be read, it can only be used with single-use
3896 # read-only transactions.
3897 #
3898 # See TransactionOptions.ReadOnly.max_staleness and
3899 # TransactionOptions.ReadOnly.min_read_timestamp.
3900 #
3901 # ### Old Read Timestamps and Garbage Collection
3902 #
3903 # Cloud Spanner continuously garbage collects deleted and overwritten data
3904 # in the background to reclaim storage space. This process is known
3905 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
3906 # are one hour old. Because of this, Cloud Spanner cannot perform reads
3907 # at read timestamps more than one hour in the past. This
3908 # restriction also applies to in-progress reads and/or SQL queries whose
3909 # timestamp become too old while executing. Reads and SQL queries with
3910 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
3911 #
3912 # ## Partitioned DML Transactions
3913 #
3914 # Partitioned DML transactions are used to execute DML statements with a
3915 # different execution strategy that provides different, and often better,
3916 # scalability properties for large, table-wide operations than DML in a
3917 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
3918 # should prefer using ReadWrite transactions.
3919 #
3920 # Partitioned DML partitions the keyspace and runs the DML statement on each
3921 # partition in separate, internal transactions. These transactions commit
3922 # automatically when complete, and run independently from one another.
3923 #
3924 # To reduce lock contention, this execution strategy only acquires read locks
3925 # on rows that match the WHERE clause of the statement. Additionally, the
3926 # smaller per-partition transactions hold locks for less time.
3927 #
3928 # That said, Partitioned DML is not a drop-in replacement for standard DML used
3929 # in ReadWrite transactions.
3930 #
3931 # - The DML statement must be fully-partitionable. Specifically, the statement
3932 # must be expressible as the union of many statements which each access only
3933 # a single row of the table.
3934 #
3935 # - The statement is not applied atomically to all rows of the table. Rather,
3936 # the statement is applied atomically to partitions of the table, in
3937 # independent transactions. Secondary index rows are updated atomically
3938 # with the base table rows.
3939 #
3940 # - Partitioned DML does not guarantee exactly-once execution semantics
3941 # against a partition. The statement will be applied at least once to each
3942 # partition. It is strongly recommended that the DML statement should be
3943 # idempotent to avoid unexpected results. For instance, it is potentially
3944 # dangerous to run a statement such as
3945 # `UPDATE table SET column = column + 1` as it could be run multiple times
3946 # against some rows.
3947 #
3948 # - The partitions are committed automatically - there is no support for
3949 # Commit or Rollback. If the call returns an error, or if the client issuing
3950 # the ExecuteSql call dies, it is possible that some rows had the statement
3951 # executed on them successfully. It is also possible that statement was
3952 # never executed against other rows.
3953 #
3954 # - Partitioned DML transactions may only contain the execution of a single
3955 # DML statement via ExecuteSql or ExecuteStreamingSql.
3956 #
3957 # - If any error is encountered during the execution of the partitioned DML
3958 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
3959 # value that cannot be stored due to schema constraints), then the
3960 # operation is stopped at that point and an error is returned. It is
3961 # possible that at this point, some partitions have been committed (or even
3962 # committed multiple times), and other partitions have not been run at all.
3963 #
3964 # Given the above, Partitioned DML is good fit for large, database-wide,
3965 # operations that are idempotent, such as deleting old rows from a very large
3966 # table.
3967 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]3968 #
3969 # Authorization to begin a Partitioned DML transaction requires
3970 # `spanner.databases.beginPartitionedDmlTransaction` permission
3971 # on the `session` resource.
3972 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]3973 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
3974 #
3975 # Authorization to begin a read-only transaction requires
3976 # `spanner.databases.beginReadOnlyTransaction` permission
3977 # on the `session` resource.
3978 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
3979 #
3980 # This is useful for requesting fresher data than some previous
3981 # read, or data that is fresh enough to observe the effects of some
3982 # previously committed transaction whose timestamp is known.
3983 #
3984 # Note that this option can only be used in single-use transactions.
3985 #
3986 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
3987 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
3988 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
3989 # reads at a specific timestamp are repeatable; the same read at
3990 # the same timestamp always returns the same data. If the
3991 # timestamp is in the future, the read will block until the
3992 # specified timestamp, modulo the read&#x27;s deadline.
3993 #
3994 # Useful for large scale consistent reads such as mapreduces, or
3995 # for coordinating many reads against a consistent snapshot of the
3996 # data.
3997 #
3998 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
3999 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
4000 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
4001 # seconds. Guarantees that all writes that have committed more
4002 # than the specified number of seconds ago are visible. Because
4003 # Cloud Spanner chooses the exact timestamp, this mode works even if
4004 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
4005 # commit timestamps.
4006 #
4007 # Useful for reading the freshest data available at a nearby
4008 # replica, while bounding the possible staleness if the local
4009 # replica has fallen behind.
4010 #
4011 # Note that this option can only be used in single-use
4012 # transactions.
4013 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
4014 # the Transaction message that describes the transaction.
4015 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
4016 # old. The timestamp is chosen soon after the read is started.
4017 #
4018 # Guarantees that all writes that have committed more than the
4019 # specified number of seconds ago are visible. Because Cloud Spanner
4020 # chooses the exact timestamp, this mode works even if the client&#x27;s
4021 # local clock is substantially skewed from Cloud Spanner commit
4022 # timestamps.
4023 #
4024 # Useful for reading at nearby replicas without the distributed
4025 # timestamp negotiation overhead of `max_staleness`.
4026 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
4027 # are visible.
4028 },
4029 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
4030 #
4031 # Authorization to begin a read-write transaction requires
4032 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
4033 # on the `session` resource.
4034 # transaction type has no options.
4035 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4036 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4037 &quot;id&quot;: &quot;A String&quot;, # Execute the read or SQL query in a previously-started transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4038 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4039 &quot;resumeToken&quot;: &quot;A String&quot;, # If this request is resuming a previously interrupted SQL statement
4040 # execution, `resume_token` should be copied from the last
4041 # PartialResultSet yielded before the interruption. Doing this
4042 # enables the new SQL statement execution to resume where the last one left
4043 # off. The rest of the request parameters must exactly match the
4044 # request that yielded this token.
4045 &quot;partitionToken&quot;: &quot;A String&quot;, # If present, results will be restricted to the specified partition
4046 # previously created using PartitionQuery(). There must be an exact
4047 # match for the values of fields common to this message and the
4048 # PartitionQueryRequest message used to create this partition_token.
4049 &quot;seqno&quot;: &quot;A String&quot;, # A per-transaction sequence number used to identify this request. This field
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4050 # makes each request idempotent such that if the request is received multiple
4051 # times, at most one will succeed.
4052 #
4053 # The sequence number must be monotonically increasing within the
4054 # transaction. If a request arrives for the first time with an out-of-order
4055 # sequence number, the transaction may be aborted. Replays of previously
4056 # handled requests will yield the same response as the first execution.
4057 #
4058 # Required for DML statements. Ignored for queries.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4059 &quot;paramTypes&quot;: { # It is not always possible for Cloud Spanner to infer the right SQL type
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4060 # from a JSON value. For example, values of type `BYTES` and values
4061 # of type `STRING` both appear in params as JSON strings.
4062 #
4063 # In these cases, `param_types` can be used to specify the exact
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4064 # SQL type for some or all of the SQL statement parameters. See the
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4065 # definition of Type for more information
4066 # about SQL types.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4067 &quot;a_key&quot;: { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4068 # table cell or returned from an SQL query.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4069 &quot;arrayElementType&quot;: # Object with schema name: Type # If code == ARRAY, then `array_element_type`
4070 # is the type of the array elements.
4071 &quot;code&quot;: &quot;A String&quot;, # Required. The TypeCode for this type.
4072 &quot;structType&quot;: { # `StructType` defines the fields of a STRUCT type. # If code == STRUCT, then `struct_type`
4073 # provides type information for the struct&#x27;s fields.
4074 &quot;fields&quot;: [ # The list of fields that make up this struct. Order is
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]4075 # significant, because values of this struct type are represented as
4076 # lists, where the order of field values matches the order of
4077 # fields in the StructType. In turn, the order of fields
4078 # matches the order of columns in a read request, or the order of
4079 # fields in the `SELECT` clause of a query.
4080 { # Message representing a single field of a struct.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4081 &quot;name&quot;: &quot;A String&quot;, # The name of the field. For reads, this is the column name. For
4082 # SQL queries, it is the column alias (e.g., `&quot;Word&quot;` in the
4083 # query `&quot;SELECT &#x27;hello&#x27; AS Word&quot;`), or the column name (e.g.,
4084 # `&quot;ColName&quot;` in the query `&quot;SELECT ColName FROM Table&quot;`). Some
4085 # columns might have an empty name (e.g., !&quot;SELECT
4086 # UPPER(ColName)&quot;`). Note that a query result can contain
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]4087 # multiple fields with the same name.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4088 &quot;type&quot;: # Object with schema name: Type # The type of the field.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]4089 },
4090 ],
4091 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4092 },
4093 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4094 &quot;sql&quot;: &quot;A String&quot;, # Required. The SQL string.
4095 &quot;params&quot;: { # Parameter names and values that bind to placeholders in the SQL string.
4096 #
4097 # A parameter placeholder consists of the `@` character followed by the
4098 # parameter name (for example, `@firstName`). Parameter names can contain
4099 # letters, numbers, and underscores.
4100 #
4101 # Parameters can appear anywhere that a literal value is expected. The same
4102 # parameter name can be used more than once, for example:
4103 #
4104 # `&quot;WHERE id &gt; @msg_id AND id &lt; @msg_id + 100&quot;`
4105 #
4106 # It is an error to execute a SQL statement with unbound parameters.
4107 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
4108 },
4109 &quot;queryOptions&quot;: { # Query optimizer configuration. # Query optimizer configuration to use for the given query.
4110 &quot;optimizerVersion&quot;: &quot;A String&quot;, # An option to control the selection of optimizer version.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]4111 #
4112 # This parameter allows individual queries to pick different query
4113 # optimizer versions.
4114 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4115 # Specifying &quot;latest&quot; as a value instructs Cloud Spanner to use the
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]4116 # latest supported query optimizer version. If not specified, Cloud Spanner
4117 # uses optimizer version set at the database level options. Any other
4118 # positive integer (from the list of supported optimizer versions)
4119 # overrides the default optimizer version for query execution.
4120 # The list of supported optimizer versions can be queried from
4121 # SPANNER_SYS.SUPPORTED_OPTIMIZER_VERSIONS. Executing a SQL statement
4122 # with an invalid optimizer version will fail with a syntax error
4123 # (`INVALID_ARGUMENT`) status.
4124 #
4125 # The `optimizer_version` statement hint has precedence over this setting.
4126 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4127 }
4128
4129 x__xgafv: string, V1 error format.
4130 Allowed values
4131 1 - v1 error format
4132 2 - v2 error format
4133
4134Returns:
4135 An object of the form:
4136
4137 { # Partial results from a streaming read or SQL query. Streaming reads and
4138 # SQL queries better tolerate large result sets, large rows, and large
4139 # values, but are a little trickier to consume.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4140 &quot;values&quot;: [ # A streamed result set consists of a stream of values, which might
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4141 # be split into many `PartialResultSet` messages to accommodate
4142 # large rows and/or large values. Every N complete values defines a
4143 # row, where N is equal to the number of entries in
4144 # metadata.row_type.fields.
4145 #
4146 # Most values are encoded based on type as described
4147 # here.
4148 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4149 # It is possible that the last value in values is &quot;chunked&quot;,
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4150 # meaning that the rest of the value is sent in subsequent
4151 # `PartialResultSet`(s). This is denoted by the chunked_value
4152 # field. Two or more chunked values can be merged to form a
4153 # complete value as follows:
4154 #
4155 # * `bool/number/null`: cannot be chunked
4156 # * `string`: concatenate the strings
4157 # * `list`: concatenate the lists. If the last element in a list is a
4158 # `string`, `list`, or `object`, merge it with the first element in
4159 # the next list by applying these rules recursively.
4160 # * `object`: concatenate the (field name, field value) pairs. If a
4161 # field name is duplicated, then apply these rules recursively
4162 # to merge the field values.
4163 #
4164 # Some examples of merging:
4165 #
4166 # # Strings are concatenated.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4167 # &quot;foo&quot;, &quot;bar&quot; =&gt; &quot;foobar&quot;
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4168 #
4169 # # Lists of non-strings are concatenated.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]4170 # [2, 3], [4] =&gt; [2, 3, 4]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4171 #
4172 # # Lists are concatenated, but the last and first elements are merged
4173 # # because they are strings.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4174 # [&quot;a&quot;, &quot;b&quot;], [&quot;c&quot;, &quot;d&quot;] =&gt; [&quot;a&quot;, &quot;bc&quot;, &quot;d&quot;]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4175 #
4176 # # Lists are concatenated, but the last and first elements are merged
4177 # # because they are lists. Recursively, the last and first elements
4178 # # of the inner lists are merged because they are strings.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4179 # [&quot;a&quot;, [&quot;b&quot;, &quot;c&quot;]], [[&quot;d&quot;], &quot;e&quot;] =&gt; [&quot;a&quot;, [&quot;b&quot;, &quot;cd&quot;], &quot;e&quot;]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4180 #
4181 # # Non-overlapping object fields are combined.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4182 # {&quot;a&quot;: &quot;1&quot;}, {&quot;b&quot;: &quot;2&quot;} =&gt; {&quot;a&quot;: &quot;1&quot;, &quot;b&quot;: 2&quot;}
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4183 #
4184 # # Overlapping object fields are merged.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4185 # {&quot;a&quot;: &quot;1&quot;}, {&quot;a&quot;: &quot;2&quot;} =&gt; {&quot;a&quot;: &quot;12&quot;}
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4186 #
4187 # # Examples of merging objects containing lists of strings.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4188 # {&quot;a&quot;: [&quot;1&quot;]}, {&quot;a&quot;: [&quot;2&quot;]} =&gt; {&quot;a&quot;: [&quot;12&quot;]}
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4189 #
4190 # For a more complete example, suppose a streaming SQL query is
4191 # yielding a result set whose rows contain a single string
4192 # field. The following `PartialResultSet`s might be yielded:
4193 #
4194 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4195 # &quot;metadata&quot;: { ... }
4196 # &quot;values&quot;: [&quot;Hello&quot;, &quot;W&quot;]
4197 # &quot;chunked_value&quot;: true
4198 # &quot;resume_token&quot;: &quot;Af65...&quot;
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4199 # }
4200 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4201 # &quot;values&quot;: [&quot;orl&quot;]
4202 # &quot;chunked_value&quot;: true
4203 # &quot;resume_token&quot;: &quot;Bqp2...&quot;
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4204 # }
4205 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4206 # &quot;values&quot;: [&quot;d&quot;]
4207 # &quot;resume_token&quot;: &quot;Zx1B...&quot;
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4208 # }
4209 #
4210 # This sequence of `PartialResultSet`s encodes two rows, one
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4211 # containing the field value `&quot;Hello&quot;`, and a second containing the
4212 # field value `&quot;World&quot; = &quot;W&quot; + &quot;orl&quot; + &quot;d&quot;`.
4213 &quot;&quot;,
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4214 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4215 &quot;metadata&quot;: { # Metadata about a ResultSet or PartialResultSet. # Metadata about the result set, such as row type information.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4216 # Only present in the first response.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4217 &quot;rowType&quot;: { # `StructType` defines the fields of a STRUCT type. # Indicates the field names and types for the rows in the result
4218 # set. For example, a SQL query like `&quot;SELECT UserId, UserName FROM
4219 # Users&quot;` could return a `row_type` value like:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4220 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4221 # &quot;fields&quot;: [
4222 # { &quot;name&quot;: &quot;UserId&quot;, &quot;type&quot;: { &quot;code&quot;: &quot;INT64&quot; } },
4223 # { &quot;name&quot;: &quot;UserName&quot;, &quot;type&quot;: { &quot;code&quot;: &quot;STRING&quot; } },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4224 # ]
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4225 &quot;fields&quot;: [ # The list of fields that make up this struct. Order is
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4226 # significant, because values of this struct type are represented as
4227 # lists, where the order of field values matches the order of
4228 # fields in the StructType. In turn, the order of fields
4229 # matches the order of columns in a read request, or the order of
4230 # fields in the `SELECT` clause of a query.
4231 { # Message representing a single field of a struct.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4232 &quot;name&quot;: &quot;A String&quot;, # The name of the field. For reads, this is the column name. For
4233 # SQL queries, it is the column alias (e.g., `&quot;Word&quot;` in the
4234 # query `&quot;SELECT &#x27;hello&#x27; AS Word&quot;`), or the column name (e.g.,
4235 # `&quot;ColName&quot;` in the query `&quot;SELECT ColName FROM Table&quot;`). Some
4236 # columns might have an empty name (e.g., !&quot;SELECT
4237 # UPPER(ColName)&quot;`). Note that a query result can contain
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4238 # multiple fields with the same name.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4239 &quot;type&quot;: # Object with schema name: Type # The type of the field.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4240 },
4241 ],
4242 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4243 &quot;transaction&quot;: { # A transaction. # If the read or SQL query began a transaction as a side-effect, the
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4244 # information about the new transaction is yielded here.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4245 &quot;id&quot;: &quot;A String&quot;, # `id` may be used to identify the transaction in subsequent
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4246 # Read,
4247 # ExecuteSql,
4248 # Commit, or
4249 # Rollback calls.
4250 #
4251 # Single-use read-only transactions do not have IDs, because
4252 # single-use transactions do not support multiple requests.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4253 &quot;readTimestamp&quot;: &quot;A String&quot;, # For snapshot read-only transactions, the read timestamp chosen
4254 # for the transaction. Not returned by default: see
4255 # TransactionOptions.ReadOnly.return_read_timestamp.
4256 #
4257 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
4258 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4259 },
4260 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4261 &quot;resumeToken&quot;: &quot;A String&quot;, # Streaming calls might be interrupted for a variety of reasons, such
4262 # as TCP connection loss. If this occurs, the stream of results can
4263 # be resumed by re-sending the original request and including
4264 # `resume_token`. Note that executing any other transaction in the
4265 # same session invalidates the token.
4266 &quot;stats&quot;: { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the statement that produced this
4267 # streaming result set. These can be requested by setting
4268 # ExecuteSqlRequest.query_mode and are sent
4269 # only once with the last response in the stream.
4270 # This field will also be present in the last response for DML
4271 # statements.
4272 &quot;rowCountExact&quot;: &quot;A String&quot;, # Standard DML returns an exact count of rows that were modified.
4273 &quot;queryStats&quot;: { # Aggregated statistics from the execution of the query. Only present when
4274 # the query is profiled. For example, a query could return the statistics as
4275 # follows:
4276 #
4277 # {
4278 # &quot;rows_returned&quot;: &quot;3&quot;,
4279 # &quot;elapsed_time&quot;: &quot;1.22 secs&quot;,
4280 # &quot;cpu_time&quot;: &quot;1.19 secs&quot;
4281 # }
4282 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
4283 },
4284 &quot;rowCountLowerBound&quot;: &quot;A String&quot;, # Partitioned DML does not offer exactly-once semantics, so it
4285 # returns a lower bound of the rows modified.
4286 &quot;queryPlan&quot;: { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
4287 &quot;planNodes&quot;: [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
4288 # with the plan root. Each PlanNode&#x27;s `id` corresponds to its index in
4289 # `plan_nodes`.
4290 { # Node information for nodes appearing in a QueryPlan.plan_nodes.
4291 &quot;metadata&quot;: { # Attributes relevant to the node contained in a group of key-value pairs.
4292 # For example, a Parameter Reference node could have the following
4293 # information in its metadata:
4294 #
4295 # {
4296 # &quot;parameter_reference&quot;: &quot;param1&quot;,
4297 # &quot;parameter_type&quot;: &quot;array&quot;
4298 # }
4299 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
4300 },
4301 &quot;executionStats&quot;: { # The execution statistics associated with the node, contained in a group of
4302 # key-value pairs. Only present if the plan was returned as a result of a
4303 # profile query. For example, number of executions, number of rows/time per
4304 # execution etc.
4305 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
4306 },
4307 &quot;shortRepresentation&quot;: { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
4308 # `SCALAR` PlanNode(s).
4309 &quot;description&quot;: &quot;A String&quot;, # A string representation of the expression subtree rooted at this node.
4310 &quot;subqueries&quot;: { # A mapping of (subquery variable name) -&gt; (subquery node id) for cases
4311 # where the `description` string of this node references a `SCALAR`
4312 # subquery contained in the expression subtree rooted at this node. The
4313 # referenced `SCALAR` subquery may not necessarily be a direct child of
4314 # this node.
4315 &quot;a_key&quot;: 42,
4316 },
4317 },
4318 &quot;index&quot;: 42, # The `PlanNode`&#x27;s index in node list.
4319 &quot;kind&quot;: &quot;A String&quot;, # Used to determine the type of node. May be needed for visualizing
4320 # different kinds of nodes differently. For example, If the node is a
4321 # SCALAR node, it will have a condensed representation
4322 # which can be used to directly embed a description of the node in its
4323 # parent.
4324 &quot;displayName&quot;: &quot;A String&quot;, # The display name for the node.
4325 &quot;childLinks&quot;: [ # List of child node `index`es and their relationship to this parent.
4326 { # Metadata associated with a parent-child relationship appearing in a
4327 # PlanNode.
4328 &quot;variable&quot;: &quot;A String&quot;, # Only present if the child node is SCALAR and corresponds
4329 # to an output variable of the parent node. The field carries the name of
4330 # the output variable.
4331 # For example, a `TableScan` operator that reads rows from a table will
4332 # have child links to the `SCALAR` nodes representing the output variables
4333 # created for each column that is read by the operator. The corresponding
4334 # `variable` fields will be set to the variable names assigned to the
4335 # columns.
4336 &quot;childIndex&quot;: 42, # The node to which the link points.
4337 &quot;type&quot;: &quot;A String&quot;, # The type of the link. For example, in Hash Joins this could be used to
4338 # distinguish between the build child and the probe child, or in the case
4339 # of the child being an output variable, to represent the tag associated
4340 # with the output variable.
4341 },
4342 ],
4343 },
4344 ],
4345 },
4346 },
4347 &quot;chunkedValue&quot;: True or False, # If true, then the final value in values is chunked, and must
4348 # be combined with more values from subsequent `PartialResultSet`s
4349 # to obtain a complete field value.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]4350 }</pre>
4351</div>
4352
4353<div class="method">
4354 <code class="details" id="get">get(name, x__xgafv=None)</code>
4355 <pre>Gets a session. Returns `NOT_FOUND` if the session does not exist.
4356This is mainly useful for determining whether a session is still
4357alive.
4358
4359Args:
4360 name: string, Required. The name of the session to retrieve. (required)
4361 x__xgafv: string, V1 error format.
4362 Allowed values
4363 1 - v1 error format
4364 2 - v2 error format
4365
4366Returns:
4367 An object of the form:
4368
4369 { # A session in the Cloud Spanner API.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4370 &quot;approximateLastUseTime&quot;: &quot;A String&quot;, # Output only. The approximate timestamp when the session is last used. It is
4371 # typically earlier than the actual last use time.
4372 &quot;name&quot;: &quot;A String&quot;, # The name of the session. This is always system-assigned; values provided
4373 # when creating a session are ignored.
4374 &quot;createTime&quot;: &quot;A String&quot;, # Output only. The timestamp when the session is created.
4375 &quot;labels&quot;: { # The labels for the session.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4376 #
4377 # * Label keys must be between 1 and 63 characters long and must conform to
4378 # the following regular expression: `[a-z]([-a-z0-9]*[a-z0-9])?`.
4379 # * Label values must be between 0 and 63 characters long and must conform
4380 # to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`.
4381 # * No more than 64 labels can be associated with a given session.
4382 #
4383 # See https://goo.gl/xmQnxf for more information on and examples of labels.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4384 &quot;a_key&quot;: &quot;A String&quot;,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4385 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4386 }</pre>
4387</div>
4388
4389<div class="method">
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4390 <code class="details" id="list">list(database, filter=None, pageToken=None, pageSize=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4391 <pre>Lists all sessions in a given database.
4392
4393Args:
4394 database: string, Required. The database in which to list sessions. (required)
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4395 filter: string, An expression for filtering the results of the request. Filter rules are
4396case insensitive. The fields eligible for filtering are:
4397
4398 * `labels.key` where key is the name of a label
4399
4400Some examples of using filters are:
4401
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4402 * `labels.env:*` --&gt; The session has the label &quot;env&quot;.
4403 * `labels.env:dev` --&gt; The session has the label &quot;env&quot; and the value of
4404 the label contains the string &quot;dev&quot;.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4405 pageToken: string, If non-empty, `page_token` should contain a
4406next_page_token from a previous
4407ListSessionsResponse.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4408 pageSize: integer, Number of sessions to be returned in the response. If 0 or less, defaults
4409to the server&#x27;s maximum allowed page size.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4410 x__xgafv: string, V1 error format.
4411 Allowed values
4412 1 - v1 error format
4413 2 - v2 error format
4414
4415Returns:
4416 An object of the form:
4417
4418 { # The response for ListSessions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4419 &quot;sessions&quot;: [ # The list of requested sessions.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4420 { # A session in the Cloud Spanner API.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4421 &quot;approximateLastUseTime&quot;: &quot;A String&quot;, # Output only. The approximate timestamp when the session is last used. It is
4422 # typically earlier than the actual last use time.
4423 &quot;name&quot;: &quot;A String&quot;, # The name of the session. This is always system-assigned; values provided
4424 # when creating a session are ignored.
4425 &quot;createTime&quot;: &quot;A String&quot;, # Output only. The timestamp when the session is created.
4426 &quot;labels&quot;: { # The labels for the session.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4427 #
4428 # * Label keys must be between 1 and 63 characters long and must conform to
4429 # the following regular expression: `[a-z]([-a-z0-9]*[a-z0-9])?`.
4430 # * Label values must be between 0 and 63 characters long and must conform
4431 # to the regular expression `([a-z]([-a-z0-9]*[a-z0-9])?)?`.
4432 # * No more than 64 labels can be associated with a given session.
4433 #
4434 # See https://goo.gl/xmQnxf for more information on and examples of labels.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4435 &quot;a_key&quot;: &quot;A String&quot;,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4436 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4437 },
4438 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4439 &quot;nextPageToken&quot;: &quot;A String&quot;, # `next_page_token` can be sent in a subsequent
4440 # ListSessions call to fetch more of the matching
4441 # sessions.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4442 }</pre>
4443</div>
4444
4445<div class="method">
4446 <code class="details" id="list_next">list_next(previous_request, previous_response)</code>
4447 <pre>Retrieves the next page of results.
4448
4449Args:
4450 previous_request: The request for the previous page. (required)
4451 previous_response: The response from the request for the previous page. (required)
4452
4453Returns:
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4454 A request object that you can call &#x27;execute()&#x27; on to request the next
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4455 page. Returns None if there are no more items in the collection.
4456 </pre>
4457</div>
4458
4459<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]4460 <code class="details" id="partitionQuery">partitionQuery(session, body=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4461 <pre>Creates a set of partition tokens that can be used to execute a query
4462operation in parallel. Each of the returned partition tokens can be used
4463by ExecuteStreamingSql to specify a subset
4464of the query result to read. The same session and read-only transaction
4465must be used by the PartitionQueryRequest used to create the
4466partition tokens and the ExecuteSqlRequests that use the partition tokens.
4467
4468Partition tokens become invalid when the session used to create them
4469is deleted, is idle for too long, begins a new transaction, or becomes too
4470old. When any of these happen, it is not possible to resume the query, and
4471the whole operation must be restarted from the beginning.
4472
4473Args:
4474 session: string, Required. The session used to create the partitions. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]4475 body: object, The request body.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4476 The object takes the form of:
4477
4478{ # The request for PartitionQuery
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4479 &quot;sql&quot;: &quot;A String&quot;, # Required. The query request to generate partitions for. The request will fail if
4480 # the query is not root partitionable. The query plan of a root
4481 # partitionable query has a single distributed union operator. A distributed
4482 # union operator conceptually divides one or more tables into multiple
4483 # splits, remotely evaluates a subquery independently on each split, and
4484 # then unions all results.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4485 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4486 # This must not contain DML commands, such as INSERT, UPDATE, or
4487 # DELETE. Use ExecuteStreamingSql with a
4488 # PartitionedDml transaction for large, partition-friendly DML operations.
4489 &quot;partitionOptions&quot;: { # Options for a PartitionQueryRequest and # Additional options that affect how many partitions are created.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4490 # PartitionReadRequest.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4491 &quot;partitionSizeBytes&quot;: &quot;A String&quot;, # **Note:** This hint is currently ignored by PartitionQuery and
4492 # PartitionRead requests.
4493 #
4494 # The desired data size for each partition generated. The default for this
4495 # option is currently 1 GiB. This is only a hint. The actual size of each
4496 # partition may be smaller or larger than this size request.
4497 &quot;maxPartitions&quot;: &quot;A String&quot;, # **Note:** This hint is currently ignored by PartitionQuery and
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4498 # PartitionRead requests.
4499 #
4500 # The desired maximum number of partitions to return. For example, this may
4501 # be set to the number of workers available. The default for this option
4502 # is currently 10,000. The maximum value is currently 200,000. This is only
4503 # a hint. The actual number of partitions returned may be smaller or larger
4504 # than this maximum count request.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4505 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4506 &quot;transaction&quot;: { # This message is used to select the transaction in which a # Read only snapshot transactions are supported, read/write and single use
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4507 # transactions are not.
4508 # Read or
4509 # ExecuteSql call runs.
4510 #
4511 # See TransactionOptions for more information about transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4512 &quot;singleUse&quot;: { # # Transactions # Execute the read or SQL query in a temporary transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4513 # This is the most efficient way to execute a transaction that
4514 # consists of a single SQL query.
4515 #
4516 #
4517 # Each session can have at most one active transaction at a time. After the
4518 # active transaction is completed, the session can immediately be
4519 # re-used for the next transaction. It is not necessary to create a
4520 # new session for each transaction.
4521 #
4522 # # Transaction Modes
4523 #
4524 # Cloud Spanner supports three transaction modes:
4525 #
4526 # 1. Locking read-write. This type of transaction is the only way
4527 # to write data into Cloud Spanner. These transactions rely on
4528 # pessimistic locking and, if necessary, two-phase commit.
4529 # Locking read-write transactions may abort, requiring the
4530 # application to retry.
4531 #
4532 # 2. Snapshot read-only. This transaction type provides guaranteed
4533 # consistency across several reads, but does not allow
4534 # writes. Snapshot read-only transactions can be configured to
4535 # read at timestamps in the past. Snapshot read-only
4536 # transactions do not need to be committed.
4537 #
4538 # 3. Partitioned DML. This type of transaction is used to execute
4539 # a single Partitioned DML statement. Partitioned DML partitions
4540 # the key space and runs the DML statement over each partition
4541 # in parallel using separate, internal transactions that commit
4542 # independently. Partitioned DML transactions do not need to be
4543 # committed.
4544 #
4545 # For transactions that only read, snapshot read-only transactions
4546 # provide simpler semantics and are almost always faster. In
4547 # particular, read-only transactions do not take locks, so they do
4548 # not conflict with read-write transactions. As a consequence of not
4549 # taking locks, they also do not abort, so retry loops are not needed.
4550 #
4551 # Transactions may only read/write data in a single database. They
4552 # may, however, read/write data in different tables within that
4553 # database.
4554 #
4555 # ## Locking Read-Write Transactions
4556 #
4557 # Locking transactions may be used to atomically read-modify-write
4558 # data anywhere in a database. This type of transaction is externally
4559 # consistent.
4560 #
4561 # Clients should attempt to minimize the amount of time a transaction
4562 # is active. Faster transactions commit with higher probability
4563 # and cause less contention. Cloud Spanner attempts to keep read locks
4564 # active as long as the transaction continues to do reads, and the
4565 # transaction has not been terminated by
4566 # Commit or
4567 # Rollback. Long periods of
4568 # inactivity at the client may cause Cloud Spanner to release a
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4569 # transaction&#x27;s locks and abort it.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4570 #
4571 # Conceptually, a read-write transaction consists of zero or more
4572 # reads or SQL statements followed by
4573 # Commit. At any time before
4574 # Commit, the client can send a
4575 # Rollback request to abort the
4576 # transaction.
4577 #
4578 # ### Semantics
4579 #
4580 # Cloud Spanner can commit the transaction if all read locks it acquired
4581 # are still valid at commit time, and it is able to acquire write
4582 # locks for all writes. Cloud Spanner can abort the transaction for any
4583 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
4584 # that the transaction has not modified any user data in Cloud Spanner.
4585 #
4586 # Unless the transaction commits, Cloud Spanner makes no guarantees about
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4587 # how long the transaction&#x27;s locks were held for. It is an error to
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4588 # use Cloud Spanner locks for any sort of mutual exclusion other than
4589 # between Cloud Spanner transactions themselves.
4590 #
4591 # ### Retrying Aborted Transactions
4592 #
4593 # When a transaction aborts, the application can choose to retry the
4594 # whole transaction again. To maximize the chances of successfully
4595 # committing the retry, the client should execute the retry in the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4596 # same session as the original attempt. The original session&#x27;s lock
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4597 # priority increases with each consecutive abort, meaning that each
4598 # attempt has a slightly better chance of success than the previous.
4599 #
4600 # Under some circumstances (e.g., many transactions attempting to
4601 # modify the same row(s)), a transaction can abort many times in a
4602 # short period before successfully committing. Thus, it is not a good
4603 # idea to cap the number of retries a transaction can attempt;
4604 # instead, it is better to limit the total amount of wall time spent
4605 # retrying.
4606 #
4607 # ### Idle Transactions
4608 #
4609 # A transaction is considered idle if it has no outstanding reads or
4610 # SQL queries and has not started a read or SQL query within the last 10
4611 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4612 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4613 # fail with error `ABORTED`.
4614 #
4615 # If this behavior is undesirable, periodically executing a simple
4616 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
4617 # transaction from becoming idle.
4618 #
4619 # ## Snapshot Read-Only Transactions
4620 #
4621 # Snapshot read-only transactions provides a simpler method than
4622 # locking read-write transactions for doing several consistent
4623 # reads. However, this type of transaction does not support writes.
4624 #
4625 # Snapshot transactions do not take locks. Instead, they work by
4626 # choosing a Cloud Spanner timestamp, then executing all reads at that
4627 # timestamp. Since they do not acquire locks, they do not block
4628 # concurrent read-write transactions.
4629 #
4630 # Unlike locking read-write transactions, snapshot read-only
4631 # transactions never abort. They can fail if the chosen read
4632 # timestamp is garbage collected; however, the default garbage
4633 # collection policy is generous enough that most applications do not
4634 # need to worry about this in practice.
4635 #
4636 # Snapshot read-only transactions do not need to call
4637 # Commit or
4638 # Rollback (and in fact are not
4639 # permitted to do so).
4640 #
4641 # To execute a snapshot transaction, the client specifies a timestamp
4642 # bound, which tells Cloud Spanner how to choose a read timestamp.
4643 #
4644 # The types of timestamp bound are:
4645 #
4646 # - Strong (the default).
4647 # - Bounded staleness.
4648 # - Exact staleness.
4649 #
4650 # If the Cloud Spanner database to be read is geographically distributed,
4651 # stale read-only transactions can execute more quickly than strong
4652 # or read-write transaction, because they are able to execute far
4653 # from the leader replica.
4654 #
4655 # Each type of timestamp bound is discussed in detail below.
4656 #
4657 # ### Strong
4658 #
4659 # Strong reads are guaranteed to see the effects of all transactions
4660 # that have committed before the start of the read. Furthermore, all
4661 # rows yielded by a single read are consistent with each other -- if
4662 # any part of the read observes a transaction, all parts of the read
4663 # see the transaction.
4664 #
4665 # Strong reads are not repeatable: two consecutive strong read-only
4666 # transactions might return inconsistent results if there are
4667 # concurrent writes. If consistency across reads is required, the
4668 # reads should be executed within a transaction or at an exact read
4669 # timestamp.
4670 #
4671 # See TransactionOptions.ReadOnly.strong.
4672 #
4673 # ### Exact Staleness
4674 #
4675 # These timestamp bounds execute reads at a user-specified
4676 # timestamp. Reads at a timestamp are guaranteed to see a consistent
4677 # prefix of the global transaction history: they observe
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]4678 # modifications done by all transactions with a commit timestamp &lt;=
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4679 # the read timestamp, and observe none of the modifications done by
4680 # transactions with a larger commit timestamp. They will block until
4681 # all conflicting transactions that may be assigned commit timestamps
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]4682 # &lt;= the read timestamp have finished.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4683 #
4684 # The timestamp can either be expressed as an absolute Cloud Spanner commit
4685 # timestamp or a staleness relative to the current time.
4686 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4687 # These modes do not require a &quot;negotiation phase&quot; to pick a
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4688 # timestamp. As a result, they execute slightly faster than the
4689 # equivalent boundedly stale concurrency modes. On the other hand,
4690 # boundedly stale reads usually return fresher results.
4691 #
4692 # See TransactionOptions.ReadOnly.read_timestamp and
4693 # TransactionOptions.ReadOnly.exact_staleness.
4694 #
4695 # ### Bounded Staleness
4696 #
4697 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
4698 # subject to a user-provided staleness bound. Cloud Spanner chooses the
4699 # newest timestamp within the staleness bound that allows execution
4700 # of the reads at the closest available replica without blocking.
4701 #
4702 # All rows yielded are consistent with each other -- if any part of
4703 # the read observes a transaction, all parts of the read see the
4704 # transaction. Boundedly stale reads are not repeatable: two stale
4705 # reads, even if they use the same staleness bound, can execute at
4706 # different timestamps and thus return inconsistent results.
4707 #
4708 # Boundedly stale reads execute in two phases: the first phase
4709 # negotiates a timestamp among all replicas needed to serve the
4710 # read. In the second phase, reads are executed at the negotiated
4711 # timestamp.
4712 #
4713 # As a result of the two phase execution, bounded staleness reads are
4714 # usually a little slower than comparable exact staleness
4715 # reads. However, they are typically able to return fresher
4716 # results, and are more likely to execute at the closest replica.
4717 #
4718 # Because the timestamp negotiation requires up-front knowledge of
4719 # which rows will be read, it can only be used with single-use
4720 # read-only transactions.
4721 #
4722 # See TransactionOptions.ReadOnly.max_staleness and
4723 # TransactionOptions.ReadOnly.min_read_timestamp.
4724 #
4725 # ### Old Read Timestamps and Garbage Collection
4726 #
4727 # Cloud Spanner continuously garbage collects deleted and overwritten data
4728 # in the background to reclaim storage space. This process is known
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4729 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4730 # are one hour old. Because of this, Cloud Spanner cannot perform reads
4731 # at read timestamps more than one hour in the past. This
4732 # restriction also applies to in-progress reads and/or SQL queries whose
4733 # timestamp become too old while executing. Reads and SQL queries with
4734 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
4735 #
4736 # ## Partitioned DML Transactions
4737 #
4738 # Partitioned DML transactions are used to execute DML statements with a
4739 # different execution strategy that provides different, and often better,
4740 # scalability properties for large, table-wide operations than DML in a
4741 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
4742 # should prefer using ReadWrite transactions.
4743 #
4744 # Partitioned DML partitions the keyspace and runs the DML statement on each
4745 # partition in separate, internal transactions. These transactions commit
4746 # automatically when complete, and run independently from one another.
4747 #
4748 # To reduce lock contention, this execution strategy only acquires read locks
4749 # on rows that match the WHERE clause of the statement. Additionally, the
4750 # smaller per-partition transactions hold locks for less time.
4751 #
4752 # That said, Partitioned DML is not a drop-in replacement for standard DML used
4753 # in ReadWrite transactions.
4754 #
4755 # - The DML statement must be fully-partitionable. Specifically, the statement
4756 # must be expressible as the union of many statements which each access only
4757 # a single row of the table.
4758 #
4759 # - The statement is not applied atomically to all rows of the table. Rather,
4760 # the statement is applied atomically to partitions of the table, in
4761 # independent transactions. Secondary index rows are updated atomically
4762 # with the base table rows.
4763 #
4764 # - Partitioned DML does not guarantee exactly-once execution semantics
4765 # against a partition. The statement will be applied at least once to each
4766 # partition. It is strongly recommended that the DML statement should be
4767 # idempotent to avoid unexpected results. For instance, it is potentially
4768 # dangerous to run a statement such as
4769 # `UPDATE table SET column = column + 1` as it could be run multiple times
4770 # against some rows.
4771 #
4772 # - The partitions are committed automatically - there is no support for
4773 # Commit or Rollback. If the call returns an error, or if the client issuing
4774 # the ExecuteSql call dies, it is possible that some rows had the statement
4775 # executed on them successfully. It is also possible that statement was
4776 # never executed against other rows.
4777 #
4778 # - Partitioned DML transactions may only contain the execution of a single
4779 # DML statement via ExecuteSql or ExecuteStreamingSql.
4780 #
4781 # - If any error is encountered during the execution of the partitioned DML
4782 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
4783 # value that cannot be stored due to schema constraints), then the
4784 # operation is stopped at that point and an error is returned. It is
4785 # possible that at this point, some partitions have been committed (or even
4786 # committed multiple times), and other partitions have not been run at all.
4787 #
4788 # Given the above, Partitioned DML is good fit for large, database-wide,
4789 # operations that are idempotent, such as deleting old rows from a very large
4790 # table.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4791 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4792 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4793 # Authorization to begin a Partitioned DML transaction requires
4794 # `spanner.databases.beginPartitionedDmlTransaction` permission
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4795 # on the `session` resource.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4796 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4797 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4798 #
4799 # Authorization to begin a read-only transaction requires
4800 # `spanner.databases.beginReadOnlyTransaction` permission
4801 # on the `session` resource.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4802 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4803 #
4804 # This is useful for requesting fresher data than some previous
4805 # read, or data that is fresh enough to observe the effects of some
4806 # previously committed transaction whose timestamp is known.
4807 #
4808 # Note that this option can only be used in single-use transactions.
4809 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4810 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
4811 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
4812 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]4813 # reads at a specific timestamp are repeatable; the same read at
4814 # the same timestamp always returns the same data. If the
4815 # timestamp is in the future, the read will block until the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4816 # specified timestamp, modulo the read&#x27;s deadline.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]4817 #
4818 # Useful for large scale consistent reads such as mapreduces, or
4819 # for coordinating many reads against a consistent snapshot of the
4820 # data.
4821 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4822 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
4823 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
4824 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4825 # seconds. Guarantees that all writes that have committed more
4826 # than the specified number of seconds ago are visible. Because
4827 # Cloud Spanner chooses the exact timestamp, this mode works even if
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4828 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4829 # commit timestamps.
4830 #
4831 # Useful for reading the freshest data available at a nearby
4832 # replica, while bounding the possible staleness if the local
4833 # replica has fallen behind.
4834 #
4835 # Note that this option can only be used in single-use
4836 # transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4837 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
4838 # the Transaction message that describes the transaction.
4839 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4840 # old. The timestamp is chosen soon after the read is started.
4841 #
4842 # Guarantees that all writes that have committed more than the
4843 # specified number of seconds ago are visible. Because Cloud Spanner
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4844 # chooses the exact timestamp, this mode works even if the client&#x27;s
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4845 # local clock is substantially skewed from Cloud Spanner commit
4846 # timestamps.
4847 #
4848 # Useful for reading at nearby replicas without the distributed
4849 # timestamp negotiation overhead of `max_staleness`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4850 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]4851 # are visible.
4852 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]4853 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
4854 #
4855 # Authorization to begin a read-write transaction requires
4856 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
4857 # on the `session` resource.
4858 # transaction type has no options.
4859 },
4860 },
4861 &quot;begin&quot;: { # # Transactions # Begin a new transaction and execute this read or SQL query in
4862 # it. The transaction ID of the new transaction is returned in
4863 # ResultSetMetadata.transaction, which is a Transaction.
4864 #
4865 #
4866 # Each session can have at most one active transaction at a time. After the
4867 # active transaction is completed, the session can immediately be
4868 # re-used for the next transaction. It is not necessary to create a
4869 # new session for each transaction.
4870 #
4871 # # Transaction Modes
4872 #
4873 # Cloud Spanner supports three transaction modes:
4874 #
4875 # 1. Locking read-write. This type of transaction is the only way
4876 # to write data into Cloud Spanner. These transactions rely on
4877 # pessimistic locking and, if necessary, two-phase commit.
4878 # Locking read-write transactions may abort, requiring the
4879 # application to retry.
4880 #
4881 # 2. Snapshot read-only. This transaction type provides guaranteed
4882 # consistency across several reads, but does not allow
4883 # writes. Snapshot read-only transactions can be configured to
4884 # read at timestamps in the past. Snapshot read-only
4885 # transactions do not need to be committed.
4886 #
4887 # 3. Partitioned DML. This type of transaction is used to execute
4888 # a single Partitioned DML statement. Partitioned DML partitions
4889 # the key space and runs the DML statement over each partition
4890 # in parallel using separate, internal transactions that commit
4891 # independently. Partitioned DML transactions do not need to be
4892 # committed.
4893 #
4894 # For transactions that only read, snapshot read-only transactions
4895 # provide simpler semantics and are almost always faster. In
4896 # particular, read-only transactions do not take locks, so they do
4897 # not conflict with read-write transactions. As a consequence of not
4898 # taking locks, they also do not abort, so retry loops are not needed.
4899 #
4900 # Transactions may only read/write data in a single database. They
4901 # may, however, read/write data in different tables within that
4902 # database.
4903 #
4904 # ## Locking Read-Write Transactions
4905 #
4906 # Locking transactions may be used to atomically read-modify-write
4907 # data anywhere in a database. This type of transaction is externally
4908 # consistent.
4909 #
4910 # Clients should attempt to minimize the amount of time a transaction
4911 # is active. Faster transactions commit with higher probability
4912 # and cause less contention. Cloud Spanner attempts to keep read locks
4913 # active as long as the transaction continues to do reads, and the
4914 # transaction has not been terminated by
4915 # Commit or
4916 # Rollback. Long periods of
4917 # inactivity at the client may cause Cloud Spanner to release a
4918 # transaction&#x27;s locks and abort it.
4919 #
4920 # Conceptually, a read-write transaction consists of zero or more
4921 # reads or SQL statements followed by
4922 # Commit. At any time before
4923 # Commit, the client can send a
4924 # Rollback request to abort the
4925 # transaction.
4926 #
4927 # ### Semantics
4928 #
4929 # Cloud Spanner can commit the transaction if all read locks it acquired
4930 # are still valid at commit time, and it is able to acquire write
4931 # locks for all writes. Cloud Spanner can abort the transaction for any
4932 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
4933 # that the transaction has not modified any user data in Cloud Spanner.
4934 #
4935 # Unless the transaction commits, Cloud Spanner makes no guarantees about
4936 # how long the transaction&#x27;s locks were held for. It is an error to
4937 # use Cloud Spanner locks for any sort of mutual exclusion other than
4938 # between Cloud Spanner transactions themselves.
4939 #
4940 # ### Retrying Aborted Transactions
4941 #
4942 # When a transaction aborts, the application can choose to retry the
4943 # whole transaction again. To maximize the chances of successfully
4944 # committing the retry, the client should execute the retry in the
4945 # same session as the original attempt. The original session&#x27;s lock
4946 # priority increases with each consecutive abort, meaning that each
4947 # attempt has a slightly better chance of success than the previous.
4948 #
4949 # Under some circumstances (e.g., many transactions attempting to
4950 # modify the same row(s)), a transaction can abort many times in a
4951 # short period before successfully committing. Thus, it is not a good
4952 # idea to cap the number of retries a transaction can attempt;
4953 # instead, it is better to limit the total amount of wall time spent
4954 # retrying.
4955 #
4956 # ### Idle Transactions
4957 #
4958 # A transaction is considered idle if it has no outstanding reads or
4959 # SQL queries and has not started a read or SQL query within the last 10
4960 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
4961 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
4962 # fail with error `ABORTED`.
4963 #
4964 # If this behavior is undesirable, periodically executing a simple
4965 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
4966 # transaction from becoming idle.
4967 #
4968 # ## Snapshot Read-Only Transactions
4969 #
4970 # Snapshot read-only transactions provides a simpler method than
4971 # locking read-write transactions for doing several consistent
4972 # reads. However, this type of transaction does not support writes.
4973 #
4974 # Snapshot transactions do not take locks. Instead, they work by
4975 # choosing a Cloud Spanner timestamp, then executing all reads at that
4976 # timestamp. Since they do not acquire locks, they do not block
4977 # concurrent read-write transactions.
4978 #
4979 # Unlike locking read-write transactions, snapshot read-only
4980 # transactions never abort. They can fail if the chosen read
4981 # timestamp is garbage collected; however, the default garbage
4982 # collection policy is generous enough that most applications do not
4983 # need to worry about this in practice.
4984 #
4985 # Snapshot read-only transactions do not need to call
4986 # Commit or
4987 # Rollback (and in fact are not
4988 # permitted to do so).
4989 #
4990 # To execute a snapshot transaction, the client specifies a timestamp
4991 # bound, which tells Cloud Spanner how to choose a read timestamp.
4992 #
4993 # The types of timestamp bound are:
4994 #
4995 # - Strong (the default).
4996 # - Bounded staleness.
4997 # - Exact staleness.
4998 #
4999 # If the Cloud Spanner database to be read is geographically distributed,
5000 # stale read-only transactions can execute more quickly than strong
5001 # or read-write transaction, because they are able to execute far
5002 # from the leader replica.
5003 #
5004 # Each type of timestamp bound is discussed in detail below.
5005 #
5006 # ### Strong
5007 #
5008 # Strong reads are guaranteed to see the effects of all transactions
5009 # that have committed before the start of the read. Furthermore, all
5010 # rows yielded by a single read are consistent with each other -- if
5011 # any part of the read observes a transaction, all parts of the read
5012 # see the transaction.
5013 #
5014 # Strong reads are not repeatable: two consecutive strong read-only
5015 # transactions might return inconsistent results if there are
5016 # concurrent writes. If consistency across reads is required, the
5017 # reads should be executed within a transaction or at an exact read
5018 # timestamp.
5019 #
5020 # See TransactionOptions.ReadOnly.strong.
5021 #
5022 # ### Exact Staleness
5023 #
5024 # These timestamp bounds execute reads at a user-specified
5025 # timestamp. Reads at a timestamp are guaranteed to see a consistent
5026 # prefix of the global transaction history: they observe
5027 # modifications done by all transactions with a commit timestamp &lt;=
5028 # the read timestamp, and observe none of the modifications done by
5029 # transactions with a larger commit timestamp. They will block until
5030 # all conflicting transactions that may be assigned commit timestamps
5031 # &lt;= the read timestamp have finished.
5032 #
5033 # The timestamp can either be expressed as an absolute Cloud Spanner commit
5034 # timestamp or a staleness relative to the current time.
5035 #
5036 # These modes do not require a &quot;negotiation phase&quot; to pick a
5037 # timestamp. As a result, they execute slightly faster than the
5038 # equivalent boundedly stale concurrency modes. On the other hand,
5039 # boundedly stale reads usually return fresher results.
5040 #
5041 # See TransactionOptions.ReadOnly.read_timestamp and
5042 # TransactionOptions.ReadOnly.exact_staleness.
5043 #
5044 # ### Bounded Staleness
5045 #
5046 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
5047 # subject to a user-provided staleness bound. Cloud Spanner chooses the
5048 # newest timestamp within the staleness bound that allows execution
5049 # of the reads at the closest available replica without blocking.
5050 #
5051 # All rows yielded are consistent with each other -- if any part of
5052 # the read observes a transaction, all parts of the read see the
5053 # transaction. Boundedly stale reads are not repeatable: two stale
5054 # reads, even if they use the same staleness bound, can execute at
5055 # different timestamps and thus return inconsistent results.
5056 #
5057 # Boundedly stale reads execute in two phases: the first phase
5058 # negotiates a timestamp among all replicas needed to serve the
5059 # read. In the second phase, reads are executed at the negotiated
5060 # timestamp.
5061 #
5062 # As a result of the two phase execution, bounded staleness reads are
5063 # usually a little slower than comparable exact staleness
5064 # reads. However, they are typically able to return fresher
5065 # results, and are more likely to execute at the closest replica.
5066 #
5067 # Because the timestamp negotiation requires up-front knowledge of
5068 # which rows will be read, it can only be used with single-use
5069 # read-only transactions.
5070 #
5071 # See TransactionOptions.ReadOnly.max_staleness and
5072 # TransactionOptions.ReadOnly.min_read_timestamp.
5073 #
5074 # ### Old Read Timestamps and Garbage Collection
5075 #
5076 # Cloud Spanner continuously garbage collects deleted and overwritten data
5077 # in the background to reclaim storage space. This process is known
5078 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
5079 # are one hour old. Because of this, Cloud Spanner cannot perform reads
5080 # at read timestamps more than one hour in the past. This
5081 # restriction also applies to in-progress reads and/or SQL queries whose
5082 # timestamp become too old while executing. Reads and SQL queries with
5083 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
5084 #
5085 # ## Partitioned DML Transactions
5086 #
5087 # Partitioned DML transactions are used to execute DML statements with a
5088 # different execution strategy that provides different, and often better,
5089 # scalability properties for large, table-wide operations than DML in a
5090 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
5091 # should prefer using ReadWrite transactions.
5092 #
5093 # Partitioned DML partitions the keyspace and runs the DML statement on each
5094 # partition in separate, internal transactions. These transactions commit
5095 # automatically when complete, and run independently from one another.
5096 #
5097 # To reduce lock contention, this execution strategy only acquires read locks
5098 # on rows that match the WHERE clause of the statement. Additionally, the
5099 # smaller per-partition transactions hold locks for less time.
5100 #
5101 # That said, Partitioned DML is not a drop-in replacement for standard DML used
5102 # in ReadWrite transactions.
5103 #
5104 # - The DML statement must be fully-partitionable. Specifically, the statement
5105 # must be expressible as the union of many statements which each access only
5106 # a single row of the table.
5107 #
5108 # - The statement is not applied atomically to all rows of the table. Rather,
5109 # the statement is applied atomically to partitions of the table, in
5110 # independent transactions. Secondary index rows are updated atomically
5111 # with the base table rows.
5112 #
5113 # - Partitioned DML does not guarantee exactly-once execution semantics
5114 # against a partition. The statement will be applied at least once to each
5115 # partition. It is strongly recommended that the DML statement should be
5116 # idempotent to avoid unexpected results. For instance, it is potentially
5117 # dangerous to run a statement such as
5118 # `UPDATE table SET column = column + 1` as it could be run multiple times
5119 # against some rows.
5120 #
5121 # - The partitions are committed automatically - there is no support for
5122 # Commit or Rollback. If the call returns an error, or if the client issuing
5123 # the ExecuteSql call dies, it is possible that some rows had the statement
5124 # executed on them successfully. It is also possible that statement was
5125 # never executed against other rows.
5126 #
5127 # - Partitioned DML transactions may only contain the execution of a single
5128 # DML statement via ExecuteSql or ExecuteStreamingSql.
5129 #
5130 # - If any error is encountered during the execution of the partitioned DML
5131 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
5132 # value that cannot be stored due to schema constraints), then the
5133 # operation is stopped at that point and an error is returned. It is
5134 # possible that at this point, some partitions have been committed (or even
5135 # committed multiple times), and other partitions have not been run at all.
5136 #
5137 # Given the above, Partitioned DML is good fit for large, database-wide,
5138 # operations that are idempotent, such as deleting old rows from a very large
5139 # table.
5140 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5141 #
5142 # Authorization to begin a Partitioned DML transaction requires
5143 # `spanner.databases.beginPartitionedDmlTransaction` permission
5144 # on the `session` resource.
5145 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5146 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
5147 #
5148 # Authorization to begin a read-only transaction requires
5149 # `spanner.databases.beginReadOnlyTransaction` permission
5150 # on the `session` resource.
5151 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
5152 #
5153 # This is useful for requesting fresher data than some previous
5154 # read, or data that is fresh enough to observe the effects of some
5155 # previously committed transaction whose timestamp is known.
5156 #
5157 # Note that this option can only be used in single-use transactions.
5158 #
5159 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
5160 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
5161 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
5162 # reads at a specific timestamp are repeatable; the same read at
5163 # the same timestamp always returns the same data. If the
5164 # timestamp is in the future, the read will block until the
5165 # specified timestamp, modulo the read&#x27;s deadline.
5166 #
5167 # Useful for large scale consistent reads such as mapreduces, or
5168 # for coordinating many reads against a consistent snapshot of the
5169 # data.
5170 #
5171 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
5172 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
5173 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
5174 # seconds. Guarantees that all writes that have committed more
5175 # than the specified number of seconds ago are visible. Because
5176 # Cloud Spanner chooses the exact timestamp, this mode works even if
5177 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
5178 # commit timestamps.
5179 #
5180 # Useful for reading the freshest data available at a nearby
5181 # replica, while bounding the possible staleness if the local
5182 # replica has fallen behind.
5183 #
5184 # Note that this option can only be used in single-use
5185 # transactions.
5186 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
5187 # the Transaction message that describes the transaction.
5188 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
5189 # old. The timestamp is chosen soon after the read is started.
5190 #
5191 # Guarantees that all writes that have committed more than the
5192 # specified number of seconds ago are visible. Because Cloud Spanner
5193 # chooses the exact timestamp, this mode works even if the client&#x27;s
5194 # local clock is substantially skewed from Cloud Spanner commit
5195 # timestamps.
5196 #
5197 # Useful for reading at nearby replicas without the distributed
5198 # timestamp negotiation overhead of `max_staleness`.
5199 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
5200 # are visible.
5201 },
5202 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
5203 #
5204 # Authorization to begin a read-write transaction requires
5205 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
5206 # on the `session` resource.
5207 # transaction type has no options.
5208 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5209 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5210 &quot;id&quot;: &quot;A String&quot;, # Execute the read or SQL query in a previously-started transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5211 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5212 &quot;params&quot;: { # Parameter names and values that bind to placeholders in the SQL string.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]5213 #
5214 # A parameter placeholder consists of the `@` character followed by the
5215 # parameter name (for example, `@firstName`). Parameter names can contain
5216 # letters, numbers, and underscores.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5217 #
5218 # Parameters can appear anywhere that a literal value is expected. The same
5219 # parameter name can be used more than once, for example:
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5220 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5221 # `&quot;WHERE id &gt; @msg_id AND id &lt; @msg_id + 100&quot;`
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5222 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]5223 # It is an error to execute a SQL statement with unbound parameters.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5224 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5225 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5226 &quot;paramTypes&quot;: { # It is not always possible for Cloud Spanner to infer the right SQL type
5227 # from a JSON value. For example, values of type `BYTES` and values
5228 # of type `STRING` both appear in params as JSON strings.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5229 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5230 # In these cases, `param_types` can be used to specify the exact
5231 # SQL type for some or all of the SQL query parameters. See the
5232 # definition of Type for more information
5233 # about SQL types.
5234 &quot;a_key&quot;: { # `Type` indicates the type of a Cloud Spanner value, as might be stored in a
5235 # table cell or returned from an SQL query.
5236 &quot;arrayElementType&quot;: # Object with schema name: Type # If code == ARRAY, then `array_element_type`
5237 # is the type of the array elements.
5238 &quot;code&quot;: &quot;A String&quot;, # Required. The TypeCode for this type.
5239 &quot;structType&quot;: { # `StructType` defines the fields of a STRUCT type. # If code == STRUCT, then `struct_type`
5240 # provides type information for the struct&#x27;s fields.
5241 &quot;fields&quot;: [ # The list of fields that make up this struct. Order is
5242 # significant, because values of this struct type are represented as
5243 # lists, where the order of field values matches the order of
5244 # fields in the StructType. In turn, the order of fields
5245 # matches the order of columns in a read request, or the order of
5246 # fields in the `SELECT` clause of a query.
5247 { # Message representing a single field of a struct.
5248 &quot;name&quot;: &quot;A String&quot;, # The name of the field. For reads, this is the column name. For
5249 # SQL queries, it is the column alias (e.g., `&quot;Word&quot;` in the
5250 # query `&quot;SELECT &#x27;hello&#x27; AS Word&quot;`), or the column name (e.g.,
5251 # `&quot;ColName&quot;` in the query `&quot;SELECT ColName FROM Table&quot;`). Some
5252 # columns might have an empty name (e.g., !&quot;SELECT
5253 # UPPER(ColName)&quot;`). Note that a query result can contain
5254 # multiple fields with the same name.
5255 &quot;type&quot;: # Object with schema name: Type # The type of the field.
5256 },
5257 ],
5258 },
5259 },
5260 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5261 }
5262
5263 x__xgafv: string, V1 error format.
5264 Allowed values
5265 1 - v1 error format
5266 2 - v2 error format
5267
5268Returns:
5269 An object of the form:
5270
5271 { # The response for PartitionQuery
5272 # or PartitionRead
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5273 &quot;transaction&quot;: { # A transaction. # Transaction created by this request.
5274 &quot;id&quot;: &quot;A String&quot;, # `id` may be used to identify the transaction in subsequent
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5275 # Read,
5276 # ExecuteSql,
5277 # Commit, or
5278 # Rollback calls.
5279 #
5280 # Single-use read-only transactions do not have IDs, because
5281 # single-use transactions do not support multiple requests.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5282 &quot;readTimestamp&quot;: &quot;A String&quot;, # For snapshot read-only transactions, the read timestamp chosen
5283 # for the transaction. Not returned by default: see
5284 # TransactionOptions.ReadOnly.return_read_timestamp.
5285 #
5286 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
5287 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5288 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5289 &quot;partitions&quot;: [ # Partitions created by this request.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5290 { # Information returned for each partition returned in a
5291 # PartitionResponse.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5292 &quot;partitionToken&quot;: &quot;A String&quot;, # This token can be passed to Read, StreamingRead, ExecuteSql, or
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5293 # ExecuteStreamingSql requests to restrict the results to those identified by
5294 # this partition token.
5295 },
5296 ],
5297 }</pre>
5298</div>
5299
5300<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]5301 <code class="details" id="partitionRead">partitionRead(session, body=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5302 <pre>Creates a set of partition tokens that can be used to execute a read
5303operation in parallel. Each of the returned partition tokens can be used
5304by StreamingRead to specify a subset of the read
5305result to read. The same session and read-only transaction must be used by
5306the PartitionReadRequest used to create the partition tokens and the
5307ReadRequests that use the partition tokens. There are no ordering
5308guarantees on rows returned among the returned partition tokens, or even
5309within each individual StreamingRead call issued with a partition_token.
5310
5311Partition tokens become invalid when the session used to create them
5312is deleted, is idle for too long, begins a new transaction, or becomes too
5313old. When any of these happen, it is not possible to resume the read, and
5314the whole operation must be restarted from the beginning.
5315
5316Args:
5317 session: string, Required. The session used to create the partitions. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]5318 body: object, The request body.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5319 The object takes the form of:
5320
5321{ # The request for PartitionRead
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5322 &quot;columns&quot;: [ # The columns of table to be returned for each row matching
5323 # this request.
5324 &quot;A String&quot;,
5325 ],
5326 &quot;transaction&quot;: { # This message is used to select the transaction in which a # Read only snapshot transactions are supported, read/write and single use
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5327 # transactions are not.
5328 # Read or
5329 # ExecuteSql call runs.
5330 #
5331 # See TransactionOptions for more information about transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5332 &quot;singleUse&quot;: { # # Transactions # Execute the read or SQL query in a temporary transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5333 # This is the most efficient way to execute a transaction that
5334 # consists of a single SQL query.
5335 #
5336 #
5337 # Each session can have at most one active transaction at a time. After the
5338 # active transaction is completed, the session can immediately be
5339 # re-used for the next transaction. It is not necessary to create a
5340 # new session for each transaction.
5341 #
5342 # # Transaction Modes
5343 #
5344 # Cloud Spanner supports three transaction modes:
5345 #
5346 # 1. Locking read-write. This type of transaction is the only way
5347 # to write data into Cloud Spanner. These transactions rely on
5348 # pessimistic locking and, if necessary, two-phase commit.
5349 # Locking read-write transactions may abort, requiring the
5350 # application to retry.
5351 #
5352 # 2. Snapshot read-only. This transaction type provides guaranteed
5353 # consistency across several reads, but does not allow
5354 # writes. Snapshot read-only transactions can be configured to
5355 # read at timestamps in the past. Snapshot read-only
5356 # transactions do not need to be committed.
5357 #
5358 # 3. Partitioned DML. This type of transaction is used to execute
5359 # a single Partitioned DML statement. Partitioned DML partitions
5360 # the key space and runs the DML statement over each partition
5361 # in parallel using separate, internal transactions that commit
5362 # independently. Partitioned DML transactions do not need to be
5363 # committed.
5364 #
5365 # For transactions that only read, snapshot read-only transactions
5366 # provide simpler semantics and are almost always faster. In
5367 # particular, read-only transactions do not take locks, so they do
5368 # not conflict with read-write transactions. As a consequence of not
5369 # taking locks, they also do not abort, so retry loops are not needed.
5370 #
5371 # Transactions may only read/write data in a single database. They
5372 # may, however, read/write data in different tables within that
5373 # database.
5374 #
5375 # ## Locking Read-Write Transactions
5376 #
5377 # Locking transactions may be used to atomically read-modify-write
5378 # data anywhere in a database. This type of transaction is externally
5379 # consistent.
5380 #
5381 # Clients should attempt to minimize the amount of time a transaction
5382 # is active. Faster transactions commit with higher probability
5383 # and cause less contention. Cloud Spanner attempts to keep read locks
5384 # active as long as the transaction continues to do reads, and the
5385 # transaction has not been terminated by
5386 # Commit or
5387 # Rollback. Long periods of
5388 # inactivity at the client may cause Cloud Spanner to release a
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5389 # transaction&#x27;s locks and abort it.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5390 #
5391 # Conceptually, a read-write transaction consists of zero or more
5392 # reads or SQL statements followed by
5393 # Commit. At any time before
5394 # Commit, the client can send a
5395 # Rollback request to abort the
5396 # transaction.
5397 #
5398 # ### Semantics
5399 #
5400 # Cloud Spanner can commit the transaction if all read locks it acquired
5401 # are still valid at commit time, and it is able to acquire write
5402 # locks for all writes. Cloud Spanner can abort the transaction for any
5403 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
5404 # that the transaction has not modified any user data in Cloud Spanner.
5405 #
5406 # Unless the transaction commits, Cloud Spanner makes no guarantees about
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5407 # how long the transaction&#x27;s locks were held for. It is an error to
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5408 # use Cloud Spanner locks for any sort of mutual exclusion other than
5409 # between Cloud Spanner transactions themselves.
5410 #
5411 # ### Retrying Aborted Transactions
5412 #
5413 # When a transaction aborts, the application can choose to retry the
5414 # whole transaction again. To maximize the chances of successfully
5415 # committing the retry, the client should execute the retry in the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5416 # same session as the original attempt. The original session&#x27;s lock
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5417 # priority increases with each consecutive abort, meaning that each
5418 # attempt has a slightly better chance of success than the previous.
5419 #
5420 # Under some circumstances (e.g., many transactions attempting to
5421 # modify the same row(s)), a transaction can abort many times in a
5422 # short period before successfully committing. Thus, it is not a good
5423 # idea to cap the number of retries a transaction can attempt;
5424 # instead, it is better to limit the total amount of wall time spent
5425 # retrying.
5426 #
5427 # ### Idle Transactions
5428 #
5429 # A transaction is considered idle if it has no outstanding reads or
5430 # SQL queries and has not started a read or SQL query within the last 10
5431 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5432 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5433 # fail with error `ABORTED`.
5434 #
5435 # If this behavior is undesirable, periodically executing a simple
5436 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
5437 # transaction from becoming idle.
5438 #
5439 # ## Snapshot Read-Only Transactions
5440 #
5441 # Snapshot read-only transactions provides a simpler method than
5442 # locking read-write transactions for doing several consistent
5443 # reads. However, this type of transaction does not support writes.
5444 #
5445 # Snapshot transactions do not take locks. Instead, they work by
5446 # choosing a Cloud Spanner timestamp, then executing all reads at that
5447 # timestamp. Since they do not acquire locks, they do not block
5448 # concurrent read-write transactions.
5449 #
5450 # Unlike locking read-write transactions, snapshot read-only
5451 # transactions never abort. They can fail if the chosen read
5452 # timestamp is garbage collected; however, the default garbage
5453 # collection policy is generous enough that most applications do not
5454 # need to worry about this in practice.
5455 #
5456 # Snapshot read-only transactions do not need to call
5457 # Commit or
5458 # Rollback (and in fact are not
5459 # permitted to do so).
5460 #
5461 # To execute a snapshot transaction, the client specifies a timestamp
5462 # bound, which tells Cloud Spanner how to choose a read timestamp.
5463 #
5464 # The types of timestamp bound are:
5465 #
5466 # - Strong (the default).
5467 # - Bounded staleness.
5468 # - Exact staleness.
5469 #
5470 # If the Cloud Spanner database to be read is geographically distributed,
5471 # stale read-only transactions can execute more quickly than strong
5472 # or read-write transaction, because they are able to execute far
5473 # from the leader replica.
5474 #
5475 # Each type of timestamp bound is discussed in detail below.
5476 #
5477 # ### Strong
5478 #
5479 # Strong reads are guaranteed to see the effects of all transactions
5480 # that have committed before the start of the read. Furthermore, all
5481 # rows yielded by a single read are consistent with each other -- if
5482 # any part of the read observes a transaction, all parts of the read
5483 # see the transaction.
5484 #
5485 # Strong reads are not repeatable: two consecutive strong read-only
5486 # transactions might return inconsistent results if there are
5487 # concurrent writes. If consistency across reads is required, the
5488 # reads should be executed within a transaction or at an exact read
5489 # timestamp.
5490 #
5491 # See TransactionOptions.ReadOnly.strong.
5492 #
5493 # ### Exact Staleness
5494 #
5495 # These timestamp bounds execute reads at a user-specified
5496 # timestamp. Reads at a timestamp are guaranteed to see a consistent
5497 # prefix of the global transaction history: they observe
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]5498 # modifications done by all transactions with a commit timestamp &lt;=
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5499 # the read timestamp, and observe none of the modifications done by
5500 # transactions with a larger commit timestamp. They will block until
5501 # all conflicting transactions that may be assigned commit timestamps
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]5502 # &lt;= the read timestamp have finished.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5503 #
5504 # The timestamp can either be expressed as an absolute Cloud Spanner commit
5505 # timestamp or a staleness relative to the current time.
5506 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5507 # These modes do not require a &quot;negotiation phase&quot; to pick a
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5508 # timestamp. As a result, they execute slightly faster than the
5509 # equivalent boundedly stale concurrency modes. On the other hand,
5510 # boundedly stale reads usually return fresher results.
5511 #
5512 # See TransactionOptions.ReadOnly.read_timestamp and
5513 # TransactionOptions.ReadOnly.exact_staleness.
5514 #
5515 # ### Bounded Staleness
5516 #
5517 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
5518 # subject to a user-provided staleness bound. Cloud Spanner chooses the
5519 # newest timestamp within the staleness bound that allows execution
5520 # of the reads at the closest available replica without blocking.
5521 #
5522 # All rows yielded are consistent with each other -- if any part of
5523 # the read observes a transaction, all parts of the read see the
5524 # transaction. Boundedly stale reads are not repeatable: two stale
5525 # reads, even if they use the same staleness bound, can execute at
5526 # different timestamps and thus return inconsistent results.
5527 #
5528 # Boundedly stale reads execute in two phases: the first phase
5529 # negotiates a timestamp among all replicas needed to serve the
5530 # read. In the second phase, reads are executed at the negotiated
5531 # timestamp.
5532 #
5533 # As a result of the two phase execution, bounded staleness reads are
5534 # usually a little slower than comparable exact staleness
5535 # reads. However, they are typically able to return fresher
5536 # results, and are more likely to execute at the closest replica.
5537 #
5538 # Because the timestamp negotiation requires up-front knowledge of
5539 # which rows will be read, it can only be used with single-use
5540 # read-only transactions.
5541 #
5542 # See TransactionOptions.ReadOnly.max_staleness and
5543 # TransactionOptions.ReadOnly.min_read_timestamp.
5544 #
5545 # ### Old Read Timestamps and Garbage Collection
5546 #
5547 # Cloud Spanner continuously garbage collects deleted and overwritten data
5548 # in the background to reclaim storage space. This process is known
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5549 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5550 # are one hour old. Because of this, Cloud Spanner cannot perform reads
5551 # at read timestamps more than one hour in the past. This
5552 # restriction also applies to in-progress reads and/or SQL queries whose
5553 # timestamp become too old while executing. Reads and SQL queries with
5554 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
5555 #
5556 # ## Partitioned DML Transactions
5557 #
5558 # Partitioned DML transactions are used to execute DML statements with a
5559 # different execution strategy that provides different, and often better,
5560 # scalability properties for large, table-wide operations than DML in a
5561 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
5562 # should prefer using ReadWrite transactions.
5563 #
5564 # Partitioned DML partitions the keyspace and runs the DML statement on each
5565 # partition in separate, internal transactions. These transactions commit
5566 # automatically when complete, and run independently from one another.
5567 #
5568 # To reduce lock contention, this execution strategy only acquires read locks
5569 # on rows that match the WHERE clause of the statement. Additionally, the
5570 # smaller per-partition transactions hold locks for less time.
5571 #
5572 # That said, Partitioned DML is not a drop-in replacement for standard DML used
5573 # in ReadWrite transactions.
5574 #
5575 # - The DML statement must be fully-partitionable. Specifically, the statement
5576 # must be expressible as the union of many statements which each access only
5577 # a single row of the table.
5578 #
5579 # - The statement is not applied atomically to all rows of the table. Rather,
5580 # the statement is applied atomically to partitions of the table, in
5581 # independent transactions. Secondary index rows are updated atomically
5582 # with the base table rows.
5583 #
5584 # - Partitioned DML does not guarantee exactly-once execution semantics
5585 # against a partition. The statement will be applied at least once to each
5586 # partition. It is strongly recommended that the DML statement should be
5587 # idempotent to avoid unexpected results. For instance, it is potentially
5588 # dangerous to run a statement such as
5589 # `UPDATE table SET column = column + 1` as it could be run multiple times
5590 # against some rows.
5591 #
5592 # - The partitions are committed automatically - there is no support for
5593 # Commit or Rollback. If the call returns an error, or if the client issuing
5594 # the ExecuteSql call dies, it is possible that some rows had the statement
5595 # executed on them successfully. It is also possible that statement was
5596 # never executed against other rows.
5597 #
5598 # - Partitioned DML transactions may only contain the execution of a single
5599 # DML statement via ExecuteSql or ExecuteStreamingSql.
5600 #
5601 # - If any error is encountered during the execution of the partitioned DML
5602 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
5603 # value that cannot be stored due to schema constraints), then the
5604 # operation is stopped at that point and an error is returned. It is
5605 # possible that at this point, some partitions have been committed (or even
5606 # committed multiple times), and other partitions have not been run at all.
5607 #
5608 # Given the above, Partitioned DML is good fit for large, database-wide,
5609 # operations that are idempotent, such as deleting old rows from a very large
5610 # table.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5611 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5612 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5613 # Authorization to begin a Partitioned DML transaction requires
5614 # `spanner.databases.beginPartitionedDmlTransaction` permission
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5615 # on the `session` resource.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5616 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5617 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5618 #
5619 # Authorization to begin a read-only transaction requires
5620 # `spanner.databases.beginReadOnlyTransaction` permission
5621 # on the `session` resource.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5622 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5623 #
5624 # This is useful for requesting fresher data than some previous
5625 # read, or data that is fresh enough to observe the effects of some
5626 # previously committed transaction whose timestamp is known.
5627 #
5628 # Note that this option can only be used in single-use transactions.
5629 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5630 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
5631 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
5632 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]5633 # reads at a specific timestamp are repeatable; the same read at
5634 # the same timestamp always returns the same data. If the
5635 # timestamp is in the future, the read will block until the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5636 # specified timestamp, modulo the read&#x27;s deadline.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]5637 #
5638 # Useful for large scale consistent reads such as mapreduces, or
5639 # for coordinating many reads against a consistent snapshot of the
5640 # data.
5641 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5642 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
5643 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
5644 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5645 # seconds. Guarantees that all writes that have committed more
5646 # than the specified number of seconds ago are visible. Because
5647 # Cloud Spanner chooses the exact timestamp, this mode works even if
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5648 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5649 # commit timestamps.
5650 #
5651 # Useful for reading the freshest data available at a nearby
5652 # replica, while bounding the possible staleness if the local
5653 # replica has fallen behind.
5654 #
5655 # Note that this option can only be used in single-use
5656 # transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5657 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
5658 # the Transaction message that describes the transaction.
5659 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5660 # old. The timestamp is chosen soon after the read is started.
5661 #
5662 # Guarantees that all writes that have committed more than the
5663 # specified number of seconds ago are visible. Because Cloud Spanner
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5664 # chooses the exact timestamp, this mode works even if the client&#x27;s
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5665 # local clock is substantially skewed from Cloud Spanner commit
5666 # timestamps.
5667 #
5668 # Useful for reading at nearby replicas without the distributed
5669 # timestamp negotiation overhead of `max_staleness`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5670 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5671 # are visible.
5672 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5673 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
5674 #
5675 # Authorization to begin a read-write transaction requires
5676 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
5677 # on the `session` resource.
5678 # transaction type has no options.
5679 },
5680 },
5681 &quot;begin&quot;: { # # Transactions # Begin a new transaction and execute this read or SQL query in
5682 # it. The transaction ID of the new transaction is returned in
5683 # ResultSetMetadata.transaction, which is a Transaction.
5684 #
5685 #
5686 # Each session can have at most one active transaction at a time. After the
5687 # active transaction is completed, the session can immediately be
5688 # re-used for the next transaction. It is not necessary to create a
5689 # new session for each transaction.
5690 #
5691 # # Transaction Modes
5692 #
5693 # Cloud Spanner supports three transaction modes:
5694 #
5695 # 1. Locking read-write. This type of transaction is the only way
5696 # to write data into Cloud Spanner. These transactions rely on
5697 # pessimistic locking and, if necessary, two-phase commit.
5698 # Locking read-write transactions may abort, requiring the
5699 # application to retry.
5700 #
5701 # 2. Snapshot read-only. This transaction type provides guaranteed
5702 # consistency across several reads, but does not allow
5703 # writes. Snapshot read-only transactions can be configured to
5704 # read at timestamps in the past. Snapshot read-only
5705 # transactions do not need to be committed.
5706 #
5707 # 3. Partitioned DML. This type of transaction is used to execute
5708 # a single Partitioned DML statement. Partitioned DML partitions
5709 # the key space and runs the DML statement over each partition
5710 # in parallel using separate, internal transactions that commit
5711 # independently. Partitioned DML transactions do not need to be
5712 # committed.
5713 #
5714 # For transactions that only read, snapshot read-only transactions
5715 # provide simpler semantics and are almost always faster. In
5716 # particular, read-only transactions do not take locks, so they do
5717 # not conflict with read-write transactions. As a consequence of not
5718 # taking locks, they also do not abort, so retry loops are not needed.
5719 #
5720 # Transactions may only read/write data in a single database. They
5721 # may, however, read/write data in different tables within that
5722 # database.
5723 #
5724 # ## Locking Read-Write Transactions
5725 #
5726 # Locking transactions may be used to atomically read-modify-write
5727 # data anywhere in a database. This type of transaction is externally
5728 # consistent.
5729 #
5730 # Clients should attempt to minimize the amount of time a transaction
5731 # is active. Faster transactions commit with higher probability
5732 # and cause less contention. Cloud Spanner attempts to keep read locks
5733 # active as long as the transaction continues to do reads, and the
5734 # transaction has not been terminated by
5735 # Commit or
5736 # Rollback. Long periods of
5737 # inactivity at the client may cause Cloud Spanner to release a
5738 # transaction&#x27;s locks and abort it.
5739 #
5740 # Conceptually, a read-write transaction consists of zero or more
5741 # reads or SQL statements followed by
5742 # Commit. At any time before
5743 # Commit, the client can send a
5744 # Rollback request to abort the
5745 # transaction.
5746 #
5747 # ### Semantics
5748 #
5749 # Cloud Spanner can commit the transaction if all read locks it acquired
5750 # are still valid at commit time, and it is able to acquire write
5751 # locks for all writes. Cloud Spanner can abort the transaction for any
5752 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
5753 # that the transaction has not modified any user data in Cloud Spanner.
5754 #
5755 # Unless the transaction commits, Cloud Spanner makes no guarantees about
5756 # how long the transaction&#x27;s locks were held for. It is an error to
5757 # use Cloud Spanner locks for any sort of mutual exclusion other than
5758 # between Cloud Spanner transactions themselves.
5759 #
5760 # ### Retrying Aborted Transactions
5761 #
5762 # When a transaction aborts, the application can choose to retry the
5763 # whole transaction again. To maximize the chances of successfully
5764 # committing the retry, the client should execute the retry in the
5765 # same session as the original attempt. The original session&#x27;s lock
5766 # priority increases with each consecutive abort, meaning that each
5767 # attempt has a slightly better chance of success than the previous.
5768 #
5769 # Under some circumstances (e.g., many transactions attempting to
5770 # modify the same row(s)), a transaction can abort many times in a
5771 # short period before successfully committing. Thus, it is not a good
5772 # idea to cap the number of retries a transaction can attempt;
5773 # instead, it is better to limit the total amount of wall time spent
5774 # retrying.
5775 #
5776 # ### Idle Transactions
5777 #
5778 # A transaction is considered idle if it has no outstanding reads or
5779 # SQL queries and has not started a read or SQL query within the last 10
5780 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
5781 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
5782 # fail with error `ABORTED`.
5783 #
5784 # If this behavior is undesirable, periodically executing a simple
5785 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
5786 # transaction from becoming idle.
5787 #
5788 # ## Snapshot Read-Only Transactions
5789 #
5790 # Snapshot read-only transactions provides a simpler method than
5791 # locking read-write transactions for doing several consistent
5792 # reads. However, this type of transaction does not support writes.
5793 #
5794 # Snapshot transactions do not take locks. Instead, they work by
5795 # choosing a Cloud Spanner timestamp, then executing all reads at that
5796 # timestamp. Since they do not acquire locks, they do not block
5797 # concurrent read-write transactions.
5798 #
5799 # Unlike locking read-write transactions, snapshot read-only
5800 # transactions never abort. They can fail if the chosen read
5801 # timestamp is garbage collected; however, the default garbage
5802 # collection policy is generous enough that most applications do not
5803 # need to worry about this in practice.
5804 #
5805 # Snapshot read-only transactions do not need to call
5806 # Commit or
5807 # Rollback (and in fact are not
5808 # permitted to do so).
5809 #
5810 # To execute a snapshot transaction, the client specifies a timestamp
5811 # bound, which tells Cloud Spanner how to choose a read timestamp.
5812 #
5813 # The types of timestamp bound are:
5814 #
5815 # - Strong (the default).
5816 # - Bounded staleness.
5817 # - Exact staleness.
5818 #
5819 # If the Cloud Spanner database to be read is geographically distributed,
5820 # stale read-only transactions can execute more quickly than strong
5821 # or read-write transaction, because they are able to execute far
5822 # from the leader replica.
5823 #
5824 # Each type of timestamp bound is discussed in detail below.
5825 #
5826 # ### Strong
5827 #
5828 # Strong reads are guaranteed to see the effects of all transactions
5829 # that have committed before the start of the read. Furthermore, all
5830 # rows yielded by a single read are consistent with each other -- if
5831 # any part of the read observes a transaction, all parts of the read
5832 # see the transaction.
5833 #
5834 # Strong reads are not repeatable: two consecutive strong read-only
5835 # transactions might return inconsistent results if there are
5836 # concurrent writes. If consistency across reads is required, the
5837 # reads should be executed within a transaction or at an exact read
5838 # timestamp.
5839 #
5840 # See TransactionOptions.ReadOnly.strong.
5841 #
5842 # ### Exact Staleness
5843 #
5844 # These timestamp bounds execute reads at a user-specified
5845 # timestamp. Reads at a timestamp are guaranteed to see a consistent
5846 # prefix of the global transaction history: they observe
5847 # modifications done by all transactions with a commit timestamp &lt;=
5848 # the read timestamp, and observe none of the modifications done by
5849 # transactions with a larger commit timestamp. They will block until
5850 # all conflicting transactions that may be assigned commit timestamps
5851 # &lt;= the read timestamp have finished.
5852 #
5853 # The timestamp can either be expressed as an absolute Cloud Spanner commit
5854 # timestamp or a staleness relative to the current time.
5855 #
5856 # These modes do not require a &quot;negotiation phase&quot; to pick a
5857 # timestamp. As a result, they execute slightly faster than the
5858 # equivalent boundedly stale concurrency modes. On the other hand,
5859 # boundedly stale reads usually return fresher results.
5860 #
5861 # See TransactionOptions.ReadOnly.read_timestamp and
5862 # TransactionOptions.ReadOnly.exact_staleness.
5863 #
5864 # ### Bounded Staleness
5865 #
5866 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
5867 # subject to a user-provided staleness bound. Cloud Spanner chooses the
5868 # newest timestamp within the staleness bound that allows execution
5869 # of the reads at the closest available replica without blocking.
5870 #
5871 # All rows yielded are consistent with each other -- if any part of
5872 # the read observes a transaction, all parts of the read see the
5873 # transaction. Boundedly stale reads are not repeatable: two stale
5874 # reads, even if they use the same staleness bound, can execute at
5875 # different timestamps and thus return inconsistent results.
5876 #
5877 # Boundedly stale reads execute in two phases: the first phase
5878 # negotiates a timestamp among all replicas needed to serve the
5879 # read. In the second phase, reads are executed at the negotiated
5880 # timestamp.
5881 #
5882 # As a result of the two phase execution, bounded staleness reads are
5883 # usually a little slower than comparable exact staleness
5884 # reads. However, they are typically able to return fresher
5885 # results, and are more likely to execute at the closest replica.
5886 #
5887 # Because the timestamp negotiation requires up-front knowledge of
5888 # which rows will be read, it can only be used with single-use
5889 # read-only transactions.
5890 #
5891 # See TransactionOptions.ReadOnly.max_staleness and
5892 # TransactionOptions.ReadOnly.min_read_timestamp.
5893 #
5894 # ### Old Read Timestamps and Garbage Collection
5895 #
5896 # Cloud Spanner continuously garbage collects deleted and overwritten data
5897 # in the background to reclaim storage space. This process is known
5898 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
5899 # are one hour old. Because of this, Cloud Spanner cannot perform reads
5900 # at read timestamps more than one hour in the past. This
5901 # restriction also applies to in-progress reads and/or SQL queries whose
5902 # timestamp become too old while executing. Reads and SQL queries with
5903 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
5904 #
5905 # ## Partitioned DML Transactions
5906 #
5907 # Partitioned DML transactions are used to execute DML statements with a
5908 # different execution strategy that provides different, and often better,
5909 # scalability properties for large, table-wide operations than DML in a
5910 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
5911 # should prefer using ReadWrite transactions.
5912 #
5913 # Partitioned DML partitions the keyspace and runs the DML statement on each
5914 # partition in separate, internal transactions. These transactions commit
5915 # automatically when complete, and run independently from one another.
5916 #
5917 # To reduce lock contention, this execution strategy only acquires read locks
5918 # on rows that match the WHERE clause of the statement. Additionally, the
5919 # smaller per-partition transactions hold locks for less time.
5920 #
5921 # That said, Partitioned DML is not a drop-in replacement for standard DML used
5922 # in ReadWrite transactions.
5923 #
5924 # - The DML statement must be fully-partitionable. Specifically, the statement
5925 # must be expressible as the union of many statements which each access only
5926 # a single row of the table.
5927 #
5928 # - The statement is not applied atomically to all rows of the table. Rather,
5929 # the statement is applied atomically to partitions of the table, in
5930 # independent transactions. Secondary index rows are updated atomically
5931 # with the base table rows.
5932 #
5933 # - Partitioned DML does not guarantee exactly-once execution semantics
5934 # against a partition. The statement will be applied at least once to each
5935 # partition. It is strongly recommended that the DML statement should be
5936 # idempotent to avoid unexpected results. For instance, it is potentially
5937 # dangerous to run a statement such as
5938 # `UPDATE table SET column = column + 1` as it could be run multiple times
5939 # against some rows.
5940 #
5941 # - The partitions are committed automatically - there is no support for
5942 # Commit or Rollback. If the call returns an error, or if the client issuing
5943 # the ExecuteSql call dies, it is possible that some rows had the statement
5944 # executed on them successfully. It is also possible that statement was
5945 # never executed against other rows.
5946 #
5947 # - Partitioned DML transactions may only contain the execution of a single
5948 # DML statement via ExecuteSql or ExecuteStreamingSql.
5949 #
5950 # - If any error is encountered during the execution of the partitioned DML
5951 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
5952 # value that cannot be stored due to schema constraints), then the
5953 # operation is stopped at that point and an error is returned. It is
5954 # possible that at this point, some partitions have been committed (or even
5955 # committed multiple times), and other partitions have not been run at all.
5956 #
5957 # Given the above, Partitioned DML is good fit for large, database-wide,
5958 # operations that are idempotent, such as deleting old rows from a very large
5959 # table.
5960 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]5961 #
5962 # Authorization to begin a Partitioned DML transaction requires
5963 # `spanner.databases.beginPartitionedDmlTransaction` permission
5964 # on the `session` resource.
5965 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]5966 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
5967 #
5968 # Authorization to begin a read-only transaction requires
5969 # `spanner.databases.beginReadOnlyTransaction` permission
5970 # on the `session` resource.
5971 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
5972 #
5973 # This is useful for requesting fresher data than some previous
5974 # read, or data that is fresh enough to observe the effects of some
5975 # previously committed transaction whose timestamp is known.
5976 #
5977 # Note that this option can only be used in single-use transactions.
5978 #
5979 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
5980 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
5981 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
5982 # reads at a specific timestamp are repeatable; the same read at
5983 # the same timestamp always returns the same data. If the
5984 # timestamp is in the future, the read will block until the
5985 # specified timestamp, modulo the read&#x27;s deadline.
5986 #
5987 # Useful for large scale consistent reads such as mapreduces, or
5988 # for coordinating many reads against a consistent snapshot of the
5989 # data.
5990 #
5991 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
5992 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
5993 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
5994 # seconds. Guarantees that all writes that have committed more
5995 # than the specified number of seconds ago are visible. Because
5996 # Cloud Spanner chooses the exact timestamp, this mode works even if
5997 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
5998 # commit timestamps.
5999 #
6000 # Useful for reading the freshest data available at a nearby
6001 # replica, while bounding the possible staleness if the local
6002 # replica has fallen behind.
6003 #
6004 # Note that this option can only be used in single-use
6005 # transactions.
6006 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
6007 # the Transaction message that describes the transaction.
6008 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
6009 # old. The timestamp is chosen soon after the read is started.
6010 #
6011 # Guarantees that all writes that have committed more than the
6012 # specified number of seconds ago are visible. Because Cloud Spanner
6013 # chooses the exact timestamp, this mode works even if the client&#x27;s
6014 # local clock is substantially skewed from Cloud Spanner commit
6015 # timestamps.
6016 #
6017 # Useful for reading at nearby replicas without the distributed
6018 # timestamp negotiation overhead of `max_staleness`.
6019 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
6020 # are visible.
6021 },
6022 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
6023 #
6024 # Authorization to begin a read-write transaction requires
6025 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
6026 # on the `session` resource.
6027 # transaction type has no options.
6028 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6029 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6030 &quot;id&quot;: &quot;A String&quot;, # Execute the read or SQL query in a previously-started transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6031 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6032 &quot;table&quot;: &quot;A String&quot;, # Required. The name of the table in the database to be read.
6033 &quot;partitionOptions&quot;: { # Options for a PartitionQueryRequest and # Additional options that affect how many partitions are created.
6034 # PartitionReadRequest.
6035 &quot;partitionSizeBytes&quot;: &quot;A String&quot;, # **Note:** This hint is currently ignored by PartitionQuery and
6036 # PartitionRead requests.
6037 #
6038 # The desired data size for each partition generated. The default for this
6039 # option is currently 1 GiB. This is only a hint. The actual size of each
6040 # partition may be smaller or larger than this size request.
6041 &quot;maxPartitions&quot;: &quot;A String&quot;, # **Note:** This hint is currently ignored by PartitionQuery and
6042 # PartitionRead requests.
6043 #
6044 # The desired maximum number of partitions to return. For example, this may
6045 # be set to the number of workers available. The default for this option
6046 # is currently 10,000. The maximum value is currently 200,000. This is only
6047 # a hint. The actual number of partitions returned may be smaller or larger
6048 # than this maximum count request.
6049 },
6050 &quot;index&quot;: &quot;A String&quot;, # If non-empty, the name of an index on table. This index is
6051 # used instead of the table primary key when interpreting key_set
6052 # and sorting result rows. See key_set for further information.
6053 &quot;keySet&quot;: { # `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
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6054 # primary keys of the rows in table to be yielded, unless index
6055 # is present. If index is present, then key_set instead names
6056 # index keys in index.
6057 #
6058 # It is not an error for the `key_set` to name rows that do not
6059 # exist in the database. Read yields nothing for nonexistent rows.
6060 # the keys are expected to be in the same table or index. The keys need
6061 # not be sorted in any particular way.
6062 #
6063 # If the same key is specified multiple times in the set (for example
6064 # if two ranges, two keys, or a key and a range overlap), Cloud Spanner
6065 # behaves as if the key were only specified once.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6066 &quot;ranges&quot;: [ # A list of key ranges. See KeyRange for more information about
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6067 # key range specifications.
6068 { # KeyRange represents a range of rows in a table or index.
6069 #
6070 # A range has a start key and an end key. These keys can be open or
6071 # closed, indicating if the range includes rows with that key.
6072 #
6073 # Keys are represented by lists, where the ith value in the list
6074 # corresponds to the ith component of the table or index primary key.
6075 # Individual values are encoded as described
6076 # here.
6077 #
6078 # For example, consider the following table definition:
6079 #
6080 # CREATE TABLE UserEvents (
6081 # UserName STRING(MAX),
6082 # EventDate STRING(10)
6083 # ) PRIMARY KEY(UserName, EventDate);
6084 #
6085 # The following keys name rows in this table:
6086 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6087 # &quot;Bob&quot;, &quot;2014-09-23&quot;
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6088 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6089 # Since the `UserEvents` table&#x27;s `PRIMARY KEY` clause names two
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6090 # columns, each `UserEvents` key has two elements; the first is the
6091 # `UserName`, and the second is the `EventDate`.
6092 #
6093 # Key ranges with multiple components are interpreted
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6094 # lexicographically by component using the table or index key&#x27;s declared
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6095 # sort order. For example, the following range returns all events for
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6096 # user `&quot;Bob&quot;` that occurred in the year 2015:
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6097 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6098 # &quot;start_closed&quot;: [&quot;Bob&quot;, &quot;2015-01-01&quot;]
6099 # &quot;end_closed&quot;: [&quot;Bob&quot;, &quot;2015-12-31&quot;]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6100 #
6101 # Start and end keys can omit trailing key components. This affects the
6102 # inclusion and exclusion of rows that exactly match the provided key
6103 # components: if the key is closed, then rows that exactly match the
6104 # provided components are included; if the key is open, then rows
6105 # that exactly match are not included.
6106 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6107 # For example, the following range includes all events for `&quot;Bob&quot;` that
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6108 # occurred during and after the year 2000:
6109 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6110 # &quot;start_closed&quot;: [&quot;Bob&quot;, &quot;2000-01-01&quot;]
6111 # &quot;end_closed&quot;: [&quot;Bob&quot;]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6112 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6113 # The next example retrieves all events for `&quot;Bob&quot;`:
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6114 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6115 # &quot;start_closed&quot;: [&quot;Bob&quot;]
6116 # &quot;end_closed&quot;: [&quot;Bob&quot;]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6117 #
6118 # To retrieve events before the year 2000:
6119 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6120 # &quot;start_closed&quot;: [&quot;Bob&quot;]
6121 # &quot;end_open&quot;: [&quot;Bob&quot;, &quot;2000-01-01&quot;]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6122 #
6123 # The following range includes all rows in the table:
6124 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6125 # &quot;start_closed&quot;: []
6126 # &quot;end_closed&quot;: []
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6127 #
6128 # This range returns all users whose `UserName` begins with any
6129 # character from A to C:
6130 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6131 # &quot;start_closed&quot;: [&quot;A&quot;]
6132 # &quot;end_open&quot;: [&quot;D&quot;]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6133 #
6134 # This range returns all users whose `UserName` begins with B:
6135 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6136 # &quot;start_closed&quot;: [&quot;B&quot;]
6137 # &quot;end_open&quot;: [&quot;C&quot;]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6138 #
6139 # Key ranges honor column sort order. For example, suppose a table is
6140 # defined as follows:
6141 #
6142 # CREATE TABLE DescendingSortedTable {
6143 # Key INT64,
6144 # ...
6145 # ) PRIMARY KEY(Key DESC);
6146 #
6147 # The following range retrieves all rows with key values between 1
6148 # and 100 inclusive:
6149 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6150 # &quot;start_closed&quot;: [&quot;100&quot;]
6151 # &quot;end_closed&quot;: [&quot;1&quot;]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6152 #
6153 # Note that 100 is passed as the start, and 1 is passed as the end,
6154 # because `Key` is a descending column in the schema.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6155 &quot;endOpen&quot;: [ # If the end is open, then the range excludes rows whose first
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6156 # `len(end_open)` key columns exactly match `end_open`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6157 &quot;&quot;,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6158 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6159 &quot;endClosed&quot;: [ # If the end is closed, then the range includes all rows whose
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6160 # first `len(end_closed)` key columns exactly match `end_closed`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6161 &quot;&quot;,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6162 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6163 &quot;startOpen&quot;: [ # If the start is open, then the range excludes rows whose first
6164 # `len(start_open)` key columns exactly match `start_open`.
6165 &quot;&quot;,
6166 ],
6167 &quot;startClosed&quot;: [ # If the start is closed, then the range includes all rows whose
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6168 # first `len(start_closed)` key columns exactly match `start_closed`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6169 &quot;&quot;,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6170 ],
6171 },
6172 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6173 &quot;all&quot;: True or False, # For convenience `all` can be set to `true` to indicate that this
6174 # `KeySet` matches all keys in the table or index. Note that any keys
6175 # specified in `keys` or `ranges` are only yielded once.
6176 &quot;keys&quot;: [ # A list of specific keys. Entries in `keys` should have exactly as
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6177 # many elements as there are columns in the primary or index key
6178 # with which this `KeySet` is used. Individual key values are
6179 # encoded as described here.
6180 [
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6181 &quot;&quot;,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6182 ],
6183 ],
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6184 },
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6185 }
6186
6187 x__xgafv: string, V1 error format.
6188 Allowed values
6189 1 - v1 error format
6190 2 - v2 error format
6191
6192Returns:
6193 An object of the form:
6194
6195 { # The response for PartitionQuery
6196 # or PartitionRead
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6197 &quot;transaction&quot;: { # A transaction. # Transaction created by this request.
6198 &quot;id&quot;: &quot;A String&quot;, # `id` may be used to identify the transaction in subsequent
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6199 # Read,
6200 # ExecuteSql,
6201 # Commit, or
6202 # Rollback calls.
6203 #
6204 # Single-use read-only transactions do not have IDs, because
6205 # single-use transactions do not support multiple requests.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6206 &quot;readTimestamp&quot;: &quot;A String&quot;, # For snapshot read-only transactions, the read timestamp chosen
6207 # for the transaction. Not returned by default: see
6208 # TransactionOptions.ReadOnly.return_read_timestamp.
6209 #
6210 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
6211 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6212 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6213 &quot;partitions&quot;: [ # Partitions created by this request.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6214 { # Information returned for each partition returned in a
6215 # PartitionResponse.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6216 &quot;partitionToken&quot;: &quot;A String&quot;, # This token can be passed to Read, StreamingRead, ExecuteSql, or
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6217 # ExecuteStreamingSql requests to restrict the results to those identified by
6218 # this partition token.
6219 },
6220 ],
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6221 }</pre>
6222</div>
6223
6224<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]6225 <code class="details" id="read">read(session, body=None, x__xgafv=None)</code>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6226 <pre>Reads rows from the database using key lookups and scans, as a
6227simple key/value style alternative to
6228ExecuteSql. This method cannot be used to
6229return a result set larger than 10 MiB; if the read matches more
6230data than that, the read fails with a `FAILED_PRECONDITION`
6231error.
6232
6233Reads inside read-write transactions might return `ABORTED`. If
6234this occurs, the application should restart the transaction from
6235the beginning. See Transaction for more details.
6236
6237Larger result sets can be yielded in streaming fashion by calling
6238StreamingRead instead.
6239
6240Args:
6241 session: string, Required. The session in which the read should be performed. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]6242 body: object, The request body.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6243 The object takes the form of:
6244
6245{ # The request for Read and
6246 # StreamingRead.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6247 &quot;index&quot;: &quot;A String&quot;, # If non-empty, the name of an index on table. This index is
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6248 # used instead of the table primary key when interpreting key_set
6249 # and sorting result rows. See key_set for further information.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6250 &quot;keySet&quot;: { # `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
6251 # primary keys of the rows in table to be yielded, unless index
6252 # is present. If index is present, then key_set instead names
6253 # index keys in index.
6254 #
6255 # If the partition_token field is empty, rows are yielded
6256 # in table primary key order (if index is empty) or index key order
6257 # (if index is non-empty). If the partition_token field is not
6258 # empty, rows will be yielded in an unspecified order.
6259 #
6260 # It is not an error for the `key_set` to name rows that do not
6261 # exist in the database. Read yields nothing for nonexistent rows.
6262 # the keys are expected to be in the same table or index. The keys need
6263 # not be sorted in any particular way.
6264 #
6265 # If the same key is specified multiple times in the set (for example
6266 # if two ranges, two keys, or a key and a range overlap), Cloud Spanner
6267 # behaves as if the key were only specified once.
6268 &quot;ranges&quot;: [ # A list of key ranges. See KeyRange for more information about
6269 # key range specifications.
6270 { # KeyRange represents a range of rows in a table or index.
6271 #
6272 # A range has a start key and an end key. These keys can be open or
6273 # closed, indicating if the range includes rows with that key.
6274 #
6275 # Keys are represented by lists, where the ith value in the list
6276 # corresponds to the ith component of the table or index primary key.
6277 # Individual values are encoded as described
6278 # here.
6279 #
6280 # For example, consider the following table definition:
6281 #
6282 # CREATE TABLE UserEvents (
6283 # UserName STRING(MAX),
6284 # EventDate STRING(10)
6285 # ) PRIMARY KEY(UserName, EventDate);
6286 #
6287 # The following keys name rows in this table:
6288 #
6289 # &quot;Bob&quot;, &quot;2014-09-23&quot;
6290 #
6291 # Since the `UserEvents` table&#x27;s `PRIMARY KEY` clause names two
6292 # columns, each `UserEvents` key has two elements; the first is the
6293 # `UserName`, and the second is the `EventDate`.
6294 #
6295 # Key ranges with multiple components are interpreted
6296 # lexicographically by component using the table or index key&#x27;s declared
6297 # sort order. For example, the following range returns all events for
6298 # user `&quot;Bob&quot;` that occurred in the year 2015:
6299 #
6300 # &quot;start_closed&quot;: [&quot;Bob&quot;, &quot;2015-01-01&quot;]
6301 # &quot;end_closed&quot;: [&quot;Bob&quot;, &quot;2015-12-31&quot;]
6302 #
6303 # Start and end keys can omit trailing key components. This affects the
6304 # inclusion and exclusion of rows that exactly match the provided key
6305 # components: if the key is closed, then rows that exactly match the
6306 # provided components are included; if the key is open, then rows
6307 # that exactly match are not included.
6308 #
6309 # For example, the following range includes all events for `&quot;Bob&quot;` that
6310 # occurred during and after the year 2000:
6311 #
6312 # &quot;start_closed&quot;: [&quot;Bob&quot;, &quot;2000-01-01&quot;]
6313 # &quot;end_closed&quot;: [&quot;Bob&quot;]
6314 #
6315 # The next example retrieves all events for `&quot;Bob&quot;`:
6316 #
6317 # &quot;start_closed&quot;: [&quot;Bob&quot;]
6318 # &quot;end_closed&quot;: [&quot;Bob&quot;]
6319 #
6320 # To retrieve events before the year 2000:
6321 #
6322 # &quot;start_closed&quot;: [&quot;Bob&quot;]
6323 # &quot;end_open&quot;: [&quot;Bob&quot;, &quot;2000-01-01&quot;]
6324 #
6325 # The following range includes all rows in the table:
6326 #
6327 # &quot;start_closed&quot;: []
6328 # &quot;end_closed&quot;: []
6329 #
6330 # This range returns all users whose `UserName` begins with any
6331 # character from A to C:
6332 #
6333 # &quot;start_closed&quot;: [&quot;A&quot;]
6334 # &quot;end_open&quot;: [&quot;D&quot;]
6335 #
6336 # This range returns all users whose `UserName` begins with B:
6337 #
6338 # &quot;start_closed&quot;: [&quot;B&quot;]
6339 # &quot;end_open&quot;: [&quot;C&quot;]
6340 #
6341 # Key ranges honor column sort order. For example, suppose a table is
6342 # defined as follows:
6343 #
6344 # CREATE TABLE DescendingSortedTable {
6345 # Key INT64,
6346 # ...
6347 # ) PRIMARY KEY(Key DESC);
6348 #
6349 # The following range retrieves all rows with key values between 1
6350 # and 100 inclusive:
6351 #
6352 # &quot;start_closed&quot;: [&quot;100&quot;]
6353 # &quot;end_closed&quot;: [&quot;1&quot;]
6354 #
6355 # Note that 100 is passed as the start, and 1 is passed as the end,
6356 # because `Key` is a descending column in the schema.
6357 &quot;endOpen&quot;: [ # If the end is open, then the range excludes rows whose first
6358 # `len(end_open)` key columns exactly match `end_open`.
6359 &quot;&quot;,
6360 ],
6361 &quot;endClosed&quot;: [ # If the end is closed, then the range includes all rows whose
6362 # first `len(end_closed)` key columns exactly match `end_closed`.
6363 &quot;&quot;,
6364 ],
6365 &quot;startOpen&quot;: [ # If the start is open, then the range excludes rows whose first
6366 # `len(start_open)` key columns exactly match `start_open`.
6367 &quot;&quot;,
6368 ],
6369 &quot;startClosed&quot;: [ # If the start is closed, then the range includes all rows whose
6370 # first `len(start_closed)` key columns exactly match `start_closed`.
6371 &quot;&quot;,
6372 ],
6373 },
6374 ],
6375 &quot;all&quot;: True or False, # For convenience `all` can be set to `true` to indicate that this
6376 # `KeySet` matches all keys in the table or index. Note that any keys
6377 # specified in `keys` or `ranges` are only yielded once.
6378 &quot;keys&quot;: [ # A list of specific keys. Entries in `keys` should have exactly as
6379 # many elements as there are columns in the primary or index key
6380 # with which this `KeySet` is used. Individual key values are
6381 # encoded as described here.
6382 [
6383 &quot;&quot;,
6384 ],
6385 ],
6386 },
6387 &quot;columns&quot;: [ # Required. The columns of table to be returned for each row matching
6388 # this request.
6389 &quot;A String&quot;,
6390 ],
6391 &quot;transaction&quot;: { # This message is used to select the transaction in which a # The transaction to use. If none is provided, the default is a
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6392 # temporary read-only transaction with strong concurrency.
6393 # Read or
6394 # ExecuteSql call runs.
6395 #
6396 # See TransactionOptions for more information about transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6397 &quot;singleUse&quot;: { # # Transactions # Execute the read or SQL query in a temporary transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6398 # This is the most efficient way to execute a transaction that
6399 # consists of a single SQL query.
6400 #
6401 #
6402 # Each session can have at most one active transaction at a time. After the
6403 # active transaction is completed, the session can immediately be
6404 # re-used for the next transaction. It is not necessary to create a
6405 # new session for each transaction.
6406 #
6407 # # Transaction Modes
6408 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6409 # Cloud Spanner supports three transaction modes:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6410 #
6411 # 1. Locking read-write. This type of transaction is the only way
6412 # to write data into Cloud Spanner. These transactions rely on
6413 # pessimistic locking and, if necessary, two-phase commit.
6414 # Locking read-write transactions may abort, requiring the
6415 # application to retry.
6416 #
6417 # 2. Snapshot read-only. This transaction type provides guaranteed
6418 # consistency across several reads, but does not allow
6419 # writes. Snapshot read-only transactions can be configured to
6420 # read at timestamps in the past. Snapshot read-only
6421 # transactions do not need to be committed.
6422 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6423 # 3. Partitioned DML. This type of transaction is used to execute
6424 # a single Partitioned DML statement. Partitioned DML partitions
6425 # the key space and runs the DML statement over each partition
6426 # in parallel using separate, internal transactions that commit
6427 # independently. Partitioned DML transactions do not need to be
6428 # committed.
6429 #
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6430 # For transactions that only read, snapshot read-only transactions
6431 # provide simpler semantics and are almost always faster. In
6432 # particular, read-only transactions do not take locks, so they do
6433 # not conflict with read-write transactions. As a consequence of not
6434 # taking locks, they also do not abort, so retry loops are not needed.
6435 #
6436 # Transactions may only read/write data in a single database. They
6437 # may, however, read/write data in different tables within that
6438 # database.
6439 #
6440 # ## Locking Read-Write Transactions
6441 #
6442 # Locking transactions may be used to atomically read-modify-write
6443 # data anywhere in a database. This type of transaction is externally
6444 # consistent.
6445 #
6446 # Clients should attempt to minimize the amount of time a transaction
6447 # is active. Faster transactions commit with higher probability
6448 # and cause less contention. Cloud Spanner attempts to keep read locks
6449 # active as long as the transaction continues to do reads, and the
6450 # transaction has not been terminated by
6451 # Commit or
6452 # Rollback. Long periods of
6453 # inactivity at the client may cause Cloud Spanner to release a
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6454 # transaction&#x27;s locks and abort it.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6455 #
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6456 # Conceptually, a read-write transaction consists of zero or more
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6457 # reads or SQL statements followed by
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6458 # Commit. At any time before
6459 # Commit, the client can send a
6460 # Rollback request to abort the
6461 # transaction.
6462 #
6463 # ### Semantics
6464 #
6465 # Cloud Spanner can commit the transaction if all read locks it acquired
6466 # are still valid at commit time, and it is able to acquire write
6467 # locks for all writes. Cloud Spanner can abort the transaction for any
6468 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
6469 # that the transaction has not modified any user data in Cloud Spanner.
6470 #
6471 # Unless the transaction commits, Cloud Spanner makes no guarantees about
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6472 # how long the transaction&#x27;s locks were held for. It is an error to
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6473 # use Cloud Spanner locks for any sort of mutual exclusion other than
6474 # between Cloud Spanner transactions themselves.
6475 #
6476 # ### Retrying Aborted Transactions
6477 #
6478 # When a transaction aborts, the application can choose to retry the
6479 # whole transaction again. To maximize the chances of successfully
6480 # committing the retry, the client should execute the retry in the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6481 # same session as the original attempt. The original session&#x27;s lock
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6482 # priority increases with each consecutive abort, meaning that each
6483 # attempt has a slightly better chance of success than the previous.
6484 #
6485 # Under some circumstances (e.g., many transactions attempting to
6486 # modify the same row(s)), a transaction can abort many times in a
6487 # short period before successfully committing. Thus, it is not a good
6488 # idea to cap the number of retries a transaction can attempt;
6489 # instead, it is better to limit the total amount of wall time spent
6490 # retrying.
6491 #
6492 # ### Idle Transactions
6493 #
6494 # A transaction is considered idle if it has no outstanding reads or
6495 # SQL queries and has not started a read or SQL query within the last 10
6496 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6497 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6498 # fail with error `ABORTED`.
6499 #
6500 # If this behavior is undesirable, periodically executing a simple
6501 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
6502 # transaction from becoming idle.
6503 #
6504 # ## Snapshot Read-Only Transactions
6505 #
6506 # Snapshot read-only transactions provides a simpler method than
6507 # locking read-write transactions for doing several consistent
6508 # reads. However, this type of transaction does not support writes.
6509 #
6510 # Snapshot transactions do not take locks. Instead, they work by
6511 # choosing a Cloud Spanner timestamp, then executing all reads at that
6512 # timestamp. Since they do not acquire locks, they do not block
6513 # concurrent read-write transactions.
6514 #
6515 # Unlike locking read-write transactions, snapshot read-only
6516 # transactions never abort. They can fail if the chosen read
6517 # timestamp is garbage collected; however, the default garbage
6518 # collection policy is generous enough that most applications do not
6519 # need to worry about this in practice.
6520 #
6521 # Snapshot read-only transactions do not need to call
6522 # Commit or
6523 # Rollback (and in fact are not
6524 # permitted to do so).
6525 #
6526 # To execute a snapshot transaction, the client specifies a timestamp
6527 # bound, which tells Cloud Spanner how to choose a read timestamp.
6528 #
6529 # The types of timestamp bound are:
6530 #
6531 # - Strong (the default).
6532 # - Bounded staleness.
6533 # - Exact staleness.
6534 #
6535 # If the Cloud Spanner database to be read is geographically distributed,
6536 # stale read-only transactions can execute more quickly than strong
6537 # or read-write transaction, because they are able to execute far
6538 # from the leader replica.
6539 #
6540 # Each type of timestamp bound is discussed in detail below.
6541 #
6542 # ### Strong
6543 #
6544 # Strong reads are guaranteed to see the effects of all transactions
6545 # that have committed before the start of the read. Furthermore, all
6546 # rows yielded by a single read are consistent with each other -- if
6547 # any part of the read observes a transaction, all parts of the read
6548 # see the transaction.
6549 #
6550 # Strong reads are not repeatable: two consecutive strong read-only
6551 # transactions might return inconsistent results if there are
6552 # concurrent writes. If consistency across reads is required, the
6553 # reads should be executed within a transaction or at an exact read
6554 # timestamp.
6555 #
6556 # See TransactionOptions.ReadOnly.strong.
6557 #
6558 # ### Exact Staleness
6559 #
6560 # These timestamp bounds execute reads at a user-specified
6561 # timestamp. Reads at a timestamp are guaranteed to see a consistent
6562 # prefix of the global transaction history: they observe
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]6563 # modifications done by all transactions with a commit timestamp &lt;=
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6564 # the read timestamp, and observe none of the modifications done by
6565 # transactions with a larger commit timestamp. They will block until
6566 # all conflicting transactions that may be assigned commit timestamps
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]6567 # &lt;= the read timestamp have finished.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6568 #
6569 # The timestamp can either be expressed as an absolute Cloud Spanner commit
6570 # timestamp or a staleness relative to the current time.
6571 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6572 # These modes do not require a &quot;negotiation phase&quot; to pick a
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6573 # timestamp. As a result, they execute slightly faster than the
6574 # equivalent boundedly stale concurrency modes. On the other hand,
6575 # boundedly stale reads usually return fresher results.
6576 #
6577 # See TransactionOptions.ReadOnly.read_timestamp and
6578 # TransactionOptions.ReadOnly.exact_staleness.
6579 #
6580 # ### Bounded Staleness
6581 #
6582 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
6583 # subject to a user-provided staleness bound. Cloud Spanner chooses the
6584 # newest timestamp within the staleness bound that allows execution
6585 # of the reads at the closest available replica without blocking.
6586 #
6587 # All rows yielded are consistent with each other -- if any part of
6588 # the read observes a transaction, all parts of the read see the
6589 # transaction. Boundedly stale reads are not repeatable: two stale
6590 # reads, even if they use the same staleness bound, can execute at
6591 # different timestamps and thus return inconsistent results.
6592 #
6593 # Boundedly stale reads execute in two phases: the first phase
6594 # negotiates a timestamp among all replicas needed to serve the
6595 # read. In the second phase, reads are executed at the negotiated
6596 # timestamp.
6597 #
6598 # As a result of the two phase execution, bounded staleness reads are
6599 # usually a little slower than comparable exact staleness
6600 # reads. However, they are typically able to return fresher
6601 # results, and are more likely to execute at the closest replica.
6602 #
6603 # Because the timestamp negotiation requires up-front knowledge of
6604 # which rows will be read, it can only be used with single-use
6605 # read-only transactions.
6606 #
6607 # See TransactionOptions.ReadOnly.max_staleness and
6608 # TransactionOptions.ReadOnly.min_read_timestamp.
6609 #
6610 # ### Old Read Timestamps and Garbage Collection
6611 #
6612 # Cloud Spanner continuously garbage collects deleted and overwritten data
6613 # in the background to reclaim storage space. This process is known
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6614 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6615 # are one hour old. Because of this, Cloud Spanner cannot perform reads
6616 # at read timestamps more than one hour in the past. This
6617 # restriction also applies to in-progress reads and/or SQL queries whose
6618 # timestamp become too old while executing. Reads and SQL queries with
6619 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6620 #
6621 # ## Partitioned DML Transactions
6622 #
6623 # Partitioned DML transactions are used to execute DML statements with a
6624 # different execution strategy that provides different, and often better,
6625 # scalability properties for large, table-wide operations than DML in a
6626 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
6627 # should prefer using ReadWrite transactions.
6628 #
6629 # Partitioned DML partitions the keyspace and runs the DML statement on each
6630 # partition in separate, internal transactions. These transactions commit
6631 # automatically when complete, and run independently from one another.
6632 #
6633 # To reduce lock contention, this execution strategy only acquires read locks
6634 # on rows that match the WHERE clause of the statement. Additionally, the
6635 # smaller per-partition transactions hold locks for less time.
6636 #
6637 # That said, Partitioned DML is not a drop-in replacement for standard DML used
6638 # in ReadWrite transactions.
6639 #
6640 # - The DML statement must be fully-partitionable. Specifically, the statement
6641 # must be expressible as the union of many statements which each access only
6642 # a single row of the table.
6643 #
6644 # - The statement is not applied atomically to all rows of the table. Rather,
6645 # the statement is applied atomically to partitions of the table, in
6646 # independent transactions. Secondary index rows are updated atomically
6647 # with the base table rows.
6648 #
6649 # - Partitioned DML does not guarantee exactly-once execution semantics
6650 # against a partition. The statement will be applied at least once to each
6651 # partition. It is strongly recommended that the DML statement should be
6652 # idempotent to avoid unexpected results. For instance, it is potentially
6653 # dangerous to run a statement such as
6654 # `UPDATE table SET column = column + 1` as it could be run multiple times
6655 # against some rows.
6656 #
6657 # - The partitions are committed automatically - there is no support for
6658 # Commit or Rollback. If the call returns an error, or if the client issuing
6659 # the ExecuteSql call dies, it is possible that some rows had the statement
6660 # executed on them successfully. It is also possible that statement was
6661 # never executed against other rows.
6662 #
6663 # - Partitioned DML transactions may only contain the execution of a single
6664 # DML statement via ExecuteSql or ExecuteStreamingSql.
6665 #
6666 # - If any error is encountered during the execution of the partitioned DML
6667 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
6668 # value that cannot be stored due to schema constraints), then the
6669 # operation is stopped at that point and an error is returned. It is
6670 # possible that at this point, some partitions have been committed (or even
6671 # committed multiple times), and other partitions have not been run at all.
6672 #
6673 # Given the above, Partitioned DML is good fit for large, database-wide,
6674 # operations that are idempotent, such as deleting old rows from a very large
6675 # table.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6676 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6677 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6678 # Authorization to begin a Partitioned DML transaction requires
6679 # `spanner.databases.beginPartitionedDmlTransaction` permission
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6680 # on the `session` resource.
6681 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6682 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6683 #
6684 # Authorization to begin a read-only transaction requires
6685 # `spanner.databases.beginReadOnlyTransaction` permission
6686 # on the `session` resource.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6687 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6688 #
6689 # This is useful for requesting fresher data than some previous
6690 # read, or data that is fresh enough to observe the effects of some
6691 # previously committed transaction whose timestamp is known.
6692 #
6693 # Note that this option can only be used in single-use transactions.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]6694 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6695 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
6696 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
6697 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]6698 # reads at a specific timestamp are repeatable; the same read at
6699 # the same timestamp always returns the same data. If the
6700 # timestamp is in the future, the read will block until the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6701 # specified timestamp, modulo the read&#x27;s deadline.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]6702 #
6703 # Useful for large scale consistent reads such as mapreduces, or
6704 # for coordinating many reads against a consistent snapshot of the
6705 # data.
6706 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6707 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
6708 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
6709 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6710 # seconds. Guarantees that all writes that have committed more
6711 # than the specified number of seconds ago are visible. Because
6712 # Cloud Spanner chooses the exact timestamp, this mode works even if
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6713 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6714 # commit timestamps.
6715 #
6716 # Useful for reading the freshest data available at a nearby
6717 # replica, while bounding the possible staleness if the local
6718 # replica has fallen behind.
6719 #
6720 # Note that this option can only be used in single-use
6721 # transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6722 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
6723 # the Transaction message that describes the transaction.
6724 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6725 # old. The timestamp is chosen soon after the read is started.
6726 #
6727 # Guarantees that all writes that have committed more than the
6728 # specified number of seconds ago are visible. Because Cloud Spanner
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6729 # chooses the exact timestamp, this mode works even if the client&#x27;s
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6730 # local clock is substantially skewed from Cloud Spanner commit
6731 # timestamps.
6732 #
6733 # Useful for reading at nearby replicas without the distributed
6734 # timestamp negotiation overhead of `max_staleness`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6735 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]6736 # are visible.
6737 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]6738 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
6739 #
6740 # Authorization to begin a read-write transaction requires
6741 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
6742 # on the `session` resource.
6743 # transaction type has no options.
6744 },
6745 },
6746 &quot;begin&quot;: { # # Transactions # Begin a new transaction and execute this read or SQL query in
6747 # it. The transaction ID of the new transaction is returned in
6748 # ResultSetMetadata.transaction, which is a Transaction.
6749 #
6750 #
6751 # Each session can have at most one active transaction at a time. After the
6752 # active transaction is completed, the session can immediately be
6753 # re-used for the next transaction. It is not necessary to create a
6754 # new session for each transaction.
6755 #
6756 # # Transaction Modes
6757 #
6758 # Cloud Spanner supports three transaction modes:
6759 #
6760 # 1. Locking read-write. This type of transaction is the only way
6761 # to write data into Cloud Spanner. These transactions rely on
6762 # pessimistic locking and, if necessary, two-phase commit.
6763 # Locking read-write transactions may abort, requiring the
6764 # application to retry.
6765 #
6766 # 2. Snapshot read-only. This transaction type provides guaranteed
6767 # consistency across several reads, but does not allow
6768 # writes. Snapshot read-only transactions can be configured to
6769 # read at timestamps in the past. Snapshot read-only
6770 # transactions do not need to be committed.
6771 #
6772 # 3. Partitioned DML. This type of transaction is used to execute
6773 # a single Partitioned DML statement. Partitioned DML partitions
6774 # the key space and runs the DML statement over each partition
6775 # in parallel using separate, internal transactions that commit
6776 # independently. Partitioned DML transactions do not need to be
6777 # committed.
6778 #
6779 # For transactions that only read, snapshot read-only transactions
6780 # provide simpler semantics and are almost always faster. In
6781 # particular, read-only transactions do not take locks, so they do
6782 # not conflict with read-write transactions. As a consequence of not
6783 # taking locks, they also do not abort, so retry loops are not needed.
6784 #
6785 # Transactions may only read/write data in a single database. They
6786 # may, however, read/write data in different tables within that
6787 # database.
6788 #
6789 # ## Locking Read-Write Transactions
6790 #
6791 # Locking transactions may be used to atomically read-modify-write
6792 # data anywhere in a database. This type of transaction is externally
6793 # consistent.
6794 #
6795 # Clients should attempt to minimize the amount of time a transaction
6796 # is active. Faster transactions commit with higher probability
6797 # and cause less contention. Cloud Spanner attempts to keep read locks
6798 # active as long as the transaction continues to do reads, and the
6799 # transaction has not been terminated by
6800 # Commit or
6801 # Rollback. Long periods of
6802 # inactivity at the client may cause Cloud Spanner to release a
6803 # transaction&#x27;s locks and abort it.
6804 #
6805 # Conceptually, a read-write transaction consists of zero or more
6806 # reads or SQL statements followed by
6807 # Commit. At any time before
6808 # Commit, the client can send a
6809 # Rollback request to abort the
6810 # transaction.
6811 #
6812 # ### Semantics
6813 #
6814 # Cloud Spanner can commit the transaction if all read locks it acquired
6815 # are still valid at commit time, and it is able to acquire write
6816 # locks for all writes. Cloud Spanner can abort the transaction for any
6817 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
6818 # that the transaction has not modified any user data in Cloud Spanner.
6819 #
6820 # Unless the transaction commits, Cloud Spanner makes no guarantees about
6821 # how long the transaction&#x27;s locks were held for. It is an error to
6822 # use Cloud Spanner locks for any sort of mutual exclusion other than
6823 # between Cloud Spanner transactions themselves.
6824 #
6825 # ### Retrying Aborted Transactions
6826 #
6827 # When a transaction aborts, the application can choose to retry the
6828 # whole transaction again. To maximize the chances of successfully
6829 # committing the retry, the client should execute the retry in the
6830 # same session as the original attempt. The original session&#x27;s lock
6831 # priority increases with each consecutive abort, meaning that each
6832 # attempt has a slightly better chance of success than the previous.
6833 #
6834 # Under some circumstances (e.g., many transactions attempting to
6835 # modify the same row(s)), a transaction can abort many times in a
6836 # short period before successfully committing. Thus, it is not a good
6837 # idea to cap the number of retries a transaction can attempt;
6838 # instead, it is better to limit the total amount of wall time spent
6839 # retrying.
6840 #
6841 # ### Idle Transactions
6842 #
6843 # A transaction is considered idle if it has no outstanding reads or
6844 # SQL queries and has not started a read or SQL query within the last 10
6845 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
6846 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
6847 # fail with error `ABORTED`.
6848 #
6849 # If this behavior is undesirable, periodically executing a simple
6850 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
6851 # transaction from becoming idle.
6852 #
6853 # ## Snapshot Read-Only Transactions
6854 #
6855 # Snapshot read-only transactions provides a simpler method than
6856 # locking read-write transactions for doing several consistent
6857 # reads. However, this type of transaction does not support writes.
6858 #
6859 # Snapshot transactions do not take locks. Instead, they work by
6860 # choosing a Cloud Spanner timestamp, then executing all reads at that
6861 # timestamp. Since they do not acquire locks, they do not block
6862 # concurrent read-write transactions.
6863 #
6864 # Unlike locking read-write transactions, snapshot read-only
6865 # transactions never abort. They can fail if the chosen read
6866 # timestamp is garbage collected; however, the default garbage
6867 # collection policy is generous enough that most applications do not
6868 # need to worry about this in practice.
6869 #
6870 # Snapshot read-only transactions do not need to call
6871 # Commit or
6872 # Rollback (and in fact are not
6873 # permitted to do so).
6874 #
6875 # To execute a snapshot transaction, the client specifies a timestamp
6876 # bound, which tells Cloud Spanner how to choose a read timestamp.
6877 #
6878 # The types of timestamp bound are:
6879 #
6880 # - Strong (the default).
6881 # - Bounded staleness.
6882 # - Exact staleness.
6883 #
6884 # If the Cloud Spanner database to be read is geographically distributed,
6885 # stale read-only transactions can execute more quickly than strong
6886 # or read-write transaction, because they are able to execute far
6887 # from the leader replica.
6888 #
6889 # Each type of timestamp bound is discussed in detail below.
6890 #
6891 # ### Strong
6892 #
6893 # Strong reads are guaranteed to see the effects of all transactions
6894 # that have committed before the start of the read. Furthermore, all
6895 # rows yielded by a single read are consistent with each other -- if
6896 # any part of the read observes a transaction, all parts of the read
6897 # see the transaction.
6898 #
6899 # Strong reads are not repeatable: two consecutive strong read-only
6900 # transactions might return inconsistent results if there are
6901 # concurrent writes. If consistency across reads is required, the
6902 # reads should be executed within a transaction or at an exact read
6903 # timestamp.
6904 #
6905 # See TransactionOptions.ReadOnly.strong.
6906 #
6907 # ### Exact Staleness
6908 #
6909 # These timestamp bounds execute reads at a user-specified
6910 # timestamp. Reads at a timestamp are guaranteed to see a consistent
6911 # prefix of the global transaction history: they observe
6912 # modifications done by all transactions with a commit timestamp &lt;=
6913 # the read timestamp, and observe none of the modifications done by
6914 # transactions with a larger commit timestamp. They will block until
6915 # all conflicting transactions that may be assigned commit timestamps
6916 # &lt;= the read timestamp have finished.
6917 #
6918 # The timestamp can either be expressed as an absolute Cloud Spanner commit
6919 # timestamp or a staleness relative to the current time.
6920 #
6921 # These modes do not require a &quot;negotiation phase&quot; to pick a
6922 # timestamp. As a result, they execute slightly faster than the
6923 # equivalent boundedly stale concurrency modes. On the other hand,
6924 # boundedly stale reads usually return fresher results.
6925 #
6926 # See TransactionOptions.ReadOnly.read_timestamp and
6927 # TransactionOptions.ReadOnly.exact_staleness.
6928 #
6929 # ### Bounded Staleness
6930 #
6931 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
6932 # subject to a user-provided staleness bound. Cloud Spanner chooses the
6933 # newest timestamp within the staleness bound that allows execution
6934 # of the reads at the closest available replica without blocking.
6935 #
6936 # All rows yielded are consistent with each other -- if any part of
6937 # the read observes a transaction, all parts of the read see the
6938 # transaction. Boundedly stale reads are not repeatable: two stale
6939 # reads, even if they use the same staleness bound, can execute at
6940 # different timestamps and thus return inconsistent results.
6941 #
6942 # Boundedly stale reads execute in two phases: the first phase
6943 # negotiates a timestamp among all replicas needed to serve the
6944 # read. In the second phase, reads are executed at the negotiated
6945 # timestamp.
6946 #
6947 # As a result of the two phase execution, bounded staleness reads are
6948 # usually a little slower than comparable exact staleness
6949 # reads. However, they are typically able to return fresher
6950 # results, and are more likely to execute at the closest replica.
6951 #
6952 # Because the timestamp negotiation requires up-front knowledge of
6953 # which rows will be read, it can only be used with single-use
6954 # read-only transactions.
6955 #
6956 # See TransactionOptions.ReadOnly.max_staleness and
6957 # TransactionOptions.ReadOnly.min_read_timestamp.
6958 #
6959 # ### Old Read Timestamps and Garbage Collection
6960 #
6961 # Cloud Spanner continuously garbage collects deleted and overwritten data
6962 # in the background to reclaim storage space. This process is known
6963 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
6964 # are one hour old. Because of this, Cloud Spanner cannot perform reads
6965 # at read timestamps more than one hour in the past. This
6966 # restriction also applies to in-progress reads and/or SQL queries whose
6967 # timestamp become too old while executing. Reads and SQL queries with
6968 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
6969 #
6970 # ## Partitioned DML Transactions
6971 #
6972 # Partitioned DML transactions are used to execute DML statements with a
6973 # different execution strategy that provides different, and often better,
6974 # scalability properties for large, table-wide operations than DML in a
6975 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
6976 # should prefer using ReadWrite transactions.
6977 #
6978 # Partitioned DML partitions the keyspace and runs the DML statement on each
6979 # partition in separate, internal transactions. These transactions commit
6980 # automatically when complete, and run independently from one another.
6981 #
6982 # To reduce lock contention, this execution strategy only acquires read locks
6983 # on rows that match the WHERE clause of the statement. Additionally, the
6984 # smaller per-partition transactions hold locks for less time.
6985 #
6986 # That said, Partitioned DML is not a drop-in replacement for standard DML used
6987 # in ReadWrite transactions.
6988 #
6989 # - The DML statement must be fully-partitionable. Specifically, the statement
6990 # must be expressible as the union of many statements which each access only
6991 # a single row of the table.
6992 #
6993 # - The statement is not applied atomically to all rows of the table. Rather,
6994 # the statement is applied atomically to partitions of the table, in
6995 # independent transactions. Secondary index rows are updated atomically
6996 # with the base table rows.
6997 #
6998 # - Partitioned DML does not guarantee exactly-once execution semantics
6999 # against a partition. The statement will be applied at least once to each
7000 # partition. It is strongly recommended that the DML statement should be
7001 # idempotent to avoid unexpected results. For instance, it is potentially
7002 # dangerous to run a statement such as
7003 # `UPDATE table SET column = column + 1` as it could be run multiple times
7004 # against some rows.
7005 #
7006 # - The partitions are committed automatically - there is no support for
7007 # Commit or Rollback. If the call returns an error, or if the client issuing
7008 # the ExecuteSql call dies, it is possible that some rows had the statement
7009 # executed on them successfully. It is also possible that statement was
7010 # never executed against other rows.
7011 #
7012 # - Partitioned DML transactions may only contain the execution of a single
7013 # DML statement via ExecuteSql or ExecuteStreamingSql.
7014 #
7015 # - If any error is encountered during the execution of the partitioned DML
7016 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
7017 # value that cannot be stored due to schema constraints), then the
7018 # operation is stopped at that point and an error is returned. It is
7019 # possible that at this point, some partitions have been committed (or even
7020 # committed multiple times), and other partitions have not been run at all.
7021 #
7022 # Given the above, Partitioned DML is good fit for large, database-wide,
7023 # operations that are idempotent, such as deleting old rows from a very large
7024 # table.
7025 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]7026 #
7027 # Authorization to begin a Partitioned DML transaction requires
7028 # `spanner.databases.beginPartitionedDmlTransaction` permission
7029 # on the `session` resource.
7030 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7031 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
7032 #
7033 # Authorization to begin a read-only transaction requires
7034 # `spanner.databases.beginReadOnlyTransaction` permission
7035 # on the `session` resource.
7036 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
7037 #
7038 # This is useful for requesting fresher data than some previous
7039 # read, or data that is fresh enough to observe the effects of some
7040 # previously committed transaction whose timestamp is known.
7041 #
7042 # Note that this option can only be used in single-use transactions.
7043 #
7044 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
7045 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
7046 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
7047 # reads at a specific timestamp are repeatable; the same read at
7048 # the same timestamp always returns the same data. If the
7049 # timestamp is in the future, the read will block until the
7050 # specified timestamp, modulo the read&#x27;s deadline.
7051 #
7052 # Useful for large scale consistent reads such as mapreduces, or
7053 # for coordinating many reads against a consistent snapshot of the
7054 # data.
7055 #
7056 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
7057 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
7058 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
7059 # seconds. Guarantees that all writes that have committed more
7060 # than the specified number of seconds ago are visible. Because
7061 # Cloud Spanner chooses the exact timestamp, this mode works even if
7062 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
7063 # commit timestamps.
7064 #
7065 # Useful for reading the freshest data available at a nearby
7066 # replica, while bounding the possible staleness if the local
7067 # replica has fallen behind.
7068 #
7069 # Note that this option can only be used in single-use
7070 # transactions.
7071 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
7072 # the Transaction message that describes the transaction.
7073 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
7074 # old. The timestamp is chosen soon after the read is started.
7075 #
7076 # Guarantees that all writes that have committed more than the
7077 # specified number of seconds ago are visible. Because Cloud Spanner
7078 # chooses the exact timestamp, this mode works even if the client&#x27;s
7079 # local clock is substantially skewed from Cloud Spanner commit
7080 # timestamps.
7081 #
7082 # Useful for reading at nearby replicas without the distributed
7083 # timestamp negotiation overhead of `max_staleness`.
7084 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
7085 # are visible.
7086 },
7087 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
7088 #
7089 # Authorization to begin a read-write transaction requires
7090 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
7091 # on the `session` resource.
7092 # transaction type has no options.
7093 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7094 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7095 &quot;id&quot;: &quot;A String&quot;, # Execute the read or SQL query in a previously-started transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7096 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7097 &quot;resumeToken&quot;: &quot;A String&quot;, # If this request is resuming a previously interrupted read,
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7098 # `resume_token` should be copied from the last
7099 # PartialResultSet yielded before the interruption. Doing this
7100 # enables the new read to resume where the last read left off. The
7101 # rest of the request parameters must exactly match the request
7102 # that yielded this token.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7103 &quot;partitionToken&quot;: &quot;A String&quot;, # If present, results will be restricted to the specified partition
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]7104 # previously created using PartitionRead(). There must be an exact
7105 # match for the values of fields common to this message and the
7106 # PartitionReadRequest message used to create this partition_token.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7107 &quot;table&quot;: &quot;A String&quot;, # Required. The name of the table in the database to be read.
7108 &quot;limit&quot;: &quot;A String&quot;, # If greater than zero, only the first `limit` rows are yielded. If `limit`
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]7109 # is zero, the default is no limit. A limit cannot be specified if
7110 # `partition_token` is set.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7111 }
7112
7113 x__xgafv: string, V1 error format.
7114 Allowed values
7115 1 - v1 error format
7116 2 - v2 error format
7117
7118Returns:
7119 An object of the form:
7120
7121 { # Results from Read or
7122 # ExecuteSql.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7123 &quot;stats&quot;: { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the SQL statement that
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]7124 # produced this result set. These can be requested by setting
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7125 # ExecuteSqlRequest.query_mode.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]7126 # DML statements always produce stats containing the number of rows
7127 # modified, unless executed using the
7128 # ExecuteSqlRequest.QueryMode.PLAN ExecuteSqlRequest.query_mode.
7129 # Other fields may or may not be populated, based on the
7130 # ExecuteSqlRequest.query_mode.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7131 &quot;rowCountExact&quot;: &quot;A String&quot;, # Standard DML returns an exact count of rows that were modified.
7132 &quot;queryStats&quot;: { # Aggregated statistics from the execution of the query. Only present when
7133 # the query is profiled. For example, a query could return the statistics as
7134 # follows:
7135 #
7136 # {
7137 # &quot;rows_returned&quot;: &quot;3&quot;,
7138 # &quot;elapsed_time&quot;: &quot;1.22 secs&quot;,
7139 # &quot;cpu_time&quot;: &quot;1.19 secs&quot;
7140 # }
7141 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
7142 },
7143 &quot;rowCountLowerBound&quot;: &quot;A String&quot;, # Partitioned DML does not offer exactly-once semantics, so it
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]7144 # returns a lower bound of the rows modified.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7145 &quot;queryPlan&quot;: { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
7146 &quot;planNodes&quot;: [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
7147 # with the plan root. Each PlanNode&#x27;s `id` corresponds to its index in
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7148 # `plan_nodes`.
7149 { # Node information for nodes appearing in a QueryPlan.plan_nodes.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7150 &quot;metadata&quot;: { # Attributes relevant to the node contained in a group of key-value pairs.
7151 # For example, a Parameter Reference node could have the following
7152 # information in its metadata:
7153 #
7154 # {
7155 # &quot;parameter_reference&quot;: &quot;param1&quot;,
7156 # &quot;parameter_type&quot;: &quot;array&quot;
7157 # }
7158 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
7159 },
7160 &quot;executionStats&quot;: { # The execution statistics associated with the node, contained in a group of
7161 # key-value pairs. Only present if the plan was returned as a result of a
7162 # profile query. For example, number of executions, number of rows/time per
7163 # execution etc.
7164 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
7165 },
7166 &quot;shortRepresentation&quot;: { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
7167 # `SCALAR` PlanNode(s).
7168 &quot;description&quot;: &quot;A String&quot;, # A string representation of the expression subtree rooted at this node.
7169 &quot;subqueries&quot;: { # A mapping of (subquery variable name) -&gt; (subquery node id) for cases
7170 # where the `description` string of this node references a `SCALAR`
7171 # subquery contained in the expression subtree rooted at this node. The
7172 # referenced `SCALAR` subquery may not necessarily be a direct child of
7173 # this node.
7174 &quot;a_key&quot;: 42,
7175 },
7176 },
7177 &quot;index&quot;: 42, # The `PlanNode`&#x27;s index in node list.
7178 &quot;kind&quot;: &quot;A String&quot;, # Used to determine the type of node. May be needed for visualizing
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7179 # different kinds of nodes differently. For example, If the node is a
7180 # SCALAR node, it will have a condensed representation
7181 # which can be used to directly embed a description of the node in its
7182 # parent.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7183 &quot;displayName&quot;: &quot;A String&quot;, # The display name for the node.
7184 &quot;childLinks&quot;: [ # List of child node `index`es and their relationship to this parent.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7185 { # Metadata associated with a parent-child relationship appearing in a
7186 # PlanNode.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7187 &quot;variable&quot;: &quot;A String&quot;, # Only present if the child node is SCALAR and corresponds
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7188 # to an output variable of the parent node. The field carries the name of
7189 # the output variable.
7190 # For example, a `TableScan` operator that reads rows from a table will
7191 # have child links to the `SCALAR` nodes representing the output variables
7192 # created for each column that is read by the operator. The corresponding
7193 # `variable` fields will be set to the variable names assigned to the
7194 # columns.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7195 &quot;childIndex&quot;: 42, # The node to which the link points.
7196 &quot;type&quot;: &quot;A String&quot;, # The type of the link. For example, in Hash Joins this could be used to
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7197 # distinguish between the build child and the probe child, or in the case
7198 # of the child being an output variable, to represent the tag associated
7199 # with the output variable.
7200 },
7201 ],
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7202 },
7203 ],
7204 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7205 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7206 &quot;rows&quot;: [ # Each element in `rows` is a row whose format is defined by
7207 # metadata.row_type. The ith element
7208 # in each row matches the ith field in
7209 # metadata.row_type. Elements are
7210 # encoded based on type as described
7211 # here.
7212 [
7213 &quot;&quot;,
7214 ],
7215 ],
7216 &quot;metadata&quot;: { # Metadata about a ResultSet or PartialResultSet. # Metadata about the result set, such as row type information.
7217 &quot;rowType&quot;: { # `StructType` defines the fields of a STRUCT type. # Indicates the field names and types for the rows in the result
7218 # set. For example, a SQL query like `&quot;SELECT UserId, UserName FROM
7219 # Users&quot;` could return a `row_type` value like:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7220 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7221 # &quot;fields&quot;: [
7222 # { &quot;name&quot;: &quot;UserId&quot;, &quot;type&quot;: { &quot;code&quot;: &quot;INT64&quot; } },
7223 # { &quot;name&quot;: &quot;UserName&quot;, &quot;type&quot;: { &quot;code&quot;: &quot;STRING&quot; } },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7224 # ]
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7225 &quot;fields&quot;: [ # The list of fields that make up this struct. Order is
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7226 # significant, because values of this struct type are represented as
7227 # lists, where the order of field values matches the order of
7228 # fields in the StructType. In turn, the order of fields
7229 # matches the order of columns in a read request, or the order of
7230 # fields in the `SELECT` clause of a query.
7231 { # Message representing a single field of a struct.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7232 &quot;name&quot;: &quot;A String&quot;, # The name of the field. For reads, this is the column name. For
7233 # SQL queries, it is the column alias (e.g., `&quot;Word&quot;` in the
7234 # query `&quot;SELECT &#x27;hello&#x27; AS Word&quot;`), or the column name (e.g.,
7235 # `&quot;ColName&quot;` in the query `&quot;SELECT ColName FROM Table&quot;`). Some
7236 # columns might have an empty name (e.g., !&quot;SELECT
7237 # UPPER(ColName)&quot;`). Note that a query result can contain
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7238 # multiple fields with the same name.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7239 &quot;type&quot;: # Object with schema name: Type # The type of the field.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7240 },
7241 ],
7242 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7243 &quot;transaction&quot;: { # A transaction. # If the read or SQL query began a transaction as a side-effect, the
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7244 # information about the new transaction is yielded here.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7245 &quot;id&quot;: &quot;A String&quot;, # `id` may be used to identify the transaction in subsequent
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7246 # Read,
7247 # ExecuteSql,
7248 # Commit, or
7249 # Rollback calls.
7250 #
7251 # Single-use read-only transactions do not have IDs, because
7252 # single-use transactions do not support multiple requests.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7253 &quot;readTimestamp&quot;: &quot;A String&quot;, # For snapshot read-only transactions, the read timestamp chosen
7254 # for the transaction. Not returned by default: see
7255 # TransactionOptions.ReadOnly.return_read_timestamp.
7256 #
7257 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
7258 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7259 },
7260 },
7261 }</pre>
7262</div>
7263
7264<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]7265 <code class="details" id="rollback">rollback(session, body=None, x__xgafv=None)</code>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7266 <pre>Rolls back a transaction, releasing any locks it holds. It is a good
7267idea to call this for any transaction that includes one or more
7268Read or ExecuteSql requests and
7269ultimately decides not to commit.
7270
7271`Rollback` returns `OK` if it successfully aborts the transaction, the
7272transaction was already aborted, or the transaction is not
7273found. `Rollback` never returns `ABORTED`.
7274
7275Args:
7276 session: string, Required. The session in which the transaction to roll back is running. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]7277 body: object, The request body.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7278 The object takes the form of:
7279
7280{ # The request for Rollback.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7281 &quot;transactionId&quot;: &quot;A String&quot;, # Required. The transaction to roll back.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7282 }
7283
7284 x__xgafv: string, V1 error format.
7285 Allowed values
7286 1 - v1 error format
7287 2 - v2 error format
7288
7289Returns:
7290 An object of the form:
7291
7292 { # A generic empty message that you can re-use to avoid defining duplicated
7293 # empty messages in your APIs. A typical example is to use it as the request
7294 # or the response type of an API method. For instance:
7295 #
7296 # service Foo {
7297 # rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);
7298 # }
7299 #
7300 # The JSON representation for `Empty` is empty JSON object `{}`.
7301 }</pre>
7302</div>
7303
7304<div class="method">
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]7305 <code class="details" id="streamingRead">streamingRead(session, body=None, x__xgafv=None)</code>
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7306 <pre>Like Read, except returns the result set as a
7307stream. Unlike Read, there is no limit on the
7308size of the returned result set. However, no individual row in
7309the result set can exceed 100 MiB, and no column value can exceed
731010 MiB.
7311
7312Args:
7313 session: string, Required. The session in which the read should be performed. (required)
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]7314 body: object, The request body.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7315 The object takes the form of:
7316
7317{ # The request for Read and
7318 # StreamingRead.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7319 &quot;index&quot;: &quot;A String&quot;, # If non-empty, the name of an index on table. This index is
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7320 # used instead of the table primary key when interpreting key_set
7321 # and sorting result rows. See key_set for further information.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7322 &quot;keySet&quot;: { # `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
7323 # primary keys of the rows in table to be yielded, unless index
7324 # is present. If index is present, then key_set instead names
7325 # index keys in index.
7326 #
7327 # If the partition_token field is empty, rows are yielded
7328 # in table primary key order (if index is empty) or index key order
7329 # (if index is non-empty). If the partition_token field is not
7330 # empty, rows will be yielded in an unspecified order.
7331 #
7332 # It is not an error for the `key_set` to name rows that do not
7333 # exist in the database. Read yields nothing for nonexistent rows.
7334 # the keys are expected to be in the same table or index. The keys need
7335 # not be sorted in any particular way.
7336 #
7337 # If the same key is specified multiple times in the set (for example
7338 # if two ranges, two keys, or a key and a range overlap), Cloud Spanner
7339 # behaves as if the key were only specified once.
7340 &quot;ranges&quot;: [ # A list of key ranges. See KeyRange for more information about
7341 # key range specifications.
7342 { # KeyRange represents a range of rows in a table or index.
7343 #
7344 # A range has a start key and an end key. These keys can be open or
7345 # closed, indicating if the range includes rows with that key.
7346 #
7347 # Keys are represented by lists, where the ith value in the list
7348 # corresponds to the ith component of the table or index primary key.
7349 # Individual values are encoded as described
7350 # here.
7351 #
7352 # For example, consider the following table definition:
7353 #
7354 # CREATE TABLE UserEvents (
7355 # UserName STRING(MAX),
7356 # EventDate STRING(10)
7357 # ) PRIMARY KEY(UserName, EventDate);
7358 #
7359 # The following keys name rows in this table:
7360 #
7361 # &quot;Bob&quot;, &quot;2014-09-23&quot;
7362 #
7363 # Since the `UserEvents` table&#x27;s `PRIMARY KEY` clause names two
7364 # columns, each `UserEvents` key has two elements; the first is the
7365 # `UserName`, and the second is the `EventDate`.
7366 #
7367 # Key ranges with multiple components are interpreted
7368 # lexicographically by component using the table or index key&#x27;s declared
7369 # sort order. For example, the following range returns all events for
7370 # user `&quot;Bob&quot;` that occurred in the year 2015:
7371 #
7372 # &quot;start_closed&quot;: [&quot;Bob&quot;, &quot;2015-01-01&quot;]
7373 # &quot;end_closed&quot;: [&quot;Bob&quot;, &quot;2015-12-31&quot;]
7374 #
7375 # Start and end keys can omit trailing key components. This affects the
7376 # inclusion and exclusion of rows that exactly match the provided key
7377 # components: if the key is closed, then rows that exactly match the
7378 # provided components are included; if the key is open, then rows
7379 # that exactly match are not included.
7380 #
7381 # For example, the following range includes all events for `&quot;Bob&quot;` that
7382 # occurred during and after the year 2000:
7383 #
7384 # &quot;start_closed&quot;: [&quot;Bob&quot;, &quot;2000-01-01&quot;]
7385 # &quot;end_closed&quot;: [&quot;Bob&quot;]
7386 #
7387 # The next example retrieves all events for `&quot;Bob&quot;`:
7388 #
7389 # &quot;start_closed&quot;: [&quot;Bob&quot;]
7390 # &quot;end_closed&quot;: [&quot;Bob&quot;]
7391 #
7392 # To retrieve events before the year 2000:
7393 #
7394 # &quot;start_closed&quot;: [&quot;Bob&quot;]
7395 # &quot;end_open&quot;: [&quot;Bob&quot;, &quot;2000-01-01&quot;]
7396 #
7397 # The following range includes all rows in the table:
7398 #
7399 # &quot;start_closed&quot;: []
7400 # &quot;end_closed&quot;: []
7401 #
7402 # This range returns all users whose `UserName` begins with any
7403 # character from A to C:
7404 #
7405 # &quot;start_closed&quot;: [&quot;A&quot;]
7406 # &quot;end_open&quot;: [&quot;D&quot;]
7407 #
7408 # This range returns all users whose `UserName` begins with B:
7409 #
7410 # &quot;start_closed&quot;: [&quot;B&quot;]
7411 # &quot;end_open&quot;: [&quot;C&quot;]
7412 #
7413 # Key ranges honor column sort order. For example, suppose a table is
7414 # defined as follows:
7415 #
7416 # CREATE TABLE DescendingSortedTable {
7417 # Key INT64,
7418 # ...
7419 # ) PRIMARY KEY(Key DESC);
7420 #
7421 # The following range retrieves all rows with key values between 1
7422 # and 100 inclusive:
7423 #
7424 # &quot;start_closed&quot;: [&quot;100&quot;]
7425 # &quot;end_closed&quot;: [&quot;1&quot;]
7426 #
7427 # Note that 100 is passed as the start, and 1 is passed as the end,
7428 # because `Key` is a descending column in the schema.
7429 &quot;endOpen&quot;: [ # If the end is open, then the range excludes rows whose first
7430 # `len(end_open)` key columns exactly match `end_open`.
7431 &quot;&quot;,
7432 ],
7433 &quot;endClosed&quot;: [ # If the end is closed, then the range includes all rows whose
7434 # first `len(end_closed)` key columns exactly match `end_closed`.
7435 &quot;&quot;,
7436 ],
7437 &quot;startOpen&quot;: [ # If the start is open, then the range excludes rows whose first
7438 # `len(start_open)` key columns exactly match `start_open`.
7439 &quot;&quot;,
7440 ],
7441 &quot;startClosed&quot;: [ # If the start is closed, then the range includes all rows whose
7442 # first `len(start_closed)` key columns exactly match `start_closed`.
7443 &quot;&quot;,
7444 ],
7445 },
7446 ],
7447 &quot;all&quot;: True or False, # For convenience `all` can be set to `true` to indicate that this
7448 # `KeySet` matches all keys in the table or index. Note that any keys
7449 # specified in `keys` or `ranges` are only yielded once.
7450 &quot;keys&quot;: [ # A list of specific keys. Entries in `keys` should have exactly as
7451 # many elements as there are columns in the primary or index key
7452 # with which this `KeySet` is used. Individual key values are
7453 # encoded as described here.
7454 [
7455 &quot;&quot;,
7456 ],
7457 ],
7458 },
7459 &quot;columns&quot;: [ # Required. The columns of table to be returned for each row matching
7460 # this request.
7461 &quot;A String&quot;,
7462 ],
7463 &quot;transaction&quot;: { # This message is used to select the transaction in which a # The transaction to use. If none is provided, the default is a
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7464 # temporary read-only transaction with strong concurrency.
7465 # Read or
7466 # ExecuteSql call runs.
7467 #
7468 # See TransactionOptions for more information about transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7469 &quot;singleUse&quot;: { # # Transactions # Execute the read or SQL query in a temporary transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7470 # This is the most efficient way to execute a transaction that
7471 # consists of a single SQL query.
7472 #
7473 #
7474 # Each session can have at most one active transaction at a time. After the
7475 # active transaction is completed, the session can immediately be
7476 # re-used for the next transaction. It is not necessary to create a
7477 # new session for each transaction.
7478 #
7479 # # Transaction Modes
7480 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]7481 # Cloud Spanner supports three transaction modes:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7482 #
7483 # 1. Locking read-write. This type of transaction is the only way
7484 # to write data into Cloud Spanner. These transactions rely on
7485 # pessimistic locking and, if necessary, two-phase commit.
7486 # Locking read-write transactions may abort, requiring the
7487 # application to retry.
7488 #
7489 # 2. Snapshot read-only. This transaction type provides guaranteed
7490 # consistency across several reads, but does not allow
7491 # writes. Snapshot read-only transactions can be configured to
7492 # read at timestamps in the past. Snapshot read-only
7493 # transactions do not need to be committed.
7494 #
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]7495 # 3. Partitioned DML. This type of transaction is used to execute
7496 # a single Partitioned DML statement. Partitioned DML partitions
7497 # the key space and runs the DML statement over each partition
7498 # in parallel using separate, internal transactions that commit
7499 # independently. Partitioned DML transactions do not need to be
7500 # committed.
7501 #
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7502 # For transactions that only read, snapshot read-only transactions
7503 # provide simpler semantics and are almost always faster. In
7504 # particular, read-only transactions do not take locks, so they do
7505 # not conflict with read-write transactions. As a consequence of not
7506 # taking locks, they also do not abort, so retry loops are not needed.
7507 #
7508 # Transactions may only read/write data in a single database. They
7509 # may, however, read/write data in different tables within that
7510 # database.
7511 #
7512 # ## Locking Read-Write Transactions
7513 #
7514 # Locking transactions may be used to atomically read-modify-write
7515 # data anywhere in a database. This type of transaction is externally
7516 # consistent.
7517 #
7518 # Clients should attempt to minimize the amount of time a transaction
7519 # is active. Faster transactions commit with higher probability
7520 # and cause less contention. Cloud Spanner attempts to keep read locks
7521 # active as long as the transaction continues to do reads, and the
7522 # transaction has not been terminated by
7523 # Commit or
7524 # Rollback. Long periods of
7525 # inactivity at the client may cause Cloud Spanner to release a
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7526 # transaction&#x27;s locks and abort it.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7527 #
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7528 # Conceptually, a read-write transaction consists of zero or more
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]7529 # reads or SQL statements followed by
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7530 # Commit. At any time before
7531 # Commit, the client can send a
7532 # Rollback request to abort the
7533 # transaction.
7534 #
7535 # ### Semantics
7536 #
7537 # Cloud Spanner can commit the transaction if all read locks it acquired
7538 # are still valid at commit time, and it is able to acquire write
7539 # locks for all writes. Cloud Spanner can abort the transaction for any
7540 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
7541 # that the transaction has not modified any user data in Cloud Spanner.
7542 #
7543 # Unless the transaction commits, Cloud Spanner makes no guarantees about
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7544 # how long the transaction&#x27;s locks were held for. It is an error to
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7545 # use Cloud Spanner locks for any sort of mutual exclusion other than
7546 # between Cloud Spanner transactions themselves.
7547 #
7548 # ### Retrying Aborted Transactions
7549 #
7550 # When a transaction aborts, the application can choose to retry the
7551 # whole transaction again. To maximize the chances of successfully
7552 # committing the retry, the client should execute the retry in the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7553 # same session as the original attempt. The original session&#x27;s lock
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7554 # priority increases with each consecutive abort, meaning that each
7555 # attempt has a slightly better chance of success than the previous.
7556 #
7557 # Under some circumstances (e.g., many transactions attempting to
7558 # modify the same row(s)), a transaction can abort many times in a
7559 # short period before successfully committing. Thus, it is not a good
7560 # idea to cap the number of retries a transaction can attempt;
7561 # instead, it is better to limit the total amount of wall time spent
7562 # retrying.
7563 #
7564 # ### Idle Transactions
7565 #
7566 # A transaction is considered idle if it has no outstanding reads or
7567 # SQL queries and has not started a read or SQL query within the last 10
7568 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7569 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7570 # fail with error `ABORTED`.
7571 #
7572 # If this behavior is undesirable, periodically executing a simple
7573 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
7574 # transaction from becoming idle.
7575 #
7576 # ## Snapshot Read-Only Transactions
7577 #
7578 # Snapshot read-only transactions provides a simpler method than
7579 # locking read-write transactions for doing several consistent
7580 # reads. However, this type of transaction does not support writes.
7581 #
7582 # Snapshot transactions do not take locks. Instead, they work by
7583 # choosing a Cloud Spanner timestamp, then executing all reads at that
7584 # timestamp. Since they do not acquire locks, they do not block
7585 # concurrent read-write transactions.
7586 #
7587 # Unlike locking read-write transactions, snapshot read-only
7588 # transactions never abort. They can fail if the chosen read
7589 # timestamp is garbage collected; however, the default garbage
7590 # collection policy is generous enough that most applications do not
7591 # need to worry about this in practice.
7592 #
7593 # Snapshot read-only transactions do not need to call
7594 # Commit or
7595 # Rollback (and in fact are not
7596 # permitted to do so).
7597 #
7598 # To execute a snapshot transaction, the client specifies a timestamp
7599 # bound, which tells Cloud Spanner how to choose a read timestamp.
7600 #
7601 # The types of timestamp bound are:
7602 #
7603 # - Strong (the default).
7604 # - Bounded staleness.
7605 # - Exact staleness.
7606 #
7607 # If the Cloud Spanner database to be read is geographically distributed,
7608 # stale read-only transactions can execute more quickly than strong
7609 # or read-write transaction, because they are able to execute far
7610 # from the leader replica.
7611 #
7612 # Each type of timestamp bound is discussed in detail below.
7613 #
7614 # ### Strong
7615 #
7616 # Strong reads are guaranteed to see the effects of all transactions
7617 # that have committed before the start of the read. Furthermore, all
7618 # rows yielded by a single read are consistent with each other -- if
7619 # any part of the read observes a transaction, all parts of the read
7620 # see the transaction.
7621 #
7622 # Strong reads are not repeatable: two consecutive strong read-only
7623 # transactions might return inconsistent results if there are
7624 # concurrent writes. If consistency across reads is required, the
7625 # reads should be executed within a transaction or at an exact read
7626 # timestamp.
7627 #
7628 # See TransactionOptions.ReadOnly.strong.
7629 #
7630 # ### Exact Staleness
7631 #
7632 # These timestamp bounds execute reads at a user-specified
7633 # timestamp. Reads at a timestamp are guaranteed to see a consistent
7634 # prefix of the global transaction history: they observe
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]7635 # modifications done by all transactions with a commit timestamp &lt;=
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7636 # the read timestamp, and observe none of the modifications done by
7637 # transactions with a larger commit timestamp. They will block until
7638 # all conflicting transactions that may be assigned commit timestamps
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]7639 # &lt;= the read timestamp have finished.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7640 #
7641 # The timestamp can either be expressed as an absolute Cloud Spanner commit
7642 # timestamp or a staleness relative to the current time.
7643 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7644 # These modes do not require a &quot;negotiation phase&quot; to pick a
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7645 # timestamp. As a result, they execute slightly faster than the
7646 # equivalent boundedly stale concurrency modes. On the other hand,
7647 # boundedly stale reads usually return fresher results.
7648 #
7649 # See TransactionOptions.ReadOnly.read_timestamp and
7650 # TransactionOptions.ReadOnly.exact_staleness.
7651 #
7652 # ### Bounded Staleness
7653 #
7654 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
7655 # subject to a user-provided staleness bound. Cloud Spanner chooses the
7656 # newest timestamp within the staleness bound that allows execution
7657 # of the reads at the closest available replica without blocking.
7658 #
7659 # All rows yielded are consistent with each other -- if any part of
7660 # the read observes a transaction, all parts of the read see the
7661 # transaction. Boundedly stale reads are not repeatable: two stale
7662 # reads, even if they use the same staleness bound, can execute at
7663 # different timestamps and thus return inconsistent results.
7664 #
7665 # Boundedly stale reads execute in two phases: the first phase
7666 # negotiates a timestamp among all replicas needed to serve the
7667 # read. In the second phase, reads are executed at the negotiated
7668 # timestamp.
7669 #
7670 # As a result of the two phase execution, bounded staleness reads are
7671 # usually a little slower than comparable exact staleness
7672 # reads. However, they are typically able to return fresher
7673 # results, and are more likely to execute at the closest replica.
7674 #
7675 # Because the timestamp negotiation requires up-front knowledge of
7676 # which rows will be read, it can only be used with single-use
7677 # read-only transactions.
7678 #
7679 # See TransactionOptions.ReadOnly.max_staleness and
7680 # TransactionOptions.ReadOnly.min_read_timestamp.
7681 #
7682 # ### Old Read Timestamps and Garbage Collection
7683 #
7684 # Cloud Spanner continuously garbage collects deleted and overwritten data
7685 # in the background to reclaim storage space. This process is known
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7686 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7687 # are one hour old. Because of this, Cloud Spanner cannot perform reads
7688 # at read timestamps more than one hour in the past. This
7689 # restriction also applies to in-progress reads and/or SQL queries whose
7690 # timestamp become too old while executing. Reads and SQL queries with
7691 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]7692 #
7693 # ## Partitioned DML Transactions
7694 #
7695 # Partitioned DML transactions are used to execute DML statements with a
7696 # different execution strategy that provides different, and often better,
7697 # scalability properties for large, table-wide operations than DML in a
7698 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
7699 # should prefer using ReadWrite transactions.
7700 #
7701 # Partitioned DML partitions the keyspace and runs the DML statement on each
7702 # partition in separate, internal transactions. These transactions commit
7703 # automatically when complete, and run independently from one another.
7704 #
7705 # To reduce lock contention, this execution strategy only acquires read locks
7706 # on rows that match the WHERE clause of the statement. Additionally, the
7707 # smaller per-partition transactions hold locks for less time.
7708 #
7709 # That said, Partitioned DML is not a drop-in replacement for standard DML used
7710 # in ReadWrite transactions.
7711 #
7712 # - The DML statement must be fully-partitionable. Specifically, the statement
7713 # must be expressible as the union of many statements which each access only
7714 # a single row of the table.
7715 #
7716 # - The statement is not applied atomically to all rows of the table. Rather,
7717 # the statement is applied atomically to partitions of the table, in
7718 # independent transactions. Secondary index rows are updated atomically
7719 # with the base table rows.
7720 #
7721 # - Partitioned DML does not guarantee exactly-once execution semantics
7722 # against a partition. The statement will be applied at least once to each
7723 # partition. It is strongly recommended that the DML statement should be
7724 # idempotent to avoid unexpected results. For instance, it is potentially
7725 # dangerous to run a statement such as
7726 # `UPDATE table SET column = column + 1` as it could be run multiple times
7727 # against some rows.
7728 #
7729 # - The partitions are committed automatically - there is no support for
7730 # Commit or Rollback. If the call returns an error, or if the client issuing
7731 # the ExecuteSql call dies, it is possible that some rows had the statement
7732 # executed on them successfully. It is also possible that statement was
7733 # never executed against other rows.
7734 #
7735 # - Partitioned DML transactions may only contain the execution of a single
7736 # DML statement via ExecuteSql or ExecuteStreamingSql.
7737 #
7738 # - If any error is encountered during the execution of the partitioned DML
7739 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
7740 # value that cannot be stored due to schema constraints), then the
7741 # operation is stopped at that point and an error is returned. It is
7742 # possible that at this point, some partitions have been committed (or even
7743 # committed multiple times), and other partitions have not been run at all.
7744 #
7745 # Given the above, Partitioned DML is good fit for large, database-wide,
7746 # operations that are idempotent, such as deleting old rows from a very large
7747 # table.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7748 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7749 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7750 # Authorization to begin a Partitioned DML transaction requires
7751 # `spanner.databases.beginPartitionedDmlTransaction` permission
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7752 # on the `session` resource.
7753 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7754 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7755 #
7756 # Authorization to begin a read-only transaction requires
7757 # `spanner.databases.beginReadOnlyTransaction` permission
7758 # on the `session` resource.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7759 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7760 #
7761 # This is useful for requesting fresher data than some previous
7762 # read, or data that is fresh enough to observe the effects of some
7763 # previously committed transaction whose timestamp is known.
7764 #
7765 # Note that this option can only be used in single-use transactions.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]7766 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7767 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
7768 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
7769 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]7770 # reads at a specific timestamp are repeatable; the same read at
7771 # the same timestamp always returns the same data. If the
7772 # timestamp is in the future, the read will block until the
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7773 # specified timestamp, modulo the read&#x27;s deadline.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]7774 #
7775 # Useful for large scale consistent reads such as mapreduces, or
7776 # for coordinating many reads against a consistent snapshot of the
7777 # data.
7778 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7779 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
7780 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
7781 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7782 # seconds. Guarantees that all writes that have committed more
7783 # than the specified number of seconds ago are visible. Because
7784 # Cloud Spanner chooses the exact timestamp, this mode works even if
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7785 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7786 # commit timestamps.
7787 #
7788 # Useful for reading the freshest data available at a nearby
7789 # replica, while bounding the possible staleness if the local
7790 # replica has fallen behind.
7791 #
7792 # Note that this option can only be used in single-use
7793 # transactions.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7794 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
7795 # the Transaction message that describes the transaction.
7796 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7797 # old. The timestamp is chosen soon after the read is started.
7798 #
7799 # Guarantees that all writes that have committed more than the
7800 # specified number of seconds ago are visible. Because Cloud Spanner
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7801 # chooses the exact timestamp, this mode works even if the client&#x27;s
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7802 # local clock is substantially skewed from Cloud Spanner commit
7803 # timestamps.
7804 #
7805 # Useful for reading at nearby replicas without the distributed
7806 # timestamp negotiation overhead of `max_staleness`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7807 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]7808 # are visible.
7809 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]7810 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
7811 #
7812 # Authorization to begin a read-write transaction requires
7813 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
7814 # on the `session` resource.
7815 # transaction type has no options.
7816 },
7817 },
7818 &quot;begin&quot;: { # # Transactions # Begin a new transaction and execute this read or SQL query in
7819 # it. The transaction ID of the new transaction is returned in
7820 # ResultSetMetadata.transaction, which is a Transaction.
7821 #
7822 #
7823 # Each session can have at most one active transaction at a time. After the
7824 # active transaction is completed, the session can immediately be
7825 # re-used for the next transaction. It is not necessary to create a
7826 # new session for each transaction.
7827 #
7828 # # Transaction Modes
7829 #
7830 # Cloud Spanner supports three transaction modes:
7831 #
7832 # 1. Locking read-write. This type of transaction is the only way
7833 # to write data into Cloud Spanner. These transactions rely on
7834 # pessimistic locking and, if necessary, two-phase commit.
7835 # Locking read-write transactions may abort, requiring the
7836 # application to retry.
7837 #
7838 # 2. Snapshot read-only. This transaction type provides guaranteed
7839 # consistency across several reads, but does not allow
7840 # writes. Snapshot read-only transactions can be configured to
7841 # read at timestamps in the past. Snapshot read-only
7842 # transactions do not need to be committed.
7843 #
7844 # 3. Partitioned DML. This type of transaction is used to execute
7845 # a single Partitioned DML statement. Partitioned DML partitions
7846 # the key space and runs the DML statement over each partition
7847 # in parallel using separate, internal transactions that commit
7848 # independently. Partitioned DML transactions do not need to be
7849 # committed.
7850 #
7851 # For transactions that only read, snapshot read-only transactions
7852 # provide simpler semantics and are almost always faster. In
7853 # particular, read-only transactions do not take locks, so they do
7854 # not conflict with read-write transactions. As a consequence of not
7855 # taking locks, they also do not abort, so retry loops are not needed.
7856 #
7857 # Transactions may only read/write data in a single database. They
7858 # may, however, read/write data in different tables within that
7859 # database.
7860 #
7861 # ## Locking Read-Write Transactions
7862 #
7863 # Locking transactions may be used to atomically read-modify-write
7864 # data anywhere in a database. This type of transaction is externally
7865 # consistent.
7866 #
7867 # Clients should attempt to minimize the amount of time a transaction
7868 # is active. Faster transactions commit with higher probability
7869 # and cause less contention. Cloud Spanner attempts to keep read locks
7870 # active as long as the transaction continues to do reads, and the
7871 # transaction has not been terminated by
7872 # Commit or
7873 # Rollback. Long periods of
7874 # inactivity at the client may cause Cloud Spanner to release a
7875 # transaction&#x27;s locks and abort it.
7876 #
7877 # Conceptually, a read-write transaction consists of zero or more
7878 # reads or SQL statements followed by
7879 # Commit. At any time before
7880 # Commit, the client can send a
7881 # Rollback request to abort the
7882 # transaction.
7883 #
7884 # ### Semantics
7885 #
7886 # Cloud Spanner can commit the transaction if all read locks it acquired
7887 # are still valid at commit time, and it is able to acquire write
7888 # locks for all writes. Cloud Spanner can abort the transaction for any
7889 # reason. If a commit attempt returns `ABORTED`, Cloud Spanner guarantees
7890 # that the transaction has not modified any user data in Cloud Spanner.
7891 #
7892 # Unless the transaction commits, Cloud Spanner makes no guarantees about
7893 # how long the transaction&#x27;s locks were held for. It is an error to
7894 # use Cloud Spanner locks for any sort of mutual exclusion other than
7895 # between Cloud Spanner transactions themselves.
7896 #
7897 # ### Retrying Aborted Transactions
7898 #
7899 # When a transaction aborts, the application can choose to retry the
7900 # whole transaction again. To maximize the chances of successfully
7901 # committing the retry, the client should execute the retry in the
7902 # same session as the original attempt. The original session&#x27;s lock
7903 # priority increases with each consecutive abort, meaning that each
7904 # attempt has a slightly better chance of success than the previous.
7905 #
7906 # Under some circumstances (e.g., many transactions attempting to
7907 # modify the same row(s)), a transaction can abort many times in a
7908 # short period before successfully committing. Thus, it is not a good
7909 # idea to cap the number of retries a transaction can attempt;
7910 # instead, it is better to limit the total amount of wall time spent
7911 # retrying.
7912 #
7913 # ### Idle Transactions
7914 #
7915 # A transaction is considered idle if it has no outstanding reads or
7916 # SQL queries and has not started a read or SQL query within the last 10
7917 # seconds. Idle transactions can be aborted by Cloud Spanner so that they
7918 # don&#x27;t hold on to locks indefinitely. In that case, the commit will
7919 # fail with error `ABORTED`.
7920 #
7921 # If this behavior is undesirable, periodically executing a simple
7922 # SQL query in the transaction (e.g., `SELECT 1`) prevents the
7923 # transaction from becoming idle.
7924 #
7925 # ## Snapshot Read-Only Transactions
7926 #
7927 # Snapshot read-only transactions provides a simpler method than
7928 # locking read-write transactions for doing several consistent
7929 # reads. However, this type of transaction does not support writes.
7930 #
7931 # Snapshot transactions do not take locks. Instead, they work by
7932 # choosing a Cloud Spanner timestamp, then executing all reads at that
7933 # timestamp. Since they do not acquire locks, they do not block
7934 # concurrent read-write transactions.
7935 #
7936 # Unlike locking read-write transactions, snapshot read-only
7937 # transactions never abort. They can fail if the chosen read
7938 # timestamp is garbage collected; however, the default garbage
7939 # collection policy is generous enough that most applications do not
7940 # need to worry about this in practice.
7941 #
7942 # Snapshot read-only transactions do not need to call
7943 # Commit or
7944 # Rollback (and in fact are not
7945 # permitted to do so).
7946 #
7947 # To execute a snapshot transaction, the client specifies a timestamp
7948 # bound, which tells Cloud Spanner how to choose a read timestamp.
7949 #
7950 # The types of timestamp bound are:
7951 #
7952 # - Strong (the default).
7953 # - Bounded staleness.
7954 # - Exact staleness.
7955 #
7956 # If the Cloud Spanner database to be read is geographically distributed,
7957 # stale read-only transactions can execute more quickly than strong
7958 # or read-write transaction, because they are able to execute far
7959 # from the leader replica.
7960 #
7961 # Each type of timestamp bound is discussed in detail below.
7962 #
7963 # ### Strong
7964 #
7965 # Strong reads are guaranteed to see the effects of all transactions
7966 # that have committed before the start of the read. Furthermore, all
7967 # rows yielded by a single read are consistent with each other -- if
7968 # any part of the read observes a transaction, all parts of the read
7969 # see the transaction.
7970 #
7971 # Strong reads are not repeatable: two consecutive strong read-only
7972 # transactions might return inconsistent results if there are
7973 # concurrent writes. If consistency across reads is required, the
7974 # reads should be executed within a transaction or at an exact read
7975 # timestamp.
7976 #
7977 # See TransactionOptions.ReadOnly.strong.
7978 #
7979 # ### Exact Staleness
7980 #
7981 # These timestamp bounds execute reads at a user-specified
7982 # timestamp. Reads at a timestamp are guaranteed to see a consistent
7983 # prefix of the global transaction history: they observe
7984 # modifications done by all transactions with a commit timestamp &lt;=
7985 # the read timestamp, and observe none of the modifications done by
7986 # transactions with a larger commit timestamp. They will block until
7987 # all conflicting transactions that may be assigned commit timestamps
7988 # &lt;= the read timestamp have finished.
7989 #
7990 # The timestamp can either be expressed as an absolute Cloud Spanner commit
7991 # timestamp or a staleness relative to the current time.
7992 #
7993 # These modes do not require a &quot;negotiation phase&quot; to pick a
7994 # timestamp. As a result, they execute slightly faster than the
7995 # equivalent boundedly stale concurrency modes. On the other hand,
7996 # boundedly stale reads usually return fresher results.
7997 #
7998 # See TransactionOptions.ReadOnly.read_timestamp and
7999 # TransactionOptions.ReadOnly.exact_staleness.
8000 #
8001 # ### Bounded Staleness
8002 #
8003 # Bounded staleness modes allow Cloud Spanner to pick the read timestamp,
8004 # subject to a user-provided staleness bound. Cloud Spanner chooses the
8005 # newest timestamp within the staleness bound that allows execution
8006 # of the reads at the closest available replica without blocking.
8007 #
8008 # All rows yielded are consistent with each other -- if any part of
8009 # the read observes a transaction, all parts of the read see the
8010 # transaction. Boundedly stale reads are not repeatable: two stale
8011 # reads, even if they use the same staleness bound, can execute at
8012 # different timestamps and thus return inconsistent results.
8013 #
8014 # Boundedly stale reads execute in two phases: the first phase
8015 # negotiates a timestamp among all replicas needed to serve the
8016 # read. In the second phase, reads are executed at the negotiated
8017 # timestamp.
8018 #
8019 # As a result of the two phase execution, bounded staleness reads are
8020 # usually a little slower than comparable exact staleness
8021 # reads. However, they are typically able to return fresher
8022 # results, and are more likely to execute at the closest replica.
8023 #
8024 # Because the timestamp negotiation requires up-front knowledge of
8025 # which rows will be read, it can only be used with single-use
8026 # read-only transactions.
8027 #
8028 # See TransactionOptions.ReadOnly.max_staleness and
8029 # TransactionOptions.ReadOnly.min_read_timestamp.
8030 #
8031 # ### Old Read Timestamps and Garbage Collection
8032 #
8033 # Cloud Spanner continuously garbage collects deleted and overwritten data
8034 # in the background to reclaim storage space. This process is known
8035 # as &quot;version GC&quot;. By default, version GC reclaims versions after they
8036 # are one hour old. Because of this, Cloud Spanner cannot perform reads
8037 # at read timestamps more than one hour in the past. This
8038 # restriction also applies to in-progress reads and/or SQL queries whose
8039 # timestamp become too old while executing. Reads and SQL queries with
8040 # too-old read timestamps fail with the error `FAILED_PRECONDITION`.
8041 #
8042 # ## Partitioned DML Transactions
8043 #
8044 # Partitioned DML transactions are used to execute DML statements with a
8045 # different execution strategy that provides different, and often better,
8046 # scalability properties for large, table-wide operations than DML in a
8047 # ReadWrite transaction. Smaller scoped statements, such as an OLTP workload,
8048 # should prefer using ReadWrite transactions.
8049 #
8050 # Partitioned DML partitions the keyspace and runs the DML statement on each
8051 # partition in separate, internal transactions. These transactions commit
8052 # automatically when complete, and run independently from one another.
8053 #
8054 # To reduce lock contention, this execution strategy only acquires read locks
8055 # on rows that match the WHERE clause of the statement. Additionally, the
8056 # smaller per-partition transactions hold locks for less time.
8057 #
8058 # That said, Partitioned DML is not a drop-in replacement for standard DML used
8059 # in ReadWrite transactions.
8060 #
8061 # - The DML statement must be fully-partitionable. Specifically, the statement
8062 # must be expressible as the union of many statements which each access only
8063 # a single row of the table.
8064 #
8065 # - The statement is not applied atomically to all rows of the table. Rather,
8066 # the statement is applied atomically to partitions of the table, in
8067 # independent transactions. Secondary index rows are updated atomically
8068 # with the base table rows.
8069 #
8070 # - Partitioned DML does not guarantee exactly-once execution semantics
8071 # against a partition. The statement will be applied at least once to each
8072 # partition. It is strongly recommended that the DML statement should be
8073 # idempotent to avoid unexpected results. For instance, it is potentially
8074 # dangerous to run a statement such as
8075 # `UPDATE table SET column = column + 1` as it could be run multiple times
8076 # against some rows.
8077 #
8078 # - The partitions are committed automatically - there is no support for
8079 # Commit or Rollback. If the call returns an error, or if the client issuing
8080 # the ExecuteSql call dies, it is possible that some rows had the statement
8081 # executed on them successfully. It is also possible that statement was
8082 # never executed against other rows.
8083 #
8084 # - Partitioned DML transactions may only contain the execution of a single
8085 # DML statement via ExecuteSql or ExecuteStreamingSql.
8086 #
8087 # - If any error is encountered during the execution of the partitioned DML
8088 # operation (for instance, a UNIQUE INDEX violation, division by zero, or a
8089 # value that cannot be stored due to schema constraints), then the
8090 # operation is stopped at that point and an error is returned. It is
8091 # possible that at this point, some partitions have been committed (or even
8092 # committed multiple times), and other partitions have not been run at all.
8093 #
8094 # Given the above, Partitioned DML is good fit for large, database-wide,
8095 # operations that are idempotent, such as deleting old rows from a very large
8096 # table.
8097 &quot;partitionedDml&quot;: { # Message type to initiate a Partitioned DML transaction. # Partitioned DML transaction.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]8098 #
8099 # Authorization to begin a Partitioned DML transaction requires
8100 # `spanner.databases.beginPartitionedDmlTransaction` permission
8101 # on the `session` resource.
8102 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8103 &quot;readOnly&quot;: { # Message type to initiate a read-only transaction. # Transaction will not write.
8104 #
8105 # Authorization to begin a read-only transaction requires
8106 # `spanner.databases.beginReadOnlyTransaction` permission
8107 # on the `session` resource.
8108 &quot;minReadTimestamp&quot;: &quot;A String&quot;, # Executes all reads at a timestamp &gt;= `min_read_timestamp`.
8109 #
8110 # This is useful for requesting fresher data than some previous
8111 # read, or data that is fresh enough to observe the effects of some
8112 # previously committed transaction whose timestamp is known.
8113 #
8114 # Note that this option can only be used in single-use transactions.
8115 #
8116 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
8117 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
8118 &quot;readTimestamp&quot;: &quot;A String&quot;, # Executes all reads at the given timestamp. Unlike other modes,
8119 # reads at a specific timestamp are repeatable; the same read at
8120 # the same timestamp always returns the same data. If the
8121 # timestamp is in the future, the read will block until the
8122 # specified timestamp, modulo the read&#x27;s deadline.
8123 #
8124 # Useful for large scale consistent reads such as mapreduces, or
8125 # for coordinating many reads against a consistent snapshot of the
8126 # data.
8127 #
8128 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
8129 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
8130 &quot;maxStaleness&quot;: &quot;A String&quot;, # Read data at a timestamp &gt;= `NOW - max_staleness`
8131 # seconds. Guarantees that all writes that have committed more
8132 # than the specified number of seconds ago are visible. Because
8133 # Cloud Spanner chooses the exact timestamp, this mode works even if
8134 # the client&#x27;s local clock is substantially skewed from Cloud Spanner
8135 # commit timestamps.
8136 #
8137 # Useful for reading the freshest data available at a nearby
8138 # replica, while bounding the possible staleness if the local
8139 # replica has fallen behind.
8140 #
8141 # Note that this option can only be used in single-use
8142 # transactions.
8143 &quot;returnReadTimestamp&quot;: True or False, # If true, the Cloud Spanner-selected read timestamp is included in
8144 # the Transaction message that describes the transaction.
8145 &quot;exactStaleness&quot;: &quot;A String&quot;, # Executes all reads at a timestamp that is `exact_staleness`
8146 # old. The timestamp is chosen soon after the read is started.
8147 #
8148 # Guarantees that all writes that have committed more than the
8149 # specified number of seconds ago are visible. Because Cloud Spanner
8150 # chooses the exact timestamp, this mode works even if the client&#x27;s
8151 # local clock is substantially skewed from Cloud Spanner commit
8152 # timestamps.
8153 #
8154 # Useful for reading at nearby replicas without the distributed
8155 # timestamp negotiation overhead of `max_staleness`.
8156 &quot;strong&quot;: True or False, # Read at a timestamp where all previously committed transactions
8157 # are visible.
8158 },
8159 &quot;readWrite&quot;: { # Message type to initiate a read-write transaction. Currently this # Transaction may write.
8160 #
8161 # Authorization to begin a read-write transaction requires
8162 # `spanner.databases.beginOrRollbackReadWriteTransaction` permission
8163 # on the `session` resource.
8164 # transaction type has no options.
8165 },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8166 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8167 &quot;id&quot;: &quot;A String&quot;, # Execute the read or SQL query in a previously-started transaction.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8168 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8169 &quot;resumeToken&quot;: &quot;A String&quot;, # If this request is resuming a previously interrupted read,
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8170 # `resume_token` should be copied from the last
8171 # PartialResultSet yielded before the interruption. Doing this
8172 # enables the new read to resume where the last read left off. The
8173 # rest of the request parameters must exactly match the request
8174 # that yielded this token.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8175 &quot;partitionToken&quot;: &quot;A String&quot;, # If present, results will be restricted to the specified partition
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]8176 # previously created using PartitionRead(). There must be an exact
8177 # match for the values of fields common to this message and the
8178 # PartitionReadRequest message used to create this partition_token.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8179 &quot;table&quot;: &quot;A String&quot;, # Required. The name of the table in the database to be read.
8180 &quot;limit&quot;: &quot;A String&quot;, # If greater than zero, only the first `limit` rows are yielded. If `limit`
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]8181 # is zero, the default is no limit. A limit cannot be specified if
8182 # `partition_token` is set.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8183 }
8184
8185 x__xgafv: string, V1 error format.
8186 Allowed values
8187 1 - v1 error format
8188 2 - v2 error format
8189
8190Returns:
8191 An object of the form:
8192
8193 { # Partial results from a streaming read or SQL query. Streaming reads and
8194 # SQL queries better tolerate large result sets, large rows, and large
8195 # values, but are a little trickier to consume.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8196 &quot;values&quot;: [ # A streamed result set consists of a stream of values, which might
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8197 # be split into many `PartialResultSet` messages to accommodate
8198 # large rows and/or large values. Every N complete values defines a
8199 # row, where N is equal to the number of entries in
8200 # metadata.row_type.fields.
8201 #
8202 # Most values are encoded based on type as described
8203 # here.
8204 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8205 # It is possible that the last value in values is &quot;chunked&quot;,
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8206 # meaning that the rest of the value is sent in subsequent
8207 # `PartialResultSet`(s). This is denoted by the chunked_value
8208 # field. Two or more chunked values can be merged to form a
8209 # complete value as follows:
8210 #
8211 # * `bool/number/null`: cannot be chunked
8212 # * `string`: concatenate the strings
8213 # * `list`: concatenate the lists. If the last element in a list is a
8214 # `string`, `list`, or `object`, merge it with the first element in
8215 # the next list by applying these rules recursively.
8216 # * `object`: concatenate the (field name, field value) pairs. If a
8217 # field name is duplicated, then apply these rules recursively
8218 # to merge the field values.
8219 #
8220 # Some examples of merging:
8221 #
8222 # # Strings are concatenated.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8223 # &quot;foo&quot;, &quot;bar&quot; =&gt; &quot;foobar&quot;
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8224 #
8225 # # Lists of non-strings are concatenated.
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]8226 # [2, 3], [4] =&gt; [2, 3, 4]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8227 #
8228 # # Lists are concatenated, but the last and first elements are merged
8229 # # because they are strings.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8230 # [&quot;a&quot;, &quot;b&quot;], [&quot;c&quot;, &quot;d&quot;] =&gt; [&quot;a&quot;, &quot;bc&quot;, &quot;d&quot;]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8231 #
8232 # # Lists are concatenated, but the last and first elements are merged
8233 # # because they are lists. Recursively, the last and first elements
8234 # # of the inner lists are merged because they are strings.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8235 # [&quot;a&quot;, [&quot;b&quot;, &quot;c&quot;]], [[&quot;d&quot;], &quot;e&quot;] =&gt; [&quot;a&quot;, [&quot;b&quot;, &quot;cd&quot;], &quot;e&quot;]
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8236 #
8237 # # Non-overlapping object fields are combined.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8238 # {&quot;a&quot;: &quot;1&quot;}, {&quot;b&quot;: &quot;2&quot;} =&gt; {&quot;a&quot;: &quot;1&quot;, &quot;b&quot;: 2&quot;}
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8239 #
8240 # # Overlapping object fields are merged.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8241 # {&quot;a&quot;: &quot;1&quot;}, {&quot;a&quot;: &quot;2&quot;} =&gt; {&quot;a&quot;: &quot;12&quot;}
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8242 #
8243 # # Examples of merging objects containing lists of strings.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8244 # {&quot;a&quot;: [&quot;1&quot;]}, {&quot;a&quot;: [&quot;2&quot;]} =&gt; {&quot;a&quot;: [&quot;12&quot;]}
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8245 #
8246 # For a more complete example, suppose a streaming SQL query is
8247 # yielding a result set whose rows contain a single string
8248 # field. The following `PartialResultSet`s might be yielded:
8249 #
8250 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8251 # &quot;metadata&quot;: { ... }
8252 # &quot;values&quot;: [&quot;Hello&quot;, &quot;W&quot;]
8253 # &quot;chunked_value&quot;: true
8254 # &quot;resume_token&quot;: &quot;Af65...&quot;
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8255 # }
8256 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8257 # &quot;values&quot;: [&quot;orl&quot;]
8258 # &quot;chunked_value&quot;: true
8259 # &quot;resume_token&quot;: &quot;Bqp2...&quot;
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8260 # }
8261 # {
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8262 # &quot;values&quot;: [&quot;d&quot;]
8263 # &quot;resume_token&quot;: &quot;Zx1B...&quot;
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8264 # }
8265 #
8266 # This sequence of `PartialResultSet`s encodes two rows, one
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8267 # containing the field value `&quot;Hello&quot;`, and a second containing the
8268 # field value `&quot;World&quot; = &quot;W&quot; + &quot;orl&quot; + &quot;d&quot;`.
8269 &quot;&quot;,
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8270 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8271 &quot;metadata&quot;: { # Metadata about a ResultSet or PartialResultSet. # Metadata about the result set, such as row type information.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8272 # Only present in the first response.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8273 &quot;rowType&quot;: { # `StructType` defines the fields of a STRUCT type. # Indicates the field names and types for the rows in the result
8274 # set. For example, a SQL query like `&quot;SELECT UserId, UserName FROM
8275 # Users&quot;` could return a `row_type` value like:
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8276 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8277 # &quot;fields&quot;: [
8278 # { &quot;name&quot;: &quot;UserId&quot;, &quot;type&quot;: { &quot;code&quot;: &quot;INT64&quot; } },
8279 # { &quot;name&quot;: &quot;UserName&quot;, &quot;type&quot;: { &quot;code&quot;: &quot;STRING&quot; } },
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8280 # ]
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8281 &quot;fields&quot;: [ # The list of fields that make up this struct. Order is
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8282 # significant, because values of this struct type are represented as
8283 # lists, where the order of field values matches the order of
8284 # fields in the StructType. In turn, the order of fields
8285 # matches the order of columns in a read request, or the order of
8286 # fields in the `SELECT` clause of a query.
8287 { # Message representing a single field of a struct.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8288 &quot;name&quot;: &quot;A String&quot;, # The name of the field. For reads, this is the column name. For
8289 # SQL queries, it is the column alias (e.g., `&quot;Word&quot;` in the
8290 # query `&quot;SELECT &#x27;hello&#x27; AS Word&quot;`), or the column name (e.g.,
8291 # `&quot;ColName&quot;` in the query `&quot;SELECT ColName FROM Table&quot;`). Some
8292 # columns might have an empty name (e.g., !&quot;SELECT
8293 # UPPER(ColName)&quot;`). Note that a query result can contain
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8294 # multiple fields with the same name.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8295 &quot;type&quot;: # Object with schema name: Type # The type of the field.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8296 },
8297 ],
8298 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8299 &quot;transaction&quot;: { # A transaction. # If the read or SQL query began a transaction as a side-effect, the
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8300 # information about the new transaction is yielded here.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8301 &quot;id&quot;: &quot;A String&quot;, # `id` may be used to identify the transaction in subsequent
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8302 # Read,
8303 # ExecuteSql,
8304 # Commit, or
8305 # Rollback calls.
8306 #
8307 # Single-use read-only transactions do not have IDs, because
8308 # single-use transactions do not support multiple requests.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8309 &quot;readTimestamp&quot;: &quot;A String&quot;, # For snapshot read-only transactions, the read timestamp chosen
8310 # for the transaction. Not returned by default: see
8311 # TransactionOptions.ReadOnly.return_read_timestamp.
8312 #
8313 # A timestamp in RFC3339 UTC \&quot;Zulu\&quot; format, accurate to nanoseconds.
8314 # Example: `&quot;2014-10-02T15:01:23.045123456Z&quot;`.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8315 },
8316 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]8317 &quot;resumeToken&quot;: &quot;A String&quot;, # Streaming calls might be interrupted for a variety of reasons, such
8318 # as TCP connection loss. If this occurs, the stream of results can
8319 # be resumed by re-sending the original request and including
8320 # `resume_token`. Note that executing any other transaction in the
8321 # same session invalidates the token.
8322 &quot;stats&quot;: { # Additional statistics about a ResultSet or PartialResultSet. # Query plan and execution statistics for the statement that produced this
8323 # streaming result set. These can be requested by setting
8324 # ExecuteSqlRequest.query_mode and are sent
8325 # only once with the last response in the stream.
8326 # This field will also be present in the last response for DML
8327 # statements.
8328 &quot;rowCountExact&quot;: &quot;A String&quot;, # Standard DML returns an exact count of rows that were modified.
8329 &quot;queryStats&quot;: { # Aggregated statistics from the execution of the query. Only present when
8330 # the query is profiled. For example, a query could return the statistics as
8331 # follows:
8332 #
8333 # {
8334 # &quot;rows_returned&quot;: &quot;3&quot;,
8335 # &quot;elapsed_time&quot;: &quot;1.22 secs&quot;,
8336 # &quot;cpu_time&quot;: &quot;1.19 secs&quot;
8337 # }
8338 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
8339 },
8340 &quot;rowCountLowerBound&quot;: &quot;A String&quot;, # Partitioned DML does not offer exactly-once semantics, so it
8341 # returns a lower bound of the rows modified.
8342 &quot;queryPlan&quot;: { # Contains an ordered list of nodes appearing in the query plan. # QueryPlan for the query associated with this result.
8343 &quot;planNodes&quot;: [ # The nodes in the query plan. Plan nodes are returned in pre-order starting
8344 # with the plan root. Each PlanNode&#x27;s `id` corresponds to its index in
8345 # `plan_nodes`.
8346 { # Node information for nodes appearing in a QueryPlan.plan_nodes.
8347 &quot;metadata&quot;: { # Attributes relevant to the node contained in a group of key-value pairs.
8348 # For example, a Parameter Reference node could have the following
8349 # information in its metadata:
8350 #
8351 # {
8352 # &quot;parameter_reference&quot;: &quot;param1&quot;,
8353 # &quot;parameter_type&quot;: &quot;array&quot;
8354 # }
8355 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
8356 },
8357 &quot;executionStats&quot;: { # The execution statistics associated with the node, contained in a group of
8358 # key-value pairs. Only present if the plan was returned as a result of a
8359 # profile query. For example, number of executions, number of rows/time per
8360 # execution etc.
8361 &quot;a_key&quot;: &quot;&quot;, # Properties of the object.
8362 },
8363 &quot;shortRepresentation&quot;: { # Condensed representation of a node and its subtree. Only present for # Condensed representation for SCALAR nodes.
8364 # `SCALAR` PlanNode(s).
8365 &quot;description&quot;: &quot;A String&quot;, # A string representation of the expression subtree rooted at this node.
8366 &quot;subqueries&quot;: { # A mapping of (subquery variable name) -&gt; (subquery node id) for cases
8367 # where the `description` string of this node references a `SCALAR`
8368 # subquery contained in the expression subtree rooted at this node. The
8369 # referenced `SCALAR` subquery may not necessarily be a direct child of
8370 # this node.
8371 &quot;a_key&quot;: 42,
8372 },
8373 },
8374 &quot;index&quot;: 42, # The `PlanNode`&#x27;s index in node list.
8375 &quot;kind&quot;: &quot;A String&quot;, # Used to determine the type of node. May be needed for visualizing
8376 # different kinds of nodes differently. For example, If the node is a
8377 # SCALAR node, it will have a condensed representation
8378 # which can be used to directly embed a description of the node in its
8379 # parent.
8380 &quot;displayName&quot;: &quot;A String&quot;, # The display name for the node.
8381 &quot;childLinks&quot;: [ # List of child node `index`es and their relationship to this parent.
8382 { # Metadata associated with a parent-child relationship appearing in a
8383 # PlanNode.
8384 &quot;variable&quot;: &quot;A String&quot;, # Only present if the child node is SCALAR and corresponds
8385 # to an output variable of the parent node. The field carries the name of
8386 # the output variable.
8387 # For example, a `TableScan` operator that reads rows from a table will
8388 # have child links to the `SCALAR` nodes representing the output variables
8389 # created for each column that is read by the operator. The corresponding
8390 # `variable` fields will be set to the variable names assigned to the
8391 # columns.
8392 &quot;childIndex&quot;: 42, # The node to which the link points.
8393 &quot;type&quot;: &quot;A String&quot;, # The type of the link. For example, in Hash Joins this could be used to
8394 # distinguish between the build child and the probe child, or in the case
8395 # of the child being an output variable, to represent the tag associated
8396 # with the output variable.
8397 },
8398 ],
8399 },
8400 ],
8401 },
8402 },
8403 &quot;chunkedValue&quot;: True or False, # If true, then the final value in values is chunked, and must
8404 # be combined with more values from subsequent `PartialResultSet`s
8405 # to obtain a complete field value.
Sai Cheemalapatic30d2b52017-03-13 12:12:03 -0400[diff] [blame]8406 }</pre>
8407</div>
8408
8409</body></html>