Skip to content

Commit 48e1c30

Browse files
authored
refactor(spanner): unify streaming read and query startup (#14776)
Streaming SQL queries and streaming key-value reads previously duplicated the same request setup and stream startup logic in two separate code paths. This change unifies both operations behind a single internal request abstraction so that option configuration, retry settings, and stream lifecycle handling are maintained in one place. As part of unifying stream startup, this also hardens how inlined BeginTransaction state is tracked across the stream lifecycle: - Records whether a request carries an inlined BeginTransaction on the request itself and passes it to the stream iterator at construction time rather than when the gRPC call is attached, keeping the state available across retry backoffs while ensuring it is cleared once the iterator is closed. - Ensures that if starting an inlined-begin stream fails before the stream can be consumed, the pending transaction ID future is failed immediately with a consistent exception so concurrent callers on the same transaction do not wait for a timeout.
1 parent 4edefc5 commit 48e1c30

12 files changed

Lines changed: 1814 additions & 261 deletions

‎java-spanner/google-cloud-spanner/src/main/java/com/google/cloud/spanner/AbstractReadContext.java‎

Lines changed: 106 additions & 177 deletions
Large diffs are not rendered by default.

‎java-spanner/google-cloud-spanner/src/main/java/com/google/cloud/spanner/GrpcStreamIterator.java‎

Lines changed: 27 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ public String toString() {
8686
private boolean callCleared;
8787
private boolean closed;
8888
@Nullable private String closeMessage;
89-
private volatile boolean withBeginTransaction;
89+
private final boolean withBeginTransaction;
9090
private final boolean lastStatement;
9191
@Nullable private volatile Timeout streamWaitTimeout;
9292
@Nullable private volatile SpannerException error;
@@ -97,7 +97,12 @@ public String toString() {
9797
@VisibleForTesting
9898
GrpcStreamIterator(
9999
boolean lastStatement, int prefetchChunks, boolean cancelQueryWhenClientIsClosed) {
100-
this(null, lastStatement, prefetchChunks, cancelQueryWhenClientIsClosed);
100+
this(
101+
/* statement= */ null,
102+
lastStatement,
103+
prefetchChunks,
104+
cancelQueryWhenClientIsClosed,
105+
/* withBeginTransaction= */ false);
101106
}
102107

103108
@VisibleForTesting
@@ -106,9 +111,24 @@ public String toString() {
106111
boolean lastStatement,
107112
int prefetchChunks,
108113
boolean cancelQueryWhenClientIsClosed) {
114+
this(
115+
statement,
116+
lastStatement,
117+
prefetchChunks,
118+
cancelQueryWhenClientIsClosed,
119+
/* withBeginTransaction= */ false);
120+
}
121+
122+
GrpcStreamIterator(
123+
Statement statement,
124+
boolean lastStatement,
125+
int prefetchChunks,
126+
boolean cancelQueryWhenClientIsClosed,
127+
boolean withBeginTransaction) {
109128
this.statement = statement;
110129
this.lastStatement = lastStatement;
111130
this.prefetchChunks = prefetchChunks;
131+
this.withBeginTransaction = withBeginTransaction;
112132
this.consumer = new ConsumerImpl(cancelQueryWhenClientIsClosed);
113133
// One extra to allow for END_OF_STREAM message.
114134
this.stream = new LinkedBlockingQueue<>(prefetchChunks + 1);
@@ -136,12 +156,11 @@ void registerListener(AsyncResultSet.StreamMessageListener streamMessageListener
136156
}
137157
}
138158

139-
public void setCall(SpannerRpc.StreamingCall call, boolean withBeginTransaction) {
159+
void setCall(SpannerRpc.StreamingCall call) {
140160
Timeout timeout = extractTimeout(call);
141161
boolean shouldCancel;
142162
String messageToCancel;
143163
synchronized (this) {
144-
this.withBeginTransaction = withBeginTransaction;
145164
shouldCancel = this.closed && !this.callCleared;
146165
if (!this.callCleared && !this.closed) {
147166
this.call = call;
@@ -246,10 +265,10 @@ public boolean isLastStatement() {
246265
*
247266
* <p>When an asynchronous {@link AsyncResultSet.StreamMessageListener} is registered, consumption
248267
* is gated until the underlying {@link SpannerRpc.StreamingCall} is initialized via {@link
249-
* #setCall(SpannerRpc.StreamingCall, boolean)} so that call context, cancellation hooks, and
250-
* listener notifications are properly established. In synchronous mode (where no listener is
251-
* registered, e.g. {@code streamMessageListener == null}), this gating is not needed because
252-
* callers invoke {@link #next()} directly on the iterator.
268+
* #setCall(SpannerRpc.StreamingCall)} so that call context, cancellation hooks, and listener
269+
* notifications are properly established. In synchronous mode (where no listener is registered,
270+
* e.g. {@code streamMessageListener == null}), this gating is not needed because callers invoke
271+
* {@link #next()} directly on the iterator.
253272
*/
254273
private boolean isReadyForConsumption() {
255274
return callInitialized || streamMessageListener == null;

‎java-spanner/google-cloud-spanner/src/main/java/com/google/cloud/spanner/MultiUseReadOnlyTransaction.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -483,7 +483,7 @@ public void onDone(boolean withBeginTransaction) {
483483
}
484484

485485
@Override
486-
void onStartFailed(boolean withBeginTransaction, Throwable throwable) {
486+
void onStartFailed(boolean withBeginTransaction, boolean lastStatement, Throwable throwable) {
487487
if (withBeginTransaction) {
488488
failTransactionIdFuture(throwable);
489489
}
Lines changed: 300 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,300 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package com.google.cloud.spanner;
18+
19+
import static com.google.common.base.Preconditions.checkNotNull;
20+
21+
import com.google.api.gax.retrying.RetrySettings;
22+
import com.google.api.gax.rpc.StatusCode.Code;
23+
import com.google.cloud.spanner.spi.v1.SpannerRpc;
24+
import com.google.protobuf.ByteString;
25+
import com.google.spanner.v1.DirectedReadOptions;
26+
import com.google.spanner.v1.ExecuteSqlRequest;
27+
import com.google.spanner.v1.ReadRequest;
28+
import com.google.spanner.v1.RequestOptions;
29+
import com.google.spanner.v1.TransactionSelector;
30+
import java.util.Map;
31+
import java.util.Set;
32+
import org.jspecify.annotations.NullMarked;
33+
import org.jspecify.annotations.Nullable;
34+
35+
/**
36+
* Package-private abstraction around either an {@link ExecuteSqlRequest.Builder} or a {@link
37+
* ReadRequest.Builder} to unify common request options, streaming request preparation, and
38+
* execution in {@link AbstractReadContext}.
39+
*/
40+
@NullMarked
41+
abstract class ReadOrQueryRequest {
42+
43+
static Query forQuery(
44+
AbstractReadContext context,
45+
ExecuteSqlRequest.Builder builder,
46+
Statement statement,
47+
Options options,
48+
@Nullable ByteString partitionToken) {
49+
return applyOptions(new Query(builder, statement), context, options, partitionToken);
50+
}
51+
52+
static Read forRead(
53+
AbstractReadContext context,
54+
ReadRequest.Builder builder,
55+
Options options,
56+
@Nullable ByteString partitionToken) {
57+
return applyOptions(new Read(builder), context, options, partitionToken);
58+
}
59+
60+
private static <T extends ReadOrQueryRequest> T applyOptions(
61+
T request,
62+
AbstractReadContext context,
63+
Options options,
64+
@Nullable ByteString partitionToken) {
65+
request.setSession(context.session.getName());
66+
if (partitionToken != null) {
67+
request.setPartitionToken(partitionToken);
68+
}
69+
if (options.hasDataBoostEnabled()) {
70+
request.setDataBoostEnabled(options.dataBoostEnabled());
71+
}
72+
if (options.hasDirectedReadOptions()) {
73+
request.setDirectedReadOptions(options.directedReadOptions());
74+
} else if (context.defaultDirectedReadOptions != null) {
75+
request.setDirectedReadOptions(context.defaultDirectedReadOptions);
76+
}
77+
request.setRequestOptions(context.buildRequestOptions(options));
78+
return request;
79+
}
80+
81+
/**
82+
* Indicates whether the most recently configured {@link TransactionSelector} carries an inlined
83+
* {@code begin} option. The underlying protobuf {@code Builder} is only accessed from {@code
84+
* startStream()}, whereas this field is {@code volatile} so {@link #isWithBeginTransaction()} can
85+
* be read safely from a concurrent {@link GrpcResultSet#close()} call.
86+
*/
87+
private volatile boolean withBeginTransaction;
88+
89+
private ReadOrQueryRequest(boolean withBeginTransaction) {
90+
this.withBeginTransaction = withBeginTransaction;
91+
}
92+
93+
abstract String getOperationName();
94+
95+
abstract RetrySettings getRetrySettings(SpannerRpc rpc);
96+
97+
abstract Set<Code> getRetryableCodes(SpannerRpc rpc);
98+
99+
abstract @Nullable Statement getStatement();
100+
101+
abstract void setSession(String session);
102+
103+
abstract void setPartitionToken(ByteString partitionToken);
104+
105+
abstract void setDataBoostEnabled(boolean dataBoostEnabled);
106+
107+
abstract void setDirectedReadOptions(DirectedReadOptions directedReadOptions);
108+
109+
abstract void setRequestOptions(RequestOptions requestOptions);
110+
111+
abstract void setResumeToken(ByteString resumeToken);
112+
113+
abstract boolean hasTransaction();
114+
115+
final void setTransaction(TransactionSelector selector) {
116+
setTransactionInternal(selector);
117+
this.withBeginTransaction = selector.hasBegin();
118+
}
119+
120+
/**
121+
* Returns {@code true} if the current {@link TransactionSelector} on this request includes an
122+
* inlined {@code BeginTransaction} option. Safe to call concurrently with {@code startStream()}.
123+
*/
124+
final boolean isWithBeginTransaction() {
125+
return withBeginTransaction;
126+
}
127+
128+
abstract void setTransactionInternal(TransactionSelector selector);
129+
130+
abstract SpannerRpc.StreamingCall start(
131+
SpannerRpc rpc,
132+
SpannerRpc.ResultStreamConsumer consumer,
133+
@Nullable Map<SpannerRpc.Option, ?> channelHint,
134+
XGoogSpannerRequestId requestId,
135+
boolean routeToLeader);
136+
137+
static final class Query extends ReadOrQueryRequest {
138+
private final ExecuteSqlRequest.Builder builder;
139+
private final Statement statement;
140+
141+
private Query(ExecuteSqlRequest.Builder builder, Statement statement) {
142+
super(checkNotNull(builder).getTransaction().hasBegin());
143+
this.builder = builder;
144+
this.statement = checkNotNull(statement);
145+
}
146+
147+
ExecuteSqlRequest.Builder getBuilder() {
148+
return builder;
149+
}
150+
151+
@Override
152+
String getOperationName() {
153+
return SpannerImpl.QUERY;
154+
}
155+
156+
@Override
157+
RetrySettings getRetrySettings(SpannerRpc rpc) {
158+
return rpc.getExecuteQueryRetrySettings();
159+
}
160+
161+
@Override
162+
Set<Code> getRetryableCodes(SpannerRpc rpc) {
163+
return rpc.getExecuteQueryRetryableCodes();
164+
}
165+
166+
@Override
167+
Statement getStatement() {
168+
return statement;
169+
}
170+
171+
@Override
172+
void setSession(String session) {
173+
builder.setSession(session);
174+
}
175+
176+
@Override
177+
void setPartitionToken(ByteString partitionToken) {
178+
builder.setPartitionToken(partitionToken);
179+
}
180+
181+
@Override
182+
void setDataBoostEnabled(boolean dataBoostEnabled) {
183+
builder.setDataBoostEnabled(dataBoostEnabled);
184+
}
185+
186+
@Override
187+
void setDirectedReadOptions(DirectedReadOptions directedReadOptions) {
188+
builder.setDirectedReadOptions(directedReadOptions);
189+
}
190+
191+
@Override
192+
void setRequestOptions(RequestOptions requestOptions) {
193+
builder.setRequestOptions(requestOptions);
194+
}
195+
196+
@Override
197+
void setResumeToken(ByteString resumeToken) {
198+
builder.setResumeToken(resumeToken);
199+
}
200+
201+
@Override
202+
boolean hasTransaction() {
203+
return builder.hasTransaction();
204+
}
205+
206+
@Override
207+
void setTransactionInternal(TransactionSelector selector) {
208+
builder.setTransaction(selector);
209+
}
210+
211+
@Override
212+
SpannerRpc.StreamingCall start(
213+
SpannerRpc rpc,
214+
SpannerRpc.ResultStreamConsumer consumer,
215+
@Nullable Map<SpannerRpc.Option, ?> channelHint,
216+
XGoogSpannerRequestId requestId,
217+
boolean routeToLeader) {
218+
return rpc.executeQuery(builder.build(), consumer, channelHint, requestId, routeToLeader);
219+
}
220+
}
221+
222+
static final class Read extends ReadOrQueryRequest {
223+
private final ReadRequest.Builder builder;
224+
225+
private Read(ReadRequest.Builder builder) {
226+
super(checkNotNull(builder).getTransaction().hasBegin());
227+
this.builder = builder;
228+
}
229+
230+
@Override
231+
String getOperationName() {
232+
return SpannerImpl.READ;
233+
}
234+
235+
@Override
236+
RetrySettings getRetrySettings(SpannerRpc rpc) {
237+
return rpc.getReadRetrySettings();
238+
}
239+
240+
@Override
241+
Set<Code> getRetryableCodes(SpannerRpc rpc) {
242+
return rpc.getReadRetryableCodes();
243+
}
244+
245+
@Override
246+
@Nullable Statement getStatement() {
247+
return null;
248+
}
249+
250+
@Override
251+
void setSession(String session) {
252+
builder.setSession(session);
253+
}
254+
255+
@Override
256+
void setPartitionToken(ByteString partitionToken) {
257+
builder.setPartitionToken(partitionToken);
258+
}
259+
260+
@Override
261+
void setDataBoostEnabled(boolean dataBoostEnabled) {
262+
builder.setDataBoostEnabled(dataBoostEnabled);
263+
}
264+
265+
@Override
266+
void setDirectedReadOptions(DirectedReadOptions directedReadOptions) {
267+
builder.setDirectedReadOptions(directedReadOptions);
268+
}
269+
270+
@Override
271+
void setRequestOptions(RequestOptions requestOptions) {
272+
builder.setRequestOptions(requestOptions);
273+
}
274+
275+
@Override
276+
void setResumeToken(ByteString resumeToken) {
277+
builder.setResumeToken(resumeToken);
278+
}
279+
280+
@Override
281+
boolean hasTransaction() {
282+
return builder.hasTransaction();
283+
}
284+
285+
@Override
286+
void setTransactionInternal(TransactionSelector selector) {
287+
builder.setTransaction(selector);
288+
}
289+
290+
@Override
291+
SpannerRpc.StreamingCall start(
292+
SpannerRpc rpc,
293+
SpannerRpc.ResultStreamConsumer consumer,
294+
@Nullable Map<SpannerRpc.Option, ?> channelHint,
295+
XGoogSpannerRequestId requestId,
296+
boolean routeToLeader) {
297+
return rpc.read(builder.build(), consumer, channelHint, requestId, routeToLeader);
298+
}
299+
}
300+
}

0 commit comments

Comments
 (0)