Skip to content

Commit 1c48a51

Browse files
ekuvardinekuvardin
committed
Add comments
1 parent dd982b0 commit 1c48a51

File tree

9 files changed

+453
-280
lines changed

9 files changed

+453
-280
lines changed

‎core/src/main/java/tech/ydb/core/OperationResult.java‎

Lines changed: 0 additions & 53 deletions
This file was deleted.

‎query/src/main/java/tech/ydb/query/QuerySession.java‎

Lines changed: 64 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,10 @@
88
import tech.ydb.core.Result;
99
import tech.ydb.core.Status;
1010
import tech.ydb.core.operation.Operation;
11+
import tech.ydb.core.operation.OperationTray;
1112
import tech.ydb.proto.query.YdbQuery;
1213
import tech.ydb.proto.scripting.ScriptingProtos;
14+
import tech.ydb.query.result.OperationResult;
1315
import tech.ydb.query.settings.BeginTransactionSettings;
1416
import tech.ydb.query.settings.ExecuteQuerySettings;
1517
import tech.ydb.query.settings.ExecuteScriptSettings;
@@ -74,38 +76,52 @@ public interface QuerySession extends AutoCloseable {
7476
*/
7577
QueryStream createQuery(String query, TxMode tx, Params params, ExecuteQuerySettings settings);
7678

77-
7879
/**
79-
* Execute yql script
80-
* @param query text of query
81-
* @param params query parameters
82-
* @param settings additional settings of query execution
83-
* @return future with result of the script execution
80+
* Executes a YQL script via the scripting service and returns its result as a completed future.
81+
*
82+
* <p>This method sends a YQL script for execution and collects the full result set in a single response.
83+
* It uses {@link ScriptingProtos.ExecuteYqlRequest} under the hood and returns
84+
* an {@link OperationResult} wrapped in {@link Result} to provide status and issues details.</p>
85+
*
86+
* @param query the YQL script text to execute
87+
* @param params input parameters for the script
88+
* @param settings execution settings such as statistics collection or tracing
89+
* @return a future that resolves to a {@link Result} containing {@link ScriptingProtos.ExecuteYqlResult}
8490
*/
85-
CompletableFuture<Result<ScriptingProtos.ExecuteYqlResult>> executeScriptYql(String query, Params params, ExecuteScriptSettings settings);
91+
CompletableFuture<Result<ScriptingProtos.ExecuteYqlResult>> executeScriptYql(String query,
92+
Params params,
93+
ExecuteScriptSettings settings);
8694

8795

8896
/**
89-
* Create {@link QueryStream} for executing query with specified {@link TxMode}. The query can contain DML, DDL and
90-
* DCL statements. Supported mix of different statement types depends on the chosen transaction type.
97+
* Submits a YQL script for asynchronous execution and returns a handle to the operation.
98+
* Take a not that join return future will not guarantee that script is finished. It's guarantee that script is passed to ydb
9199
*
92-
* @param query text of query
93-
* @param params query parameters
94-
* @param settings additional settings of query execution
95-
* @return a ready to execute instance of {@link QueryStream}
100+
* <p>This method executes the given script asynchronously and immediately returns
101+
* a {@link CompletableFuture} for an {@link Operation}, which can be later monitored or fetched
102+
* via {@link #waitForScript(CompletableFuture)} or {@link #fetchScriptResults(String, Params, FetchScriptSettings)}.</p>
103+
*
104+
* @param query the YQL script text to execute
105+
* @param params input parameters to pass to the script
106+
* @param settings script execution options such as TTL, statistics mode, or resource pool
107+
* @return a future resolving to an {@link Operation} representing the submitted script execution
96108
*/
97109
CompletableFuture<Operation<Status>> executeScript(String query, Params params, ExecuteScriptSettings settings);
98110

99111
/**
100-
* Fetch result from script which has already passed to YDB
101-
* Before use wait for CompletableFuture with operation
112+
* Fetches partial or complete results from a previously executed YQL script.
102113
*
103-
* @param query text of query
104-
* @param params query parameters
105-
* @param settings additional settings of query execution
106-
* @return a ready to execute instance of {@link QueryStream}
114+
* <p>This method retrieves result sets produced by an asynchronous script execution.
115+
* It supports incremental fetching using tokens, row limits, and result set index selection.</p>
116+
*
117+
* @param query optional query text for context (not used by the server but may help debugging)
118+
* @param params parameters used during script execution (typically empty)
119+
* @param settings settings that define which operation to fetch results from, including fetch token, row limit, and index
120+
* @return a future resolving to a {@link Result} containing {@link YdbQuery.FetchScriptResultsResponse}
107121
*/
108-
CompletableFuture<Result<YdbQuery.FetchScriptResultsResponse>> fetchScriptResults(String query, Params params, FetchScriptSettings settings);
122+
CompletableFuture<Result<YdbQuery.FetchScriptResultsResponse>> fetchScriptResults(String query,
123+
Params params,
124+
FetchScriptSettings settings);
109125

110126
@Override
111127
void close();
@@ -147,23 +163,44 @@ default CompletableFuture<Result<QueryTransaction>> beginTransaction(TxMode txMo
147163
}
148164

149165
/**
150-
* Execute Yql script with different type of operation
166+
* Executes a YQL script via the scripting service and returns its result as a completed future.
151167
*
152-
* @param query text of query
153-
* @return a future join on it to wait for script finished
168+
* <p>This method sends a YQL script for execution and collects the full result set in a single response.
169+
* It uses {@link ScriptingProtos.ExecuteYqlRequest} under the hood and returns
170+
* an {@link OperationResult} wrapped in {@link Result} to provide status and issues details.</p>
171+
*
172+
* @param query the YQL script text to execute
173+
* @return a future that resolves to a {@link Result} containing {@link ScriptingProtos.ExecuteYqlResult}
154174
*/
155175
default CompletableFuture<Result<ScriptingProtos.ExecuteYqlResult>> executeScriptYql(String query) {
156176
return executeScriptYql(query, Params.empty(), ExecuteScriptSettings.newBuilder().build());
157177
}
158178

159179
/**
160-
* Execute Yql script with different type of operation
161-
* Take a not join on a future is not granted that script is executed instead join guarantee that script pass to YDB
180+
* Submits a YQL script for asynchronous execution and returns a handle to the operation.
181+
* Take a not that join return future will not guarantee that script is finished. It's guarantee that script is passed to ydb
162182
*
163-
* @param query text of query
164-
* @return future join on it to wait for script pass to YDB but not get result
183+
* <p>This method executes the given script asynchronously and immediately returns
184+
* a {@link CompletableFuture} for an {@link Operation}, which can be later monitored or fetched
185+
* via {@link #waitForScript(CompletableFuture)} or {@link #fetchScriptResults(String, Params, FetchScriptSettings)}.</p>
186+
*
187+
* @param query the YQL script text to execute
188+
* @return a future resolving to an {@link Operation} representing the submitted script execution
165189
*/
166190
default CompletableFuture<Operation<Status>> executeScript(String query) {
167191
return executeScript(query, Params.empty(), ExecuteScriptSettings.newBuilder().build());
168192
}
193+
194+
/**
195+
* Waits for a previously submitted script operation to complete.
196+
*
197+
* <p>This method polls or fetches the state of the running operation via {@link OperationTray#fetchOperation}
198+
* until the operation completes successfully or fails. It is typically used after calling
199+
* {@link #executeScript(String, Params, ExecuteScriptSettings)}.</p>
200+
*
201+
* @param scriptFuture a {@link CompletableFuture} returned by {@link #executeScript(String, Params, ExecuteScriptSettings)}
202+
* @return a future resolving to the final {@link Status} of the script execution
203+
*/
204+
CompletableFuture<Status> waitForScript(CompletableFuture<Operation<Status>> scriptFuture);
205+
169206
}

‎query/src/main/java/tech/ydb/query/impl/QueryServiceRpc.java‎

Lines changed: 25 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,12 @@
1818
import tech.ydb.proto.scripting.v1.ScriptingServiceGrpc;
1919

2020
/**
21+
* Low-level RPC client for YDB Query and Scripting services.
22+
* <p>
23+
* Provides direct gRPC bindings for session management, query execution,
24+
* transaction control, and script execution APIs.
25+
* <p>
26+
* Used internally by higher-level query session and client abstractions.
2127
*
2228
* @author Aleksandr Gorshenin
2329
*/
@@ -111,27 +117,30 @@ public GrpcReadStream<YdbQuery.ExecuteQueryResponsePart> executeQuery(
111117
}
112118

113119
/**
114-
* Run execute script using Yql
120+
* Executes a YQL script via the scripting service.
115121
*
116-
* @param request request for execute script
117-
* @param settings grpc settings
118-
* @return future with result of execution
122+
* @param request the {@link ScriptingProtos.ExecuteYqlRequest} containing the script definition
123+
* @param settings gRPC request settings
124+
* @return a future resolving to an {@link Operation} with {@link ScriptingProtos.ExecuteYqlResult}
119125
*/
120126
public CompletableFuture<Operation<Result<ScriptingProtos.ExecuteYqlResult>>> executeScriptYql(
121127
ScriptingProtos.ExecuteYqlRequest request, GrpcRequestSettings settings) {
122128

123129
return transport.unaryCall(ScriptingServiceGrpc.getExecuteYqlMethod(), settings, request)
124130
.thenApply(OperationBinder.bindAsync(
125-
transport, ScriptingProtos.ExecuteYqlResponse::getOperation, ScriptingProtos.ExecuteYqlResult.class)
131+
transport,
132+
ScriptingProtos.ExecuteYqlResponse::getOperation,
133+
ScriptingProtos.ExecuteYqlResult.class)
126134
);
127135
}
128136

129137
/**
130-
* Execute script using query
138+
* Executes a YQL script using the Query service API.
131139
*
132-
* @param request request for execute script
133-
* @param settings grpc settings
134-
* @return future with result of execution
140+
*
141+
* @param request the {@link YdbQuery.ExecuteScriptRequest} containing the script
142+
* @param settings gRPC request settings
143+
* @return a future resolving to an {@link Operation} representing the script execution
135144
*/
136145
public CompletableFuture<Operation<Status>> executeScript(
137146
YdbQuery.ExecuteScriptRequest request, GrpcRequestSettings settings) {
@@ -144,11 +153,14 @@ public CompletableFuture<Operation<Status>> executeScript(
144153
}
145154

146155
/**
147-
* Fetch script using query
156+
* Fetches the results of a previously executed script.
157+
*
158+
* <p>This method retrieves the next portion of script execution results,
159+
* supporting pagination and partial fetch using tokens.</p>
148160
*
149-
* @param request for execute script
150-
* @param settings grpc settings
151-
* @return future with result of execution
161+
* @param request the {@link YdbQuery.FetchScriptResultsRequest} specifying the fetch parameters
162+
* @param settings gRPC request settings
163+
* @return a future resolving to {@link Result} containing {@link YdbQuery.FetchScriptResultsResponse}
152164
*/
153165
public CompletableFuture<Result<YdbQuery.FetchScriptResultsResponse>> fetchScriptResults(
154166
YdbQuery.FetchScriptResultsRequest request, GrpcRequestSettings settings) {

‎query/src/main/java/tech/ydb/query/impl/SessionImpl.java‎

Lines changed: 20 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,13 @@
1818
import tech.ydb.common.transaction.TxMode;
1919
import tech.ydb.common.transaction.impl.YdbTransactionImpl;
2020
import tech.ydb.core.Issue;
21-
import tech.ydb.core.OperationResult;
2221
import tech.ydb.core.Result;
2322
import tech.ydb.core.Status;
2423
import tech.ydb.core.StatusCode;
2524
import tech.ydb.core.grpc.GrpcReadStream;
2625
import tech.ydb.core.grpc.GrpcRequestSettings;
2726
import tech.ydb.core.operation.Operation;
27+
import tech.ydb.core.operation.OperationTray;
2828
import tech.ydb.core.operation.StatusExtractor;
2929
import tech.ydb.core.settings.BaseRequestSettings;
3030
import tech.ydb.core.utils.URITools;
@@ -35,6 +35,7 @@
3535
import tech.ydb.query.QuerySession;
3636
import tech.ydb.query.QueryStream;
3737
import tech.ydb.query.QueryTransaction;
38+
import tech.ydb.query.result.OperationResult;
3839
import tech.ydb.query.result.QueryInfo;
3940
import tech.ydb.query.result.QueryStats;
4041
import tech.ydb.query.settings.AttachSessionSettings;
@@ -266,7 +267,10 @@ void handleTxMeta(String txID) {
266267
}
267268

268269
@Override
269-
public CompletableFuture<Result<ScriptingProtos.ExecuteYqlResult>> executeScriptYql(String query, Params params, ExecuteScriptSettings settings) {
270+
public CompletableFuture<Result<ScriptingProtos.ExecuteYqlResult>> executeScriptYql(
271+
String query,
272+
Params params,
273+
ExecuteScriptSettings settings) {
270274
ScriptingProtos.ExecuteYqlRequest.Builder requestBuilder = ScriptingProtos.ExecuteYqlRequest.newBuilder()
271275
.setScript(query)
272276
.setCollectStats(mapStatsCollectionMode(settings.getStatsMode()));
@@ -279,7 +283,9 @@ public CompletableFuture<Result<ScriptingProtos.ExecuteYqlResult>> executeScript
279283
}
280284

281285
@Override
282-
public CompletableFuture<Operation<Status>> executeScript(String query, Params params, ExecuteScriptSettings settings) {
286+
public CompletableFuture<Operation<Status>> executeScript(String query,
287+
Params params,
288+
ExecuteScriptSettings settings) {
283289
YdbQuery.ExecuteScriptRequest.Builder request = YdbQuery.ExecuteScriptRequest.newBuilder()
284290
.setExecMode(mapExecMode(settings.getExecMode()))
285291
.setStatsMode(mapStatsMode(settings.getStatsMode()))
@@ -289,7 +295,7 @@ public CompletableFuture<Operation<Status>> executeScript(String query, Params p
289295
.build());
290296

291297
java.time.Duration ttl = settings.getTtl();
292-
if(ttl != null) {
298+
if (ttl != null) {
293299
request.setResultsTtl(Duration.newBuilder().setNanos(settings.getTtl().getNano()));
294300
}
295301

@@ -306,20 +312,26 @@ public CompletableFuture<Operation<Status>> executeScript(String query, Params p
306312
}
307313

308314
@Override
309-
public CompletableFuture<Result<YdbQuery.FetchScriptResultsResponse>> fetchScriptResults(String query, Params params, FetchScriptSettings settings) {
315+
public CompletableFuture<Status> waitForScript(CompletableFuture<Operation<Status>> scriptFuture) {
316+
return scriptFuture.thenCompose(operation -> OperationTray.fetchOperation(operation, 1));
317+
}
318+
319+
@Override
320+
public CompletableFuture<Result<YdbQuery.FetchScriptResultsResponse>>
321+
fetchScriptResults(String query, Params params, FetchScriptSettings settings) {
310322
YdbQuery.FetchScriptResultsRequest.Builder requestBuilder = YdbQuery.FetchScriptResultsRequest.newBuilder();
311323

312-
if(!Strings.isNullOrEmpty(settings.getFetchToken())) {
324+
if (!Strings.isNullOrEmpty(settings.getFetchToken())) {
313325
requestBuilder.setFetchToken(settings.getFetchToken());
314326
}
315327

316-
if(settings.getRowsLimit() > 0) {
328+
if (settings.getRowsLimit() > 0) {
317329
requestBuilder.setRowsLimit(settings.getRowsLimit());
318330
}
319331

320332
requestBuilder.setOperationId(settings.getOperationId());
321333

322-
if(settings.getSetResultSetIndex() >= 0) {
334+
if (settings.getSetResultSetIndex() >= 0) {
323335
requestBuilder.setResultSetIndex(settings.getSetResultSetIndex());
324336
}
325337

0 commit comments

Comments
 (0)