diff options
Diffstat (limited to 'third_party/googleapis/google/spanner/v1/spanner.proto')
| -rw-r--r-- | third_party/googleapis/google/spanner/v1/spanner.proto | 348 |
1 files changed, 348 insertions, 0 deletions
diff --git a/third_party/googleapis/google/spanner/v1/spanner.proto b/third_party/googleapis/google/spanner/v1/spanner.proto new file mode 100644 index 0000000000..80992f00be --- /dev/null +++ b/third_party/googleapis/google/spanner/v1/spanner.proto @@ -0,0 +1,348 @@ +// Copyright 2017 Google Inc. +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// 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"; + +package google.spanner.v1; + +import "google/api/annotations.proto"; +import "google/api/auth.proto"; +import "google/protobuf/empty.proto"; +import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; +import "google/spanner/v1/keys.proto"; +import "google/spanner/v1/mutation.proto"; +import "google/spanner/v1/result_set.proto"; +import "google/spanner/v1/transaction.proto"; +import "google/spanner/v1/type.proto"; + +option csharp_namespace = "Google.Cloud.Spanner.V1"; +option go_package = "google.golang.org/genproto/googleapis/spanner/v1;spanner"; +option java_multiple_files = true; +option java_outer_classname = "SpannerProto"; +option java_package = "com.google.spanner.v1"; + + +// Cloud Spanner API +// +// The Cloud Spanner API can be used to manage sessions and execute +// transactions on data stored in Cloud Spanner databases. +service Spanner { + // Creates a new session. A session can be used to perform + // transactions that read and/or modify data in a Cloud Spanner database. + // Sessions are meant to be reused for many consecutive + // transactions. + // + // Sessions can only execute one transaction at a time. To execute + // multiple concurrent read-write/write-only transactions, create + // multiple sessions. Note that standalone reads and queries use a + // transaction internally, and count toward the one transaction + // limit. + // + // Cloud Spanner limits the number of sessions that can exist at any given + // time; thus, it is a good idea to delete idle and/or unneeded sessions. + // Aside from explicit deletes, Cloud Spanner can delete sessions for which no + // operations are sent for more than an hour. If a session is deleted, + // requests to it return `NOT_FOUND`. + // + // Idle sessions can be kept alive by sending a trivial SQL query + // periodically, e.g., `"SELECT 1"`. + rpc CreateSession(CreateSessionRequest) returns (Session) { + option (google.api.http) = { post: "/v1/{database=projects/*/instances/*/databases/*}/sessions" body: "" }; + } + + // Gets a session. Returns `NOT_FOUND` if the session does not exist. + // This is mainly useful for determining whether a session is still + // alive. + rpc GetSession(GetSessionRequest) returns (Session) { + option (google.api.http) = { get: "/v1/{name=projects/*/instances/*/databases/*/sessions/*}" }; + } + + // Ends a session, releasing server resources associated with it. + rpc DeleteSession(DeleteSessionRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { delete: "/v1/{name=projects/*/instances/*/databases/*/sessions/*}" }; + } + + // Executes an SQL query, returning all rows in a single reply. This + // method cannot be used to return a result set larger than 10 MiB; + // if the query yields more data than that, the query fails with + // a `FAILED_PRECONDITION` error. + // + // Queries 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. + // + // Larger result sets can be fetched in streaming fashion by calling + // [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql] instead. + rpc ExecuteSql(ExecuteSqlRequest) returns (ResultSet) { + option (google.api.http) = { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeSql" body: "*" }; + } + + // 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" body: "*" }; + } + + // 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 + // 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. + // + // Larger result sets can be yielded in streaming fashion by calling + // [StreamingRead][google.spanner.v1.Spanner.StreamingRead] instead. + rpc Read(ReadRequest) returns (ResultSet) { + option (google.api.http) = { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:read" body: "*" }; + } + + // 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) { + option (google.api.http) = { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:streamingRead" body: "*" }; + } + + // Begins a new transaction. This step can often be skipped: + // [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) { + option (google.api.http) = { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:beginTransaction" body: "*" }; + } + + // Commits a transaction. The request includes the mutations to be + // applied to rows in the database. + // + // `Commit` might return an `ABORTED` error. This can occur at any time; + // commonly, the cause is conflicts with concurrent + // transactions. However, it can also happen for a variety of other + // reasons. If `Commit` returns `ABORTED`, the caller should re-attempt + // the transaction from the beginning, re-using the same session. + rpc Commit(CommitRequest) returns (CommitResponse) { + option (google.api.http) = { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:commit" body: "*" }; + } + + // 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. + // + // `Rollback` returns `OK` if it successfully aborts the transaction, the + // transaction was already aborted, or the transaction is not + // found. `Rollback` never returns `ABORTED`. + rpc Rollback(RollbackRequest) returns (google.protobuf.Empty) { + option (google.api.http) = { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:rollback" body: "*" }; + } +} + +// The request for [CreateSession][google.spanner.v1.Spanner.CreateSession]. +message CreateSessionRequest { + // Required. The database in which the new session is created. + string database = 1; +} + +// A session in the Cloud Spanner API. +message Session { + // Required. The name of the session. + string name = 1; +} + +// The request for [GetSession][google.spanner.v1.Spanner.GetSession]. +message GetSessionRequest { + // Required. The name of the session to retrieve. + string name = 1; +} + +// The request for [DeleteSession][google.spanner.v1.Spanner.DeleteSession]. +message DeleteSessionRequest { + // Required. The name of the session to delete. + string name = 1; +} + +// The request for [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and +// [ExecuteStreamingSql][google.spanner.v1.Spanner.ExecuteStreamingSql]. +message ExecuteSqlRequest { + // Mode in which the query must be processed. + enum QueryMode { + // The default mode where only the query result, without any information + // about the query plan is returned. + NORMAL = 0; + + // This mode returns only the query plan, without any result rows or + // execution statistics information. + PLAN = 1; + + // This mode returns both the query plan and the execution statistics along + // with the result rows. + PROFILE = 2; + } + + // Required. The session in which the SQL query should be performed. + string session = 1; + + // The transaction to use. If none is provided, the default is a + // temporary read-only transaction with strong concurrency. + TransactionSelector transaction = 2; + + // Required. The SQL query string. + string sql = 3; + + // The SQL query string can contain parameter placeholders. A parameter + // placeholder consists of `'@'` followed by the parameter + // name. Parameter names consist of any combination of letters, + // numbers, and underscores. + // + // Parameters can appear anywhere that a literal value is expected. The same + // parameter name can be used more than once, for example: + // `"WHERE id > @msg_id AND id < @msg_id + 100"` + // + // It is an error to execute an SQL query with unbound parameters. + // + // Parameter values are specified using `params`, which is a JSON + // object whose keys are parameter names, and whose values are the + // corresponding parameter values. + google.protobuf.Struct params = 4; + + // 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. + // + // 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 + // definition of [Type][google.spanner.v1.Type] for more information + // about SQL types. + map<string, Type> param_types = 5; + + // If this request is resuming a previously interrupted SQL query + // execution, `resume_token` should be copied from the last + // [PartialResultSet][google.spanner.v1.PartialResultSet] yielded before the interruption. Doing this + // enables the new SQL query 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]. + QueryMode query_mode = 7; +} + +// The request for [Read][google.spanner.v1.Spanner.Read] and +// [StreamingRead][google.spanner.v1.Spanner.StreamingRead]. +message ReadRequest { + // Required. The session in which the read should be performed. + string session = 1; + + // The transaction to use. If none is provided, the default is a + // temporary read-only transaction with strong concurrency. + TransactionSelector transaction = 2; + + // Required. The name of the table in the database to be read. + string table = 3; + + // 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; + + // The columns of [table][google.spanner.v1.ReadRequest.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.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]. + // + // 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). + // + // 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. + KeySet key_set = 6; + + // If greater than zero, only the first `limit` rows are yielded. If `limit` + // is zero, the default is no limit. + int64 limit = 8; + + // 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 + // that yielded this token. + bytes resume_token = 9; +} + +// The request for [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction]. +message BeginTransactionRequest { + // Required. The session in which the transaction runs. + string session = 1; + + // Required. Options for the new transaction. + TransactionOptions options = 2; +} + +// The request for [Commit][google.spanner.v1.Spanner.Commit]. +message CommitRequest { + // Required. The session in which the transaction to be committed is running. + string session = 1; + + // Required. The transaction in which to commit. + oneof transaction { + // Commit a previously-started transaction. + bytes transaction_id = 2; + + // Execute mutations in a temporary transaction. Note that unlike + // commit of a previously-started transaction, commit with a + // temporary transaction is non-idempotent. That is, if the + // `CommitRequest` is sent to Cloud Spanner more than once (for + // instance, due to retries in the application, or in the + // transport library), it is possible that the mutations are + // executed more than once. If this is undesirable, use + // [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction] and + // [Commit][google.spanner.v1.Spanner.Commit] instead. + TransactionOptions single_use_transaction = 3; + } + + // The mutations to be executed when this transaction commits. All + // mutations are applied atomically, in the order they appear in + // this list. + repeated Mutation mutations = 4; +} + +// The response for [Commit][google.spanner.v1.Spanner.Commit]. +message CommitResponse { + // The Cloud Spanner timestamp at which the transaction committed. + google.protobuf.Timestamp commit_timestamp = 1; +} + +// The request for [Rollback][google.spanner.v1.Spanner.Rollback]. +message RollbackRequest { + // Required. The session in which the transaction to roll back is running. + string session = 1; + + // Required. The transaction to roll back. + bytes transaction_id = 2; +} |