|
|
|
|
@ -1,4 +1,4 @@ |
|
|
|
|
// Copyright 2019 Google LLC. |
|
|
|
|
// Copyright 2020 Google LLC |
|
|
|
|
// |
|
|
|
|
// Licensed under the Apache License, Version 2.0 (the "License"); |
|
|
|
|
// you may not use this file except in compliance with the License. |
|
|
|
|
@ -11,7 +11,6 @@ |
|
|
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
|
|
|
|
// See the License for the specific language governing permissions and |
|
|
|
|
// limitations under the License. |
|
|
|
|
// |
|
|
|
|
|
|
|
|
|
syntax = "proto3"; |
|
|
|
|
|
|
|
|
|
@ -37,10 +36,6 @@ option java_multiple_files = true; |
|
|
|
|
option java_outer_classname = "SpannerProto"; |
|
|
|
|
option java_package = "com.google.spanner.v1"; |
|
|
|
|
option php_namespace = "Google\\Cloud\\Spanner\\V1"; |
|
|
|
|
|
|
|
|
|
// The Database resource is defined in `google.spanner.admin.database.v1`. |
|
|
|
|
// Because this is a separate, independent API (technically), we redefine |
|
|
|
|
// the resource name pattern here. |
|
|
|
|
option (google.api.resource_definition) = { |
|
|
|
|
type: "spanner.googleapis.com/Database" |
|
|
|
|
pattern: "projects/{project}/instances/{instance}/databases/{database}" |
|
|
|
|
@ -69,7 +64,7 @@ service Spanner { |
|
|
|
|
// |
|
|
|
|
// Active sessions use additional server resources, so it is a good idea to |
|
|
|
|
// delete idle and unneeded sessions. |
|
|
|
|
// Aside from explicit deletes, Cloud Spanner can delete sessions for which no |
|
|
|
|
// Aside from explicit deletes, Cloud Spanner may delete sessions for which no |
|
|
|
|
// operations are sent for more than an hour. If a session is deleted, |
|
|
|
|
// requests to it return `NOT_FOUND`. |
|
|
|
|
// |
|
|
|
|
@ -87,8 +82,7 @@ service Spanner { |
|
|
|
|
// |
|
|
|
|
// This API can be used to initialize a session cache on the clients. |
|
|
|
|
// See https://goo.gl/TgSFN2 for best practices on session cache management. |
|
|
|
|
rpc BatchCreateSessions(BatchCreateSessionsRequest) |
|
|
|
|
returns (BatchCreateSessionsResponse) { |
|
|
|
|
rpc BatchCreateSessions(BatchCreateSessionsRequest) returns (BatchCreateSessionsResponse) { |
|
|
|
|
option (google.api.http) = { |
|
|
|
|
post: "/v1/{database=projects/*/instances/*/databases/*}/sessions:batchCreate" |
|
|
|
|
body: "*" |
|
|
|
|
@ -131,12 +125,10 @@ service Spanner { |
|
|
|
|
// |
|
|
|
|
// Operations inside read-write transactions might return `ABORTED`. If |
|
|
|
|
// this occurs, the application should restart the transaction from |
|
|
|
|
// the beginning. See [Transaction][google.spanner.v1.Transaction] for more |
|
|
|
|
// details. |
|
|
|
|
// the beginning. See [Transaction][google.spanner.v1.Transaction] for more details. |
|
|
|
|
// |
|
|
|
|
// Larger result sets can be fetched in streaming fashion by calling |
|
|
|
|
// [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] |
|
|
|
|
// instead. |
|
|
|
|
// [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] instead. |
|
|
|
|
rpc ExecuteSql(ExecuteSqlRequest) returns (ResultSet) { |
|
|
|
|
option (google.api.http) = { |
|
|
|
|
post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeSql" |
|
|
|
|
@ -144,11 +136,11 @@ service Spanner { |
|
|
|
|
}; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
// Like [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], except returns the |
|
|
|
|
// result set as a stream. Unlike |
|
|
|
|
// [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], there is no limit on |
|
|
|
|
// the size of the returned result set. However, no individual row in the |
|
|
|
|
// result set can exceed 100 MiB, and no column value can exceed 10 MiB. |
|
|
|
|
// Like [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], except returns the result |
|
|
|
|
// set as a stream. Unlike [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql], there |
|
|
|
|
// is no limit on the size of the returned result set. However, no |
|
|
|
|
// individual row in the result set can exceed 100 MiB, and no |
|
|
|
|
// column value can exceed 10 MiB. |
|
|
|
|
rpc ExecuteStreamingSql(ExecuteSqlRequest) returns (stream PartialResultSet) { |
|
|
|
|
option (google.api.http) = { |
|
|
|
|
post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeStreamingSql" |
|
|
|
|
@ -161,15 +153,13 @@ service Spanner { |
|
|
|
|
// [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. |
|
|
|
|
// |
|
|
|
|
// Statements are executed in sequential order. A request can succeed even if |
|
|
|
|
// a statement fails. The |
|
|
|
|
// [ExecuteBatchDmlResponse.status][google.spanner.v1.ExecuteBatchDmlResponse.status] |
|
|
|
|
// field in the response provides information about the statement that failed. |
|
|
|
|
// Clients must inspect this field to determine whether an error occurred. |
|
|
|
|
// a statement fails. The [ExecuteBatchDmlResponse.status][google.spanner.v1.ExecuteBatchDmlResponse.status] field in the |
|
|
|
|
// response provides information about the statement that failed. Clients must |
|
|
|
|
// inspect this field to determine whether an error occurred. |
|
|
|
|
// |
|
|
|
|
// Execution stops after the first failed statement; the remaining statements |
|
|
|
|
// are not executed. |
|
|
|
|
rpc ExecuteBatchDml(ExecuteBatchDmlRequest) |
|
|
|
|
returns (ExecuteBatchDmlResponse) { |
|
|
|
|
rpc ExecuteBatchDml(ExecuteBatchDmlRequest) returns (ExecuteBatchDmlResponse) { |
|
|
|
|
option (google.api.http) = { |
|
|
|
|
post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeBatchDml" |
|
|
|
|
body: "*" |
|
|
|
|
@ -178,15 +168,14 @@ service Spanner { |
|
|
|
|
|
|
|
|
|
// Reads rows from the database using key lookups and scans, as a |
|
|
|
|
// simple key/value style alternative to |
|
|
|
|
// [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. This method cannot be |
|
|
|
|
// used to return a result set larger than 10 MiB; if the read matches more |
|
|
|
|
// [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. This method cannot be used to |
|
|
|
|
// return a result set larger than 10 MiB; if the read matches more |
|
|
|
|
// data than that, the read fails with a `FAILED_PRECONDITION` |
|
|
|
|
// error. |
|
|
|
|
// |
|
|
|
|
// Reads inside read-write transactions might return `ABORTED`. If |
|
|
|
|
// this occurs, the application should restart the transaction from |
|
|
|
|
// the beginning. See [Transaction][google.spanner.v1.Transaction] for more |
|
|
|
|
// details. |
|
|
|
|
// the beginning. See [Transaction][google.spanner.v1.Transaction] for more details. |
|
|
|
|
// |
|
|
|
|
// Larger result sets can be yielded in streaming fashion by calling |
|
|
|
|
// [StreamingRead][google.spanner.v1.Spanner.StreamingRead] instead. |
|
|
|
|
@ -197,9 +186,9 @@ service Spanner { |
|
|
|
|
}; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
// Like [Read][google.spanner.v1.Spanner.Read], except returns the result set |
|
|
|
|
// as a stream. Unlike [Read][google.spanner.v1.Spanner.Read], there is no |
|
|
|
|
// limit on the size of the returned result set. However, no individual row in |
|
|
|
|
// Like [Read][google.spanner.v1.Spanner.Read], except returns the result set as a |
|
|
|
|
// stream. Unlike [Read][google.spanner.v1.Spanner.Read], there is no limit on the |
|
|
|
|
// size of the returned result set. However, no individual row in |
|
|
|
|
// the result set can exceed 100 MiB, and no column value can exceed |
|
|
|
|
// 10 MiB. |
|
|
|
|
rpc StreamingRead(ReadRequest) returns (stream PartialResultSet) { |
|
|
|
|
@ -210,8 +199,7 @@ service Spanner { |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
// Begins a new transaction. This step can often be skipped: |
|
|
|
|
// [Read][google.spanner.v1.Spanner.Read], |
|
|
|
|
// [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and |
|
|
|
|
// [Read][google.spanner.v1.Spanner.Read], [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and |
|
|
|
|
// [Commit][google.spanner.v1.Spanner.Commit] can begin a new transaction as a |
|
|
|
|
// side-effect. |
|
|
|
|
rpc BeginTransaction(BeginTransactionRequest) returns (Transaction) { |
|
|
|
|
@ -236,15 +224,13 @@ service Spanner { |
|
|
|
|
body: "*" |
|
|
|
|
}; |
|
|
|
|
option (google.api.method_signature) = "session,transaction_id,mutations"; |
|
|
|
|
option (google.api.method_signature) = |
|
|
|
|
"session,single_use_transaction,mutations"; |
|
|
|
|
option (google.api.method_signature) = "session,single_use_transaction,mutations"; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
// Rolls back a transaction, releasing any locks it holds. It is a good |
|
|
|
|
// idea to call this for any transaction that includes one or more |
|
|
|
|
// [Read][google.spanner.v1.Spanner.Read] or |
|
|
|
|
// [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] requests and ultimately |
|
|
|
|
// decides not to commit. |
|
|
|
|
// [Read][google.spanner.v1.Spanner.Read] or [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] requests and |
|
|
|
|
// ultimately decides not to commit. |
|
|
|
|
// |
|
|
|
|
// `Rollback` returns `OK` if it successfully aborts the transaction, the |
|
|
|
|
// transaction was already aborted, or the transaction is not |
|
|
|
|
@ -259,11 +245,10 @@ service Spanner { |
|
|
|
|
|
|
|
|
|
// Creates a set of partition tokens that can be used to execute a query |
|
|
|
|
// operation in parallel. Each of the returned partition tokens can be used |
|
|
|
|
// by [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] to |
|
|
|
|
// specify a subset of the query result to read. The same session and |
|
|
|
|
// read-only transaction must be used by the PartitionQueryRequest used to |
|
|
|
|
// create the partition tokens and the ExecuteSqlRequests that use the |
|
|
|
|
// partition tokens. |
|
|
|
|
// by [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] to specify a subset |
|
|
|
|
// of the query result to read. The same session and read-only transaction |
|
|
|
|
// must be used by the PartitionQueryRequest used to create the |
|
|
|
|
// partition tokens and the ExecuteSqlRequests that use the partition tokens. |
|
|
|
|
// |
|
|
|
|
// Partition tokens become invalid when the session used to create them |
|
|
|
|
// is deleted, is idle for too long, begins a new transaction, or becomes too |
|
|
|
|
@ -278,13 +263,12 @@ service Spanner { |
|
|
|
|
|
|
|
|
|
// Creates a set of partition tokens that can be used to execute a read |
|
|
|
|
// operation in parallel. Each of the returned partition tokens can be used |
|
|
|
|
// by [StreamingRead][google.spanner.v1.Spanner.StreamingRead] to specify a |
|
|
|
|
// subset of the read result to read. The same session and read-only |
|
|
|
|
// transaction must be used by the PartitionReadRequest used to create the |
|
|
|
|
// partition tokens and the ReadRequests that use the partition tokens. There |
|
|
|
|
// are no ordering guarantees on rows returned among the returned partition |
|
|
|
|
// tokens, or even within each individual StreamingRead call issued with a |
|
|
|
|
// partition_token. |
|
|
|
|
// by [StreamingRead][google.spanner.v1.Spanner.StreamingRead] to specify a subset of the read |
|
|
|
|
// result to read. The same session and read-only transaction must be used by |
|
|
|
|
// the PartitionReadRequest used to create the partition tokens and the |
|
|
|
|
// ReadRequests that use the partition tokens. There are no ordering |
|
|
|
|
// guarantees on rows returned among the returned partition tokens, or even |
|
|
|
|
// within each individual StreamingRead call issued with a partition_token. |
|
|
|
|
// |
|
|
|
|
// Partition tokens become invalid when the session used to create them |
|
|
|
|
// is deleted, is idle for too long, begins a new transaction, or becomes too |
|
|
|
|
@ -312,8 +296,7 @@ message CreateSessionRequest { |
|
|
|
|
Session session = 2; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
// The request for |
|
|
|
|
// [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions]. |
|
|
|
|
// The request for [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions]. |
|
|
|
|
message BatchCreateSessionsRequest { |
|
|
|
|
// Required. The database in which the new sessions are created. |
|
|
|
|
string database = 1 [ |
|
|
|
|
@ -330,13 +313,11 @@ message BatchCreateSessionsRequest { |
|
|
|
|
// The API may return fewer than the requested number of sessions. If a |
|
|
|
|
// specific number of sessions are desired, the client can make additional |
|
|
|
|
// calls to BatchCreateSessions (adjusting |
|
|
|
|
// [session_count][google.spanner.v1.BatchCreateSessionsRequest.session_count] |
|
|
|
|
// as necessary). |
|
|
|
|
// [session_count][google.spanner.v1.BatchCreateSessionsRequest.session_count] as necessary). |
|
|
|
|
int32 session_count = 3 [(google.api.field_behavior) = REQUIRED]; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
// The response for |
|
|
|
|
// [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions]. |
|
|
|
|
// The response for [BatchCreateSessions][google.spanner.v1.Spanner.BatchCreateSessions]. |
|
|
|
|
message BatchCreateSessionsResponse { |
|
|
|
|
// The freshly created sessions. |
|
|
|
|
repeated Session session = 1; |
|
|
|
|
@ -377,7 +358,9 @@ message GetSessionRequest { |
|
|
|
|
// Required. The name of the session to retrieve. |
|
|
|
|
string name = 1 [ |
|
|
|
|
(google.api.field_behavior) = REQUIRED, |
|
|
|
|
(google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } |
|
|
|
|
(google.api.resource_reference) = { |
|
|
|
|
type: "spanner.googleapis.com/Session" |
|
|
|
|
} |
|
|
|
|
]; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
@ -396,8 +379,7 @@ message ListSessionsRequest { |
|
|
|
|
int32 page_size = 2; |
|
|
|
|
|
|
|
|
|
// If non-empty, `page_token` should contain a |
|
|
|
|
// [next_page_token][google.spanner.v1.ListSessionsResponse.next_page_token] |
|
|
|
|
// from a previous |
|
|
|
|
// [next_page_token][google.spanner.v1.ListSessionsResponse.next_page_token] from a previous |
|
|
|
|
// [ListSessionsResponse][google.spanner.v1.ListSessionsResponse]. |
|
|
|
|
string page_token = 3; |
|
|
|
|
|
|
|
|
|
@ -420,8 +402,8 @@ message ListSessionsResponse { |
|
|
|
|
repeated Session sessions = 1; |
|
|
|
|
|
|
|
|
|
// `next_page_token` can be sent in a subsequent |
|
|
|
|
// [ListSessions][google.spanner.v1.Spanner.ListSessions] call to fetch more |
|
|
|
|
// of the matching sessions. |
|
|
|
|
// [ListSessions][google.spanner.v1.Spanner.ListSessions] call to fetch more of the matching |
|
|
|
|
// sessions. |
|
|
|
|
string next_page_token = 2; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
@ -430,13 +412,36 @@ message DeleteSessionRequest { |
|
|
|
|
// Required. The name of the session to delete. |
|
|
|
|
string name = 1 [ |
|
|
|
|
(google.api.field_behavior) = REQUIRED, |
|
|
|
|
(google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } |
|
|
|
|
(google.api.resource_reference) = { |
|
|
|
|
type: "spanner.googleapis.com/Session" |
|
|
|
|
} |
|
|
|
|
]; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
// The request for [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and |
|
|
|
|
// [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql]. |
|
|
|
|
message ExecuteSqlRequest { |
|
|
|
|
// Query optimizer configuration. |
|
|
|
|
message QueryOptions { |
|
|
|
|
// An option to control the selection of optimizer version. |
|
|
|
|
// |
|
|
|
|
// This parameter allows individual queries to pick different query |
|
|
|
|
// optimizer versions. |
|
|
|
|
// |
|
|
|
|
// Specifying "latest" as a value instructs Cloud Spanner to use the |
|
|
|
|
// latest supported query optimizer version. If not specified, Cloud Spanner |
|
|
|
|
// uses optimizer version set at the database level options. Any other |
|
|
|
|
// positive integer (from the list of supported optimizer versions) |
|
|
|
|
// overrides the default optimizer version for query execution. |
|
|
|
|
// The list of supported optimizer versions can be queried from |
|
|
|
|
// SPANNER_SYS.SUPPORTED_OPTIMIZER_VERSIONS. Executing a SQL statement |
|
|
|
|
// with an invalid optimizer version will fail with a syntax error |
|
|
|
|
// (`INVALID_ARGUMENT`) status. |
|
|
|
|
// |
|
|
|
|
// The `optimizer_version` statement hint has precedence over this setting. |
|
|
|
|
string optimizer_version = 1; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
// Mode in which the statement must be processed. |
|
|
|
|
enum QueryMode { |
|
|
|
|
// The default mode. Only the statement results are returned. |
|
|
|
|
@ -454,7 +459,9 @@ message ExecuteSqlRequest { |
|
|
|
|
// Required. The session in which the SQL query should be performed. |
|
|
|
|
string session = 1 [ |
|
|
|
|
(google.api.field_behavior) = REQUIRED, |
|
|
|
|
(google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } |
|
|
|
|
(google.api.resource_reference) = { |
|
|
|
|
type: "spanner.googleapis.com/Session" |
|
|
|
|
} |
|
|
|
|
]; |
|
|
|
|
|
|
|
|
|
// The transaction to use. |
|
|
|
|
@ -488,8 +495,7 @@ message ExecuteSqlRequest { |
|
|
|
|
|
|
|
|
|
// It is not always possible for Cloud Spanner to infer the right SQL type |
|
|
|
|
// from a JSON value. For example, values of type `BYTES` and values |
|
|
|
|
// of type `STRING` both appear in |
|
|
|
|
// [params][google.spanner.v1.ExecuteSqlRequest.params] as JSON strings. |
|
|
|
|
// of type `STRING` both appear in [params][google.spanner.v1.ExecuteSqlRequest.params] as JSON strings. |
|
|
|
|
// |
|
|
|
|
// In these cases, `param_types` can be used to specify the exact |
|
|
|
|
// SQL type for some or all of the SQL statement parameters. See the |
|
|
|
|
@ -499,18 +505,15 @@ message ExecuteSqlRequest { |
|
|
|
|
|
|
|
|
|
// If this request is resuming a previously interrupted SQL statement |
|
|
|
|
// execution, `resume_token` should be copied from the last |
|
|
|
|
// [PartialResultSet][google.spanner.v1.PartialResultSet] yielded before the |
|
|
|
|
// interruption. Doing this enables the new SQL statement execution to resume |
|
|
|
|
// where the last one left off. The rest of the request parameters must |
|
|
|
|
// exactly match the request that yielded this token. |
|
|
|
|
// [PartialResultSet][google.spanner.v1.PartialResultSet] yielded before the interruption. Doing this |
|
|
|
|
// enables the new SQL statement execution to resume where the last one left |
|
|
|
|
// off. The rest of the request parameters must exactly match the |
|
|
|
|
// request that yielded this token. |
|
|
|
|
bytes resume_token = 6; |
|
|
|
|
|
|
|
|
|
// Used to control the amount of debugging information returned in |
|
|
|
|
// [ResultSetStats][google.spanner.v1.ResultSetStats]. If |
|
|
|
|
// [partition_token][google.spanner.v1.ExecuteSqlRequest.partition_token] is |
|
|
|
|
// set, [query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode] can only |
|
|
|
|
// be set to |
|
|
|
|
// [QueryMode.NORMAL][google.spanner.v1.ExecuteSqlRequest.QueryMode.NORMAL]. |
|
|
|
|
// [ResultSetStats][google.spanner.v1.ResultSetStats]. If [partition_token][google.spanner.v1.ExecuteSqlRequest.partition_token] is set, [query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode] can only |
|
|
|
|
// be set to [QueryMode.NORMAL][google.spanner.v1.ExecuteSqlRequest.QueryMode.NORMAL]. |
|
|
|
|
QueryMode query_mode = 7; |
|
|
|
|
|
|
|
|
|
// If present, results will be restricted to the specified partition |
|
|
|
|
@ -530,6 +533,9 @@ message ExecuteSqlRequest { |
|
|
|
|
// |
|
|
|
|
// Required for DML statements. Ignored for queries. |
|
|
|
|
int64 seqno = 9; |
|
|
|
|
|
|
|
|
|
// Query optimizer configuration to use for the given query. |
|
|
|
|
QueryOptions query_options = 10; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
// The request for [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. |
|
|
|
|
@ -555,9 +561,7 @@ message ExecuteBatchDmlRequest { |
|
|
|
|
|
|
|
|
|
// It is not always possible for Cloud Spanner to infer the right SQL type |
|
|
|
|
// from a JSON value. For example, values of type `BYTES` and values |
|
|
|
|
// of type `STRING` both appear in |
|
|
|
|
// [params][google.spanner.v1.ExecuteBatchDmlRequest.Statement.params] as |
|
|
|
|
// JSON strings. |
|
|
|
|
// of type `STRING` both appear in [params][google.spanner.v1.ExecuteBatchDmlRequest.Statement.params] as JSON strings. |
|
|
|
|
// |
|
|
|
|
// In these cases, `param_types` can be used to specify the exact |
|
|
|
|
// SQL type for some or all of the SQL statement parameters. See the |
|
|
|
|
@ -569,7 +573,9 @@ message ExecuteBatchDmlRequest { |
|
|
|
|
// Required. The session in which the DML statements should be performed. |
|
|
|
|
string session = 1 [ |
|
|
|
|
(google.api.field_behavior) = REQUIRED, |
|
|
|
|
(google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } |
|
|
|
|
(google.api.resource_reference) = { |
|
|
|
|
type: "spanner.googleapis.com/Session" |
|
|
|
|
} |
|
|
|
|
]; |
|
|
|
|
|
|
|
|
|
// Required. The transaction to use. Must be a read-write transaction. |
|
|
|
|
@ -579,17 +585,17 @@ message ExecuteBatchDmlRequest { |
|
|
|
|
// transaction. |
|
|
|
|
TransactionSelector transaction = 2 [(google.api.field_behavior) = REQUIRED]; |
|
|
|
|
|
|
|
|
|
// Required. The list of statements to execute in this batch. Statements are |
|
|
|
|
// executed serially, such that the effects of statement `i` are visible to |
|
|
|
|
// statement `i+1`. Each statement must be a DML statement. Execution stops at |
|
|
|
|
// the first failed statement; the remaining statements are not executed. |
|
|
|
|
// Required. The list of statements to execute in this batch. Statements are executed |
|
|
|
|
// serially, such that the effects of statement `i` are visible to statement |
|
|
|
|
// `i+1`. Each statement must be a DML statement. Execution stops at the |
|
|
|
|
// first failed statement; the remaining statements are not executed. |
|
|
|
|
// |
|
|
|
|
// Callers must provide at least one statement. |
|
|
|
|
repeated Statement statements = 3 [(google.api.field_behavior) = REQUIRED]; |
|
|
|
|
|
|
|
|
|
// Required. A per-transaction sequence number used to identify this request. |
|
|
|
|
// This field makes each request idempotent such that if the request is |
|
|
|
|
// received multiple times, at most one will succeed. |
|
|
|
|
// Required. A per-transaction sequence number used to identify this request. This field |
|
|
|
|
// makes each request idempotent such that if the request is received multiple |
|
|
|
|
// times, at most one will succeed. |
|
|
|
|
// |
|
|
|
|
// The sequence number must be monotonically increasing within the |
|
|
|
|
// transaction. If a request arrives for the first time with an out-of-order |
|
|
|
|
@ -598,47 +604,38 @@ message ExecuteBatchDmlRequest { |
|
|
|
|
int64 seqno = 4 [(google.api.field_behavior) = REQUIRED]; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
// The response for |
|
|
|
|
// [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. Contains a list |
|
|
|
|
// of [ResultSet][google.spanner.v1.ResultSet] messages, one for each DML |
|
|
|
|
// statement that has successfully executed, in the same order as the statements |
|
|
|
|
// in the request. If a statement fails, the status in the response body |
|
|
|
|
// identifies the cause of the failure. |
|
|
|
|
// The response for [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. Contains a list |
|
|
|
|
// of [ResultSet][google.spanner.v1.ResultSet] messages, one for each DML statement that has successfully |
|
|
|
|
// executed, in the same order as the statements in the request. If a statement |
|
|
|
|
// fails, the status in the response body identifies the cause of the failure. |
|
|
|
|
// |
|
|
|
|
// To check for DML statements that failed, use the following approach: |
|
|
|
|
// |
|
|
|
|
// 1. Check the status in the response message. The |
|
|
|
|
// [google.rpc.Code][google.rpc.Code] enum |
|
|
|
|
// 1. Check the status in the response message. The [google.rpc.Code][google.rpc.Code] enum |
|
|
|
|
// value `OK` indicates that all statements were executed successfully. |
|
|
|
|
// 2. If the status was not `OK`, check the number of result sets in the |
|
|
|
|
// response. If the response contains `N` |
|
|
|
|
// [ResultSet][google.spanner.v1.ResultSet] messages, then statement `N+1` in |
|
|
|
|
// the request failed. |
|
|
|
|
// response. If the response contains `N` [ResultSet][google.spanner.v1.ResultSet] messages, then |
|
|
|
|
// statement `N+1` in the request failed. |
|
|
|
|
// |
|
|
|
|
// Example 1: |
|
|
|
|
// |
|
|
|
|
// * Request: 5 DML statements, all executed successfully. |
|
|
|
|
// * Response: 5 [ResultSet][google.spanner.v1.ResultSet] messages, with the |
|
|
|
|
// status `OK`. |
|
|
|
|
// * Response: 5 [ResultSet][google.spanner.v1.ResultSet] messages, with the status `OK`. |
|
|
|
|
// |
|
|
|
|
// Example 2: |
|
|
|
|
// |
|
|
|
|
// * Request: 5 DML statements. The third statement has a syntax error. |
|
|
|
|
// * Response: 2 [ResultSet][google.spanner.v1.ResultSet] messages, and a syntax |
|
|
|
|
// error (`INVALID_ARGUMENT`) |
|
|
|
|
// status. The number of [ResultSet][google.spanner.v1.ResultSet] messages |
|
|
|
|
// indicates that the third statement failed, and the fourth and fifth |
|
|
|
|
// statements were not executed. |
|
|
|
|
// * Response: 2 [ResultSet][google.spanner.v1.ResultSet] messages, and a syntax error (`INVALID_ARGUMENT`) |
|
|
|
|
// status. The number of [ResultSet][google.spanner.v1.ResultSet] messages indicates that the third |
|
|
|
|
// statement failed, and the fourth and fifth statements were not executed. |
|
|
|
|
message ExecuteBatchDmlResponse { |
|
|
|
|
// One [ResultSet][google.spanner.v1.ResultSet] for each statement in the |
|
|
|
|
// request that ran successfully, in the same order as the statements in the |
|
|
|
|
// request. Each [ResultSet][google.spanner.v1.ResultSet] does not contain any |
|
|
|
|
// rows. The [ResultSetStats][google.spanner.v1.ResultSetStats] in each |
|
|
|
|
// [ResultSet][google.spanner.v1.ResultSet] contain the number of rows |
|
|
|
|
// modified by the statement. |
|
|
|
|
// |
|
|
|
|
// Only the first [ResultSet][google.spanner.v1.ResultSet] in the response |
|
|
|
|
// contains valid [ResultSetMetadata][google.spanner.v1.ResultSetMetadata]. |
|
|
|
|
// One [ResultSet][google.spanner.v1.ResultSet] for each statement in the request that ran successfully, |
|
|
|
|
// in the same order as the statements in the request. Each [ResultSet][google.spanner.v1.ResultSet] does |
|
|
|
|
// not contain any rows. The [ResultSetStats][google.spanner.v1.ResultSetStats] in each [ResultSet][google.spanner.v1.ResultSet] contain |
|
|
|
|
// the number of rows modified by the statement. |
|
|
|
|
// |
|
|
|
|
// Only the first [ResultSet][google.spanner.v1.ResultSet] in the response contains valid |
|
|
|
|
// [ResultSetMetadata][google.spanner.v1.ResultSetMetadata]. |
|
|
|
|
repeated ResultSet result_sets = 1; |
|
|
|
|
|
|
|
|
|
// If all DML statements are executed successfully, the status is `OK`. |
|
|
|
|
@ -673,23 +670,24 @@ message PartitionQueryRequest { |
|
|
|
|
// Required. The session used to create the partitions. |
|
|
|
|
string session = 1 [ |
|
|
|
|
(google.api.field_behavior) = REQUIRED, |
|
|
|
|
(google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } |
|
|
|
|
(google.api.resource_reference) = { |
|
|
|
|
type: "spanner.googleapis.com/Session" |
|
|
|
|
} |
|
|
|
|
]; |
|
|
|
|
|
|
|
|
|
// Read only snapshot transactions are supported, read/write and single use |
|
|
|
|
// transactions are not. |
|
|
|
|
TransactionSelector transaction = 2; |
|
|
|
|
|
|
|
|
|
// Required. The query request to generate partitions for. The request will |
|
|
|
|
// fail if the query is not root partitionable. The query plan of a root |
|
|
|
|
// Required. The query request to generate partitions for. The request will fail if |
|
|
|
|
// the query is not root partitionable. The query plan of a root |
|
|
|
|
// partitionable query has a single distributed union operator. A distributed |
|
|
|
|
// union operator conceptually divides one or more tables into multiple |
|
|
|
|
// splits, remotely evaluates a subquery independently on each split, and |
|
|
|
|
// then unions all results. |
|
|
|
|
// |
|
|
|
|
// This must not contain DML commands, such as INSERT, UPDATE, or |
|
|
|
|
// DELETE. Use |
|
|
|
|
// [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] with a |
|
|
|
|
// DELETE. Use [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] with a |
|
|
|
|
// PartitionedDml transaction for large, partition-friendly DML operations. |
|
|
|
|
string sql = 3 [(google.api.field_behavior) = REQUIRED]; |
|
|
|
|
|
|
|
|
|
@ -709,8 +707,7 @@ message PartitionQueryRequest { |
|
|
|
|
|
|
|
|
|
// It is not always possible for Cloud Spanner to infer the right SQL type |
|
|
|
|
// from a JSON value. For example, values of type `BYTES` and values |
|
|
|
|
// of type `STRING` both appear in |
|
|
|
|
// [params][google.spanner.v1.PartitionQueryRequest.params] as JSON strings. |
|
|
|
|
// of type `STRING` both appear in [params][google.spanner.v1.PartitionQueryRequest.params] as JSON strings. |
|
|
|
|
// |
|
|
|
|
// In these cases, `param_types` can be used to specify the exact |
|
|
|
|
// SQL type for some or all of the SQL query parameters. See the |
|
|
|
|
@ -727,7 +724,9 @@ message PartitionReadRequest { |
|
|
|
|
// Required. The session used to create the partitions. |
|
|
|
|
string session = 1 [ |
|
|
|
|
(google.api.field_behavior) = REQUIRED, |
|
|
|
|
(google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } |
|
|
|
|
(google.api.resource_reference) = { |
|
|
|
|
type: "spanner.googleapis.com/Session" |
|
|
|
|
} |
|
|
|
|
]; |
|
|
|
|
|
|
|
|
|
// Read only snapshot transactions are supported, read/write and single use |
|
|
|
|
@ -737,24 +736,18 @@ message PartitionReadRequest { |
|
|
|
|
// Required. The name of the table in the database to be read. |
|
|
|
|
string table = 3 [(google.api.field_behavior) = REQUIRED]; |
|
|
|
|
|
|
|
|
|
// If non-empty, the name of an index on |
|
|
|
|
// [table][google.spanner.v1.PartitionReadRequest.table]. This index is used |
|
|
|
|
// instead of the table primary key when interpreting |
|
|
|
|
// [key_set][google.spanner.v1.PartitionReadRequest.key_set] and sorting |
|
|
|
|
// result rows. See [key_set][google.spanner.v1.PartitionReadRequest.key_set] |
|
|
|
|
// for further information. |
|
|
|
|
// If non-empty, the name of an index on [table][google.spanner.v1.PartitionReadRequest.table]. This index is |
|
|
|
|
// used instead of the table primary key when interpreting [key_set][google.spanner.v1.PartitionReadRequest.key_set] |
|
|
|
|
// and sorting result rows. See [key_set][google.spanner.v1.PartitionReadRequest.key_set] for further information. |
|
|
|
|
string index = 4; |
|
|
|
|
|
|
|
|
|
// The columns of [table][google.spanner.v1.PartitionReadRequest.table] to be |
|
|
|
|
// returned for each row matching this request. |
|
|
|
|
// The columns of [table][google.spanner.v1.PartitionReadRequest.table] to be returned for each row matching |
|
|
|
|
// this request. |
|
|
|
|
repeated string columns = 5; |
|
|
|
|
|
|
|
|
|
// Required. `key_set` identifies the rows to be yielded. `key_set` names the |
|
|
|
|
// primary keys of the rows in |
|
|
|
|
// [table][google.spanner.v1.PartitionReadRequest.table] to be yielded, unless |
|
|
|
|
// [index][google.spanner.v1.PartitionReadRequest.index] is present. If |
|
|
|
|
// [index][google.spanner.v1.PartitionReadRequest.index] is present, then |
|
|
|
|
// [key_set][google.spanner.v1.PartitionReadRequest.key_set] instead names |
|
|
|
|
// primary keys of the rows in [table][google.spanner.v1.PartitionReadRequest.table] to be yielded, unless [index][google.spanner.v1.PartitionReadRequest.index] |
|
|
|
|
// is present. If [index][google.spanner.v1.PartitionReadRequest.index] is present, then [key_set][google.spanner.v1.PartitionReadRequest.key_set] instead names |
|
|
|
|
// index keys in [index][google.spanner.v1.PartitionReadRequest.index]. |
|
|
|
|
// |
|
|
|
|
// It is not an error for the `key_set` to name rows that do not |
|
|
|
|
@ -790,7 +783,9 @@ message ReadRequest { |
|
|
|
|
// Required. The session in which the read should be performed. |
|
|
|
|
string session = 1 [ |
|
|
|
|
(google.api.field_behavior) = REQUIRED, |
|
|
|
|
(google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } |
|
|
|
|
(google.api.resource_reference) = { |
|
|
|
|
type: "spanner.googleapis.com/Session" |
|
|
|
|
} |
|
|
|
|
]; |
|
|
|
|
|
|
|
|
|
// The transaction to use. If none is provided, the default is a |
|
|
|
|
@ -800,31 +795,24 @@ message ReadRequest { |
|
|
|
|
// Required. The name of the table in the database to be read. |
|
|
|
|
string table = 3 [(google.api.field_behavior) = REQUIRED]; |
|
|
|
|
|
|
|
|
|
// If non-empty, the name of an index on |
|
|
|
|
// [table][google.spanner.v1.ReadRequest.table]. This index is used instead of |
|
|
|
|
// the table primary key when interpreting |
|
|
|
|
// [key_set][google.spanner.v1.ReadRequest.key_set] and sorting result rows. |
|
|
|
|
// See [key_set][google.spanner.v1.ReadRequest.key_set] for further |
|
|
|
|
// information. |
|
|
|
|
// If non-empty, the name of an index on [table][google.spanner.v1.ReadRequest.table]. This index is |
|
|
|
|
// used instead of the table primary key when interpreting [key_set][google.spanner.v1.ReadRequest.key_set] |
|
|
|
|
// and sorting result rows. See [key_set][google.spanner.v1.ReadRequest.key_set] for further information. |
|
|
|
|
string index = 4; |
|
|
|
|
|
|
|
|
|
// Required. The columns of [table][google.spanner.v1.ReadRequest.table] to be |
|
|
|
|
// returned for each row matching this request. |
|
|
|
|
// Required. The columns of [table][google.spanner.v1.ReadRequest.table] to be returned for each row matching |
|
|
|
|
// this request. |
|
|
|
|
repeated string columns = 5 [(google.api.field_behavior) = REQUIRED]; |
|
|
|
|
|
|
|
|
|
// Required. `key_set` identifies the rows to be yielded. `key_set` names the |
|
|
|
|
// primary keys of the rows in [table][google.spanner.v1.ReadRequest.table] to |
|
|
|
|
// be yielded, unless [index][google.spanner.v1.ReadRequest.index] is present. |
|
|
|
|
// If [index][google.spanner.v1.ReadRequest.index] is present, then |
|
|
|
|
// [key_set][google.spanner.v1.ReadRequest.key_set] instead names index keys |
|
|
|
|
// in [index][google.spanner.v1.ReadRequest.index]. |
|
|
|
|
// |
|
|
|
|
// If the [partition_token][google.spanner.v1.ReadRequest.partition_token] |
|
|
|
|
// field is empty, rows are yielded in table primary key order (if |
|
|
|
|
// [index][google.spanner.v1.ReadRequest.index] is empty) or index key order |
|
|
|
|
// (if [index][google.spanner.v1.ReadRequest.index] is non-empty). If the |
|
|
|
|
// [partition_token][google.spanner.v1.ReadRequest.partition_token] field is |
|
|
|
|
// not empty, rows will be yielded in an unspecified order. |
|
|
|
|
// primary keys of the rows in [table][google.spanner.v1.ReadRequest.table] to be yielded, unless [index][google.spanner.v1.ReadRequest.index] |
|
|
|
|
// is present. If [index][google.spanner.v1.ReadRequest.index] is present, then [key_set][google.spanner.v1.ReadRequest.key_set] instead names |
|
|
|
|
// index keys in [index][google.spanner.v1.ReadRequest.index]. |
|
|
|
|
// |
|
|
|
|
// If the [partition_token][google.spanner.v1.ReadRequest.partition_token] field is empty, rows are yielded |
|
|
|
|
// in table primary key order (if [index][google.spanner.v1.ReadRequest.index] is empty) or index key order |
|
|
|
|
// (if [index][google.spanner.v1.ReadRequest.index] is non-empty). If the [partition_token][google.spanner.v1.ReadRequest.partition_token] field is not |
|
|
|
|
// empty, rows will be yielded in an unspecified order. |
|
|
|
|
// |
|
|
|
|
// It is not an error for the `key_set` to name rows that do not |
|
|
|
|
// exist in the database. Read yields nothing for nonexistent rows. |
|
|
|
|
@ -837,9 +825,9 @@ message ReadRequest { |
|
|
|
|
|
|
|
|
|
// If this request is resuming a previously interrupted read, |
|
|
|
|
// `resume_token` should be copied from the last |
|
|
|
|
// [PartialResultSet][google.spanner.v1.PartialResultSet] yielded before the |
|
|
|
|
// interruption. Doing this enables the new read to resume where the last read |
|
|
|
|
// left off. The rest of the request parameters must exactly match the request |
|
|
|
|
// [PartialResultSet][google.spanner.v1.PartialResultSet] yielded before the interruption. Doing this |
|
|
|
|
// enables the new read to resume where the last read left off. The |
|
|
|
|
// rest of the request parameters must exactly match the request |
|
|
|
|
// that yielded this token. |
|
|
|
|
bytes resume_token = 9; |
|
|
|
|
|
|
|
|
|
@ -850,13 +838,14 @@ message ReadRequest { |
|
|
|
|
bytes partition_token = 10; |
|
|
|
|
} |
|
|
|
|
|
|
|
|
|
// The request for |
|
|
|
|
// [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction]. |
|
|
|
|
// The request for [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction]. |
|
|
|
|
message BeginTransactionRequest { |
|
|
|
|
// Required. The session in which the transaction runs. |
|
|
|
|
string session = 1 [ |
|
|
|
|
(google.api.field_behavior) = REQUIRED, |
|
|
|
|
(google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } |
|
|
|
|
(google.api.resource_reference) = { |
|
|
|
|
type: "spanner.googleapis.com/Session" |
|
|
|
|
} |
|
|
|
|
]; |
|
|
|
|
|
|
|
|
|
// Required. Options for the new transaction. |
|
|
|
|
@ -868,7 +857,9 @@ message CommitRequest { |
|
|
|
|
// Required. The session in which the transaction to be committed is running. |
|
|
|
|
string session = 1 [ |
|
|
|
|
(google.api.field_behavior) = REQUIRED, |
|
|
|
|
(google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } |
|
|
|
|
(google.api.resource_reference) = { |
|
|
|
|
type: "spanner.googleapis.com/Session" |
|
|
|
|
} |
|
|
|
|
]; |
|
|
|
|
|
|
|
|
|
// Required. The transaction in which to commit. |
|
|
|
|
@ -905,7 +896,9 @@ message RollbackRequest { |
|
|
|
|
// Required. The session in which the transaction to roll back is running. |
|
|
|
|
string session = 1 [ |
|
|
|
|
(google.api.field_behavior) = REQUIRED, |
|
|
|
|
(google.api.resource_reference) = { type: "spanner.googleapis.com/Session" } |
|
|
|
|
(google.api.resource_reference) = { |
|
|
|
|
type: "spanner.googleapis.com/Session" |
|
|
|
|
} |
|
|
|
|
]; |
|
|
|
|
|
|
|
|
|
// Required. The transaction to roll back. |
|
|
|
|
|
Google APIs
5 years ago
committed by
Copybara-Service