ydb_query_v1.proto

syntax = "proto3";

package Ydb.Query.V1;
option go_package = "github.com/ydb-platform/ydb-go-genproto/Ydb_Query_V1";
option java_package = "tech.ydb.proto.query.v1";

import "protos/ydb_operation.proto";
import "protos/ydb_query.proto";

service QueryService {
    // Sessions are basic primitives for communicating with YDB Query Service. The are similar to
    // connections for classic relational DBs. Sessions serve three main purposes:
    // 1. Provide a flow control for DB requests with limited number of active channels.
    // 2. Distribute load evenly across multiple DB nodes.
    // 3. Store state for volatile stateful operations, such as short-living transactions.
    rpc CreateSession(Query.CreateSessionRequest) returns (Query.CreateSessionResponse);
    rpc DeleteSession(Query.DeleteSessionRequest) returns (Query.DeleteSessionResponse);
    rpc AttachSession(Query.AttachSessionRequest) returns (stream Query.SessionState);

    // Short-living transactions allow transactional execution of several queries, including support
    // for interactive transactions. Transaction control can be implemented via flags in ExecuteQuery
    // call (recommended), or via explicit calls to Begin/Commit/RollbackTransaction.
    rpc BeginTransaction(Query.BeginTransactionRequest) returns (Query.BeginTransactionResponse);
    rpc CommitTransaction(Query.CommitTransactionRequest) returns (Query.CommitTransactionResponse);
    rpc RollbackTransaction(Query.RollbackTransactionRequest) returns (Query.RollbackTransactionResponse);

    // Execute interactive query in a specified short-living transaction.
    // YDB query can contain DML, DDL and DCL statements. Supported mix of different statement types depends
    // on the chosen transaction type.
    // In case of error, including transport errors such as interrupted stream, whole transaction
    // needs to be retried. For non-idempotent transaction, a custom client logic is required to
    // retry conditionally retriable statuses, when transaction execution state is unknown.
    rpc ExecuteQuery(Query.ExecuteQueryRequest) returns (stream Query.ExecuteQueryResponsePart);

    // Execute long-running script.
    // YDB scripts can contain all type of statements, including TCL statements. This way you can execute multiple
    // transactions in a single YDB script.
    // ExecuteScript call returns long-running Ydb.Operation object with:
    //   operation.metadata = ExecuteScriptMetadata
    //   operation.result = Empty
    // Script execution metadata contains all information about current execution state, including
    // execution_id, execution statistics and result sets info.
    // You can use standard operation methods such as Get/Cancel/Forget/ListOperations to work with script executions.
    // Script can be executed as persistent, in which case all execution information and results will be stored
    // persistently and available after successful or unsuccessful execution.
    rpc ExecuteScript(Query.ExecuteScriptRequest) returns (Ydb.Operations.Operation);

    // Fetch results for script execution using fetch_token for continuation.
    // For script with multiple result sets, parts of different results sets are interleaved in responses.
    // For persistent scripts, you can fetch results in specific position of specific result set using
    // position instead of fetch_token.
    rpc FetchScriptResults(Query.FetchScriptResultsRequest) returns (Query.FetchScriptResultsResponse);
}