diff --git a/spanner/google/cloud/spanner_admin_database_v1/gapic/database_admin_client.py b/spanner/google/cloud/spanner_admin_database_v1/gapic/database_admin_client.py index 6555ec3c8da0..52eaacd7dcf6 100644 --- a/spanner/google/cloud/spanner_admin_database_v1/gapic/database_admin_client.py +++ b/spanner/google/cloud/spanner_admin_database_v1/gapic/database_admin_client.py @@ -540,7 +540,7 @@ def update_database_ddl( Args: database (str): Required. The database to update. - statements (list[str]): DDL statements to be applied to the database. + statements (list[str]): Required. DDL statements to be applied to the database. operation_id (str): If empty, the new update request is assigned an automatically-generated operation ID. Otherwise, ``operation_id`` is used to construct the name of the resulting ``Operation``. diff --git a/spanner/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin.proto b/spanner/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin.proto index 491606e6f711..8bd8f2c66523 100644 --- a/spanner/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin.proto +++ b/spanner/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC +// Copyright 2019 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,12 +11,16 @@ // 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.admin.database.v1; import "google/api/annotations.proto"; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; import "google/iam/v1/iam_policy.proto"; import "google/iam/v1/policy.proto"; import "google/longrunning/operations.proto"; @@ -36,11 +40,17 @@ option php_namespace = "Google\\Cloud\\Spanner\\Admin\\Database\\V1"; // list databases. It also enables updating the schema of pre-existing // databases. service DatabaseAdmin { + option (google.api.default_host) = "spanner.googleapis.com"; + option (google.api.oauth_scopes) = + "https://www.googleapis.com/auth/cloud-platform," + "https://www.googleapis.com/auth/spanner.admin"; + // Lists Cloud Spanner databases. rpc ListDatabases(ListDatabasesRequest) returns (ListDatabasesResponse) { option (google.api.http) = { get: "/v1/{parent=projects/*/instances/*}/databases" }; + option (google.api.method_signature) = "parent"; } // Creates a new Cloud Spanner database and starts to prepare it for serving. @@ -48,15 +58,19 @@ service DatabaseAdmin { // have a name of the format `/operations/` and // can be used to track preparation of the database. The // [metadata][google.longrunning.Operation.metadata] field type is - // [CreateDatabaseMetadata][google.spanner.admin.database.v1.CreateDatabaseMetadata]. - // The [response][google.longrunning.Operation.response] field type is + // [CreateDatabaseMetadata][google.spanner.admin.database.v1.CreateDatabaseMetadata]. The + // [response][google.longrunning.Operation.response] field type is // [Database][google.spanner.admin.database.v1.Database], if successful. - rpc CreateDatabase(CreateDatabaseRequest) - returns (google.longrunning.Operation) { + rpc CreateDatabase(CreateDatabaseRequest) returns (google.longrunning.Operation) { option (google.api.http) = { post: "/v1/{parent=projects/*/instances/*}/databases" body: "*" }; + option (google.api.method_signature) = "parent,create_statement"; + option (google.longrunning.operation_info) = { + response_type: "google.spanner.admin.database.v1.Database" + metadata_type: "google.spanner.admin.database.v1.CreateDatabaseMetadata" + }; } // Gets the state of a Cloud Spanner database. @@ -64,6 +78,7 @@ service DatabaseAdmin { option (google.api.http) = { get: "/v1/{name=projects/*/instances/*/databases/*}" }; + option (google.api.method_signature) = "name"; } // Updates the schema of a Cloud Spanner database by @@ -72,14 +87,17 @@ service DatabaseAdmin { // the format `/operations/` and can be used to // track execution of the schema change(s). The // [metadata][google.longrunning.Operation.metadata] field type is - // [UpdateDatabaseDdlMetadata][google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata]. - // The operation has no response. - rpc UpdateDatabaseDdl(UpdateDatabaseDdlRequest) - returns (google.longrunning.Operation) { + // [UpdateDatabaseDdlMetadata][google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata]. The operation has no response. + rpc UpdateDatabaseDdl(UpdateDatabaseDdlRequest) returns (google.longrunning.Operation) { option (google.api.http) = { patch: "/v1/{database=projects/*/instances/*/databases/*}/ddl" body: "*" }; + option (google.api.method_signature) = "database,statements"; + option (google.longrunning.operation_info) = { + response_type: "google.protobuf.Empty" + metadata_type: "google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata" + }; } // Drops (aka deletes) a Cloud Spanner database. @@ -87,6 +105,7 @@ service DatabaseAdmin { option (google.api.http) = { delete: "/v1/{database=projects/*/instances/*/databases/*}" }; + option (google.api.method_signature) = "database"; } // Returns the schema of a Cloud Spanner database as a list of formatted @@ -96,51 +115,70 @@ service DatabaseAdmin { option (google.api.http) = { get: "/v1/{database=projects/*/instances/*/databases/*}/ddl" }; + option (google.api.method_signature) = "database"; } - // Sets the access control policy on a database resource. Replaces any - // existing policy. + // Sets the access control policy on a database resource. + // Replaces any existing policy. // - // Authorization requires `spanner.databases.setIamPolicy` permission on - // [resource][google.iam.v1.SetIamPolicyRequest.resource]. - rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) - returns (google.iam.v1.Policy) { + // Authorization requires `spanner.databases.setIamPolicy` + // permission on [resource][google.iam.v1.SetIamPolicyRequest.resource]. + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*/databases/*}:setIamPolicy" body: "*" + additional_bindings { + post: "/v1/{resource=projects/*/instances/*/backups/*}:setIamPolicy" + body: "*" + } }; + option (google.api.method_signature) = "resource,policy"; } - // Gets the access control policy for a database resource. Returns an empty - // policy if a database exists but does not have a policy set. + // Gets the access control policy for a database resource. + // Returns an empty policy if a database exists but does + // not have a policy set. // // Authorization requires `spanner.databases.getIamPolicy` permission on // [resource][google.iam.v1.GetIamPolicyRequest.resource]. - rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) - returns (google.iam.v1.Policy) { + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*/databases/*}:getIamPolicy" body: "*" + additional_bindings { + post: "/v1/{resource=projects/*/instances/*/backups/*}:getIamPolicy" + body: "*" + } }; + option (google.api.method_signature) = "resource"; } // Returns permissions that the caller has on the specified database resource. // - // Attempting this RPC on a non-existent Cloud Spanner database will result in - // a NOT_FOUND error if the user has `spanner.databases.list` permission on - // the containing Cloud Spanner instance. Otherwise returns an empty set of - // permissions. - rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) - returns (google.iam.v1.TestIamPermissionsResponse) { + // Attempting this RPC on a non-existent Cloud Spanner database will + // result in a NOT_FOUND error if the user has + // `spanner.databases.list` permission on the containing Cloud + // Spanner instance. Otherwise returns an empty set of permissions. + rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*/databases/*}:testIamPermissions" body: "*" + additional_bindings { + post: "/v1/{resource=projects/*/instances/*/backups/*}:testIamPermissions" + body: "*" + } }; + option (google.api.method_signature) = "resource,permissions"; } } // A Cloud Spanner database. message Database { + option (google.api.resource) = { + type: "spanner.googleapis.com/Database" + pattern: "projects/{project}/instances/{instance}/databases/{database}" + }; + // Indicates the current state of the database. enum State { // Not specified. @@ -165,49 +203,55 @@ message Database { State state = 2; } -// The request for -// [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases]. +// The request for [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases]. message ListDatabasesRequest { // Required. The instance whose databases should be listed. // Values are of the form `projects//instances/`. - string parent = 1; + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Instance" + } + ]; // Number of databases to be returned in the response. If 0 or less, // defaults to the server's maximum allowed page size. int32 page_size = 3; // If non-empty, `page_token` should contain a - // [next_page_token][google.spanner.admin.database.v1.ListDatabasesResponse.next_page_token] - // from a previous - // [ListDatabasesResponse][google.spanner.admin.database.v1.ListDatabasesResponse]. + // [next_page_token][google.spanner.admin.database.v1.ListDatabasesResponse.next_page_token] from a + // previous [ListDatabasesResponse][google.spanner.admin.database.v1.ListDatabasesResponse]. string page_token = 4; } -// The response for -// [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases]. +// The response for [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases]. message ListDatabasesResponse { // Databases that matched the request. repeated Database databases = 1; // `next_page_token` can be sent in a subsequent - // [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases] - // call to fetch more of the matching databases. + // [ListDatabases][google.spanner.admin.database.v1.DatabaseAdmin.ListDatabases] call to fetch more + // of the matching databases. string next_page_token = 2; } -// The request for -// [CreateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase]. +// The request for [CreateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase]. message CreateDatabaseRequest { // Required. The name of the instance that will serve the new database. // Values are of the form `projects//instances/`. - string parent = 1; + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Instance" + } + ]; // Required. A `CREATE DATABASE` statement, which specifies the ID of the // new database. The database ID must conform to the regular expression // `[a-z][a-z0-9_\-]*[a-z0-9]` and be between 2 and 30 characters in length. // If the database ID is a reserved word or if it contains a hyphen, the // database ID must be enclosed in backticks (`` ` ``). - string create_statement = 2; + string create_statement = 2 [(google.api.field_behavior) = REQUIRED]; // An optional list of DDL statements to run inside the newly created // database. Statements can create tables, indexes, etc. These @@ -220,15 +264,21 @@ message CreateDatabaseRequest { // [CreateDatabase][google.spanner.admin.database.v1.DatabaseAdmin.CreateDatabase]. message CreateDatabaseMetadata { // The database being created. - string database = 1; + string database = 1 [(google.api.resource_reference) = { + type: "spanner.googleapis.com/Database" + }]; } -// The request for -// [GetDatabase][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabase]. +// The request for [GetDatabase][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabase]. message GetDatabaseRequest { // Required. The name of the requested database. Values are of the form // `projects//instances//databases/`. - string name = 1; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Database" + } + ]; } // Enqueues the given DDL statements to be applied, in order but not @@ -245,14 +295,19 @@ message GetDatabaseRequest { // Each batch of statements is assigned a name which can be used with // the [Operations][google.longrunning.Operations] API to monitor // progress. See the -// [operation_id][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.operation_id] -// field for more details. +// [operation_id][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.operation_id] field for more +// details. message UpdateDatabaseDdlRequest { // Required. The database to update. - string database = 1; + string database = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Database" + } + ]; - // DDL statements to be applied to the database. - repeated string statements = 2; + // Required. DDL statements to be applied to the database. + repeated string statements = 2 [(google.api.field_behavior) = REQUIRED]; // If empty, the new update request is assigned an // automatically-generated operation ID. Otherwise, `operation_id` @@ -261,20 +316,18 @@ message UpdateDatabaseDdlRequest { // // Specifying an explicit operation ID simplifies determining // whether the statements were executed in the event that the - // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl] - // call is replayed, or the return value is otherwise lost: the - // [database][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.database] - // and `operation_id` fields can be combined to form the + // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl] call is replayed, + // or the return value is otherwise lost: the [database][google.spanner.admin.database.v1.UpdateDatabaseDdlRequest.database] and + // `operation_id` fields can be combined to form the // [name][google.longrunning.Operation.name] of the resulting - // [longrunning.Operation][google.longrunning.Operation]: - // `/operations/`. + // [longrunning.Operation][google.longrunning.Operation]: `/operations/`. // // `operation_id` should be unique within the database, and must be // a valid identifier: `[a-z][a-z0-9_]*`. Note that // automatically-generated operation IDs always begin with an // underscore. If the named operation already exists, - // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl] - // returns `ALREADY_EXISTS`. + // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl] returns + // `ALREADY_EXISTS`. string operation_id = 3; } @@ -282,7 +335,9 @@ message UpdateDatabaseDdlRequest { // [UpdateDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.UpdateDatabaseDdl]. message UpdateDatabaseDdlMetadata { // The database being modified. - string database = 1; + string database = 1 [(google.api.resource_reference) = { + type: "spanner.googleapis.com/Database" + }]; // For an update this list contains all the statements. For an // individual statement, this list contains only that statement. @@ -294,24 +349,39 @@ message UpdateDatabaseDdlMetadata { repeated google.protobuf.Timestamp commit_timestamps = 3; } -// The request for -// [DropDatabase][google.spanner.admin.database.v1.DatabaseAdmin.DropDatabase]. +// The request for [DropDatabase][google.spanner.admin.database.v1.DatabaseAdmin.DropDatabase]. message DropDatabaseRequest { // Required. The database to be dropped. - string database = 1; + string database = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Database" + } + ]; } -// The request for -// [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl]. +// The request for [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl]. message GetDatabaseDdlRequest { // Required. The database whose schema we wish to get. - string database = 1; + string database = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Database" + } + ]; } -// The response for -// [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl]. +// The response for [GetDatabaseDdl][google.spanner.admin.database.v1.DatabaseAdmin.GetDatabaseDdl]. message GetDatabaseDdlResponse { // A list of formatted DDL statements defining the schema of the database // specified in the request. repeated string statements = 1; } + +// The Instance resource is defined in `google.spanner.admin.instance.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/Instance" + pattern: "projects/{project}/instances/{instance}" +}; diff --git a/spanner/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin_pb2.py b/spanner/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin_pb2.py index bce18741da55..2091661949ac 100644 --- a/spanner/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin_pb2.py +++ b/spanner/google/cloud/spanner_admin_database_v1/proto/spanner_database_admin_pb2.py @@ -16,6 +16,9 @@ from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2 +from google.api import client_pb2 as google_dot_api_dot_client__pb2 +from google.api import field_behavior_pb2 as google_dot_api_dot_field__behavior__pb2 +from google.api import resource_pb2 as google_dot_api_dot_resource__pb2 from google.iam.v1 import iam_policy_pb2 as google_dot_iam_dot_v1_dot_iam__policy__pb2 from google.iam.v1 import policy_pb2 as google_dot_iam_dot_v1_dot_policy__pb2 from google.longrunning import ( @@ -30,13 +33,16 @@ package="google.spanner.admin.database.v1", syntax="proto3", serialized_options=_b( - "\n$com.google.spanner.admin.database.v1B\031SpannerDatabaseAdminProtoP\001ZHgoogle.golang.org/genproto/googleapis/spanner/admin/database/v1;database\252\002&Google.Cloud.Spanner.Admin.Database.V1\312\002&Google\\Cloud\\Spanner\\Admin\\Database\\V1" + "\n$com.google.spanner.admin.database.v1B\031SpannerDatabaseAdminProtoP\001ZHgoogle.golang.org/genproto/googleapis/spanner/admin/database/v1;database\252\002&Google.Cloud.Spanner.Admin.Database.V1\312\002&Google\\Cloud\\Spanner\\Admin\\Database\\V1\352AJ\n\037spanner.googleapis.com/Instance\022'projects/{project}/instances/{instance}" ), serialized_pb=_b( - '\nIgoogle/cloud/spanner/admin/database_v1/proto/spanner_database_admin.proto\x12 google.spanner.admin.database.v1\x1a\x1cgoogle/api/annotations.proto\x1a\x1egoogle/iam/v1/iam_policy.proto\x1a\x1agoogle/iam/v1/policy.proto\x1a#google/longrunning/operations.proto\x1a\x1bgoogle/protobuf/empty.proto\x1a\x1fgoogle/protobuf/timestamp.proto"\x92\x01\n\x08\x44\x61tabase\x12\x0c\n\x04name\x18\x01 \x01(\t\x12?\n\x05state\x18\x02 \x01(\x0e\x32\x30.google.spanner.admin.database.v1.Database.State"7\n\x05State\x12\x15\n\x11STATE_UNSPECIFIED\x10\x00\x12\x0c\n\x08\x43REATING\x10\x01\x12\t\n\x05READY\x10\x02"M\n\x14ListDatabasesRequest\x12\x0e\n\x06parent\x18\x01 \x01(\t\x12\x11\n\tpage_size\x18\x03 \x01(\x05\x12\x12\n\npage_token\x18\x04 \x01(\t"o\n\x15ListDatabasesResponse\x12=\n\tdatabases\x18\x01 \x03(\x0b\x32*.google.spanner.admin.database.v1.Database\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t"[\n\x15\x43reateDatabaseRequest\x12\x0e\n\x06parent\x18\x01 \x01(\t\x12\x18\n\x10\x63reate_statement\x18\x02 \x01(\t\x12\x18\n\x10\x65xtra_statements\x18\x03 \x03(\t"*\n\x16\x43reateDatabaseMetadata\x12\x10\n\x08\x64\x61tabase\x18\x01 \x01(\t""\n\x12GetDatabaseRequest\x12\x0c\n\x04name\x18\x01 \x01(\t"V\n\x18UpdateDatabaseDdlRequest\x12\x10\n\x08\x64\x61tabase\x18\x01 \x01(\t\x12\x12\n\nstatements\x18\x02 \x03(\t\x12\x14\n\x0coperation_id\x18\x03 \x01(\t"x\n\x19UpdateDatabaseDdlMetadata\x12\x10\n\x08\x64\x61tabase\x18\x01 \x01(\t\x12\x12\n\nstatements\x18\x02 \x03(\t\x12\x35\n\x11\x63ommit_timestamps\x18\x03 \x03(\x0b\x32\x1a.google.protobuf.Timestamp"\'\n\x13\x44ropDatabaseRequest\x12\x10\n\x08\x64\x61tabase\x18\x01 \x01(\t")\n\x15GetDatabaseDdlRequest\x12\x10\n\x08\x64\x61tabase\x18\x01 \x01(\t",\n\x16GetDatabaseDdlResponse\x12\x12\n\nstatements\x18\x01 \x03(\t2\x95\x0c\n\rDatabaseAdmin\x12\xb7\x01\n\rListDatabases\x12\x36.google.spanner.admin.database.v1.ListDatabasesRequest\x1a\x37.google.spanner.admin.database.v1.ListDatabasesResponse"5\x82\xd3\xe4\x93\x02/\x12-/v1/{parent=projects/*/instances/*}/databases\x12\xa2\x01\n\x0e\x43reateDatabase\x12\x37.google.spanner.admin.database.v1.CreateDatabaseRequest\x1a\x1d.google.longrunning.Operation"8\x82\xd3\xe4\x93\x02\x32"-/v1/{parent=projects/*/instances/*}/databases:\x01*\x12\xa6\x01\n\x0bGetDatabase\x12\x34.google.spanner.admin.database.v1.GetDatabaseRequest\x1a*.google.spanner.admin.database.v1.Database"5\x82\xd3\xe4\x93\x02/\x12-/v1/{name=projects/*/instances/*/databases/*}\x12\xb0\x01\n\x11UpdateDatabaseDdl\x12:.google.spanner.admin.database.v1.UpdateDatabaseDdlRequest\x1a\x1d.google.longrunning.Operation"@\x82\xd3\xe4\x93\x02:25/v1/{database=projects/*/instances/*/databases/*}/ddl:\x01*\x12\x98\x01\n\x0c\x44ropDatabase\x12\x35.google.spanner.admin.database.v1.DropDatabaseRequest\x1a\x16.google.protobuf.Empty"9\x82\xd3\xe4\x93\x02\x33*1/v1/{database=projects/*/instances/*/databases/*}\x12\xc2\x01\n\x0eGetDatabaseDdl\x12\x37.google.spanner.admin.database.v1.GetDatabaseDdlRequest\x1a\x38.google.spanner.admin.database.v1.GetDatabaseDdlResponse"=\x82\xd3\xe4\x93\x02\x37\x12\x35/v1/{database=projects/*/instances/*/databases/*}/ddl\x12\x94\x01\n\x0cSetIamPolicy\x12".google.iam.v1.SetIamPolicyRequest\x1a\x15.google.iam.v1.Policy"I\x82\xd3\xe4\x93\x02\x43">/v1/{resource=projects/*/instances/*/databases/*}:setIamPolicy:\x01*\x12\x94\x01\n\x0cGetIamPolicy\x12".google.iam.v1.GetIamPolicyRequest\x1a\x15.google.iam.v1.Policy"I\x82\xd3\xe4\x93\x02\x43">/v1/{resource=projects/*/instances/*/databases/*}:getIamPolicy:\x01*\x12\xba\x01\n\x12TestIamPermissions\x12(.google.iam.v1.TestIamPermissionsRequest\x1a).google.iam.v1.TestIamPermissionsResponse"O\x82\xd3\xe4\x93\x02I"D/v1/{resource=projects/*/instances/*/databases/*}:testIamPermissions:\x01*B\xdf\x01\n$com.google.spanner.admin.database.v1B\x19SpannerDatabaseAdminProtoP\x01ZHgoogle.golang.org/genproto/googleapis/spanner/admin/database/v1;database\xaa\x02&Google.Cloud.Spanner.Admin.Database.V1\xca\x02&Google\\Cloud\\Spanner\\Admin\\Database\\V1b\x06proto3' + '\nIgoogle/cloud/spanner/admin/database_v1/proto/spanner_database_admin.proto\x12 google.spanner.admin.database.v1\x1a\x1cgoogle/api/annotations.proto\x1a\x17google/api/client.proto\x1a\x1fgoogle/api/field_behavior.proto\x1a\x19google/api/resource.proto\x1a\x1egoogle/iam/v1/iam_policy.proto\x1a\x1agoogle/iam/v1/policy.proto\x1a#google/longrunning/operations.proto\x1a\x1bgoogle/protobuf/empty.proto\x1a\x1fgoogle/protobuf/timestamp.proto"\xf6\x01\n\x08\x44\x61tabase\x12\x0c\n\x04name\x18\x01 \x01(\t\x12?\n\x05state\x18\x02 \x01(\x0e\x32\x30.google.spanner.admin.database.v1.Database.State"7\n\x05State\x12\x15\n\x11STATE_UNSPECIFIED\x10\x00\x12\x0c\n\x08\x43REATING\x10\x01\x12\t\n\x05READY\x10\x02:b\xea\x41_\n\x1fspanner.googleapis.com/Database\x12\x82\xd3\xe4\x93\x02/\x12-/v1/{parent=projects/*/instances/*}/databases\xda\x41\x06parent\x12\xa4\x02\n\x0e\x43reateDatabase\x12\x37.google.spanner.admin.database.v1.CreateDatabaseRequest\x1a\x1d.google.longrunning.Operation"\xb9\x01\x82\xd3\xe4\x93\x02\x32"-/v1/{parent=projects/*/instances/*}/databases:\x01*\xda\x41\x17parent,create_statement\xca\x41\x64\n)google.spanner.admin.database.v1.Database\x12\x37google.spanner.admin.database.v1.CreateDatabaseMetadata\x12\xad\x01\n\x0bGetDatabase\x12\x34.google.spanner.admin.database.v1.GetDatabaseRequest\x1a*.google.spanner.admin.database.v1.Database"<\x82\xd3\xe4\x93\x02/\x12-/v1/{name=projects/*/instances/*/databases/*}\xda\x41\x04name\x12\x9d\x02\n\x11UpdateDatabaseDdl\x12:.google.spanner.admin.database.v1.UpdateDatabaseDdlRequest\x1a\x1d.google.longrunning.Operation"\xac\x01\x82\xd3\xe4\x93\x02:25/v1/{database=projects/*/instances/*/databases/*}/ddl:\x01*\xda\x41\x13\x64\x61tabase,statements\xca\x41S\n\x15google.protobuf.Empty\x12:google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata\x12\xa3\x01\n\x0c\x44ropDatabase\x12\x35.google.spanner.admin.database.v1.DropDatabaseRequest\x1a\x16.google.protobuf.Empty"D\x82\xd3\xe4\x93\x02\x33*1/v1/{database=projects/*/instances/*/databases/*}\xda\x41\x08\x64\x61tabase\x12\xcd\x01\n\x0eGetDatabaseDdl\x12\x37.google.spanner.admin.database.v1.GetDatabaseDdlRequest\x1a\x38.google.spanner.admin.database.v1.GetDatabaseDdlResponse"H\x82\xd3\xe4\x93\x02\x37\x12\x35/v1/{database=projects/*/instances/*/databases/*}/ddl\xda\x41\x08\x64\x61tabase\x12\xeb\x01\n\x0cSetIamPolicy\x12".google.iam.v1.SetIamPolicyRequest\x1a\x15.google.iam.v1.Policy"\x9f\x01\x82\xd3\xe4\x93\x02\x86\x01">/v1/{resource=projects/*/instances/*/databases/*}:setIamPolicy:\x01*ZA"/v1/{resource=projects/*/instances/*/databases/*}:getIamPolicy:\x01*ZA"/v1/{resource=projects/*/instances/*/databases/*}:setIamPolicy:\001*' + '\202\323\344\223\002\206\001">/v1/{resource=projects/*/instances/*/databases/*}:setIamPolicy:\001*ZA"/v1/{resource=projects/*/instances/*/databases/*}:getIamPolicy:\001*' + '\202\323\344\223\002\206\001">/v1/{resource=projects/*/instances/*/databases/*}:getIamPolicy:\001*ZA"/operations/` and can be used to track preparation of the database. The [metadata][google.longrunning.Operation.metadata] field type is - [CreateDatabaseMetadata][google.spanner.admin.database.v1.CreateDatabaseMetadata]. - The [response][google.longrunning.Operation.response] field type is + [CreateDatabaseMetadata][google.spanner.admin.database.v1.CreateDatabaseMetadata]. The + [response][google.longrunning.Operation.response] field type is [Database][google.spanner.admin.database.v1.Database], if successful. """ context.set_code(grpc.StatusCode.UNIMPLEMENTED) @@ -116,8 +116,7 @@ def UpdateDatabaseDdl(self, request, context): the format `/operations/` and can be used to track execution of the schema change(s). The [metadata][google.longrunning.Operation.metadata] field type is - [UpdateDatabaseDdlMetadata][google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata]. - The operation has no response. + [UpdateDatabaseDdlMetadata][google.spanner.admin.database.v1.UpdateDatabaseDdlMetadata]. The operation has no response. """ context.set_code(grpc.StatusCode.UNIMPLEMENTED) context.set_details("Method not implemented!") @@ -140,19 +139,20 @@ def GetDatabaseDdl(self, request, context): raise NotImplementedError("Method not implemented!") def SetIamPolicy(self, request, context): - """Sets the access control policy on a database resource. Replaces any - existing policy. + """Sets the access control policy on a database resource. + Replaces any existing policy. - Authorization requires `spanner.databases.setIamPolicy` permission on - [resource][google.iam.v1.SetIamPolicyRequest.resource]. + Authorization requires `spanner.databases.setIamPolicy` + permission on [resource][google.iam.v1.SetIamPolicyRequest.resource]. """ context.set_code(grpc.StatusCode.UNIMPLEMENTED) context.set_details("Method not implemented!") raise NotImplementedError("Method not implemented!") def GetIamPolicy(self, request, context): - """Gets the access control policy for a database resource. Returns an empty - policy if a database exists but does not have a policy set. + """Gets the access control policy for a database resource. + Returns an empty policy if a database exists but does + not have a policy set. Authorization requires `spanner.databases.getIamPolicy` permission on [resource][google.iam.v1.GetIamPolicyRequest.resource]. @@ -164,10 +164,10 @@ def GetIamPolicy(self, request, context): def TestIamPermissions(self, request, context): """Returns permissions that the caller has on the specified database resource. - Attempting this RPC on a non-existent Cloud Spanner database will result in - a NOT_FOUND error if the user has `spanner.databases.list` permission on - the containing Cloud Spanner instance. Otherwise returns an empty set of - permissions. + Attempting this RPC on a non-existent Cloud Spanner database will + result in a NOT_FOUND error if the user has + `spanner.databases.list` permission on the containing Cloud + Spanner instance. Otherwise returns an empty set of permissions. """ context.set_code(grpc.StatusCode.UNIMPLEMENTED) context.set_details("Method not implemented!") diff --git a/spanner/google/cloud/spanner_admin_instance_v1/gapic/enums.py b/spanner/google/cloud/spanner_admin_instance_v1/gapic/enums.py index 93650fd1f4a8..e029ed491811 100644 --- a/spanner/google/cloud/spanner_admin_instance_v1/gapic/enums.py +++ b/spanner/google/cloud/spanner_admin_instance_v1/gapic/enums.py @@ -36,3 +36,40 @@ class State(enum.IntEnum): STATE_UNSPECIFIED = 0 CREATING = 1 READY = 2 + + +class ReplicaInfo(object): + class ReplicaType(enum.IntEnum): + """ + Indicates the type of replica. See the `replica types + documentation `__ + for more details. + + Attributes: + TYPE_UNSPECIFIED (int): Not specified. + READ_WRITE (int): Read-write replicas support both reads and writes. These replicas: + + - Maintain a full copy of your data. + - Serve reads. + - Can vote whether to commit a write. + - Participate in leadership election. + - Are eligible to become a leader. + READ_ONLY (int): Read-only replicas only support reads (not writes). Read-only replicas: + + - Maintain a full copy of your data. + - Serve reads. + - Do not participate in voting to commit writes. + - Are not eligible to become a leader. + WITNESS (int): Witness replicas don't support reads but do participate in voting to + commit writes. Witness replicas: + + - Do not maintain a full copy of data. + - Do not serve reads. + - Vote whether to commit writes. + - Participate in leader election but are not eligible to become leader. + """ + + TYPE_UNSPECIFIED = 0 + READ_WRITE = 1 + READ_ONLY = 2 + WITNESS = 3 diff --git a/spanner/google/cloud/spanner_admin_instance_v1/gapic/instance_admin_client.py b/spanner/google/cloud/spanner_admin_instance_v1/gapic/instance_admin_client.py index d66b505a7caf..c2c18a5840c5 100644 --- a/spanner/google/cloud/spanner_admin_instance_v1/gapic/instance_admin_client.py +++ b/spanner/google/cloud/spanner_admin_instance_v1/gapic/instance_admin_client.py @@ -679,7 +679,7 @@ def create_instance( parent (str): Required. The name of the project in which to create the instance. Values are of the form ``projects/``. instance_id (str): Required. The ID of the instance to create. Valid identifiers are of the - form ``[a-z][-a-z0-9]*[a-z0-9]`` and must be between 6 and 30 characters + form ``[a-z][-a-z0-9]*[a-z0-9]`` and must be between 2 and 64 characters in length. instance (Union[dict, ~google.cloud.spanner_admin_instance_v1.types.Instance]): Required. The instance to create. The name may be omitted, but if specified must be ``/instances/``. diff --git a/spanner/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin.proto b/spanner/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin.proto index c6ca85c9ce89..12b090e5d273 100644 --- a/spanner/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin.proto +++ b/spanner/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC +// Copyright 2019 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,12 +11,16 @@ // 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.admin.instance.v1; import "google/api/annotations.proto"; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; import "google/iam/v1/iam_policy.proto"; import "google/iam/v1/policy.proto"; import "google/longrunning/operations.proto"; @@ -53,12 +57,17 @@ option php_namespace = "Google\\Cloud\\Spanner\\Admin\\Instance\\V1"; // instance resources, fewer resources are available for other // databases in that instance, and their performance may suffer. service InstanceAdmin { + option (google.api.default_host) = "spanner.googleapis.com"; + option (google.api.oauth_scopes) = + "https://www.googleapis.com/auth/cloud-platform," + "https://www.googleapis.com/auth/spanner.admin"; + // Lists the supported instance configurations for a given project. - rpc ListInstanceConfigs(ListInstanceConfigsRequest) - returns (ListInstanceConfigsResponse) { + rpc ListInstanceConfigs(ListInstanceConfigsRequest) returns (ListInstanceConfigsResponse) { option (google.api.http) = { get: "/v1/{parent=projects/*}/instanceConfigs" }; + option (google.api.method_signature) = "parent"; } // Gets information about a particular instance configuration. @@ -66,6 +75,7 @@ service InstanceAdmin { option (google.api.http) = { get: "/v1/{name=projects/*/instanceConfigs/*}" }; + option (google.api.method_signature) = "name"; } // Lists all instances in the given project. @@ -73,6 +83,7 @@ service InstanceAdmin { option (google.api.http) = { get: "/v1/{parent=projects/*}/instances" }; + option (google.api.method_signature) = "parent"; } // Gets information about a particular instance. @@ -80,6 +91,7 @@ service InstanceAdmin { option (google.api.http) = { get: "/v1/{name=projects/*/instances/*}" }; + option (google.api.method_signature) = "name"; } // Creates an instance and begins preparing it to begin serving. The @@ -116,12 +128,16 @@ service InstanceAdmin { // [CreateInstanceMetadata][google.spanner.admin.instance.v1.CreateInstanceMetadata]. // The [response][google.longrunning.Operation.response] field type is // [Instance][google.spanner.admin.instance.v1.Instance], if successful. - rpc CreateInstance(CreateInstanceRequest) - returns (google.longrunning.Operation) { + rpc CreateInstance(CreateInstanceRequest) returns (google.longrunning.Operation) { option (google.api.http) = { post: "/v1/{parent=projects/*}/instances" body: "*" }; + option (google.api.method_signature) = "parent,instance_id,instance"; + option (google.longrunning.operation_info) = { + response_type: "google.spanner.admin.instance.v1.Instance" + metadata_type: "google.spanner.admin.instance.v1.CreateInstanceMetadata" + }; } // Updates an instance, and begins allocating or releasing resources @@ -138,9 +154,9 @@ service InstanceAdmin { // Until completion of the returned operation: // // * Cancelling the operation sets its metadata's - // [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], - // and begins restoring resources to their pre-request values. The - // operation is guaranteed to succeed at undoing all resource changes, + // [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], and begins + // restoring resources to their pre-request values. The operation + // is guaranteed to succeed at undoing all resource changes, // after which point it terminates with a `CANCELLED` status. // * All other attempts to modify the instance are rejected. // * Reading the instance via the API continues to give the pre-request @@ -164,12 +180,16 @@ service InstanceAdmin { // // Authorization requires `spanner.instances.update` permission on // resource [name][google.spanner.admin.instance.v1.Instance.name]. - rpc UpdateInstance(UpdateInstanceRequest) - returns (google.longrunning.Operation) { + rpc UpdateInstance(UpdateInstanceRequest) returns (google.longrunning.Operation) { option (google.api.http) = { patch: "/v1/{instance.name=projects/*/instances/*}" body: "*" }; + option (google.api.method_signature) = "instance,field_mask"; + option (google.longrunning.operation_info) = { + response_type: "google.spanner.admin.instance.v1.Instance" + metadata_type: "google.spanner.admin.instance.v1.UpdateInstanceMetadata" + }; } // Deletes an instance. @@ -187,6 +207,7 @@ service InstanceAdmin { option (google.api.http) = { delete: "/v1/{name=projects/*/instances/*}" }; + option (google.api.method_signature) = "name"; } // Sets the access control policy on an instance resource. Replaces any @@ -194,12 +215,12 @@ service InstanceAdmin { // // Authorization requires `spanner.instances.setIamPolicy` on // [resource][google.iam.v1.SetIamPolicyRequest.resource]. - rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) - returns (google.iam.v1.Policy) { + rpc SetIamPolicy(google.iam.v1.SetIamPolicyRequest) returns (google.iam.v1.Policy) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*}:setIamPolicy" body: "*" }; + option (google.api.method_signature) = "resource,policy"; } // Gets the access control policy for an instance resource. Returns an empty @@ -207,12 +228,12 @@ service InstanceAdmin { // // Authorization requires `spanner.instances.getIamPolicy` on // [resource][google.iam.v1.GetIamPolicyRequest.resource]. - rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) - returns (google.iam.v1.Policy) { + rpc GetIamPolicy(google.iam.v1.GetIamPolicyRequest) returns (google.iam.v1.Policy) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*}:getIamPolicy" body: "*" }; + option (google.api.method_signature) = "resource"; } // Returns permissions that the caller has on the specified instance resource. @@ -221,18 +242,71 @@ service InstanceAdmin { // result in a NOT_FOUND error if the user has `spanner.instances.list` // permission on the containing Google Cloud Project. Otherwise returns an // empty set of permissions. - rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) - returns (google.iam.v1.TestIamPermissionsResponse) { + rpc TestIamPermissions(google.iam.v1.TestIamPermissionsRequest) returns (google.iam.v1.TestIamPermissionsResponse) { option (google.api.http) = { post: "/v1/{resource=projects/*/instances/*}:testIamPermissions" body: "*" }; + option (google.api.method_signature) = "resource,permissions"; + } +} + +message ReplicaInfo { + // Indicates the type of replica. See the [replica types + // documentation](https://cloud.google.com/spanner/docs/replication#replica_types) + // for more details. + enum ReplicaType { + // Not specified. + TYPE_UNSPECIFIED = 0; + + // Read-write replicas support both reads and writes. These replicas: + // + // * Maintain a full copy of your data. + // * Serve reads. + // * Can vote whether to commit a write. + // * Participate in leadership election. + // * Are eligible to become a leader. + READ_WRITE = 1; + + // Read-only replicas only support reads (not writes). Read-only replicas: + // + // * Maintain a full copy of your data. + // * Serve reads. + // * Do not participate in voting to commit writes. + // * Are not eligible to become a leader. + READ_ONLY = 2; + + // Witness replicas don't support reads but do participate in voting to + // commit writes. Witness replicas: + // + // * Do not maintain a full copy of data. + // * Do not serve reads. + // * Vote whether to commit writes. + // * Participate in leader election but are not eligible to become leader. + WITNESS = 3; } + + // The location of the serving resources, e.g. "us-central1". + string location = 1; + + // The type of replica. + ReplicaType type = 2; + + // If true, this location is designated as the default leader location where + // leader replicas are placed. See the [region types + // documentation](https://cloud.google.com/spanner/docs/instances#region_types) + // for more details. + bool default_leader_location = 3; } // A possible configuration for a Cloud Spanner instance. Configurations // define the geographic placement of nodes and their replication. message InstanceConfig { + option (google.api.resource) = { + type: "spanner.googleapis.com/InstanceConfig" + pattern: "projects/{project}/instanceConfigs/{instance_config}" + }; + // A unique identifier for the instance configuration. Values // are of the form // `projects//instanceConfigs/[a-z][-a-z0-9]*` @@ -240,10 +314,19 @@ message InstanceConfig { // The name of this instance configuration as it appears in UIs. string display_name = 2; + + // The geographic placement of nodes in this instance configuration and their + // replication properties. + repeated ReplicaInfo replicas = 3; } // An isolated set of Cloud Spanner resources on which databases can be hosted. message Instance { + option (google.api.resource) = { + type: "spanner.googleapis.com/Instance" + pattern: "projects/{project}/instances/{instance}" + }; + // Indicates the current state of the instance. enum State { // Not specified. @@ -262,14 +345,16 @@ message Instance { // Required. A unique identifier for the instance, which cannot be changed // after the instance is created. Values are of the form // `projects//instances/[a-z][-a-z0-9]*[a-z0-9]`. The final - // segment of the name must be between 6 and 30 characters in length. + // segment of the name must be between 2 and 64 characters in length. string name = 1; // Required. The name of the instance's configuration. Values are of the form // `projects//instanceConfigs/`. See // also [InstanceConfig][google.spanner.admin.instance.v1.InstanceConfig] and // [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. - string config = 2; + string config = 2 [(google.api.resource_reference) = { + type: "spanner.googleapis.com/InstanceConfig" + }]; // Required. The descriptive name for this instance as it appears in UIs. // Must be unique per project and between 4 and 30 characters in length. @@ -284,10 +369,10 @@ message Instance { int32 node_count = 5; // Output only. The current instance state. For - // [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance], - // the state must be either omitted or set to `CREATING`. For - // [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance], - // the state must be either omitted or set to `READY`. + // [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance], the state must be + // either omitted or set to `CREATING`. For + // [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance], the state must be + // either omitted or set to `READY`. State state = 6; // Cloud Labels are a flexible and lightweight mechanism for organizing cloud @@ -314,13 +399,17 @@ message Instance { map labels = 7; } -// The request for -// [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. +// The request for [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. message ListInstanceConfigsRequest { // Required. The name of the project for which a list of supported instance // configurations is requested. Values are of the form // `projects/`. - string parent = 1; + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "cloudresourcemanager.googleapis.com/Project" + } + ]; // Number of instance configurations to be returned in the response. If 0 or // less, defaults to the server's maximum allowed page size. @@ -328,20 +417,18 @@ message ListInstanceConfigsRequest { // If non-empty, `page_token` should contain a // [next_page_token][google.spanner.admin.instance.v1.ListInstanceConfigsResponse.next_page_token] - // from a previous - // [ListInstanceConfigsResponse][google.spanner.admin.instance.v1.ListInstanceConfigsResponse]. + // from a previous [ListInstanceConfigsResponse][google.spanner.admin.instance.v1.ListInstanceConfigsResponse]. string page_token = 3; } -// The response for -// [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. +// The response for [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs]. message ListInstanceConfigsResponse { // The list of requested instance configurations. repeated InstanceConfig instance_configs = 1; // `next_page_token` can be sent in a subsequent - // [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs] - // call to fetch more of the matching instance configurations. + // [ListInstanceConfigs][google.spanner.admin.instance.v1.InstanceAdmin.ListInstanceConfigs] call to + // fetch more of the matching instance configurations. string next_page_token = 2; } @@ -350,49 +437,65 @@ message ListInstanceConfigsResponse { message GetInstanceConfigRequest { // Required. The name of the requested instance configuration. Values are of // the form `projects//instanceConfigs/`. - string name = 1; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/InstanceConfig" + } + ]; } -// The request for -// [GetInstance][google.spanner.admin.instance.v1.InstanceAdmin.GetInstance]. +// The request for [GetInstance][google.spanner.admin.instance.v1.InstanceAdmin.GetInstance]. message GetInstanceRequest { // Required. The name of the requested instance. Values are of the form // `projects//instances/`. - string name = 1; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Instance" + } + ]; } -// The request for -// [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance]. +// The request for [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance]. message CreateInstanceRequest { // Required. The name of the project in which to create the instance. Values // are of the form `projects/`. - string parent = 1; + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "cloudresourcemanager.googleapis.com/Project" + } + ]; // Required. The ID of the instance to create. Valid identifiers are of the - // form `[a-z][-a-z0-9]*[a-z0-9]` and must be between 6 and 30 characters in + // form `[a-z][-a-z0-9]*[a-z0-9]` and must be between 2 and 64 characters in // length. - string instance_id = 2; + string instance_id = 2 [(google.api.field_behavior) = REQUIRED]; // Required. The instance to create. The name may be omitted, but if // specified must be `/instances/`. - Instance instance = 3; + Instance instance = 3 [(google.api.field_behavior) = REQUIRED]; } -// The request for -// [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances]. +// The request for [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances]. message ListInstancesRequest { // Required. The name of the project for which a list of instances is // requested. Values are of the form `projects/`. - string parent = 1; + string parent = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "cloudresourcemanager.googleapis.com/Project" + } + ]; // Number of instances to be returned in the response. If 0 or less, defaults // to the server's maximum allowed page size. int32 page_size = 2; // If non-empty, `page_token` should contain a - // [next_page_token][google.spanner.admin.instance.v1.ListInstancesResponse.next_page_token] - // from a previous - // [ListInstancesResponse][google.spanner.admin.instance.v1.ListInstancesResponse]. + // [next_page_token][google.spanner.admin.instance.v1.ListInstancesResponse.next_page_token] from a + // previous [ListInstancesResponse][google.spanner.admin.instance.v1.ListInstancesResponse]. string page_token = 3; // An expression for filtering the results of the request. Filter rules are @@ -417,42 +520,40 @@ message ListInstancesRequest { string filter = 4; } -// The response for -// [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances]. +// The response for [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances]. message ListInstancesResponse { // The list of requested instances. repeated Instance instances = 1; // `next_page_token` can be sent in a subsequent - // [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances] - // call to fetch more of the matching instances. + // [ListInstances][google.spanner.admin.instance.v1.InstanceAdmin.ListInstances] call to fetch more + // of the matching instances. string next_page_token = 2; } -// The request for -// [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance]. +// The request for [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance]. message UpdateInstanceRequest { // Required. The instance to update, which must always include the instance - // name. Otherwise, only fields mentioned in - // [][google.spanner.admin.instance.v1.UpdateInstanceRequest.field_mask] need - // be included. - Instance instance = 1; - - // Required. A mask specifying which fields in - // [][google.spanner.admin.instance.v1.UpdateInstanceRequest.instance] should - // be updated. The field mask must always be specified; this prevents any - // future fields in - // [][google.spanner.admin.instance.v1.Instance] from being erased - // accidentally by clients that do not know about them. - google.protobuf.FieldMask field_mask = 2; + // name. Otherwise, only fields mentioned in [][google.spanner.admin.instance.v1.UpdateInstanceRequest.field_mask] need be included. + Instance instance = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. A mask specifying which fields in [][google.spanner.admin.instance.v1.UpdateInstanceRequest.instance] should be updated. + // The field mask must always be specified; this prevents any future fields in + // [][google.spanner.admin.instance.v1.Instance] from being erased accidentally by clients that do not know + // about them. + google.protobuf.FieldMask field_mask = 2 [(google.api.field_behavior) = REQUIRED]; } -// The request for -// [DeleteInstance][google.spanner.admin.instance.v1.InstanceAdmin.DeleteInstance]. +// The request for [DeleteInstance][google.spanner.admin.instance.v1.InstanceAdmin.DeleteInstance]. message DeleteInstanceRequest { // Required. The name of the instance to be deleted. Values are of the form // `projects//instances/` - string name = 1; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Instance" + } + ]; } // Metadata type for the operation returned by @@ -462,8 +563,8 @@ message CreateInstanceMetadata { Instance instance = 1; // The time at which the - // [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance] - // request was received. + // [CreateInstance][google.spanner.admin.instance.v1.InstanceAdmin.CreateInstance] request was + // received. google.protobuf.Timestamp start_time = 2; // The time at which this operation was cancelled. If set, this operation is @@ -481,8 +582,7 @@ message UpdateInstanceMetadata { // The desired end state of the update. Instance instance = 1; - // The time at which - // [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance] + // The time at which [UpdateInstance][google.spanner.admin.instance.v1.InstanceAdmin.UpdateInstance] // request was received. google.protobuf.Timestamp start_time = 2; diff --git a/spanner/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin_pb2.py b/spanner/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin_pb2.py index 2e16c4a16681..d1fe569a9fe1 100644 --- a/spanner/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin_pb2.py +++ b/spanner/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin_pb2.py @@ -16,6 +16,9 @@ from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2 +from google.api import client_pb2 as google_dot_api_dot_client__pb2 +from google.api import field_behavior_pb2 as google_dot_api_dot_field__behavior__pb2 +from google.api import resource_pb2 as google_dot_api_dot_resource__pb2 from google.iam.v1 import iam_policy_pb2 as google_dot_iam_dot_v1_dot_iam__policy__pb2 from google.iam.v1 import policy_pb2 as google_dot_iam_dot_v1_dot_policy__pb2 from google.longrunning import ( @@ -34,10 +37,13 @@ "\n$com.google.spanner.admin.instance.v1B\031SpannerInstanceAdminProtoP\001ZHgoogle.golang.org/genproto/googleapis/spanner/admin/instance/v1;instance\252\002&Google.Cloud.Spanner.Admin.Instance.V1\312\002&Google\\Cloud\\Spanner\\Admin\\Instance\\V1" ), serialized_pb=_b( - '\nIgoogle/cloud/spanner/admin/instance_v1/proto/spanner_instance_admin.proto\x12 google.spanner.admin.instance.v1\x1a\x1cgoogle/api/annotations.proto\x1a\x1egoogle/iam/v1/iam_policy.proto\x1a\x1agoogle/iam/v1/policy.proto\x1a#google/longrunning/operations.proto\x1a\x1bgoogle/protobuf/empty.proto\x1a google/protobuf/field_mask.proto\x1a\x1fgoogle/protobuf/timestamp.proto"4\n\x0eInstanceConfig\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x14\n\x0c\x64isplay_name\x18\x02 \x01(\t"\xc3\x02\n\x08Instance\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x0e\n\x06\x63onfig\x18\x02 \x01(\t\x12\x14\n\x0c\x64isplay_name\x18\x03 \x01(\t\x12\x12\n\nnode_count\x18\x05 \x01(\x05\x12?\n\x05state\x18\x06 \x01(\x0e\x32\x30.google.spanner.admin.instance.v1.Instance.State\x12\x46\n\x06labels\x18\x07 \x03(\x0b\x32\x36.google.spanner.admin.instance.v1.Instance.LabelsEntry\x1a-\n\x0bLabelsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01"7\n\x05State\x12\x15\n\x11STATE_UNSPECIFIED\x10\x00\x12\x0c\n\x08\x43REATING\x10\x01\x12\t\n\x05READY\x10\x02"S\n\x1aListInstanceConfigsRequest\x12\x0e\n\x06parent\x18\x01 \x01(\t\x12\x11\n\tpage_size\x18\x02 \x01(\x05\x12\x12\n\npage_token\x18\x03 \x01(\t"\x82\x01\n\x1bListInstanceConfigsResponse\x12J\n\x10instance_configs\x18\x01 \x03(\x0b\x32\x30.google.spanner.admin.instance.v1.InstanceConfig\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t"(\n\x18GetInstanceConfigRequest\x12\x0c\n\x04name\x18\x01 \x01(\t""\n\x12GetInstanceRequest\x12\x0c\n\x04name\x18\x01 \x01(\t"z\n\x15\x43reateInstanceRequest\x12\x0e\n\x06parent\x18\x01 \x01(\t\x12\x13\n\x0binstance_id\x18\x02 \x01(\t\x12<\n\x08instance\x18\x03 \x01(\x0b\x32*.google.spanner.admin.instance.v1.Instance"]\n\x14ListInstancesRequest\x12\x0e\n\x06parent\x18\x01 \x01(\t\x12\x11\n\tpage_size\x18\x02 \x01(\x05\x12\x12\n\npage_token\x18\x03 \x01(\t\x12\x0e\n\x06\x66ilter\x18\x04 \x01(\t"o\n\x15ListInstancesResponse\x12=\n\tinstances\x18\x01 \x03(\x0b\x32*.google.spanner.admin.instance.v1.Instance\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t"\x85\x01\n\x15UpdateInstanceRequest\x12<\n\x08instance\x18\x01 \x01(\x0b\x32*.google.spanner.admin.instance.v1.Instance\x12.\n\nfield_mask\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.FieldMask"%\n\x15\x44\x65leteInstanceRequest\x12\x0c\n\x04name\x18\x01 \x01(\t"\xe5\x01\n\x16\x43reateInstanceMetadata\x12<\n\x08instance\x18\x01 \x01(\x0b\x32*.google.spanner.admin.instance.v1.Instance\x12.\n\nstart_time\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12/\n\x0b\x63\x61ncel_time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12,\n\x08\x65nd_time\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp"\xe5\x01\n\x16UpdateInstanceMetadata\x12<\n\x08instance\x18\x01 \x01(\x0b\x32*.google.spanner.admin.instance.v1.Instance\x12.\n\nstart_time\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12/\n\x0b\x63\x61ncel_time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12,\n\x08\x65nd_time\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp2\xe6\x0c\n\rInstanceAdmin\x12\xc3\x01\n\x13ListInstanceConfigs\x12<.google.spanner.admin.instance.v1.ListInstanceConfigsRequest\x1a=.google.spanner.admin.instance.v1.ListInstanceConfigsResponse"/\x82\xd3\xe4\x93\x02)\x12\'/v1/{parent=projects/*}/instanceConfigs\x12\xb2\x01\n\x11GetInstanceConfig\x12:.google.spanner.admin.instance.v1.GetInstanceConfigRequest\x1a\x30.google.spanner.admin.instance.v1.InstanceConfig"/\x82\xd3\xe4\x93\x02)\x12\'/v1/{name=projects/*/instanceConfigs/*}\x12\xab\x01\n\rListInstances\x12\x36.google.spanner.admin.instance.v1.ListInstancesRequest\x1a\x37.google.spanner.admin.instance.v1.ListInstancesResponse")\x82\xd3\xe4\x93\x02#\x12!/v1/{parent=projects/*}/instances\x12\x9a\x01\n\x0bGetInstance\x12\x34.google.spanner.admin.instance.v1.GetInstanceRequest\x1a*.google.spanner.admin.instance.v1.Instance")\x82\xd3\xe4\x93\x02#\x12!/v1/{name=projects/*/instances/*}\x12\x96\x01\n\x0e\x43reateInstance\x12\x37.google.spanner.admin.instance.v1.CreateInstanceRequest\x1a\x1d.google.longrunning.Operation",\x82\xd3\xe4\x93\x02&"!/v1/{parent=projects/*}/instances:\x01*\x12\x9f\x01\n\x0eUpdateInstance\x12\x37.google.spanner.admin.instance.v1.UpdateInstanceRequest\x1a\x1d.google.longrunning.Operation"5\x82\xd3\xe4\x93\x02/2*/v1/{instance.name=projects/*/instances/*}:\x01*\x12\x8c\x01\n\x0e\x44\x65leteInstance\x12\x37.google.spanner.admin.instance.v1.DeleteInstanceRequest\x1a\x16.google.protobuf.Empty")\x82\xd3\xe4\x93\x02#*!/v1/{name=projects/*/instances/*}\x12\x88\x01\n\x0cSetIamPolicy\x12".google.iam.v1.SetIamPolicyRequest\x1a\x15.google.iam.v1.Policy"=\x82\xd3\xe4\x93\x02\x37"2/v1/{resource=projects/*/instances/*}:setIamPolicy:\x01*\x12\x88\x01\n\x0cGetIamPolicy\x12".google.iam.v1.GetIamPolicyRequest\x1a\x15.google.iam.v1.Policy"=\x82\xd3\xe4\x93\x02\x37"2/v1/{resource=projects/*/instances/*}:getIamPolicy:\x01*\x12\xae\x01\n\x12TestIamPermissions\x12(.google.iam.v1.TestIamPermissionsRequest\x1a).google.iam.v1.TestIamPermissionsResponse"C\x82\xd3\xe4\x93\x02="8/v1/{resource=projects/*/instances/*}:testIamPermissions:\x01*B\xdf\x01\n$com.google.spanner.admin.instance.v1B\x19SpannerInstanceAdminProtoP\x01ZHgoogle.golang.org/genproto/googleapis/spanner/admin/instance/v1;instance\xaa\x02&Google.Cloud.Spanner.Admin.Instance.V1\xca\x02&Google\\Cloud\\Spanner\\Admin\\Instance\\V1b\x06proto3' + '\nIgoogle/cloud/spanner/admin/instance_v1/proto/spanner_instance_admin.proto\x12 google.spanner.admin.instance.v1\x1a\x1cgoogle/api/annotations.proto\x1a\x17google/api/client.proto\x1a\x1fgoogle/api/field_behavior.proto\x1a\x19google/api/resource.proto\x1a\x1egoogle/iam/v1/iam_policy.proto\x1a\x1agoogle/iam/v1/policy.proto\x1a#google/longrunning/operations.proto\x1a\x1bgoogle/protobuf/empty.proto\x1a google/protobuf/field_mask.proto\x1a\x1fgoogle/protobuf/timestamp.proto"\xda\x01\n\x0bReplicaInfo\x12\x10\n\x08location\x18\x01 \x01(\t\x12G\n\x04type\x18\x02 \x01(\x0e\x32\x39.google.spanner.admin.instance.v1.ReplicaInfo.ReplicaType\x12\x1f\n\x17\x64\x65\x66\x61ult_leader_location\x18\x03 \x01(\x08"O\n\x0bReplicaType\x12\x14\n\x10TYPE_UNSPECIFIED\x10\x00\x12\x0e\n\nREAD_WRITE\x10\x01\x12\r\n\tREAD_ONLY\x10\x02\x12\x0b\n\x07WITNESS\x10\x03"\xd7\x01\n\x0eInstanceConfig\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x14\n\x0c\x64isplay_name\x18\x02 \x01(\t\x12?\n\x08replicas\x18\x03 \x03(\x0b\x32-.google.spanner.admin.instance.v1.ReplicaInfo:`\xea\x41]\n%spanner.googleapis.com/InstanceConfig\x12\x34projects/{project}/instanceConfigs/{instance_config}"\xbe\x03\n\x08Instance\x12\x0c\n\x04name\x18\x01 \x01(\t\x12:\n\x06\x63onfig\x18\x02 \x01(\tB*\xfa\x41\'\n%spanner.googleapis.com/InstanceConfig\x12\x14\n\x0c\x64isplay_name\x18\x03 \x01(\t\x12\x12\n\nnode_count\x18\x05 \x01(\x05\x12?\n\x05state\x18\x06 \x01(\x0e\x32\x30.google.spanner.admin.instance.v1.Instance.State\x12\x46\n\x06labels\x18\x07 \x03(\x0b\x32\x36.google.spanner.admin.instance.v1.Instance.LabelsEntry\x1a-\n\x0bLabelsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01"7\n\x05State\x12\x15\n\x11STATE_UNSPECIFIED\x10\x00\x12\x0c\n\x08\x43REATING\x10\x01\x12\t\n\x05READY\x10\x02:M\xea\x41J\n\x1fspanner.googleapis.com/Instance\x12\'projects/{project}/instances/{instance}"\x88\x01\n\x1aListInstanceConfigsRequest\x12\x43\n\x06parent\x18\x01 \x01(\tB3\xe0\x41\x02\xfa\x41-\n+cloudresourcemanager.googleapis.com/Project\x12\x11\n\tpage_size\x18\x02 \x01(\x05\x12\x12\n\npage_token\x18\x03 \x01(\t"\x82\x01\n\x1bListInstanceConfigsResponse\x12J\n\x10instance_configs\x18\x01 \x03(\x0b\x32\x30.google.spanner.admin.instance.v1.InstanceConfig\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t"W\n\x18GetInstanceConfigRequest\x12;\n\x04name\x18\x01 \x01(\tB-\xe0\x41\x02\xfa\x41\'\n%spanner.googleapis.com/InstanceConfig"K\n\x12GetInstanceRequest\x12\x35\n\x04name\x18\x01 \x01(\tB\'\xe0\x41\x02\xfa\x41!\n\x1fspanner.googleapis.com/Instance"\xb9\x01\n\x15\x43reateInstanceRequest\x12\x43\n\x06parent\x18\x01 \x01(\tB3\xe0\x41\x02\xfa\x41-\n+cloudresourcemanager.googleapis.com/Project\x12\x18\n\x0binstance_id\x18\x02 \x01(\tB\x03\xe0\x41\x02\x12\x41\n\x08instance\x18\x03 \x01(\x0b\x32*.google.spanner.admin.instance.v1.InstanceB\x03\xe0\x41\x02"\x92\x01\n\x14ListInstancesRequest\x12\x43\n\x06parent\x18\x01 \x01(\tB3\xe0\x41\x02\xfa\x41-\n+cloudresourcemanager.googleapis.com/Project\x12\x11\n\tpage_size\x18\x02 \x01(\x05\x12\x12\n\npage_token\x18\x03 \x01(\t\x12\x0e\n\x06\x66ilter\x18\x04 \x01(\t"o\n\x15ListInstancesResponse\x12=\n\tinstances\x18\x01 \x03(\x0b\x32*.google.spanner.admin.instance.v1.Instance\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t"\x8f\x01\n\x15UpdateInstanceRequest\x12\x41\n\x08instance\x18\x01 \x01(\x0b\x32*.google.spanner.admin.instance.v1.InstanceB\x03\xe0\x41\x02\x12\x33\n\nfield_mask\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.FieldMaskB\x03\xe0\x41\x02"N\n\x15\x44\x65leteInstanceRequest\x12\x35\n\x04name\x18\x01 \x01(\tB\'\xe0\x41\x02\xfa\x41!\n\x1fspanner.googleapis.com/Instance"\xe5\x01\n\x16\x43reateInstanceMetadata\x12<\n\x08instance\x18\x01 \x01(\x0b\x32*.google.spanner.admin.instance.v1.Instance\x12.\n\nstart_time\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12/\n\x0b\x63\x61ncel_time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12,\n\x08\x65nd_time\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp"\xe5\x01\n\x16UpdateInstanceMetadata\x12<\n\x08instance\x18\x01 \x01(\x0b\x32*.google.spanner.admin.instance.v1.Instance\x12.\n\nstart_time\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12/\n\x0b\x63\x61ncel_time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12,\n\x08\x65nd_time\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp2\xbf\x10\n\rInstanceAdmin\x12\xcc\x01\n\x13ListInstanceConfigs\x12<.google.spanner.admin.instance.v1.ListInstanceConfigsRequest\x1a=.google.spanner.admin.instance.v1.ListInstanceConfigsResponse"8\x82\xd3\xe4\x93\x02)\x12\'/v1/{parent=projects/*}/instanceConfigs\xda\x41\x06parent\x12\xb9\x01\n\x11GetInstanceConfig\x12:.google.spanner.admin.instance.v1.GetInstanceConfigRequest\x1a\x30.google.spanner.admin.instance.v1.InstanceConfig"6\x82\xd3\xe4\x93\x02)\x12\'/v1/{name=projects/*/instanceConfigs/*}\xda\x41\x04name\x12\xb4\x01\n\rListInstances\x12\x36.google.spanner.admin.instance.v1.ListInstancesRequest\x1a\x37.google.spanner.admin.instance.v1.ListInstancesResponse"2\x82\xd3\xe4\x93\x02#\x12!/v1/{parent=projects/*}/instances\xda\x41\x06parent\x12\xa1\x01\n\x0bGetInstance\x12\x34.google.spanner.admin.instance.v1.GetInstanceRequest\x1a*.google.spanner.admin.instance.v1.Instance"0\x82\xd3\xe4\x93\x02#\x12!/v1/{name=projects/*/instances/*}\xda\x41\x04name\x12\x9c\x02\n\x0e\x43reateInstance\x12\x37.google.spanner.admin.instance.v1.CreateInstanceRequest\x1a\x1d.google.longrunning.Operation"\xb1\x01\x82\xd3\xe4\x93\x02&"!/v1/{parent=projects/*}/instances:\x01*\xda\x41\x1bparent,instance_id,instance\xca\x41\x64\n)google.spanner.admin.instance.v1.Instance\x12\x37google.spanner.admin.instance.v1.CreateInstanceMetadata\x12\x9d\x02\n\x0eUpdateInstance\x12\x37.google.spanner.admin.instance.v1.UpdateInstanceRequest\x1a\x1d.google.longrunning.Operation"\xb2\x01\x82\xd3\xe4\x93\x02/2*/v1/{instance.name=projects/*/instances/*}:\x01*\xda\x41\x13instance,field_mask\xca\x41\x64\n)google.spanner.admin.instance.v1.Instance\x12\x37google.spanner.admin.instance.v1.UpdateInstanceMetadata\x12\x93\x01\n\x0e\x44\x65leteInstance\x12\x37.google.spanner.admin.instance.v1.DeleteInstanceRequest\x1a\x16.google.protobuf.Empty"0\x82\xd3\xe4\x93\x02#*!/v1/{name=projects/*/instances/*}\xda\x41\x04name\x12\x9a\x01\n\x0cSetIamPolicy\x12".google.iam.v1.SetIamPolicyRequest\x1a\x15.google.iam.v1.Policy"O\x82\xd3\xe4\x93\x02\x37"2/v1/{resource=projects/*/instances/*}:setIamPolicy:\x01*\xda\x41\x0fresource,policy\x12\x93\x01\n\x0cGetIamPolicy\x12".google.iam.v1.GetIamPolicyRequest\x1a\x15.google.iam.v1.Policy"H\x82\xd3\xe4\x93\x02\x37"2/v1/{resource=projects/*/instances/*}:getIamPolicy:\x01*\xda\x41\x08resource\x12\xc5\x01\n\x12TestIamPermissions\x12(.google.iam.v1.TestIamPermissionsRequest\x1a).google.iam.v1.TestIamPermissionsResponse"Z\x82\xd3\xe4\x93\x02="8/v1/{resource=projects/*/instances/*}:testIamPermissions:\x01*\xda\x41\x14resource,permissions\x1ax\xca\x41\x16spanner.googleapis.com\xd2\x41\\https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spanner.adminB\xdf\x01\n$com.google.spanner.admin.instance.v1B\x19SpannerInstanceAdminProtoP\x01ZHgoogle.golang.org/genproto/googleapis/spanner/admin/instance/v1;instance\xaa\x02&Google.Cloud.Spanner.Admin.Instance.V1\xca\x02&Google\\Cloud\\Spanner\\Admin\\Instance\\V1b\x06proto3' ), dependencies=[ google_dot_api_dot_annotations__pb2.DESCRIPTOR, + google_dot_api_dot_client__pb2.DESCRIPTOR, + google_dot_api_dot_field__behavior__pb2.DESCRIPTOR, + google_dot_api_dot_resource__pb2.DESCRIPTOR, google_dot_iam_dot_v1_dot_iam__policy__pb2.DESCRIPTOR, google_dot_iam_dot_v1_dot_policy__pb2.DESCRIPTOR, google_dot_longrunning_dot_operations__pb2.DESCRIPTOR, @@ -48,6 +54,36 @@ ) +_REPLICAINFO_REPLICATYPE = _descriptor.EnumDescriptor( + name="ReplicaType", + full_name="google.spanner.admin.instance.v1.ReplicaInfo.ReplicaType", + filename=None, + file=DESCRIPTOR, + values=[ + _descriptor.EnumValueDescriptor( + name="TYPE_UNSPECIFIED", + index=0, + number=0, + serialized_options=None, + type=None, + ), + _descriptor.EnumValueDescriptor( + name="READ_WRITE", index=1, number=1, serialized_options=None, type=None + ), + _descriptor.EnumValueDescriptor( + name="READ_ONLY", index=2, number=2, serialized_options=None, type=None + ), + _descriptor.EnumValueDescriptor( + name="WITNESS", index=3, number=3, serialized_options=None, type=None + ), + ], + containing_type=None, + serialized_options=None, + serialized_start=559, + serialized_end=638, +) +_sym_db.RegisterEnumDescriptor(_REPLICAINFO_REPLICATYPE) + _INSTANCE_STATE = _descriptor.EnumDescriptor( name="State", full_name="google.spanner.admin.instance.v1.Instance.State", @@ -70,12 +106,87 @@ ], containing_type=None, serialized_options=None, - serialized_start=657, - serialized_end=712, + serialized_start=1171, + serialized_end=1226, ) _sym_db.RegisterEnumDescriptor(_INSTANCE_STATE) +_REPLICAINFO = _descriptor.Descriptor( + name="ReplicaInfo", + full_name="google.spanner.admin.instance.v1.ReplicaInfo", + filename=None, + file=DESCRIPTOR, + containing_type=None, + fields=[ + _descriptor.FieldDescriptor( + name="location", + full_name="google.spanner.admin.instance.v1.ReplicaInfo.location", + index=0, + number=1, + type=9, + cpp_type=9, + label=1, + has_default_value=False, + default_value=_b("").decode("utf-8"), + message_type=None, + enum_type=None, + containing_type=None, + is_extension=False, + extension_scope=None, + serialized_options=None, + file=DESCRIPTOR, + ), + _descriptor.FieldDescriptor( + name="type", + full_name="google.spanner.admin.instance.v1.ReplicaInfo.type", + index=1, + number=2, + type=14, + cpp_type=8, + label=1, + has_default_value=False, + default_value=0, + message_type=None, + enum_type=None, + containing_type=None, + is_extension=False, + extension_scope=None, + serialized_options=None, + file=DESCRIPTOR, + ), + _descriptor.FieldDescriptor( + name="default_leader_location", + full_name="google.spanner.admin.instance.v1.ReplicaInfo.default_leader_location", + index=2, + number=3, + type=8, + cpp_type=7, + label=1, + has_default_value=False, + default_value=False, + message_type=None, + enum_type=None, + containing_type=None, + is_extension=False, + extension_scope=None, + serialized_options=None, + file=DESCRIPTOR, + ), + ], + extensions=[], + nested_types=[], + enum_types=[_REPLICAINFO_REPLICATYPE], + serialized_options=None, + is_extendable=False, + syntax="proto3", + extension_ranges=[], + oneofs=[], + serialized_start=420, + serialized_end=638, +) + + _INSTANCECONFIG = _descriptor.Descriptor( name="InstanceConfig", full_name="google.spanner.admin.instance.v1.InstanceConfig", @@ -119,17 +230,37 @@ serialized_options=None, file=DESCRIPTOR, ), + _descriptor.FieldDescriptor( + name="replicas", + full_name="google.spanner.admin.instance.v1.InstanceConfig.replicas", + index=2, + number=3, + type=11, + cpp_type=10, + label=3, + has_default_value=False, + default_value=[], + message_type=None, + enum_type=None, + containing_type=None, + is_extension=False, + extension_scope=None, + serialized_options=None, + file=DESCRIPTOR, + ), ], extensions=[], nested_types=[], enum_types=[], - serialized_options=None, + serialized_options=_b( + "\352A]\n%spanner.googleapis.com/InstanceConfig\0224projects/{project}/instanceConfigs/{instance_config}" + ), is_extendable=False, syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=334, - serialized_end=386, + serialized_start=641, + serialized_end=856, ) @@ -185,8 +316,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=610, - serialized_end=655, + serialized_start=1124, + serialized_end=1169, ) _INSTANCE = _descriptor.Descriptor( @@ -229,7 +360,7 @@ containing_type=None, is_extension=False, extension_scope=None, - serialized_options=None, + serialized_options=_b("\372A'\n%spanner.googleapis.com/InstanceConfig"), file=DESCRIPTOR, ), _descriptor.FieldDescriptor( @@ -308,13 +439,15 @@ extensions=[], nested_types=[_INSTANCE_LABELSENTRY], enum_types=[_INSTANCE_STATE], - serialized_options=None, + serialized_options=_b( + "\352AJ\n\037spanner.googleapis.com/Instance\022'projects/{project}/instances/{instance}" + ), is_extendable=False, syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=389, - serialized_end=712, + serialized_start=859, + serialized_end=1305, ) @@ -340,7 +473,9 @@ containing_type=None, is_extension=False, extension_scope=None, - serialized_options=None, + serialized_options=_b( + "\340A\002\372A-\n+cloudresourcemanager.googleapis.com/Project" + ), file=DESCRIPTOR, ), _descriptor.FieldDescriptor( @@ -388,8 +523,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=714, - serialized_end=797, + serialized_start=1308, + serialized_end=1444, ) @@ -445,8 +580,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=800, - serialized_end=930, + serialized_start=1447, + serialized_end=1577, ) @@ -472,7 +607,9 @@ containing_type=None, is_extension=False, extension_scope=None, - serialized_options=None, + serialized_options=_b( + "\340A\002\372A'\n%spanner.googleapis.com/InstanceConfig" + ), file=DESCRIPTOR, ) ], @@ -484,8 +621,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=932, - serialized_end=972, + serialized_start=1579, + serialized_end=1666, ) @@ -511,7 +648,9 @@ containing_type=None, is_extension=False, extension_scope=None, - serialized_options=None, + serialized_options=_b( + "\340A\002\372A!\n\037spanner.googleapis.com/Instance" + ), file=DESCRIPTOR, ) ], @@ -523,8 +662,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=974, - serialized_end=1008, + serialized_start=1668, + serialized_end=1743, ) @@ -550,7 +689,9 @@ containing_type=None, is_extension=False, extension_scope=None, - serialized_options=None, + serialized_options=_b( + "\340A\002\372A-\n+cloudresourcemanager.googleapis.com/Project" + ), file=DESCRIPTOR, ), _descriptor.FieldDescriptor( @@ -568,7 +709,7 @@ containing_type=None, is_extension=False, extension_scope=None, - serialized_options=None, + serialized_options=_b("\340A\002"), file=DESCRIPTOR, ), _descriptor.FieldDescriptor( @@ -586,7 +727,7 @@ containing_type=None, is_extension=False, extension_scope=None, - serialized_options=None, + serialized_options=_b("\340A\002"), file=DESCRIPTOR, ), ], @@ -598,8 +739,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1010, - serialized_end=1132, + serialized_start=1746, + serialized_end=1931, ) @@ -625,7 +766,9 @@ containing_type=None, is_extension=False, extension_scope=None, - serialized_options=None, + serialized_options=_b( + "\340A\002\372A-\n+cloudresourcemanager.googleapis.com/Project" + ), file=DESCRIPTOR, ), _descriptor.FieldDescriptor( @@ -691,8 +834,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1134, - serialized_end=1227, + serialized_start=1934, + serialized_end=2080, ) @@ -748,8 +891,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1229, - serialized_end=1340, + serialized_start=2082, + serialized_end=2193, ) @@ -775,7 +918,7 @@ containing_type=None, is_extension=False, extension_scope=None, - serialized_options=None, + serialized_options=_b("\340A\002"), file=DESCRIPTOR, ), _descriptor.FieldDescriptor( @@ -793,7 +936,7 @@ containing_type=None, is_extension=False, extension_scope=None, - serialized_options=None, + serialized_options=_b("\340A\002"), file=DESCRIPTOR, ), ], @@ -805,8 +948,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1343, - serialized_end=1476, + serialized_start=2196, + serialized_end=2339, ) @@ -832,7 +975,9 @@ containing_type=None, is_extension=False, extension_scope=None, - serialized_options=None, + serialized_options=_b( + "\340A\002\372A!\n\037spanner.googleapis.com/Instance" + ), file=DESCRIPTOR, ) ], @@ -844,8 +989,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1478, - serialized_end=1515, + serialized_start=2341, + serialized_end=2419, ) @@ -937,8 +1082,8 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1518, - serialized_end=1747, + serialized_start=2422, + serialized_end=2651, ) @@ -1030,10 +1175,13 @@ syntax="proto3", extension_ranges=[], oneofs=[], - serialized_start=1750, - serialized_end=1979, + serialized_start=2654, + serialized_end=2883, ) +_REPLICAINFO.fields_by_name["type"].enum_type = _REPLICAINFO_REPLICATYPE +_REPLICAINFO_REPLICATYPE.containing_type = _REPLICAINFO +_INSTANCECONFIG.fields_by_name["replicas"].message_type = _REPLICAINFO _INSTANCE_LABELSENTRY.containing_type = _INSTANCE _INSTANCE.fields_by_name["state"].enum_type = _INSTANCE_STATE _INSTANCE.fields_by_name["labels"].message_type = _INSTANCE_LABELSENTRY @@ -1067,6 +1215,7 @@ _UPDATEINSTANCEMETADATA.fields_by_name[ "end_time" ].message_type = google_dot_protobuf_dot_timestamp__pb2._TIMESTAMP +DESCRIPTOR.message_types_by_name["ReplicaInfo"] = _REPLICAINFO DESCRIPTOR.message_types_by_name["InstanceConfig"] = _INSTANCECONFIG DESCRIPTOR.message_types_by_name["Instance"] = _INSTANCE DESCRIPTOR.message_types_by_name[ @@ -1086,6 +1235,30 @@ DESCRIPTOR.message_types_by_name["UpdateInstanceMetadata"] = _UPDATEINSTANCEMETADATA _sym_db.RegisterFileDescriptor(DESCRIPTOR) +ReplicaInfo = _reflection.GeneratedProtocolMessageType( + "ReplicaInfo", + (_message.Message,), + dict( + DESCRIPTOR=_REPLICAINFO, + __module__="google.cloud.spanner.admin.instance_v1.proto.spanner_instance_admin_pb2", + __doc__="""Protocol buffer. + + Attributes: + location: + The location of the serving resources, e.g. "us-central1". + type: + The type of replica. + default_leader_location: + If true, this location is designated as the default leader + location where leader replicas are placed. See the `region + types documentation `__ for more details. + """, + # @@protoc_insertion_point(class_scope:google.spanner.admin.instance.v1.ReplicaInfo) + ), +) +_sym_db.RegisterMessage(ReplicaInfo) + InstanceConfig = _reflection.GeneratedProtocolMessageType( "InstanceConfig", (_message.Message,), @@ -1103,6 +1276,9 @@ ``projects//instanceConfigs/[a-z][-a-z0-9]*`` display_name: The name of this instance configuration as it appears in UIs. + replicas: + The geographic placement of nodes in this instance + configuration and their replication properties. """, # @@protoc_insertion_point(class_scope:google.spanner.admin.instance.v1.InstanceConfig) ), @@ -1133,7 +1309,7 @@ Required. A unique identifier for the instance, which cannot be changed after the instance is created. Values are of the form ``projects//instances/[a-z][-a-z0-9]*[a-z0-9]``. - The final segment of the name must be between 6 and 30 + The final segment of the name must be between 2 and 64 characters in length. config: Required. The name of the instance's configuration. Values are @@ -1301,7 +1477,7 @@ instance_id: Required. The ID of the instance to create. Valid identifiers are of the form ``[a-z][-a-z0-9]*[a-z0-9]`` and must be - between 6 and 30 characters in length. + between 2 and 64 characters in length. instance: Required. The instance to create. The name may be omitted, but if specified must be ``/instances/``. @@ -1486,16 +1662,31 @@ DESCRIPTOR._options = None +_INSTANCECONFIG._options = None _INSTANCE_LABELSENTRY._options = None +_INSTANCE.fields_by_name["config"]._options = None +_INSTANCE._options = None +_LISTINSTANCECONFIGSREQUEST.fields_by_name["parent"]._options = None +_GETINSTANCECONFIGREQUEST.fields_by_name["name"]._options = None +_GETINSTANCEREQUEST.fields_by_name["name"]._options = None +_CREATEINSTANCEREQUEST.fields_by_name["parent"]._options = None +_CREATEINSTANCEREQUEST.fields_by_name["instance_id"]._options = None +_CREATEINSTANCEREQUEST.fields_by_name["instance"]._options = None +_LISTINSTANCESREQUEST.fields_by_name["parent"]._options = None +_UPDATEINSTANCEREQUEST.fields_by_name["instance"]._options = None +_UPDATEINSTANCEREQUEST.fields_by_name["field_mask"]._options = None +_DELETEINSTANCEREQUEST.fields_by_name["name"]._options = None _INSTANCEADMIN = _descriptor.ServiceDescriptor( name="InstanceAdmin", full_name="google.spanner.admin.instance.v1.InstanceAdmin", file=DESCRIPTOR, index=0, - serialized_options=None, - serialized_start=1982, - serialized_end=3620, + serialized_options=_b( + "\312A\026spanner.googleapis.com\322A\\https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spanner.admin" + ), + serialized_start=2886, + serialized_end=4997, methods=[ _descriptor.MethodDescriptor( name="ListInstanceConfigs", @@ -1505,7 +1696,7 @@ input_type=_LISTINSTANCECONFIGSREQUEST, output_type=_LISTINSTANCECONFIGSRESPONSE, serialized_options=_b( - "\202\323\344\223\002)\022'/v1/{parent=projects/*}/instanceConfigs" + "\202\323\344\223\002)\022'/v1/{parent=projects/*}/instanceConfigs\332A\006parent" ), ), _descriptor.MethodDescriptor( @@ -1516,7 +1707,7 @@ input_type=_GETINSTANCECONFIGREQUEST, output_type=_INSTANCECONFIG, serialized_options=_b( - "\202\323\344\223\002)\022'/v1/{name=projects/*/instanceConfigs/*}" + "\202\323\344\223\002)\022'/v1/{name=projects/*/instanceConfigs/*}\332A\004name" ), ), _descriptor.MethodDescriptor( @@ -1527,7 +1718,7 @@ input_type=_LISTINSTANCESREQUEST, output_type=_LISTINSTANCESRESPONSE, serialized_options=_b( - "\202\323\344\223\002#\022!/v1/{parent=projects/*}/instances" + "\202\323\344\223\002#\022!/v1/{parent=projects/*}/instances\332A\006parent" ), ), _descriptor.MethodDescriptor( @@ -1538,7 +1729,7 @@ input_type=_GETINSTANCEREQUEST, output_type=_INSTANCE, serialized_options=_b( - "\202\323\344\223\002#\022!/v1/{name=projects/*/instances/*}" + "\202\323\344\223\002#\022!/v1/{name=projects/*/instances/*}\332A\004name" ), ), _descriptor.MethodDescriptor( @@ -1549,7 +1740,7 @@ input_type=_CREATEINSTANCEREQUEST, output_type=google_dot_longrunning_dot_operations__pb2._OPERATION, serialized_options=_b( - '\202\323\344\223\002&"!/v1/{parent=projects/*}/instances:\001*' + '\202\323\344\223\002&"!/v1/{parent=projects/*}/instances:\001*\332A\033parent,instance_id,instance\312Ad\n)google.spanner.admin.instance.v1.Instance\0227google.spanner.admin.instance.v1.CreateInstanceMetadata' ), ), _descriptor.MethodDescriptor( @@ -1560,7 +1751,7 @@ input_type=_UPDATEINSTANCEREQUEST, output_type=google_dot_longrunning_dot_operations__pb2._OPERATION, serialized_options=_b( - "\202\323\344\223\002/2*/v1/{instance.name=projects/*/instances/*}:\001*" + "\202\323\344\223\002/2*/v1/{instance.name=projects/*/instances/*}:\001*\332A\023instance,field_mask\312Ad\n)google.spanner.admin.instance.v1.Instance\0227google.spanner.admin.instance.v1.UpdateInstanceMetadata" ), ), _descriptor.MethodDescriptor( @@ -1571,7 +1762,7 @@ input_type=_DELETEINSTANCEREQUEST, output_type=google_dot_protobuf_dot_empty__pb2._EMPTY, serialized_options=_b( - "\202\323\344\223\002#*!/v1/{name=projects/*/instances/*}" + "\202\323\344\223\002#*!/v1/{name=projects/*/instances/*}\332A\004name" ), ), _descriptor.MethodDescriptor( @@ -1582,7 +1773,7 @@ input_type=google_dot_iam_dot_v1_dot_iam__policy__pb2._SETIAMPOLICYREQUEST, output_type=google_dot_iam_dot_v1_dot_policy__pb2._POLICY, serialized_options=_b( - '\202\323\344\223\0027"2/v1/{resource=projects/*/instances/*}:setIamPolicy:\001*' + '\202\323\344\223\0027"2/v1/{resource=projects/*/instances/*}:setIamPolicy:\001*\332A\017resource,policy' ), ), _descriptor.MethodDescriptor( @@ -1593,7 +1784,7 @@ input_type=google_dot_iam_dot_v1_dot_iam__policy__pb2._GETIAMPOLICYREQUEST, output_type=google_dot_iam_dot_v1_dot_policy__pb2._POLICY, serialized_options=_b( - '\202\323\344\223\0027"2/v1/{resource=projects/*/instances/*}:getIamPolicy:\001*' + '\202\323\344\223\0027"2/v1/{resource=projects/*/instances/*}:getIamPolicy:\001*\332A\010resource' ), ), _descriptor.MethodDescriptor( @@ -1604,7 +1795,7 @@ input_type=google_dot_iam_dot_v1_dot_iam__policy__pb2._TESTIAMPERMISSIONSREQUEST, output_type=google_dot_iam_dot_v1_dot_iam__policy__pb2._TESTIAMPERMISSIONSRESPONSE, serialized_options=_b( - '\202\323\344\223\002="8/v1/{resource=projects/*/instances/*}:testIamPermissions:\001*' + '\202\323\344\223\002="8/v1/{resource=projects/*/instances/*}:testIamPermissions:\001*\332A\024resource,permissions' ), ), ], diff --git a/spanner/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin_pb2_grpc.py b/spanner/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin_pb2_grpc.py index 922bba7e0df7..b7276a9f9252 100644 --- a/spanner/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin_pb2_grpc.py +++ b/spanner/google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin_pb2_grpc.py @@ -201,9 +201,9 @@ def UpdateInstance(self, request, context): Until completion of the returned operation: * Cancelling the operation sets its metadata's - [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], - and begins restoring resources to their pre-request values. The - operation is guaranteed to succeed at undoing all resource changes, + [cancel_time][google.spanner.admin.instance.v1.UpdateInstanceMetadata.cancel_time], and begins + restoring resources to their pre-request values. The operation + is guaranteed to succeed at undoing all resource changes, after which point it terminates with a `CANCELLED` status. * All other attempts to modify the instance are rejected. * Reading the instance via the API continues to give the pre-request diff --git a/spanner/google/cloud/spanner_v1/gapic/spanner_client.py b/spanner/google/cloud/spanner_v1/gapic/spanner_client.py index f49481d1200b..91fe9b9fa140 100644 --- a/spanner/google/cloud/spanner_v1/gapic/spanner_client.py +++ b/spanner/google/cloud/spanner_v1/gapic/spanner_client.py @@ -235,11 +235,11 @@ def create_session( 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``. + 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 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"``. @@ -696,28 +696,26 @@ def execute_sql( For queries, if none is provided, the default is a temporary read-only transaction with strong concurrency. - Standard DML statements require a ReadWrite transaction. Single-use - transactions are not supported (to avoid replay). The caller must - either supply an existing transaction ID or begin a new transaction. + Standard DML statements require a read-write transaction. To protect + against replays, single-use transactions are not supported. The caller + must either supply an existing transaction ID or begin a new transaction. - Partitioned DML requires an existing PartitionedDml transaction ID. + Partitioned DML requires an existing Partitioned DML transaction ID. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.TransactionSelector` - params (Union[dict, ~google.cloud.spanner_v1.types.Struct]): The SQL 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. + params (Union[dict, ~google.cloud.spanner_v1.types.Struct]): Parameter names and values that bind to placeholders in the SQL string. + + A parameter placeholder consists of the ``@`` character followed by the + parameter name (for example, ``@firstName``). Parameter names can + contain 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 statement with unbound parameters. + ``"WHERE id > @msg_id AND id < @msg_id + 100"`` - Parameter values are specified using ``params``, which is a JSON object - whose keys are parameter names, and whose values are the corresponding - parameter values. + It is an error to execute a SQL statement with unbound parameters. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.Struct` @@ -744,7 +742,7 @@ def execute_sql( previously created using PartitionQuery(). There must be an exact match for the values of fields common to this message and the PartitionQueryRequest message used to create this partition\_token. - seqno (long): A per-transaction sequence number used to identify this request. This + seqno (long): 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. @@ -855,28 +853,26 @@ def execute_streaming_sql( For queries, if none is provided, the default is a temporary read-only transaction with strong concurrency. - Standard DML statements require a ReadWrite transaction. Single-use - transactions are not supported (to avoid replay). The caller must - either supply an existing transaction ID or begin a new transaction. + Standard DML statements require a read-write transaction. To protect + against replays, single-use transactions are not supported. The caller + must either supply an existing transaction ID or begin a new transaction. - Partitioned DML requires an existing PartitionedDml transaction ID. + Partitioned DML requires an existing Partitioned DML transaction ID. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.TransactionSelector` - params (Union[dict, ~google.cloud.spanner_v1.types.Struct]): The SQL 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. + params (Union[dict, ~google.cloud.spanner_v1.types.Struct]): Parameter names and values that bind to placeholders in the SQL string. + + A parameter placeholder consists of the ``@`` character followed by the + parameter name (for example, ``@firstName``). Parameter names can + contain 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 statement with unbound parameters. + ``"WHERE id > @msg_id AND id < @msg_id + 100"`` - Parameter values are specified using ``params``, which is a JSON object - whose keys are parameter names, and whose values are the corresponding - parameter values. + It is an error to execute a SQL statement with unbound parameters. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.Struct` @@ -903,7 +899,7 @@ def execute_streaming_sql( previously created using PartitionQuery(). There must be an exact match for the values of fields common to this message and the PartitionQueryRequest message used to create this partition\_token. - seqno (long): A per-transaction sequence number used to identify this request. This + seqno (long): 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. @@ -986,20 +982,13 @@ def execute_batch_dml( statements to be run with lower latency than submitting them sequentially with ``ExecuteSql``. - Statements are executed in order, sequentially. - ``ExecuteBatchDmlResponse`` will contain a ``ResultSet`` for each DML - statement that has successfully executed. If a statement fails, its - error status will be returned as part of the - ``ExecuteBatchDmlResponse``. Execution will stop at the first failed - statement; the remaining statements will not run. + Statements are executed in sequential order. A request can succeed even + if a statement fails. The ``ExecuteBatchDmlResponse.status`` field in + the response provides information about the statement that failed. + Clients must inspect this field to determine whether an error occurred. - ExecuteBatchDml is expected to return an OK status with a response even - if there was an error while processing one of the DML statements. - Clients must inspect response.status to determine if there were any - errors while processing the request. - - See more details in ``ExecuteBatchDmlRequest`` and - ``ExecuteBatchDmlResponse``. + Execution stops after the first failed statement; the remaining + statements are not executed. Example: >>> from google.cloud import spanner_v1 @@ -1021,24 +1010,32 @@ def execute_batch_dml( Args: session (str): Required. The session in which the DML statements should be performed. - transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionSelector]): The transaction to use. A ReadWrite transaction is required. Single-use - transactions are not supported (to avoid replay). The caller must either - supply an existing transaction ID or begin a new transaction. + transaction (Union[dict, ~google.cloud.spanner_v1.types.TransactionSelector]): Required. The transaction to use. Must be a read-write transaction. + + To protect against replays, single-use transactions are not supported. The + caller must either supply an existing transaction ID or begin a new + transaction. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.TransactionSelector` - statements (list[Union[dict, ~google.cloud.spanner_v1.types.Statement]]): 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 will stop at the - first failed statement; the remaining statements will not run. + statements (list[Union[dict, ~google.cloud.spanner_v1.types.Statement]]): 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. - REQUIRES: statements\_size() > 0. + Callers must provide at least one statement. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.Statement` - seqno (long): A per-transaction sequence number used to identify this request. This is - used in the same space as the seqno in ``ExecuteSqlRequest``. See more - details in ``ExecuteSqlRequest``. + seqno (long): 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 + sequence number, the transaction may be aborted. Replays of previously + handled requests will yield the same response as the first execution. retry (Optional[google.api_core.retry.Retry]): A retry object used to retry requests. If ``None`` is specified, requests will be retried using a default configuration. @@ -1138,8 +1135,8 @@ def read( Args: session (str): Required. The session in which the read should be performed. table (str): Required. The name of the table in the database to be read. - columns (list[str]): The columns of ``table`` to be returned for each row matching this - request. + columns (list[str]): Required. The columns of ``table`` to be returned for each row matching + this request. key_set (Union[dict, ~google.cloud.spanner_v1.types.KeySet]): Required. ``key_set`` identifies the rows to be yielded. ``key_set`` names the primary keys of the rows in ``table`` to be yielded, unless ``index`` is present. If ``index`` is present, then ``key_set`` instead @@ -1275,8 +1272,8 @@ def streaming_read( Args: session (str): Required. The session in which the read should be performed. table (str): Required. The name of the table in the database to be read. - columns (list[str]): The columns of ``table`` to be returned for each row matching this - request. + columns (list[str]): Required. The columns of ``table`` to be returned for each row matching + this request. key_set (Union[dict, ~google.cloud.spanner_v1.types.KeySet]): Required. ``key_set`` identifies the rows to be yielded. ``key_set`` names the primary keys of the rows in ``table`` to be yielded, unless ``index`` is present. If ``index`` is present, then ``key_set`` instead @@ -1677,8 +1674,8 @@ def partition_query( Args: session (str): Required. The session used to create the partitions. - sql (str): The query request to generate partitions for. The request will fail if - the query is not root partitionable. The query plan of a root + sql (str): 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 @@ -1692,20 +1689,18 @@ def partition_query( If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.TransactionSelector` - params (Union[dict, ~google.cloud.spanner_v1.types.Struct]): 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. + params (Union[dict, ~google.cloud.spanner_v1.types.Struct]): Parameter names and values that bind to placeholders in the SQL string. + + A parameter placeholder consists of the ``@`` character followed by the + parameter name (for example, ``@firstName``). Parameter names can + contain 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. + ``"WHERE id > @msg_id AND id < @msg_id + 100"`` - Parameter values are specified using ``params``, which is a JSON object - whose keys are parameter names, and whose values are the corresponding - parameter values. + It is an error to execute a SQL statement with unbound parameters. If a dict is provided, it must be of the same form as the protobuf message :class:`~google.cloud.spanner_v1.types.Struct` diff --git a/spanner/google/cloud/spanner_v1/gapic/transports/spanner_grpc_transport.py b/spanner/google/cloud/spanner_v1/gapic/transports/spanner_grpc_transport.py index 2b5f1fd1d67f..0d16522afb69 100644 --- a/spanner/google/cloud/spanner_v1/gapic/transports/spanner_grpc_transport.py +++ b/spanner/google/cloud/spanner_v1/gapic/transports/spanner_grpc_transport.py @@ -131,11 +131,11 @@ def create_session(self): 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``. + 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 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"``. @@ -252,20 +252,13 @@ def execute_batch_dml(self): statements to be run with lower latency than submitting them sequentially with ``ExecuteSql``. - Statements are executed in order, sequentially. - ``ExecuteBatchDmlResponse`` will contain a ``ResultSet`` for each DML - statement that has successfully executed. If a statement fails, its - error status will be returned as part of the - ``ExecuteBatchDmlResponse``. Execution will stop at the first failed - statement; the remaining statements will not run. + Statements are executed in sequential order. A request can succeed even + if a statement fails. The ``ExecuteBatchDmlResponse.status`` field in + the response provides information about the statement that failed. + Clients must inspect this field to determine whether an error occurred. - ExecuteBatchDml is expected to return an OK status with a response even - if there was an error while processing one of the DML statements. - Clients must inspect response.status to determine if there were any - errors while processing the request. - - See more details in ``ExecuteBatchDmlRequest`` and - ``ExecuteBatchDmlResponse``. + Execution stops after the first failed statement; the remaining + statements are not executed. Returns: Callable: A callable which accepts the appropriate diff --git a/spanner/google/cloud/spanner_v1/proto/keys.proto b/spanner/google/cloud/spanner_v1/proto/keys.proto index 1ae95749362f..de5307aaaf93 100644 --- a/spanner/google/cloud/spanner_v1/proto/keys.proto +++ b/spanner/google/cloud/spanner_v1/proto/keys.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC +// Copyright 2019 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,13 +11,14 @@ // 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/protobuf/struct.proto"; +import "google/api/annotations.proto"; option csharp_namespace = "Google.Cloud.Spanner.V1"; option go_package = "google.golang.org/genproto/googleapis/spanner/v1;spanner"; @@ -152,8 +153,8 @@ message KeySet { // encoded as described [here][google.spanner.v1.TypeCode]. repeated google.protobuf.ListValue keys = 1; - // A list of key ranges. See [KeyRange][google.spanner.v1.KeyRange] for more - // information about key range specifications. + // A list of key ranges. See [KeyRange][google.spanner.v1.KeyRange] for more information about + // key range specifications. repeated KeyRange ranges = 2; // For convenience `all` can be set to `true` to indicate that this diff --git a/spanner/google/cloud/spanner_v1/proto/keys_pb2.py b/spanner/google/cloud/spanner_v1/proto/keys_pb2.py index 3d381357b88c..0a7966084df3 100644 --- a/spanner/google/cloud/spanner_v1/proto/keys_pb2.py +++ b/spanner/google/cloud/spanner_v1/proto/keys_pb2.py @@ -15,8 +15,8 @@ _sym_db = _symbol_database.Default() -from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2 from google.protobuf import struct_pb2 as google_dot_protobuf_dot_struct__pb2 +from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2 DESCRIPTOR = _descriptor.FileDescriptor( @@ -27,11 +27,11 @@ "\n\025com.google.spanner.v1B\tKeysProtoP\001Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\252\002\027Google.Cloud.Spanner.V1\312\002\027Google\\Cloud\\Spanner\\V1" ), serialized_pb=_b( - '\n(google/cloud/spanner_v1/proto/keys.proto\x12\x11google.spanner.v1\x1a\x1cgoogle/api/annotations.proto\x1a\x1cgoogle/protobuf/struct.proto"\xf4\x01\n\x08KeyRange\x12\x32\n\x0cstart_closed\x18\x01 \x01(\x0b\x32\x1a.google.protobuf.ListValueH\x00\x12\x30\n\nstart_open\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.ListValueH\x00\x12\x30\n\nend_closed\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.ListValueH\x01\x12.\n\x08\x65nd_open\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.ListValueH\x01\x42\x10\n\x0estart_key_typeB\x0e\n\x0c\x65nd_key_type"l\n\x06KeySet\x12(\n\x04keys\x18\x01 \x03(\x0b\x32\x1a.google.protobuf.ListValue\x12+\n\x06ranges\x18\x02 \x03(\x0b\x32\x1b.google.spanner.v1.KeyRange\x12\x0b\n\x03\x61ll\x18\x03 \x01(\x08\x42\x92\x01\n\x15\x63om.google.spanner.v1B\tKeysProtoP\x01Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\xaa\x02\x17Google.Cloud.Spanner.V1\xca\x02\x17Google\\Cloud\\Spanner\\V1b\x06proto3' + '\n(google/cloud/spanner_v1/proto/keys.proto\x12\x11google.spanner.v1\x1a\x1cgoogle/protobuf/struct.proto\x1a\x1cgoogle/api/annotations.proto"\xf4\x01\n\x08KeyRange\x12\x32\n\x0cstart_closed\x18\x01 \x01(\x0b\x32\x1a.google.protobuf.ListValueH\x00\x12\x30\n\nstart_open\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.ListValueH\x00\x12\x30\n\nend_closed\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.ListValueH\x01\x12.\n\x08\x65nd_open\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.ListValueH\x01\x42\x10\n\x0estart_key_typeB\x0e\n\x0c\x65nd_key_type"l\n\x06KeySet\x12(\n\x04keys\x18\x01 \x03(\x0b\x32\x1a.google.protobuf.ListValue\x12+\n\x06ranges\x18\x02 \x03(\x0b\x32\x1b.google.spanner.v1.KeyRange\x12\x0b\n\x03\x61ll\x18\x03 \x01(\x08\x42\x92\x01\n\x15\x63om.google.spanner.v1B\tKeysProtoP\x01Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\xaa\x02\x17Google.Cloud.Spanner.V1\xca\x02\x17Google\\Cloud\\Spanner\\V1b\x06proto3' ), dependencies=[ - google_dot_api_dot_annotations__pb2.DESCRIPTOR, google_dot_protobuf_dot_struct__pb2.DESCRIPTOR, + google_dot_api_dot_annotations__pb2.DESCRIPTOR, ], ) diff --git a/spanner/google/cloud/spanner_v1/proto/mutation.proto b/spanner/google/cloud/spanner_v1/proto/mutation.proto index 901e6cfe001a..7df99c0ee6f2 100644 --- a/spanner/google/cloud/spanner_v1/proto/mutation.proto +++ b/spanner/google/cloud/spanner_v1/proto/mutation.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC +// Copyright 2019 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,14 +11,15 @@ // 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/protobuf/struct.proto"; import "google/spanner/v1/keys.proto"; +import "google/api/annotations.proto"; option csharp_namespace = "Google.Cloud.Spanner.V1"; option go_package = "google.golang.org/genproto/googleapis/spanner/v1;spanner"; @@ -31,16 +32,13 @@ option php_namespace = "Google\\Cloud\\Spanner\\V1"; // applied to a Cloud Spanner database by sending them in a // [Commit][google.spanner.v1.Spanner.Commit] call. message Mutation { - // Arguments to [insert][google.spanner.v1.Mutation.insert], - // [update][google.spanner.v1.Mutation.update], - // [insert_or_update][google.spanner.v1.Mutation.insert_or_update], and + // Arguments to [insert][google.spanner.v1.Mutation.insert], [update][google.spanner.v1.Mutation.update], [insert_or_update][google.spanner.v1.Mutation.insert_or_update], and // [replace][google.spanner.v1.Mutation.replace] operations. message Write { // Required. The table whose rows will be written. string table = 1; - // The names of the columns in - // [table][google.spanner.v1.Mutation.Write.table] to be written. + // The names of the columns in [table][google.spanner.v1.Mutation.Write.table] to be written. // // The list of columns must contain enough columns to allow // Cloud Spanner to derive values for all primary key columns in the @@ -50,13 +48,11 @@ message Mutation { // The values to be written. `values` can contain more than one // list of values. If it does, then multiple rows are written, one // for each entry in `values`. Each list in `values` must have - // exactly as many entries as there are entries in - // [columns][google.spanner.v1.Mutation.Write.columns] above. Sending - // multiple lists is equivalent to sending multiple `Mutation`s, each - // containing one `values` entry and repeating - // [table][google.spanner.v1.Mutation.Write.table] and - // [columns][google.spanner.v1.Mutation.Write.columns]. Individual values in - // each list are encoded as described [here][google.spanner.v1.TypeCode]. + // exactly as many entries as there are entries in [columns][google.spanner.v1.Mutation.Write.columns] + // above. Sending multiple lists is equivalent to sending multiple + // `Mutation`s, each containing one `values` entry and repeating + // [table][google.spanner.v1.Mutation.Write.table] and [columns][google.spanner.v1.Mutation.Write.columns]. Individual values in each list are + // encoded as described [here][google.spanner.v1.TypeCode]. repeated google.protobuf.ListValue values = 3; } @@ -65,10 +61,9 @@ message Mutation { // Required. The table whose rows will be deleted. string table = 1; - // Required. The primary keys of the rows within - // [table][google.spanner.v1.Mutation.Delete.table] to delete. Delete is - // idempotent. The transaction will succeed even if some or all rows do not - // exist. + // Required. The primary keys of the rows within [table][google.spanner.v1.Mutation.Delete.table] to delete. + // Delete is idempotent. The transaction will succeed even if some or all + // rows do not exist. KeySet key_set = 2; } @@ -82,16 +77,20 @@ message Mutation { // already exist, the transaction fails with error `NOT_FOUND`. Write update = 2; - // Like [insert][google.spanner.v1.Mutation.insert], except that if the row - // already exists, then its column values are overwritten with the ones - // provided. Any column values not explicitly written are preserved. + // Like [insert][google.spanner.v1.Mutation.insert], except that if the row already exists, then + // its column values are overwritten with the ones provided. Any + // column values not explicitly written are preserved. Write insert_or_update = 3; - // Like [insert][google.spanner.v1.Mutation.insert], except that if the row - // already exists, it is deleted, and the column values provided are - // inserted instead. Unlike - // [insert_or_update][google.spanner.v1.Mutation.insert_or_update], this - // means any values not explicitly written become `NULL`. + // Like [insert][google.spanner.v1.Mutation.insert], except that if the row already exists, it is + // deleted, and the column values provided are inserted + // instead. Unlike [insert_or_update][google.spanner.v1.Mutation.insert_or_update], this means any values not + // explicitly written become `NULL`. + // + // In an interleaved table, if you create the child table with the + // `ON DELETE CASCADE` annotation, then replacing a parent row + // also deletes the child rows. Otherwise, you must delete the + // child rows before you replace the parent row. Write replace = 4; // Delete rows from a table. Succeeds whether or not the named diff --git a/spanner/google/cloud/spanner_v1/proto/mutation_pb2.py b/spanner/google/cloud/spanner_v1/proto/mutation_pb2.py index 6002879385af..fe963839156f 100644 --- a/spanner/google/cloud/spanner_v1/proto/mutation_pb2.py +++ b/spanner/google/cloud/spanner_v1/proto/mutation_pb2.py @@ -15,11 +15,11 @@ _sym_db = _symbol_database.Default() -from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2 from google.protobuf import struct_pb2 as google_dot_protobuf_dot_struct__pb2 from google.cloud.spanner_v1.proto import ( keys_pb2 as google_dot_cloud_dot_spanner__v1_dot_proto_dot_keys__pb2, ) +from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2 DESCRIPTOR = _descriptor.FileDescriptor( @@ -30,12 +30,12 @@ "\n\025com.google.spanner.v1B\rMutationProtoP\001Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\252\002\027Google.Cloud.Spanner.V1\312\002\027Google\\Cloud\\Spanner\\V1" ), serialized_pb=_b( - '\n,google/cloud/spanner_v1/proto/mutation.proto\x12\x11google.spanner.v1\x1a\x1cgoogle/api/annotations.proto\x1a\x1cgoogle/protobuf/struct.proto\x1a(google/cloud/spanner_v1/proto/keys.proto"\xc6\x03\n\x08Mutation\x12\x33\n\x06insert\x18\x01 \x01(\x0b\x32!.google.spanner.v1.Mutation.WriteH\x00\x12\x33\n\x06update\x18\x02 \x01(\x0b\x32!.google.spanner.v1.Mutation.WriteH\x00\x12=\n\x10insert_or_update\x18\x03 \x01(\x0b\x32!.google.spanner.v1.Mutation.WriteH\x00\x12\x34\n\x07replace\x18\x04 \x01(\x0b\x32!.google.spanner.v1.Mutation.WriteH\x00\x12\x34\n\x06\x64\x65lete\x18\x05 \x01(\x0b\x32".google.spanner.v1.Mutation.DeleteH\x00\x1aS\n\x05Write\x12\r\n\x05table\x18\x01 \x01(\t\x12\x0f\n\x07\x63olumns\x18\x02 \x03(\t\x12*\n\x06values\x18\x03 \x03(\x0b\x32\x1a.google.protobuf.ListValue\x1a\x43\n\x06\x44\x65lete\x12\r\n\x05table\x18\x01 \x01(\t\x12*\n\x07key_set\x18\x02 \x01(\x0b\x32\x19.google.spanner.v1.KeySetB\x0b\n\toperationB\x96\x01\n\x15\x63om.google.spanner.v1B\rMutationProtoP\x01Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\xaa\x02\x17Google.Cloud.Spanner.V1\xca\x02\x17Google\\Cloud\\Spanner\\V1b\x06proto3' + '\n,google/cloud/spanner_v1/proto/mutation.proto\x12\x11google.spanner.v1\x1a\x1cgoogle/protobuf/struct.proto\x1a(google/cloud/spanner_v1/proto/keys.proto\x1a\x1cgoogle/api/annotations.proto"\xc6\x03\n\x08Mutation\x12\x33\n\x06insert\x18\x01 \x01(\x0b\x32!.google.spanner.v1.Mutation.WriteH\x00\x12\x33\n\x06update\x18\x02 \x01(\x0b\x32!.google.spanner.v1.Mutation.WriteH\x00\x12=\n\x10insert_or_update\x18\x03 \x01(\x0b\x32!.google.spanner.v1.Mutation.WriteH\x00\x12\x34\n\x07replace\x18\x04 \x01(\x0b\x32!.google.spanner.v1.Mutation.WriteH\x00\x12\x34\n\x06\x64\x65lete\x18\x05 \x01(\x0b\x32".google.spanner.v1.Mutation.DeleteH\x00\x1aS\n\x05Write\x12\r\n\x05table\x18\x01 \x01(\t\x12\x0f\n\x07\x63olumns\x18\x02 \x03(\t\x12*\n\x06values\x18\x03 \x03(\x0b\x32\x1a.google.protobuf.ListValue\x1a\x43\n\x06\x44\x65lete\x12\r\n\x05table\x18\x01 \x01(\t\x12*\n\x07key_set\x18\x02 \x01(\x0b\x32\x19.google.spanner.v1.KeySetB\x0b\n\toperationB\x96\x01\n\x15\x63om.google.spanner.v1B\rMutationProtoP\x01Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\xaa\x02\x17Google.Cloud.Spanner.V1\xca\x02\x17Google\\Cloud\\Spanner\\V1b\x06proto3' ), dependencies=[ - google_dot_api_dot_annotations__pb2.DESCRIPTOR, google_dot_protobuf_dot_struct__pb2.DESCRIPTOR, google_dot_cloud_dot_spanner__v1_dot_proto_dot_keys__pb2.DESCRIPTOR, + google_dot_api_dot_annotations__pb2.DESCRIPTOR, ], ) @@ -414,7 +414,11 @@ if the row already exists, it is deleted, and the column values provided are inserted instead. Unlike [insert\_or\_upda te][google.spanner.v1.Mutation.insert\_or\_update], this means - any values not explicitly written become ``NULL``. + any values not explicitly written become ``NULL``. In an + interleaved table, if you create the child table with the ``ON + DELETE CASCADE`` annotation, then replacing a parent row also + deletes the child rows. Otherwise, you must delete the child + rows before you replace the parent row. delete: Delete rows from a table. Succeeds whether or not the named rows were present. diff --git a/spanner/google/cloud/spanner_v1/proto/query_plan.proto b/spanner/google/cloud/spanner_v1/proto/query_plan.proto index 3f3fe6733db4..2d6be2e2bd31 100644 --- a/spanner/google/cloud/spanner_v1/proto/query_plan.proto +++ b/spanner/google/cloud/spanner_v1/proto/query_plan.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC +// Copyright 2019 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,13 +11,14 @@ // 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/protobuf/struct.proto"; +import "google/api/annotations.proto"; option csharp_namespace = "Google.Cloud.Spanner.V1"; option go_package = "google.golang.org/genproto/googleapis/spanner/v1;spanner"; @@ -26,8 +27,7 @@ option java_outer_classname = "QueryPlanProto"; option java_package = "com.google.spanner.v1"; option php_namespace = "Google\\Cloud\\Spanner\\V1"; -// Node information for nodes appearing in a -// [QueryPlan.plan_nodes][google.spanner.v1.QueryPlan.plan_nodes]. +// Node information for nodes appearing in a [QueryPlan.plan_nodes][google.spanner.v1.QueryPlan.plan_nodes]. message PlanNode { // Metadata associated with a parent-child relationship appearing in a // [PlanNode][google.spanner.v1.PlanNode]. @@ -41,14 +41,14 @@ message PlanNode { // with the output variable. string type = 2; - // Only present if the child node is - // [SCALAR][google.spanner.v1.PlanNode.Kind.SCALAR] and corresponds to an - // output variable of the parent node. The field carries the name of the - // output variable. For example, a `TableScan` operator that reads rows from - // a table will have child links to the `SCALAR` nodes representing the - // output variables created for each column that is read by the operator. - // The corresponding `variable` fields will be set to the variable names - // assigned to the columns. + // Only present if the child node is [SCALAR][google.spanner.v1.PlanNode.Kind.SCALAR] and corresponds + // to an output variable of the parent node. The field carries the name of + // the output variable. + // For example, a `TableScan` operator that reads rows from a table will + // have child links to the `SCALAR` nodes representing the output variables + // created for each column that is read by the operator. The corresponding + // `variable` fields will be set to the variable names assigned to the + // columns. string variable = 3; } @@ -66,8 +66,8 @@ message PlanNode { map subqueries = 2; } - // The kind of [PlanNode][google.spanner.v1.PlanNode]. Distinguishes between - // the two different kinds of nodes that can appear in a query plan. + // The kind of [PlanNode][google.spanner.v1.PlanNode]. Distinguishes between the two different kinds of + // nodes that can appear in a query plan. enum Kind { // Not specified. KIND_UNSPECIFIED = 0; @@ -84,15 +84,14 @@ message PlanNode { SCALAR = 2; } - // The `PlanNode`'s index in [node - // list][google.spanner.v1.QueryPlan.plan_nodes]. + // The `PlanNode`'s index in [node list][google.spanner.v1.QueryPlan.plan_nodes]. int32 index = 1; // Used to determine the type of node. May be needed for visualizing // different kinds of nodes differently. For example, If the node is a - // [SCALAR][google.spanner.v1.PlanNode.Kind.SCALAR] node, it will have a - // condensed representation which can be used to directly embed a description - // of the node in its parent. + // [SCALAR][google.spanner.v1.PlanNode.Kind.SCALAR] node, it will have a condensed representation + // which can be used to directly embed a description of the node in its + // parent. Kind kind = 2; // The display name for the node. @@ -101,8 +100,7 @@ message PlanNode { // List of child node `index`es and their relationship to this parent. repeated ChildLink child_links = 4; - // Condensed representation for - // [SCALAR][google.spanner.v1.PlanNode.Kind.SCALAR] nodes. + // Condensed representation for [SCALAR][google.spanner.v1.PlanNode.Kind.SCALAR] nodes. ShortRepresentation short_representation = 5; // Attributes relevant to the node contained in a group of key-value pairs. @@ -125,7 +123,7 @@ message PlanNode { // Contains an ordered list of nodes appearing in the query plan. message QueryPlan { // The nodes in the query plan. Plan nodes are returned in pre-order starting - // with the plan root. Each [PlanNode][google.spanner.v1.PlanNode]'s `id` - // corresponds to its index in `plan_nodes`. + // with the plan root. Each [PlanNode][google.spanner.v1.PlanNode]'s `id` corresponds to its index in + // `plan_nodes`. repeated PlanNode plan_nodes = 1; } diff --git a/spanner/google/cloud/spanner_v1/proto/query_plan_pb2.py b/spanner/google/cloud/spanner_v1/proto/query_plan_pb2.py index 37718bdad555..8fe752ce8caa 100644 --- a/spanner/google/cloud/spanner_v1/proto/query_plan_pb2.py +++ b/spanner/google/cloud/spanner_v1/proto/query_plan_pb2.py @@ -15,8 +15,8 @@ _sym_db = _symbol_database.Default() -from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2 from google.protobuf import struct_pb2 as google_dot_protobuf_dot_struct__pb2 +from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2 DESCRIPTOR = _descriptor.FileDescriptor( @@ -27,11 +27,11 @@ "\n\025com.google.spanner.v1B\016QueryPlanProtoP\001Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\252\002\027Google.Cloud.Spanner.V1\312\002\027Google\\Cloud\\Spanner\\V1" ), serialized_pb=_b( - '\n.google/cloud/spanner_v1/proto/query_plan.proto\x12\x11google.spanner.v1\x1a\x1cgoogle/api/annotations.proto\x1a\x1cgoogle/protobuf/struct.proto"\xf8\x04\n\x08PlanNode\x12\r\n\x05index\x18\x01 \x01(\x05\x12.\n\x04kind\x18\x02 \x01(\x0e\x32 .google.spanner.v1.PlanNode.Kind\x12\x14\n\x0c\x64isplay_name\x18\x03 \x01(\t\x12:\n\x0b\x63hild_links\x18\x04 \x03(\x0b\x32%.google.spanner.v1.PlanNode.ChildLink\x12M\n\x14short_representation\x18\x05 \x01(\x0b\x32/.google.spanner.v1.PlanNode.ShortRepresentation\x12)\n\x08metadata\x18\x06 \x01(\x0b\x32\x17.google.protobuf.Struct\x12\x30\n\x0f\x65xecution_stats\x18\x07 \x01(\x0b\x32\x17.google.protobuf.Struct\x1a@\n\tChildLink\x12\x13\n\x0b\x63hild_index\x18\x01 \x01(\x05\x12\x0c\n\x04type\x18\x02 \x01(\t\x12\x10\n\x08variable\x18\x03 \x01(\t\x1a\xb2\x01\n\x13ShortRepresentation\x12\x13\n\x0b\x64\x65scription\x18\x01 \x01(\t\x12S\n\nsubqueries\x18\x02 \x03(\x0b\x32?.google.spanner.v1.PlanNode.ShortRepresentation.SubqueriesEntry\x1a\x31\n\x0fSubqueriesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\x05:\x02\x38\x01"8\n\x04Kind\x12\x14\n\x10KIND_UNSPECIFIED\x10\x00\x12\x0e\n\nRELATIONAL\x10\x01\x12\n\n\x06SCALAR\x10\x02"<\n\tQueryPlan\x12/\n\nplan_nodes\x18\x01 \x03(\x0b\x32\x1b.google.spanner.v1.PlanNodeB\x97\x01\n\x15\x63om.google.spanner.v1B\x0eQueryPlanProtoP\x01Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\xaa\x02\x17Google.Cloud.Spanner.V1\xca\x02\x17Google\\Cloud\\Spanner\\V1b\x06proto3' + '\n.google/cloud/spanner_v1/proto/query_plan.proto\x12\x11google.spanner.v1\x1a\x1cgoogle/protobuf/struct.proto\x1a\x1cgoogle/api/annotations.proto"\xf8\x04\n\x08PlanNode\x12\r\n\x05index\x18\x01 \x01(\x05\x12.\n\x04kind\x18\x02 \x01(\x0e\x32 .google.spanner.v1.PlanNode.Kind\x12\x14\n\x0c\x64isplay_name\x18\x03 \x01(\t\x12:\n\x0b\x63hild_links\x18\x04 \x03(\x0b\x32%.google.spanner.v1.PlanNode.ChildLink\x12M\n\x14short_representation\x18\x05 \x01(\x0b\x32/.google.spanner.v1.PlanNode.ShortRepresentation\x12)\n\x08metadata\x18\x06 \x01(\x0b\x32\x17.google.protobuf.Struct\x12\x30\n\x0f\x65xecution_stats\x18\x07 \x01(\x0b\x32\x17.google.protobuf.Struct\x1a@\n\tChildLink\x12\x13\n\x0b\x63hild_index\x18\x01 \x01(\x05\x12\x0c\n\x04type\x18\x02 \x01(\t\x12\x10\n\x08variable\x18\x03 \x01(\t\x1a\xb2\x01\n\x13ShortRepresentation\x12\x13\n\x0b\x64\x65scription\x18\x01 \x01(\t\x12S\n\nsubqueries\x18\x02 \x03(\x0b\x32?.google.spanner.v1.PlanNode.ShortRepresentation.SubqueriesEntry\x1a\x31\n\x0fSubqueriesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\x05:\x02\x38\x01"8\n\x04Kind\x12\x14\n\x10KIND_UNSPECIFIED\x10\x00\x12\x0e\n\nRELATIONAL\x10\x01\x12\n\n\x06SCALAR\x10\x02"<\n\tQueryPlan\x12/\n\nplan_nodes\x18\x01 \x03(\x0b\x32\x1b.google.spanner.v1.PlanNodeB\x97\x01\n\x15\x63om.google.spanner.v1B\x0eQueryPlanProtoP\x01Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\xaa\x02\x17Google.Cloud.Spanner.V1\xca\x02\x17Google\\Cloud\\Spanner\\V1b\x06proto3' ), dependencies=[ - google_dot_api_dot_annotations__pb2.DESCRIPTOR, google_dot_protobuf_dot_struct__pb2.DESCRIPTOR, + google_dot_api_dot_annotations__pb2.DESCRIPTOR, ], ) diff --git a/spanner/google/cloud/spanner_v1/proto/result_set.proto b/spanner/google/cloud/spanner_v1/proto/result_set.proto index 55f612f1b9bc..a4b785283cdf 100644 --- a/spanner/google/cloud/spanner_v1/proto/result_set.proto +++ b/spanner/google/cloud/spanner_v1/proto/result_set.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC +// Copyright 2019 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,16 +11,17 @@ // 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/protobuf/struct.proto"; import "google/spanner/v1/query_plan.proto"; import "google/spanner/v1/transaction.proto"; import "google/spanner/v1/type.proto"; +import "google/api/annotations.proto"; option cc_enable_arenas = true; option csharp_namespace = "Google.Cloud.Spanner.V1"; @@ -37,10 +38,11 @@ message ResultSet { ResultSetMetadata metadata = 1; // Each element in `rows` is a row whose format is defined by - // [metadata.row_type][google.spanner.v1.ResultSetMetadata.row_type]. The ith - // element in each row matches the ith field in - // [metadata.row_type][google.spanner.v1.ResultSetMetadata.row_type]. Elements - // are encoded based on type as described [here][google.spanner.v1.TypeCode]. + // [metadata.row_type][google.spanner.v1.ResultSetMetadata.row_type]. The ith element + // in each row matches the ith field in + // [metadata.row_type][google.spanner.v1.ResultSetMetadata.row_type]. Elements are + // encoded based on type as described + // [here][google.spanner.v1.TypeCode]. repeated google.protobuf.ListValue rows = 2; // Query plan and execution statistics for the SQL statement that @@ -48,8 +50,7 @@ message ResultSet { // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode]. // DML statements always produce stats containing the number of rows // modified, unless executed using the - // [ExecuteSqlRequest.QueryMode.PLAN][google.spanner.v1.ExecuteSqlRequest.QueryMode.PLAN] - // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode]. + // [ExecuteSqlRequest.QueryMode.PLAN][google.spanner.v1.ExecuteSqlRequest.QueryMode.PLAN] [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode]. // Other fields may or may not be populated, based on the // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode]. ResultSetStats stats = 3; @@ -74,10 +75,9 @@ message PartialResultSet { // // It is possible that the last value in values is "chunked", // meaning that the rest of the value is sent in subsequent - // `PartialResultSet`(s). This is denoted by the - // [chunked_value][google.spanner.v1.PartialResultSet.chunked_value] field. - // Two or more chunked values can be merged to form a complete value as - // follows: + // `PartialResultSet`(s). This is denoted by the [chunked_value][google.spanner.v1.PartialResultSet.chunked_value] + // field. Two or more chunked values can be merged to form a + // complete value as follows: // // * `bool/number/null`: cannot be chunked // * `string`: concatenate the strings @@ -139,10 +139,9 @@ message PartialResultSet { // field value `"World" = "W" + "orl" + "d"`. repeated google.protobuf.Value values = 2; - // If true, then the final value in - // [values][google.spanner.v1.PartialResultSet.values] is chunked, and must be - // combined with more values from subsequent `PartialResultSet`s to obtain a - // complete field value. + // If true, then the final value in [values][google.spanner.v1.PartialResultSet.values] is chunked, and must + // be combined with more values from subsequent `PartialResultSet`s + // to obtain a complete field value. bool chunked_value = 3; // Streaming calls might be interrupted for a variety of reasons, such @@ -154,14 +153,14 @@ message PartialResultSet { // Query plan and execution statistics for the statement that produced this // streaming result set. These can be requested by setting - // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode] - // and are sent only once with the last response in the stream. This field - // will also be present in the last response for DML statements. + // [ExecuteSqlRequest.query_mode][google.spanner.v1.ExecuteSqlRequest.query_mode] and are sent + // only once with the last response in the stream. + // This field will also be present in the last response for DML + // statements. ResultSetStats stats = 5; } -// Metadata about a [ResultSet][google.spanner.v1.ResultSet] or -// [PartialResultSet][google.spanner.v1.PartialResultSet]. +// Metadata about a [ResultSet][google.spanner.v1.ResultSet] or [PartialResultSet][google.spanner.v1.PartialResultSet]. message ResultSetMetadata { // Indicates the field names and types for the rows in the result // set. For example, a SQL query like `"SELECT UserId, UserName FROM @@ -178,11 +177,9 @@ message ResultSetMetadata { Transaction transaction = 2; } -// Additional statistics about a [ResultSet][google.spanner.v1.ResultSet] or -// [PartialResultSet][google.spanner.v1.PartialResultSet]. +// Additional statistics about a [ResultSet][google.spanner.v1.ResultSet] or [PartialResultSet][google.spanner.v1.PartialResultSet]. message ResultSetStats { - // [QueryPlan][google.spanner.v1.QueryPlan] for the query associated with this - // result. + // [QueryPlan][google.spanner.v1.QueryPlan] for the query associated with this result. QueryPlan query_plan = 1; // Aggregated statistics from the execution of the query. Only present when diff --git a/spanner/google/cloud/spanner_v1/proto/result_set_pb2.py b/spanner/google/cloud/spanner_v1/proto/result_set_pb2.py index 2639bd03417e..f99728f6b920 100644 --- a/spanner/google/cloud/spanner_v1/proto/result_set_pb2.py +++ b/spanner/google/cloud/spanner_v1/proto/result_set_pb2.py @@ -15,7 +15,6 @@ _sym_db = _symbol_database.Default() -from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2 from google.protobuf import struct_pb2 as google_dot_protobuf_dot_struct__pb2 from google.cloud.spanner_v1.proto import ( query_plan_pb2 as google_dot_cloud_dot_spanner__v1_dot_proto_dot_query__plan__pb2, @@ -26,6 +25,7 @@ from google.cloud.spanner_v1.proto import ( type_pb2 as google_dot_cloud_dot_spanner__v1_dot_proto_dot_type__pb2, ) +from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2 DESCRIPTOR = _descriptor.FileDescriptor( @@ -36,14 +36,14 @@ "\n\025com.google.spanner.v1B\016ResultSetProtoP\001Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\370\001\001\252\002\027Google.Cloud.Spanner.V1\312\002\027Google\\Cloud\\Spanner\\V1" ), serialized_pb=_b( - '\n.google/cloud/spanner_v1/proto/result_set.proto\x12\x11google.spanner.v1\x1a\x1cgoogle/api/annotations.proto\x1a\x1cgoogle/protobuf/struct.proto\x1a.google/cloud/spanner_v1/proto/query_plan.proto\x1a/google/cloud/spanner_v1/proto/transaction.proto\x1a(google/cloud/spanner_v1/proto/type.proto"\x9f\x01\n\tResultSet\x12\x36\n\x08metadata\x18\x01 \x01(\x0b\x32$.google.spanner.v1.ResultSetMetadata\x12(\n\x04rows\x18\x02 \x03(\x0b\x32\x1a.google.protobuf.ListValue\x12\x30\n\x05stats\x18\x03 \x01(\x0b\x32!.google.spanner.v1.ResultSetStats"\xd1\x01\n\x10PartialResultSet\x12\x36\n\x08metadata\x18\x01 \x01(\x0b\x32$.google.spanner.v1.ResultSetMetadata\x12&\n\x06values\x18\x02 \x03(\x0b\x32\x16.google.protobuf.Value\x12\x15\n\rchunked_value\x18\x03 \x01(\x08\x12\x14\n\x0cresume_token\x18\x04 \x01(\x0c\x12\x30\n\x05stats\x18\x05 \x01(\x0b\x32!.google.spanner.v1.ResultSetStats"y\n\x11ResultSetMetadata\x12/\n\x08row_type\x18\x01 \x01(\x0b\x32\x1d.google.spanner.v1.StructType\x12\x33\n\x0btransaction\x18\x02 \x01(\x0b\x32\x1e.google.spanner.v1.Transaction"\xb9\x01\n\x0eResultSetStats\x12\x30\n\nquery_plan\x18\x01 \x01(\x0b\x32\x1c.google.spanner.v1.QueryPlan\x12,\n\x0bquery_stats\x18\x02 \x01(\x0b\x32\x17.google.protobuf.Struct\x12\x19\n\x0frow_count_exact\x18\x03 \x01(\x03H\x00\x12\x1f\n\x15row_count_lower_bound\x18\x04 \x01(\x03H\x00\x42\x0b\n\trow_countB\x9a\x01\n\x15\x63om.google.spanner.v1B\x0eResultSetProtoP\x01Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\xf8\x01\x01\xaa\x02\x17Google.Cloud.Spanner.V1\xca\x02\x17Google\\Cloud\\Spanner\\V1b\x06proto3' + '\n.google/cloud/spanner_v1/proto/result_set.proto\x12\x11google.spanner.v1\x1a\x1cgoogle/protobuf/struct.proto\x1a.google/cloud/spanner_v1/proto/query_plan.proto\x1a/google/cloud/spanner_v1/proto/transaction.proto\x1a(google/cloud/spanner_v1/proto/type.proto\x1a\x1cgoogle/api/annotations.proto"\x9f\x01\n\tResultSet\x12\x36\n\x08metadata\x18\x01 \x01(\x0b\x32$.google.spanner.v1.ResultSetMetadata\x12(\n\x04rows\x18\x02 \x03(\x0b\x32\x1a.google.protobuf.ListValue\x12\x30\n\x05stats\x18\x03 \x01(\x0b\x32!.google.spanner.v1.ResultSetStats"\xd1\x01\n\x10PartialResultSet\x12\x36\n\x08metadata\x18\x01 \x01(\x0b\x32$.google.spanner.v1.ResultSetMetadata\x12&\n\x06values\x18\x02 \x03(\x0b\x32\x16.google.protobuf.Value\x12\x15\n\rchunked_value\x18\x03 \x01(\x08\x12\x14\n\x0cresume_token\x18\x04 \x01(\x0c\x12\x30\n\x05stats\x18\x05 \x01(\x0b\x32!.google.spanner.v1.ResultSetStats"y\n\x11ResultSetMetadata\x12/\n\x08row_type\x18\x01 \x01(\x0b\x32\x1d.google.spanner.v1.StructType\x12\x33\n\x0btransaction\x18\x02 \x01(\x0b\x32\x1e.google.spanner.v1.Transaction"\xb9\x01\n\x0eResultSetStats\x12\x30\n\nquery_plan\x18\x01 \x01(\x0b\x32\x1c.google.spanner.v1.QueryPlan\x12,\n\x0bquery_stats\x18\x02 \x01(\x0b\x32\x17.google.protobuf.Struct\x12\x19\n\x0frow_count_exact\x18\x03 \x01(\x03H\x00\x12\x1f\n\x15row_count_lower_bound\x18\x04 \x01(\x03H\x00\x42\x0b\n\trow_countB\x9a\x01\n\x15\x63om.google.spanner.v1B\x0eResultSetProtoP\x01Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\xf8\x01\x01\xaa\x02\x17Google.Cloud.Spanner.V1\xca\x02\x17Google\\Cloud\\Spanner\\V1b\x06proto3' ), dependencies=[ - google_dot_api_dot_annotations__pb2.DESCRIPTOR, google_dot_protobuf_dot_struct__pb2.DESCRIPTOR, google_dot_cloud_dot_spanner__v1_dot_proto_dot_query__plan__pb2.DESCRIPTOR, google_dot_cloud_dot_spanner__v1_dot_proto_dot_transaction__pb2.DESCRIPTOR, google_dot_cloud_dot_spanner__v1_dot_proto_dot_type__pb2.DESCRIPTOR, + google_dot_api_dot_annotations__pb2.DESCRIPTOR, ], ) diff --git a/spanner/google/cloud/spanner_v1/proto/spanner.proto b/spanner/google/cloud/spanner_v1/proto/spanner.proto index a643e7a6c1a1..9cdbd7881c65 100644 --- a/spanner/google/cloud/spanner_v1/proto/spanner.proto +++ b/spanner/google/cloud/spanner_v1/proto/spanner.proto @@ -18,6 +18,9 @@ syntax = "proto3"; package google.spanner.v1; import "google/api/annotations.proto"; +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; +import "google/api/resource.proto"; import "google/protobuf/empty.proto"; import "google/protobuf/struct.proto"; import "google/protobuf/timestamp.proto"; @@ -40,6 +43,11 @@ option php_namespace = "Google\\Cloud\\Spanner\\V1"; // The Cloud Spanner API can be used to manage sessions and execute // transactions on data stored in Cloud Spanner databases. service Spanner { + option (google.api.default_host) = "spanner.googleapis.com"; + option (google.api.oauth_scopes) = + "https://www.googleapis.com/auth/cloud-platform," + "https://www.googleapis.com/auth/spanner.data"; + // 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 @@ -51,8 +59,8 @@ service Spanner { // 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. + // 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 // operations are sent for more than an hour. If a session is deleted, // requests to it return `NOT_FOUND`. @@ -64,18 +72,19 @@ service Spanner { post: "/v1/{database=projects/*/instances/*/databases/*}/sessions" body: "*" }; + option (google.api.method_signature) = "database"; } // Creates multiple new sessions. // // 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: "*" }; + option (google.api.method_signature) = "database,session_count"; } // Gets a session. Returns `NOT_FOUND` if the session does not exist. @@ -85,6 +94,7 @@ service Spanner { option (google.api.http) = { get: "/v1/{name=projects/*/instances/*/databases/*/sessions/*}" }; + option (google.api.method_signature) = "name"; } // Lists all sessions in a given database. @@ -92,6 +102,7 @@ service Spanner { option (google.api.http) = { get: "/v1/{database=projects/*/instances/*/databases/*}/sessions" }; + option (google.api.method_signature) = "database"; } // Ends a session, releasing server resources associated with it. This will @@ -101,6 +112,7 @@ service Spanner { option (google.api.http) = { delete: "/v1/{name=projects/*/instances/*/databases/*/sessions/*}" }; + option (google.api.method_signature) = "name"; } // Executes an SQL statement, returning all results in a single reply. This @@ -110,12 +122,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" @@ -123,11 +133,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" @@ -139,24 +149,14 @@ service Spanner { // to be run with lower latency than submitting them sequentially with // [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. // - // Statements are executed in order, sequentially. - // [ExecuteBatchDmlResponse][Spanner.ExecuteBatchDmlResponse] will contain a - // [ResultSet][google.spanner.v1.ResultSet] for each DML statement that has - // successfully executed. If a statement fails, its error status will be - // returned as part of the - // [ExecuteBatchDmlResponse][Spanner.ExecuteBatchDmlResponse]. Execution will - // stop at the first failed statement; the remaining statements will not run. - // - // ExecuteBatchDml is expected to return an OK status with a response even if - // there was an error while processing one of the DML statements. Clients must - // inspect response.status to determine if there were any errors while - // processing the request. - // - // See more details in - // [ExecuteBatchDmlRequest][Spanner.ExecuteBatchDmlRequest] and - // [ExecuteBatchDmlResponse][Spanner.ExecuteBatchDmlResponse]. - rpc ExecuteBatchDml(ExecuteBatchDmlRequest) - returns (ExecuteBatchDmlResponse) { + // 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. + // + // Execution stops after the first failed statement; the remaining statements + // are not executed. + rpc ExecuteBatchDml(ExecuteBatchDmlRequest) returns (ExecuteBatchDmlResponse) { option (google.api.http) = { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeBatchDml" body: "*" @@ -165,15 +165,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. @@ -184,9 +183,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) { @@ -197,8 +196,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) { @@ -206,6 +204,7 @@ service Spanner { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:beginTransaction" body: "*" }; + option (google.api.method_signature) = "session,options"; } // Commits a transaction. The request includes the mutations to be @@ -221,13 +220,14 @@ service Spanner { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:commit" body: "*" }; + option (google.api.method_signature) = "session,transaction_id,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 @@ -237,15 +237,15 @@ service Spanner { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:rollback" body: "*" }; + option (google.api.method_signature) = "session,transaction_id"; } // 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 @@ -260,13 +260,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 @@ -283,17 +282,26 @@ service Spanner { // The request for [CreateSession][google.spanner.v1.Spanner.CreateSession]. message CreateSessionRequest { // Required. The database in which the new session is created. - string database = 1; + string database = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Database" + } + ]; // The session to create. 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; + string database = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Database" + } + ]; // Parameters to be applied to each created session. Session session_template = 2; @@ -302,13 +310,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). - int32 session_count = 3; + // [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; @@ -316,6 +322,11 @@ message BatchCreateSessionsResponse { // A session in the Cloud Spanner API. message Session { + option (google.api.resource) = { + type: "spanner.googleapis.com/Session" + pattern: "projects/{project}/instances/{instance}/databases/{database}/sessions/{session}" + }; + // The name of the session. This is always system-assigned; values provided // when creating a session are ignored. string name = 1; @@ -342,21 +353,30 @@ message Session { // The request for [GetSession][google.spanner.v1.Spanner.GetSession]. message GetSessionRequest { // Required. The name of the session to retrieve. - string name = 1; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Session" + } + ]; } // The request for [ListSessions][google.spanner.v1.Spanner.ListSessions]. message ListSessionsRequest { // Required. The database in which to list sessions. - string database = 1; + string database = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Database" + } + ]; // Number of sessions to be returned in the response. If 0 or less, defaults // to the server's maximum allowed page size. 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; @@ -379,15 +399,20 @@ 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; } // The request for [DeleteSession][google.spanner.v1.Spanner.DeleteSession]. message DeleteSessionRequest { // Required. The name of the session to delete. - string name = 1; + string name = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Session" + } + ]; } // The request for [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] and @@ -408,43 +433,45 @@ message ExecuteSqlRequest { } // Required. The session in which the SQL query should be performed. - string session = 1; + string session = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Session" + } + ]; // The transaction to use. // // For queries, if none is provided, the default is a temporary read-only // transaction with strong concurrency. // - // Standard DML statements require a ReadWrite transaction. Single-use - // transactions are not supported (to avoid replay). The caller must - // either supply an existing transaction ID or begin a new transaction. + // Standard DML statements require a read-write transaction. To protect + // against replays, single-use transactions are not supported. The caller + // must either supply an existing transaction ID or begin a new transaction. // - // Partitioned DML requires an existing PartitionedDml transaction ID. + // Partitioned DML requires an existing Partitioned DML transaction ID. TransactionSelector transaction = 2; // Required. The SQL string. - string sql = 3; + string sql = 3 [(google.api.field_behavior) = REQUIRED]; - // The SQL 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. + // Parameter names and values that bind to placeholders in the SQL string. + // + // A parameter placeholder consists of the `@` character followed by the + // parameter name (for example, `@firstName`). Parameter names can contain + // 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 statement with unbound parameters. + // `"WHERE id > @msg_id AND id < @msg_id + 100"` // - // Parameter values are specified using `params`, which is a JSON - // object whose keys are parameter names, and whose values are the - // corresponding parameter values. + // It is an error to execute a SQL statement with unbound parameters. 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. + // 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 @@ -454,18 +481,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 @@ -474,7 +498,7 @@ message ExecuteSqlRequest { // PartitionQueryRequest message used to create this partition_token. bytes partition_token = 8; - // A per-transaction sequence number used to identify this request. This + // 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. // @@ -487,34 +511,30 @@ message ExecuteSqlRequest { int64 seqno = 9; } -// The request for [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml] +// The request for [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. message ExecuteBatchDmlRequest { // A single DML statement. message Statement { // Required. The DML string. string sql = 1; - // The DML 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. + // Parameter names and values that bind to placeholders in the DML string. + // + // A parameter placeholder consists of the `@` character followed by the + // parameter name (for example, `@firstName`). Parameter names can contain + // 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 statement with unbound parameters. + // `"WHERE id > @msg_id AND id < @msg_id + 100"` // - // Parameter values are specified using `params`, which is a JSON - // object whose keys are parameter names, and whose values are the - // corresponding parameter values. + // It is an error to execute a SQL statement with unbound parameters. google.protobuf.Struct params = 2; // 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 @@ -524,62 +544,74 @@ message ExecuteBatchDmlRequest { } // Required. The session in which the DML statements should be performed. - string session = 1; + string session = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Session" + } + ]; - // The transaction to use. A ReadWrite transaction is required. Single-use - // transactions are not supported (to avoid replay). The caller must either - // supply an existing transaction ID or begin a new transaction. - TransactionSelector transaction = 2; + // Required. The transaction to use. Must be a read-write transaction. + // + // To protect against replays, single-use transactions are not supported. The + // caller must either supply an existing transaction ID or begin a new + // transaction. + TransactionSelector transaction = 2 [(google.api.field_behavior) = 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 will stop at the - // first failed statement; the remaining statements will not run. + // 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. // - // REQUIRES: statements_size() > 0. - repeated Statement statements = 3; + // Callers must provide at least one statement. + repeated Statement statements = 3 [(google.api.field_behavior) = REQUIRED]; - // A per-transaction sequence number used to identify this request. This is - // used in the same space as the seqno in - // [ExecuteSqlRequest][Spanner.ExecuteSqlRequest]. See more details - // in [ExecuteSqlRequest][Spanner.ExecuteSqlRequest]. - int64 seqno = 4; + // 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 + // sequence number, the transaction may be aborted. Replays of previously + // handled requests will yield the same response as the first execution. + 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], one for each DML statement that -// has successfully executed. If a statement fails, the error is returned as -// part of the response payload. Clients can determine whether all DML -// statements have run successfully, or if a statement failed, using one of the -// following approaches: +// 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 if 'status' field is OkStatus. -// 2. Check if result_sets_size() equals the number of statements in -// [ExecuteBatchDmlRequest][Spanner.ExecuteBatchDmlRequest]. +// 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. // -// Example 1: A request with 5 DML statements, all executed successfully. -// Result: A response with 5 ResultSets, one for each statement in the same -// order, and an OK status. +// Example 1: // -// Example 2: A request with 5 DML statements. The 3rd statement has a syntax -// error. -// Result: A response with 2 ResultSets, for the first 2 statements that -// run successfully, and a syntax error (INVALID_ARGUMENT) status. From -// result_set_size() client can determine that the 3rd statement has failed. +// * Request: 5 DML statements, all executed successfully. +// * 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. message ExecuteBatchDmlResponse { - // ResultSets, one 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] will not contain any rows. The - // [ResultSetStats][google.spanner.v1.ResultSetStats] in each - // [ResultSet][google.spanner.v1.ResultSet] will contain the number of rows - // modified by the statement. - // - // Only the first ResultSet in the response contains a valid + // 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, status will be OK. + // If all DML statements are executed successfully, the status is `OK`. // Otherwise, the error status of the first failed statement. google.rpc.Status status = 2; } @@ -609,13 +641,18 @@ message PartitionOptions { // The request for [PartitionQuery][google.spanner.v1.Spanner.PartitionQuery] message PartitionQueryRequest { // Required. The session used to create the partitions. - string session = 1; + string session = 1 [ + (google.api.field_behavior) = REQUIRED, + (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; - // The query request to generate partitions for. The request will fail if + // 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 @@ -623,31 +660,27 @@ message PartitionQueryRequest { // 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; + string sql = 3 [(google.api.field_behavior) = REQUIRED]; - // 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. + // Parameter names and values that bind to placeholders in the SQL string. + // + // A parameter placeholder consists of the `@` character followed by the + // parameter name (for example, `@firstName`). Parameter names can contain + // 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. + // `"WHERE id > @msg_id AND id < @msg_id + 100"` // - // Parameter values are specified using `params`, which is a JSON - // object whose keys are parameter names, and whose values are the - // corresponding parameter values. + // It is an error to execute a SQL statement with unbound parameters. 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.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 @@ -662,38 +695,37 @@ message PartitionQueryRequest { // The request for [PartitionRead][google.spanner.v1.Spanner.PartitionRead] message PartitionReadRequest { // Required. The session used to create the partitions. - string session = 1; + string session = 1 [ + (google.api.field_behavior) = REQUIRED, + (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 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.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 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. 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 // exist in the database. Read yields nothing for nonexistent rows. - KeySet key_set = 6; + KeySet key_set = 6 [(google.api.field_behavior) = REQUIRED]; // Additional options that affect how many partitions are created. PartitionOptions partition_options = 9; @@ -722,44 +754,42 @@ message PartitionResponse { // [StreamingRead][google.spanner.v1.Spanner.StreamingRead]. message ReadRequest { // Required. The session in which the read should be performed. - string session = 1; + string session = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Session" + } + ]; // 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 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. 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. 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. - KeySet key_set = 6; + KeySet key_set = 6 [(google.api.field_behavior) = REQUIRED]; // If greater than zero, only the first `limit` rows are yielded. If `limit` // is zero, the default is no limit. A limit cannot be specified if @@ -768,9 +798,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; @@ -781,20 +811,29 @@ 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; + string session = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Session" + } + ]; // Required. Options for the new transaction. - TransactionOptions options = 2; + TransactionOptions options = 2 [(google.api.field_behavior) = REQUIRED]; } // 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; + string session = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Session" + } + ]; // Required. The transaction in which to commit. oneof transaction { @@ -828,8 +867,21 @@ message CommitResponse { // 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; + string session = 1 [ + (google.api.field_behavior) = REQUIRED, + (google.api.resource_reference) = { + type: "spanner.googleapis.com/Session" + } + ]; // Required. The transaction to roll back. - bytes transaction_id = 2; + bytes transaction_id = 2 [(google.api.field_behavior) = REQUIRED]; } + +// 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}" +}; diff --git a/spanner/google/cloud/spanner_v1/proto/spanner_pb2.py b/spanner/google/cloud/spanner_v1/proto/spanner_pb2.py index 78a7c4b109ef..9581f229f2b3 100644 --- a/spanner/google/cloud/spanner_v1/proto/spanner_pb2.py +++ b/spanner/google/cloud/spanner_v1/proto/spanner_pb2.py @@ -16,6 +16,9 @@ from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2 +from google.api import client_pb2 as google_dot_api_dot_client__pb2 +from google.api import field_behavior_pb2 as google_dot_api_dot_field__behavior__pb2 +from google.api import resource_pb2 as google_dot_api_dot_resource__pb2 from google.protobuf import empty_pb2 as google_dot_protobuf_dot_empty__pb2 from google.protobuf import struct_pb2 as google_dot_protobuf_dot_struct__pb2 from google.protobuf import timestamp_pb2 as google_dot_protobuf_dot_timestamp__pb2 @@ -42,13 +45,16 @@ package="google.spanner.v1", syntax="proto3", serialized_options=_b( - "\n\025com.google.spanner.v1B\014SpannerProtoP\001Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\252\002\027Google.Cloud.Spanner.V1\312\002\027Google\\Cloud\\Spanner\\V1" + "\n\025com.google.spanner.v1B\014SpannerProtoP\001Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\252\002\027Google.Cloud.Spanner.V1\312\002\027Google\\Cloud\\Spanner\\V1\352A_\n\037spanner.googleapis.com/Database\022\n\x11partition_options\x18\x06 \x01(\x0b\x32#.google.spanner.v1.PartitionOptions\x1aJ\n\x0fParamTypesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12&\n\x05value\x18\x02 \x01(\x0b\x32\x17.google.spanner.v1.Type:\x02\x38\x01"\xff\x01\n\x14PartitionReadRequest\x12\x0f\n\x07session\x18\x01 \x01(\t\x12;\n\x0btransaction\x18\x02 \x01(\x0b\x32&.google.spanner.v1.TransactionSelector\x12\r\n\x05table\x18\x03 \x01(\t\x12\r\n\x05index\x18\x04 \x01(\t\x12\x0f\n\x07\x63olumns\x18\x05 \x03(\t\x12*\n\x07key_set\x18\x06 \x01(\x0b\x32\x19.google.spanner.v1.KeySet\x12>\n\x11partition_options\x18\t \x01(\x0b\x32#.google.spanner.v1.PartitionOptions"$\n\tPartition\x12\x17\n\x0fpartition_token\x18\x01 \x01(\x0c"z\n\x11PartitionResponse\x12\x30\n\npartitions\x18\x01 \x03(\x0b\x32\x1c.google.spanner.v1.Partition\x12\x33\n\x0btransaction\x18\x02 \x01(\x0b\x32\x1e.google.spanner.v1.Transaction"\xf4\x01\n\x0bReadRequest\x12\x0f\n\x07session\x18\x01 \x01(\t\x12;\n\x0btransaction\x18\x02 \x01(\x0b\x32&.google.spanner.v1.TransactionSelector\x12\r\n\x05table\x18\x03 \x01(\t\x12\r\n\x05index\x18\x04 \x01(\t\x12\x0f\n\x07\x63olumns\x18\x05 \x03(\t\x12*\n\x07key_set\x18\x06 \x01(\x0b\x32\x19.google.spanner.v1.KeySet\x12\r\n\x05limit\x18\x08 \x01(\x03\x12\x14\n\x0cresume_token\x18\t \x01(\x0c\x12\x17\n\x0fpartition_token\x18\n \x01(\x0c"b\n\x17\x42\x65ginTransactionRequest\x12\x0f\n\x07session\x18\x01 \x01(\t\x12\x36\n\x07options\x18\x02 \x01(\x0b\x32%.google.spanner.v1.TransactionOptions"\xc2\x01\n\rCommitRequest\x12\x0f\n\x07session\x18\x01 \x01(\t\x12\x18\n\x0etransaction_id\x18\x02 \x01(\x0cH\x00\x12G\n\x16single_use_transaction\x18\x03 \x01(\x0b\x32%.google.spanner.v1.TransactionOptionsH\x00\x12.\n\tmutations\x18\x04 \x03(\x0b\x32\x1b.google.spanner.v1.MutationB\r\n\x0btransaction"F\n\x0e\x43ommitResponse\x12\x34\n\x10\x63ommit_timestamp\x18\x01 \x01(\x0b\x32\x1a.google.protobuf.Timestamp":\n\x0fRollbackRequest\x12\x0f\n\x07session\x18\x01 \x01(\t\x12\x16\n\x0etransaction_id\x18\x02 \x01(\x0c\x32\x90\x14\n\x07Spanner\x12\x9b\x01\n\rCreateSession\x12\'.google.spanner.v1.CreateSessionRequest\x1a\x1a.google.spanner.v1.Session"E\x82\xd3\xe4\x93\x02?":/v1/{database=projects/*/instances/*/databases/*}/sessions:\x01*\x12\xc7\x01\n\x13\x42\x61tchCreateSessions\x12-.google.spanner.v1.BatchCreateSessionsRequest\x1a..google.spanner.v1.BatchCreateSessionsResponse"Q\x82\xd3\xe4\x93\x02K"F/v1/{database=projects/*/instances/*/databases/*}/sessions:batchCreate:\x01*\x12\x90\x01\n\nGetSession\x12$.google.spanner.v1.GetSessionRequest\x1a\x1a.google.spanner.v1.Session"@\x82\xd3\xe4\x93\x02:\x12\x38/v1/{name=projects/*/instances/*/databases/*/sessions/*}\x12\xa3\x01\n\x0cListSessions\x12&.google.spanner.v1.ListSessionsRequest\x1a\'.google.spanner.v1.ListSessionsResponse"B\x82\xd3\xe4\x93\x02<\x12:/v1/{database=projects/*/instances/*/databases/*}/sessions\x12\x92\x01\n\rDeleteSession\x12\'.google.spanner.v1.DeleteSessionRequest\x1a\x16.google.protobuf.Empty"@\x82\xd3\xe4\x93\x02:*8/v1/{name=projects/*/instances/*/databases/*/sessions/*}\x12\xa3\x01\n\nExecuteSql\x12$.google.spanner.v1.ExecuteSqlRequest\x1a\x1c.google.spanner.v1.ResultSet"Q\x82\xd3\xe4\x93\x02K"F/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeSql:\x01*\x12\xbe\x01\n\x13\x45xecuteStreamingSql\x12$.google.spanner.v1.ExecuteSqlRequest\x1a#.google.spanner.v1.PartialResultSet"Z\x82\xd3\xe4\x93\x02T"O/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeStreamingSql:\x01*0\x01\x12\xc0\x01\n\x0f\x45xecuteBatchDml\x12).google.spanner.v1.ExecuteBatchDmlRequest\x1a*.google.spanner.v1.ExecuteBatchDmlResponse"V\x82\xd3\xe4\x93\x02P"K/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeBatchDml:\x01*\x12\x91\x01\n\x04Read\x12\x1e.google.spanner.v1.ReadRequest\x1a\x1c.google.spanner.v1.ResultSet"K\x82\xd3\xe4\x93\x02\x45"@/v1/{session=projects/*/instances/*/databases/*/sessions/*}:read:\x01*\x12\xac\x01\n\rStreamingRead\x12\x1e.google.spanner.v1.ReadRequest\x1a#.google.spanner.v1.PartialResultSet"T\x82\xd3\xe4\x93\x02N"I/v1/{session=projects/*/instances/*/databases/*/sessions/*}:streamingRead:\x01*0\x01\x12\xb7\x01\n\x10\x42\x65ginTransaction\x12*.google.spanner.v1.BeginTransactionRequest\x1a\x1e.google.spanner.v1.Transaction"W\x82\xd3\xe4\x93\x02Q"L/v1/{session=projects/*/instances/*/databases/*/sessions/*}:beginTransaction:\x01*\x12\x9c\x01\n\x06\x43ommit\x12 .google.spanner.v1.CommitRequest\x1a!.google.spanner.v1.CommitResponse"M\x82\xd3\xe4\x93\x02G"B/v1/{session=projects/*/instances/*/databases/*/sessions/*}:commit:\x01*\x12\x97\x01\n\x08Rollback\x12".google.spanner.v1.RollbackRequest\x1a\x16.google.protobuf.Empty"O\x82\xd3\xe4\x93\x02I"D/v1/{session=projects/*/instances/*/databases/*/sessions/*}:rollback:\x01*\x12\xb7\x01\n\x0ePartitionQuery\x12(.google.spanner.v1.PartitionQueryRequest\x1a$.google.spanner.v1.PartitionResponse"U\x82\xd3\xe4\x93\x02O"J/v1/{session=projects/*/instances/*/databases/*/sessions/*}:partitionQuery:\x01*\x12\xb4\x01\n\rPartitionRead\x12\'.google.spanner.v1.PartitionReadRequest\x1a$.google.spanner.v1.PartitionResponse"T\x82\xd3\xe4\x93\x02N"I/v1/{session=projects/*/instances/*/databases/*/sessions/*}:partitionRead:\x01*B\x95\x01\n\x15\x63om.google.spanner.v1B\x0cSpannerProtoP\x01Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\xaa\x02\x17Google.Cloud.Spanner.V1\xca\x02\x17Google\\Cloud\\Spanner\\V1b\x06proto3' + '\n+google/cloud/spanner_v1/proto/spanner.proto\x12\x11google.spanner.v1\x1a\x1cgoogle/api/annotations.proto\x1a\x17google/api/client.proto\x1a\x1fgoogle/api/field_behavior.proto\x1a\x19google/api/resource.proto\x1a\x1bgoogle/protobuf/empty.proto\x1a\x1cgoogle/protobuf/struct.proto\x1a\x1fgoogle/protobuf/timestamp.proto\x1a\x17google/rpc/status.proto\x1a(google/cloud/spanner_v1/proto/keys.proto\x1a,google/cloud/spanner_v1/proto/mutation.proto\x1a.google/cloud/spanner_v1/proto/result_set.proto\x1a/google/cloud/spanner_v1/proto/transaction.proto\x1a(google/cloud/spanner_v1/proto/type.proto"~\n\x14\x43reateSessionRequest\x12\x39\n\x08\x64\x61tabase\x18\x01 \x01(\tB\'\xe0\x41\x02\xfa\x41!\n\x1fspanner.googleapis.com/Database\x12+\n\x07session\x18\x02 \x01(\x0b\x32\x1a.google.spanner.v1.Session"\xa9\x01\n\x1a\x42\x61tchCreateSessionsRequest\x12\x39\n\x08\x64\x61tabase\x18\x01 \x01(\tB\'\xe0\x41\x02\xfa\x41!\n\x1fspanner.googleapis.com/Database\x12\x34\n\x10session_template\x18\x02 \x01(\x0b\x32\x1a.google.spanner.v1.Session\x12\x1a\n\rsession_count\x18\x03 \x01(\x05\x42\x03\xe0\x41\x02"J\n\x1b\x42\x61tchCreateSessionsResponse\x12+\n\x07session\x18\x01 \x03(\x0b\x32\x1a.google.spanner.v1.Session"\xe4\x02\n\x07Session\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x36\n\x06labels\x18\x02 \x03(\x0b\x32&.google.spanner.v1.Session.LabelsEntry\x12/\n\x0b\x63reate_time\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12=\n\x19\x61pproximate_last_use_time\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x1a-\n\x0bLabelsEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t:\x02\x38\x01:t\xea\x41q\n\x1espanner.googleapis.com/Session\x12Oprojects/{project}/instances/{instance}/databases/{database}/sessions/{session}"I\n\x11GetSessionRequest\x12\x34\n\x04name\x18\x01 \x01(\tB&\xe0\x41\x02\xfa\x41 \n\x1espanner.googleapis.com/Session"\x87\x01\n\x13ListSessionsRequest\x12\x39\n\x08\x64\x61tabase\x18\x01 \x01(\tB\'\xe0\x41\x02\xfa\x41!\n\x1fspanner.googleapis.com/Database\x12\x11\n\tpage_size\x18\x02 \x01(\x05\x12\x12\n\npage_token\x18\x03 \x01(\t\x12\x0e\n\x06\x66ilter\x18\x04 \x01(\t"]\n\x14ListSessionsResponse\x12,\n\x08sessions\x18\x01 \x03(\x0b\x32\x1a.google.spanner.v1.Session\x12\x17\n\x0fnext_page_token\x18\x02 \x01(\t"L\n\x14\x44\x65leteSessionRequest\x12\x34\n\x04name\x18\x01 \x01(\tB&\xe0\x41\x02\xfa\x41 \n\x1espanner.googleapis.com/Session"\x8d\x04\n\x11\x45xecuteSqlRequest\x12\x37\n\x07session\x18\x01 \x01(\tB&\xe0\x41\x02\xfa\x41 \n\x1espanner.googleapis.com/Session\x12;\n\x0btransaction\x18\x02 \x01(\x0b\x32&.google.spanner.v1.TransactionSelector\x12\x10\n\x03sql\x18\x03 \x01(\tB\x03\xe0\x41\x02\x12\'\n\x06params\x18\x04 \x01(\x0b\x32\x17.google.protobuf.Struct\x12I\n\x0bparam_types\x18\x05 \x03(\x0b\x32\x34.google.spanner.v1.ExecuteSqlRequest.ParamTypesEntry\x12\x14\n\x0cresume_token\x18\x06 \x01(\x0c\x12\x42\n\nquery_mode\x18\x07 \x01(\x0e\x32..google.spanner.v1.ExecuteSqlRequest.QueryMode\x12\x17\n\x0fpartition_token\x18\x08 \x01(\x0c\x12\r\n\x05seqno\x18\t \x01(\x03\x1aJ\n\x0fParamTypesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12&\n\x05value\x18\x02 \x01(\x0b\x32\x17.google.spanner.v1.Type:\x02\x38\x01".\n\tQueryMode\x12\n\n\x06NORMAL\x10\x00\x12\x08\n\x04PLAN\x10\x01\x12\x0b\n\x07PROFILE\x10\x02"\xdf\x03\n\x16\x45xecuteBatchDmlRequest\x12\x37\n\x07session\x18\x01 \x01(\tB&\xe0\x41\x02\xfa\x41 \n\x1espanner.googleapis.com/Session\x12@\n\x0btransaction\x18\x02 \x01(\x0b\x32&.google.spanner.v1.TransactionSelectorB\x03\xe0\x41\x02\x12L\n\nstatements\x18\x03 \x03(\x0b\x32\x33.google.spanner.v1.ExecuteBatchDmlRequest.StatementB\x03\xe0\x41\x02\x12\x12\n\x05seqno\x18\x04 \x01(\x03\x42\x03\xe0\x41\x02\x1a\xe7\x01\n\tStatement\x12\x0b\n\x03sql\x18\x01 \x01(\t\x12\'\n\x06params\x18\x02 \x01(\x0b\x32\x17.google.protobuf.Struct\x12X\n\x0bparam_types\x18\x03 \x03(\x0b\x32\x43.google.spanner.v1.ExecuteBatchDmlRequest.Statement.ParamTypesEntry\x1aJ\n\x0fParamTypesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12&\n\x05value\x18\x02 \x01(\x0b\x32\x17.google.spanner.v1.Type:\x02\x38\x01"p\n\x17\x45xecuteBatchDmlResponse\x12\x31\n\x0bresult_sets\x18\x01 \x03(\x0b\x32\x1c.google.spanner.v1.ResultSet\x12"\n\x06status\x18\x02 \x01(\x0b\x32\x12.google.rpc.Status"H\n\x10PartitionOptions\x12\x1c\n\x14partition_size_bytes\x18\x01 \x01(\x03\x12\x16\n\x0emax_partitions\x18\x02 \x01(\x03"\xa3\x03\n\x15PartitionQueryRequest\x12\x37\n\x07session\x18\x01 \x01(\tB&\xe0\x41\x02\xfa\x41 \n\x1espanner.googleapis.com/Session\x12;\n\x0btransaction\x18\x02 \x01(\x0b\x32&.google.spanner.v1.TransactionSelector\x12\x10\n\x03sql\x18\x03 \x01(\tB\x03\xe0\x41\x02\x12\'\n\x06params\x18\x04 \x01(\x0b\x32\x17.google.protobuf.Struct\x12M\n\x0bparam_types\x18\x05 \x03(\x0b\x32\x38.google.spanner.v1.PartitionQueryRequest.ParamTypesEntry\x12>\n\x11partition_options\x18\x06 \x01(\x0b\x32#.google.spanner.v1.PartitionOptions\x1aJ\n\x0fParamTypesEntry\x12\x0b\n\x03key\x18\x01 \x01(\t\x12&\n\x05value\x18\x02 \x01(\x0b\x32\x17.google.spanner.v1.Type:\x02\x38\x01"\xb1\x02\n\x14PartitionReadRequest\x12\x37\n\x07session\x18\x01 \x01(\tB&\xe0\x41\x02\xfa\x41 \n\x1espanner.googleapis.com/Session\x12;\n\x0btransaction\x18\x02 \x01(\x0b\x32&.google.spanner.v1.TransactionSelector\x12\x12\n\x05table\x18\x03 \x01(\tB\x03\xe0\x41\x02\x12\r\n\x05index\x18\x04 \x01(\t\x12\x0f\n\x07\x63olumns\x18\x05 \x03(\t\x12/\n\x07key_set\x18\x06 \x01(\x0b\x32\x19.google.spanner.v1.KeySetB\x03\xe0\x41\x02\x12>\n\x11partition_options\x18\t \x01(\x0b\x32#.google.spanner.v1.PartitionOptions"$\n\tPartition\x12\x17\n\x0fpartition_token\x18\x01 \x01(\x0c"z\n\x11PartitionResponse\x12\x30\n\npartitions\x18\x01 \x03(\x0b\x32\x1c.google.spanner.v1.Partition\x12\x33\n\x0btransaction\x18\x02 \x01(\x0b\x32\x1e.google.spanner.v1.Transaction"\xab\x02\n\x0bReadRequest\x12\x37\n\x07session\x18\x01 \x01(\tB&\xe0\x41\x02\xfa\x41 \n\x1espanner.googleapis.com/Session\x12;\n\x0btransaction\x18\x02 \x01(\x0b\x32&.google.spanner.v1.TransactionSelector\x12\x12\n\x05table\x18\x03 \x01(\tB\x03\xe0\x41\x02\x12\r\n\x05index\x18\x04 \x01(\t\x12\x14\n\x07\x63olumns\x18\x05 \x03(\tB\x03\xe0\x41\x02\x12/\n\x07key_set\x18\x06 \x01(\x0b\x32\x19.google.spanner.v1.KeySetB\x03\xe0\x41\x02\x12\r\n\x05limit\x18\x08 \x01(\x03\x12\x14\n\x0cresume_token\x18\t \x01(\x0c\x12\x17\n\x0fpartition_token\x18\n \x01(\x0c"\x8f\x01\n\x17\x42\x65ginTransactionRequest\x12\x37\n\x07session\x18\x01 \x01(\tB&\xe0\x41\x02\xfa\x41 \n\x1espanner.googleapis.com/Session\x12;\n\x07options\x18\x02 \x01(\x0b\x32%.google.spanner.v1.TransactionOptionsB\x03\xe0\x41\x02"\xea\x01\n\rCommitRequest\x12\x37\n\x07session\x18\x01 \x01(\tB&\xe0\x41\x02\xfa\x41 \n\x1espanner.googleapis.com/Session\x12\x18\n\x0etransaction_id\x18\x02 \x01(\x0cH\x00\x12G\n\x16single_use_transaction\x18\x03 \x01(\x0b\x32%.google.spanner.v1.TransactionOptionsH\x00\x12.\n\tmutations\x18\x04 \x03(\x0b\x32\x1b.google.spanner.v1.MutationB\r\n\x0btransaction"F\n\x0e\x43ommitResponse\x12\x34\n\x10\x63ommit_timestamp\x18\x01 \x01(\x0b\x32\x1a.google.protobuf.Timestamp"g\n\x0fRollbackRequest\x12\x37\n\x07session\x18\x01 \x01(\tB&\xe0\x41\x02\xfa\x41 \n\x1espanner.googleapis.com/Session\x12\x1b\n\x0etransaction_id\x18\x02 \x01(\x0c\x42\x03\xe0\x41\x02\x32\xc0\x16\n\x07Spanner\x12\xa6\x01\n\rCreateSession\x12\'.google.spanner.v1.CreateSessionRequest\x1a\x1a.google.spanner.v1.Session"P\x82\xd3\xe4\x93\x02?":/v1/{database=projects/*/instances/*/databases/*}/sessions:\x01*\xda\x41\x08\x64\x61tabase\x12\xe0\x01\n\x13\x42\x61tchCreateSessions\x12-.google.spanner.v1.BatchCreateSessionsRequest\x1a..google.spanner.v1.BatchCreateSessionsResponse"j\x82\xd3\xe4\x93\x02K"F/v1/{database=projects/*/instances/*/databases/*}/sessions:batchCreate:\x01*\xda\x41\x16\x64\x61tabase,session_count\x12\x97\x01\n\nGetSession\x12$.google.spanner.v1.GetSessionRequest\x1a\x1a.google.spanner.v1.Session"G\x82\xd3\xe4\x93\x02:\x12\x38/v1/{name=projects/*/instances/*/databases/*/sessions/*}\xda\x41\x04name\x12\xae\x01\n\x0cListSessions\x12&.google.spanner.v1.ListSessionsRequest\x1a\'.google.spanner.v1.ListSessionsResponse"M\x82\xd3\xe4\x93\x02<\x12:/v1/{database=projects/*/instances/*/databases/*}/sessions\xda\x41\x08\x64\x61tabase\x12\x99\x01\n\rDeleteSession\x12\'.google.spanner.v1.DeleteSessionRequest\x1a\x16.google.protobuf.Empty"G\x82\xd3\xe4\x93\x02:*8/v1/{name=projects/*/instances/*/databases/*/sessions/*}\xda\x41\x04name\x12\xa3\x01\n\nExecuteSql\x12$.google.spanner.v1.ExecuteSqlRequest\x1a\x1c.google.spanner.v1.ResultSet"Q\x82\xd3\xe4\x93\x02K"F/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeSql:\x01*\x12\xbe\x01\n\x13\x45xecuteStreamingSql\x12$.google.spanner.v1.ExecuteSqlRequest\x1a#.google.spanner.v1.PartialResultSet"Z\x82\xd3\xe4\x93\x02T"O/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeStreamingSql:\x01*0\x01\x12\xc0\x01\n\x0f\x45xecuteBatchDml\x12).google.spanner.v1.ExecuteBatchDmlRequest\x1a*.google.spanner.v1.ExecuteBatchDmlResponse"V\x82\xd3\xe4\x93\x02P"K/v1/{session=projects/*/instances/*/databases/*/sessions/*}:executeBatchDml:\x01*\x12\x91\x01\n\x04Read\x12\x1e.google.spanner.v1.ReadRequest\x1a\x1c.google.spanner.v1.ResultSet"K\x82\xd3\xe4\x93\x02\x45"@/v1/{session=projects/*/instances/*/databases/*/sessions/*}:read:\x01*\x12\xac\x01\n\rStreamingRead\x12\x1e.google.spanner.v1.ReadRequest\x1a#.google.spanner.v1.PartialResultSet"T\x82\xd3\xe4\x93\x02N"I/v1/{session=projects/*/instances/*/databases/*/sessions/*}:streamingRead:\x01*0\x01\x12\xc9\x01\n\x10\x42\x65ginTransaction\x12*.google.spanner.v1.BeginTransactionRequest\x1a\x1e.google.spanner.v1.Transaction"i\x82\xd3\xe4\x93\x02Q"L/v1/{session=projects/*/instances/*/databases/*/sessions/*}:beginTransaction:\x01*\xda\x41\x0fsession,options\x12\xeb\x01\n\x06\x43ommit\x12 .google.spanner.v1.CommitRequest\x1a!.google.spanner.v1.CommitResponse"\x9b\x01\x82\xd3\xe4\x93\x02G"B/v1/{session=projects/*/instances/*/databases/*/sessions/*}:commit:\x01*\xda\x41 session,transaction_id,mutations\xda\x41(session,single_use_transaction,mutations\x12\xb0\x01\n\x08Rollback\x12".google.spanner.v1.RollbackRequest\x1a\x16.google.protobuf.Empty"h\x82\xd3\xe4\x93\x02I"D/v1/{session=projects/*/instances/*/databases/*/sessions/*}:rollback:\x01*\xda\x41\x16session,transaction_id\x12\xb7\x01\n\x0ePartitionQuery\x12(.google.spanner.v1.PartitionQueryRequest\x1a$.google.spanner.v1.PartitionResponse"U\x82\xd3\xe4\x93\x02O"J/v1/{session=projects/*/instances/*/databases/*/sessions/*}:partitionQuery:\x01*\x12\xb4\x01\n\rPartitionRead\x12\'.google.spanner.v1.PartitionReadRequest\x1a$.google.spanner.v1.PartitionResponse"T\x82\xd3\xe4\x93\x02N"I/v1/{session=projects/*/instances/*/databases/*/sessions/*}:partitionRead:\x01*\x1aw\xca\x41\x16spanner.googleapis.com\xd2\x41[https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spanner.dataB\xf7\x01\n\x15\x63om.google.spanner.v1B\x0cSpannerProtoP\x01Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\xaa\x02\x17Google.Cloud.Spanner.V1\xca\x02\x17Google\\Cloud\\Spanner\\V1\xea\x41_\n\x1fspanner.googleapis.com/Database\x12 @msg_id AND id - < @msg_id + 100"`` It is an error to execute an SQL statement - 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. + Parameter names and values that bind to placeholders in the + SQL string. A parameter placeholder consists of the ``@`` + character followed by the parameter name (for example, + ``@firstName``). Parameter names can contain 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 a SQL statement + with unbound parameters. param_types: It is not always possible for Cloud Spanner to infer the right SQL type from a JSON value. For example, values of type @@ -2516,13 +2549,13 @@ this partition\_token. seqno: A per-transaction sequence number used to identify this - request. This 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 sequence number, the transaction may be - aborted. Replays of previously handled requests will yield the - same response as the first execution. Required for DML + 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 sequence number, the transaction may + be aborted. Replays of previously handled requests will yield + the same response as the first execution. Required for DML statements. Ignored for queries. """, # @@protoc_insertion_point(class_scope:google.spanner.v1.ExecuteSqlRequest) @@ -2557,17 +2590,15 @@ sql: Required. The DML string. params: - The DML 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 statement - 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. + Parameter names and values that bind to placeholders in the + DML string. A parameter placeholder consists of the ``@`` + character followed by the parameter name (for example, + ``@firstName``). Parameter names can contain 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 a SQL statement + with unbound parameters. param_types: It is not always possible for Cloud Spanner to infer the right SQL type from a JSON value. For example, values of type @@ -2585,7 +2616,7 @@ DESCRIPTOR=_EXECUTEBATCHDMLREQUEST, __module__="google.cloud.spanner_v1.proto.spanner_pb2", __doc__="""The request for - [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml] + [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. Attributes: @@ -2593,22 +2624,26 @@ Required. The session in which the DML statements should be performed. transaction: - The transaction to use. A ReadWrite transaction is required. - Single-use transactions are not supported (to avoid replay). - The caller must either supply an existing transaction ID or - begin a new transaction. + Required. The transaction to use. Must be a read-write + transaction. To protect against replays, single-use + transactions are not supported. The caller must either supply + an existing transaction ID or begin a new transaction. statements: - 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 will stop at the first failed statement; - the remaining statements will not run. REQUIRES: - statements\_size() > 0. + 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. seqno: - A per-transaction sequence number used to identify this - request. This is used in the same space as the seqno in - [ExecuteSqlRequest][Spanner.ExecuteSqlRequest]. See more - details in [ExecuteSqlRequest][Spanner.ExecuteSqlRequest]. + 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 sequence number, the + transaction may be aborted. Replays of previously handled + requests will yield the same response as the first execution. """, # @@protoc_insertion_point(class_scope:google.spanner.v1.ExecuteBatchDmlRequest) ), @@ -2625,41 +2660,52 @@ __module__="google.cloud.spanner_v1.proto.spanner_pb2", __doc__="""The response for [ExecuteBatchDml][google.spanner.v1.Spanner.ExecuteBatchDml]. Contains a - list of [ResultSet][google.spanner.v1.ResultSet], one for each DML - statement that has successfully executed. If a statement fails, the - error is returned as part of the response payload. Clients can determine - whether all DML statements have run successfully, or if a statement - failed, using one of the following approaches: + 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 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. + + Example 1: - 1. Check if 'status' field is OkStatus. - 2. Check if result\_sets\_size() equals the number of statements in - [ExecuteBatchDmlRequest][Spanner.ExecuteBatchDmlRequest]. + - Request: 5 DML statements, all executed successfully. + - Response: 5 [ResultSet][google.spanner.v1.ResultSet] messages, with + the status ``OK``. - Example 1: A request with 5 DML statements, all executed successfully. - Result: A response with 5 ResultSets, one for each statement in the same - order, and an OK status. + Example 2: - Example 2: A request with 5 DML statements. The 3rd statement has a - syntax error. Result: A response with 2 ResultSets, for the first 2 - statements that run successfully, and a syntax error (INVALID\_ARGUMENT) - status. From result\_set\_size() client can determine that the 3rd - statement has failed. + - 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. Attributes: result_sets: - ResultSets, one 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] will - not contain any rows. The - [ResultSetStats][google.spanner.v1.ResultSetStats] in each - [ResultSet][google.spanner.v1.ResultSet] will contain the + 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 in the response contains a valid + [ResultSet][google.spanner.v1.ResultSet] in the response + contains valid [ResultSetMetadata][google.spanner.v1.ResultSetMetadata]. status: - If all DML statements are executed successfully, status will - be OK. Otherwise, the error status of the first failed + If all DML statements are executed successfully, the status is + ``OK``. Otherwise, the error status of the first failed statement. """, # @@protoc_insertion_point(class_scope:google.spanner.v1.ExecuteBatchDmlResponse) @@ -2723,28 +2769,27 @@ Read only snapshot transactions are supported, read/write and single use transactions are not. sql: - 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 PartitionedDml - transaction for large, partition-friendly DML operations. + 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][g + oogle.spanner.v1.Spanner.ExecuteStreamingSql] with a + PartitionedDml transaction for large, partition-friendly DML + operations. params: - 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. + Parameter names and values that bind to placeholders in the + SQL string. A parameter placeholder consists of the ``@`` + character followed by the parameter name (for example, + ``@firstName``). Parameter names can contain 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 a SQL statement + with unbound parameters. param_types: It is not always possible for Cloud Spanner to infer the right SQL type from a JSON value. For example, values of type @@ -2888,8 +2933,9 @@ [key\_set][google.spanner.v1.ReadRequest.key\_set] for further information. columns: - 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. key_set: Required. ``key_set`` identifies the rows to be yielded. ``key_set`` names the primary keys of the rows in @@ -3034,19 +3080,48 @@ DESCRIPTOR._options = None +_CREATESESSIONREQUEST.fields_by_name["database"]._options = None +_BATCHCREATESESSIONSREQUEST.fields_by_name["database"]._options = None +_BATCHCREATESESSIONSREQUEST.fields_by_name["session_count"]._options = None _SESSION_LABELSENTRY._options = None +_SESSION._options = None +_GETSESSIONREQUEST.fields_by_name["name"]._options = None +_LISTSESSIONSREQUEST.fields_by_name["database"]._options = None +_DELETESESSIONREQUEST.fields_by_name["name"]._options = None _EXECUTESQLREQUEST_PARAMTYPESENTRY._options = None +_EXECUTESQLREQUEST.fields_by_name["session"]._options = None +_EXECUTESQLREQUEST.fields_by_name["sql"]._options = None _EXECUTEBATCHDMLREQUEST_STATEMENT_PARAMTYPESENTRY._options = None +_EXECUTEBATCHDMLREQUEST.fields_by_name["session"]._options = None +_EXECUTEBATCHDMLREQUEST.fields_by_name["transaction"]._options = None +_EXECUTEBATCHDMLREQUEST.fields_by_name["statements"]._options = None +_EXECUTEBATCHDMLREQUEST.fields_by_name["seqno"]._options = None _PARTITIONQUERYREQUEST_PARAMTYPESENTRY._options = None +_PARTITIONQUERYREQUEST.fields_by_name["session"]._options = None +_PARTITIONQUERYREQUEST.fields_by_name["sql"]._options = None +_PARTITIONREADREQUEST.fields_by_name["session"]._options = None +_PARTITIONREADREQUEST.fields_by_name["table"]._options = None +_PARTITIONREADREQUEST.fields_by_name["key_set"]._options = None +_READREQUEST.fields_by_name["session"]._options = None +_READREQUEST.fields_by_name["table"]._options = None +_READREQUEST.fields_by_name["columns"]._options = None +_READREQUEST.fields_by_name["key_set"]._options = None +_BEGINTRANSACTIONREQUEST.fields_by_name["session"]._options = None +_BEGINTRANSACTIONREQUEST.fields_by_name["options"]._options = None +_COMMITREQUEST.fields_by_name["session"]._options = None +_ROLLBACKREQUEST.fields_by_name["session"]._options = None +_ROLLBACKREQUEST.fields_by_name["transaction_id"]._options = None _SPANNER = _descriptor.ServiceDescriptor( name="Spanner", full_name="google.spanner.v1.Spanner", file=DESCRIPTOR, index=0, - serialized_options=None, - serialized_start=3805, - serialized_end=6381, + serialized_options=_b( + "\312A\026spanner.googleapis.com\322A[https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spanner.data" + ), + serialized_start=4599, + serialized_end=7479, methods=[ _descriptor.MethodDescriptor( name="CreateSession", @@ -3056,7 +3131,7 @@ input_type=_CREATESESSIONREQUEST, output_type=_SESSION, serialized_options=_b( - '\202\323\344\223\002?":/v1/{database=projects/*/instances/*/databases/*}/sessions:\001*' + '\202\323\344\223\002?":/v1/{database=projects/*/instances/*/databases/*}/sessions:\001*\332A\010database' ), ), _descriptor.MethodDescriptor( @@ -3067,7 +3142,7 @@ input_type=_BATCHCREATESESSIONSREQUEST, output_type=_BATCHCREATESESSIONSRESPONSE, serialized_options=_b( - '\202\323\344\223\002K"F/v1/{database=projects/*/instances/*/databases/*}/sessions:batchCreate:\001*' + '\202\323\344\223\002K"F/v1/{database=projects/*/instances/*/databases/*}/sessions:batchCreate:\001*\332A\026database,session_count' ), ), _descriptor.MethodDescriptor( @@ -3078,7 +3153,7 @@ input_type=_GETSESSIONREQUEST, output_type=_SESSION, serialized_options=_b( - "\202\323\344\223\002:\0228/v1/{name=projects/*/instances/*/databases/*/sessions/*}" + "\202\323\344\223\002:\0228/v1/{name=projects/*/instances/*/databases/*/sessions/*}\332A\004name" ), ), _descriptor.MethodDescriptor( @@ -3089,7 +3164,7 @@ input_type=_LISTSESSIONSREQUEST, output_type=_LISTSESSIONSRESPONSE, serialized_options=_b( - "\202\323\344\223\002<\022:/v1/{database=projects/*/instances/*/databases/*}/sessions" + "\202\323\344\223\002<\022:/v1/{database=projects/*/instances/*/databases/*}/sessions\332A\010database" ), ), _descriptor.MethodDescriptor( @@ -3100,7 +3175,7 @@ input_type=_DELETESESSIONREQUEST, output_type=google_dot_protobuf_dot_empty__pb2._EMPTY, serialized_options=_b( - "\202\323\344\223\002:*8/v1/{name=projects/*/instances/*/databases/*/sessions/*}" + "\202\323\344\223\002:*8/v1/{name=projects/*/instances/*/databases/*/sessions/*}\332A\004name" ), ), _descriptor.MethodDescriptor( @@ -3166,7 +3241,7 @@ input_type=_BEGINTRANSACTIONREQUEST, output_type=google_dot_cloud_dot_spanner__v1_dot_proto_dot_transaction__pb2._TRANSACTION, serialized_options=_b( - '\202\323\344\223\002Q"L/v1/{session=projects/*/instances/*/databases/*/sessions/*}:beginTransaction:\001*' + '\202\323\344\223\002Q"L/v1/{session=projects/*/instances/*/databases/*/sessions/*}:beginTransaction:\001*\332A\017session,options' ), ), _descriptor.MethodDescriptor( @@ -3177,7 +3252,7 @@ input_type=_COMMITREQUEST, output_type=_COMMITRESPONSE, serialized_options=_b( - '\202\323\344\223\002G"B/v1/{session=projects/*/instances/*/databases/*/sessions/*}:commit:\001*' + '\202\323\344\223\002G"B/v1/{session=projects/*/instances/*/databases/*/sessions/*}:commit:\001*\332A session,transaction_id,mutations\332A(session,single_use_transaction,mutations' ), ), _descriptor.MethodDescriptor( @@ -3188,7 +3263,7 @@ input_type=_ROLLBACKREQUEST, output_type=google_dot_protobuf_dot_empty__pb2._EMPTY, serialized_options=_b( - '\202\323\344\223\002I"D/v1/{session=projects/*/instances/*/databases/*/sessions/*}:rollback:\001*' + '\202\323\344\223\002I"D/v1/{session=projects/*/instances/*/databases/*/sessions/*}:rollback:\001*\332A\026session,transaction_id' ), ), _descriptor.MethodDescriptor( diff --git a/spanner/google/cloud/spanner_v1/proto/spanner_pb2_grpc.py b/spanner/google/cloud/spanner_v1/proto/spanner_pb2_grpc.py index b99970b34b15..266d7bdc6193 100644 --- a/spanner/google/cloud/spanner_v1/proto/spanner_pb2_grpc.py +++ b/spanner/google/cloud/spanner_v1/proto/spanner_pb2_grpc.py @@ -122,8 +122,8 @@ def CreateSession(self, request, context): 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. + 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 operations are sent for more than an hour. If a session is deleted, requests to it return `NOT_FOUND`. @@ -178,23 +178,21 @@ def ExecuteSql(self, request, context): 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. """ context.set_code(grpc.StatusCode.UNIMPLEMENTED) context.set_details("Method not implemented!") raise NotImplementedError("Method not implemented!") def ExecuteStreamingSql(self, request, context): - """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. """ context.set_code(grpc.StatusCode.UNIMPLEMENTED) context.set_details("Method not implemented!") @@ -205,22 +203,13 @@ def ExecuteBatchDml(self, request, context): to be run with lower latency than submitting them sequentially with [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql]. - Statements are executed in order, sequentially. - [ExecuteBatchDmlResponse][Spanner.ExecuteBatchDmlResponse] will contain a - [ResultSet][google.spanner.v1.ResultSet] for each DML statement that has - successfully executed. If a statement fails, its error status will be - returned as part of the - [ExecuteBatchDmlResponse][Spanner.ExecuteBatchDmlResponse]. Execution will - stop at the first failed statement; the remaining statements will not run. - - ExecuteBatchDml is expected to return an OK status with a response even if - there was an error while processing one of the DML statements. Clients must - inspect response.status to determine if there were any errors while - processing the request. - - See more details in - [ExecuteBatchDmlRequest][Spanner.ExecuteBatchDmlRequest] and - [ExecuteBatchDmlResponse][Spanner.ExecuteBatchDmlResponse]. + 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. + + Execution stops after the first failed statement; the remaining statements + are not executed. """ context.set_code(grpc.StatusCode.UNIMPLEMENTED) context.set_details("Method not implemented!") @@ -229,15 +218,14 @@ def ExecuteBatchDml(self, request, context): def Read(self, request, context): """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. @@ -247,9 +235,9 @@ def Read(self, request, context): raise NotImplementedError("Method not implemented!") def StreamingRead(self, request, context): - """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. """ @@ -259,8 +247,7 @@ def StreamingRead(self, request, context): def BeginTransaction(self, request, context): """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. """ @@ -285,9 +272,8 @@ def Commit(self, request, context): def Rollback(self, request, context): """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 @@ -300,11 +286,10 @@ def Rollback(self, request, context): def PartitionQuery(self, request, context): """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 @@ -318,13 +303,12 @@ def PartitionQuery(self, request, context): def PartitionRead(self, request, context): """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 diff --git a/spanner/google/cloud/spanner_v1/proto/transaction.proto b/spanner/google/cloud/spanner_v1/proto/transaction.proto index 7253bcbe0044..7c2434b14a81 100644 --- a/spanner/google/cloud/spanner_v1/proto/transaction.proto +++ b/spanner/google/cloud/spanner_v1/proto/transaction.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC +// Copyright 2019 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,14 +11,15 @@ // 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/protobuf/duration.proto"; import "google/protobuf/timestamp.proto"; +import "google/api/annotations.proto"; option csharp_namespace = "Google.Cloud.Spanner.V1"; option go_package = "google.golang.org/genproto/googleapis/spanner/v1;spanner"; @@ -184,8 +185,7 @@ option php_namespace = "Google\\Cloud\\Spanner\\V1"; // reads should be executed within a transaction or at an exact read // timestamp. // -// See -// [TransactionOptions.ReadOnly.strong][google.spanner.v1.TransactionOptions.ReadOnly.strong]. +// See [TransactionOptions.ReadOnly.strong][google.spanner.v1.TransactionOptions.ReadOnly.strong]. // // ### Exact Staleness // @@ -206,9 +206,7 @@ option php_namespace = "Google\\Cloud\\Spanner\\V1"; // equivalent boundedly stale concurrency modes. On the other hand, // boundedly stale reads usually return fresher results. // -// See -// [TransactionOptions.ReadOnly.read_timestamp][google.spanner.v1.TransactionOptions.ReadOnly.read_timestamp] -// and +// See [TransactionOptions.ReadOnly.read_timestamp][google.spanner.v1.TransactionOptions.ReadOnly.read_timestamp] and // [TransactionOptions.ReadOnly.exact_staleness][google.spanner.v1.TransactionOptions.ReadOnly.exact_staleness]. // // ### Bounded Staleness @@ -238,9 +236,7 @@ option php_namespace = "Google\\Cloud\\Spanner\\V1"; // which rows will be read, it can only be used with single-use // read-only transactions. // -// See -// [TransactionOptions.ReadOnly.max_staleness][google.spanner.v1.TransactionOptions.ReadOnly.max_staleness] -// and +// See [TransactionOptions.ReadOnly.max_staleness][google.spanner.v1.TransactionOptions.ReadOnly.max_staleness] and // [TransactionOptions.ReadOnly.min_read_timestamp][google.spanner.v1.TransactionOptions.ReadOnly.min_read_timestamp]. // // ### Old Read Timestamps and Garbage Collection @@ -312,10 +308,14 @@ option php_namespace = "Google\\Cloud\\Spanner\\V1"; message TransactionOptions { // Message type to initiate a read-write transaction. Currently this // transaction type has no options. - message ReadWrite {} + message ReadWrite { + + } // Message type to initiate a Partitioned DML transaction. - message PartitionedDml {} + message PartitionedDml { + + } // Message type to initiate a read-only transaction. message ReadOnly { @@ -381,8 +381,7 @@ message TransactionOptions { } // If true, the Cloud Spanner-selected read timestamp is included in - // the [Transaction][google.spanner.v1.Transaction] message that describes - // the transaction. + // the [Transaction][google.spanner.v1.Transaction] message that describes the transaction. bool return_read_timestamp = 6; } @@ -436,8 +435,7 @@ message Transaction { // [Read][google.spanner.v1.Spanner.Read] or // [ExecuteSql][google.spanner.v1.Spanner.ExecuteSql] call runs. // -// See [TransactionOptions][google.spanner.v1.TransactionOptions] for more -// information about transactions. +// See [TransactionOptions][google.spanner.v1.TransactionOptions] for more information about transactions. message TransactionSelector { // If no fields are set, the default is a single use transaction // with strong concurrency. @@ -452,8 +450,7 @@ message TransactionSelector { // Begin a new transaction and execute this read or SQL query in // it. The transaction ID of the new transaction is returned in - // [ResultSetMetadata.transaction][google.spanner.v1.ResultSetMetadata.transaction], - // which is a [Transaction][google.spanner.v1.Transaction]. + // [ResultSetMetadata.transaction][google.spanner.v1.ResultSetMetadata.transaction], which is a [Transaction][google.spanner.v1.Transaction]. TransactionOptions begin = 3; } } diff --git a/spanner/google/cloud/spanner_v1/proto/transaction_pb2.py b/spanner/google/cloud/spanner_v1/proto/transaction_pb2.py index db95c96805ad..62c21f8e7788 100644 --- a/spanner/google/cloud/spanner_v1/proto/transaction_pb2.py +++ b/spanner/google/cloud/spanner_v1/proto/transaction_pb2.py @@ -15,9 +15,9 @@ _sym_db = _symbol_database.Default() -from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2 from google.protobuf import duration_pb2 as google_dot_protobuf_dot_duration__pb2 from google.protobuf import timestamp_pb2 as google_dot_protobuf_dot_timestamp__pb2 +from google.api import annotations_pb2 as google_dot_api_dot_annotations__pb2 DESCRIPTOR = _descriptor.FileDescriptor( @@ -28,12 +28,12 @@ "\n\025com.google.spanner.v1B\020TransactionProtoP\001Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\252\002\027Google.Cloud.Spanner.V1\312\002\027Google\\Cloud\\Spanner\\V1" ), serialized_pb=_b( - '\n/google/cloud/spanner_v1/proto/transaction.proto\x12\x11google.spanner.v1\x1a\x1cgoogle/api/annotations.proto\x1a\x1egoogle/protobuf/duration.proto\x1a\x1fgoogle/protobuf/timestamp.proto"\xc3\x04\n\x12TransactionOptions\x12\x45\n\nread_write\x18\x01 \x01(\x0b\x32/.google.spanner.v1.TransactionOptions.ReadWriteH\x00\x12O\n\x0fpartitioned_dml\x18\x03 \x01(\x0b\x32\x34.google.spanner.v1.TransactionOptions.PartitionedDmlH\x00\x12\x43\n\tread_only\x18\x02 \x01(\x0b\x32..google.spanner.v1.TransactionOptions.ReadOnlyH\x00\x1a\x0b\n\tReadWrite\x1a\x10\n\x0ePartitionedDml\x1a\xa8\x02\n\x08ReadOnly\x12\x10\n\x06strong\x18\x01 \x01(\x08H\x00\x12\x38\n\x12min_read_timestamp\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.TimestampH\x00\x12\x32\n\rmax_staleness\x18\x03 \x01(\x0b\x32\x19.google.protobuf.DurationH\x00\x12\x34\n\x0eread_timestamp\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.TimestampH\x00\x12\x34\n\x0f\x65xact_staleness\x18\x05 \x01(\x0b\x32\x19.google.protobuf.DurationH\x00\x12\x1d\n\x15return_read_timestamp\x18\x06 \x01(\x08\x42\x11\n\x0ftimestamp_boundB\x06\n\x04mode"M\n\x0bTransaction\x12\n\n\x02id\x18\x01 \x01(\x0c\x12\x32\n\x0eread_timestamp\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp"\xa4\x01\n\x13TransactionSelector\x12;\n\nsingle_use\x18\x01 \x01(\x0b\x32%.google.spanner.v1.TransactionOptionsH\x00\x12\x0c\n\x02id\x18\x02 \x01(\x0cH\x00\x12\x36\n\x05\x62\x65gin\x18\x03 \x01(\x0b\x32%.google.spanner.v1.TransactionOptionsH\x00\x42\n\n\x08selectorB\x99\x01\n\x15\x63om.google.spanner.v1B\x10TransactionProtoP\x01Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\xaa\x02\x17Google.Cloud.Spanner.V1\xca\x02\x17Google\\Cloud\\Spanner\\V1b\x06proto3' + '\n/google/cloud/spanner_v1/proto/transaction.proto\x12\x11google.spanner.v1\x1a\x1egoogle/protobuf/duration.proto\x1a\x1fgoogle/protobuf/timestamp.proto\x1a\x1cgoogle/api/annotations.proto"\xc3\x04\n\x12TransactionOptions\x12\x45\n\nread_write\x18\x01 \x01(\x0b\x32/.google.spanner.v1.TransactionOptions.ReadWriteH\x00\x12O\n\x0fpartitioned_dml\x18\x03 \x01(\x0b\x32\x34.google.spanner.v1.TransactionOptions.PartitionedDmlH\x00\x12\x43\n\tread_only\x18\x02 \x01(\x0b\x32..google.spanner.v1.TransactionOptions.ReadOnlyH\x00\x1a\x0b\n\tReadWrite\x1a\x10\n\x0ePartitionedDml\x1a\xa8\x02\n\x08ReadOnly\x12\x10\n\x06strong\x18\x01 \x01(\x08H\x00\x12\x38\n\x12min_read_timestamp\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.TimestampH\x00\x12\x32\n\rmax_staleness\x18\x03 \x01(\x0b\x32\x19.google.protobuf.DurationH\x00\x12\x34\n\x0eread_timestamp\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.TimestampH\x00\x12\x34\n\x0f\x65xact_staleness\x18\x05 \x01(\x0b\x32\x19.google.protobuf.DurationH\x00\x12\x1d\n\x15return_read_timestamp\x18\x06 \x01(\x08\x42\x11\n\x0ftimestamp_boundB\x06\n\x04mode"M\n\x0bTransaction\x12\n\n\x02id\x18\x01 \x01(\x0c\x12\x32\n\x0eread_timestamp\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp"\xa4\x01\n\x13TransactionSelector\x12;\n\nsingle_use\x18\x01 \x01(\x0b\x32%.google.spanner.v1.TransactionOptionsH\x00\x12\x0c\n\x02id\x18\x02 \x01(\x0cH\x00\x12\x36\n\x05\x62\x65gin\x18\x03 \x01(\x0b\x32%.google.spanner.v1.TransactionOptionsH\x00\x42\n\n\x08selectorB\x99\x01\n\x15\x63om.google.spanner.v1B\x10TransactionProtoP\x01Z8google.golang.org/genproto/googleapis/spanner/v1;spanner\xaa\x02\x17Google.Cloud.Spanner.V1\xca\x02\x17Google\\Cloud\\Spanner\\V1b\x06proto3' ), dependencies=[ - google_dot_api_dot_annotations__pb2.DESCRIPTOR, google_dot_protobuf_dot_duration__pb2.DESCRIPTOR, google_dot_protobuf_dot_timestamp__pb2.DESCRIPTOR, + google_dot_api_dot_annotations__pb2.DESCRIPTOR, ], ) diff --git a/spanner/google/cloud/spanner_v1/proto/type.proto b/spanner/google/cloud/spanner_v1/proto/type.proto index 1ddbd62be56c..ccef29143e9a 100644 --- a/spanner/google/cloud/spanner_v1/proto/type.proto +++ b/spanner/google/cloud/spanner_v1/proto/type.proto @@ -1,4 +1,4 @@ -// Copyright 2018 Google LLC +// Copyright 2019 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,6 +11,7 @@ // 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"; @@ -25,50 +26,6 @@ option java_outer_classname = "TypeProto"; option java_package = "com.google.spanner.v1"; option php_namespace = "Google\\Cloud\\Spanner\\V1"; -// `Type` indicates the type of a Cloud Spanner value, as might be stored in a -// table cell or returned from an SQL query. -message Type { - // Required. The [TypeCode][google.spanner.v1.TypeCode] for this type. - TypeCode code = 1; - - // If [code][google.spanner.v1.Type.code] == - // [ARRAY][google.spanner.v1.TypeCode.ARRAY], then `array_element_type` is the - // type of the array elements. - Type array_element_type = 2; - - // If [code][google.spanner.v1.Type.code] == - // [STRUCT][google.spanner.v1.TypeCode.STRUCT], then `struct_type` provides - // type information for the struct's fields. - StructType struct_type = 3; -} - -// `StructType` defines the fields of a -// [STRUCT][google.spanner.v1.TypeCode.STRUCT] type. -message StructType { - // Message representing a single field of a struct. - message Field { - // The name of the field. For reads, this is the column name. For - // SQL queries, it is the column alias (e.g., `"Word"` in the - // query `"SELECT 'hello' AS Word"`), or the column name (e.g., - // `"ColName"` in the query `"SELECT ColName FROM Table"`). Some - // columns might have an empty name (e.g., !"SELECT - // UPPER(ColName)"`). Note that a query result can contain - // multiple fields with the same name. - string name = 1; - - // The type of the field. - Type type = 2; - } - - // The list of fields that make up this struct. Order is - // significant, because values of this struct type are represented as - // lists, where the order of field values matches the order of - // fields in the [StructType][google.spanner.v1.StructType]. In turn, the - // order of fields matches the order of columns in a read request, or the - // order of fields in the `SELECT` clause of a query. - repeated Field fields = 1; -} - // `TypeCode` is used as part of [Type][google.spanner.v1.Type] to // indicate the type of a Cloud Spanner value. // @@ -119,3 +76,44 @@ enum TypeCode { // to [struct_type.fields[i]][google.spanner.v1.StructType.fields]. STRUCT = 9; } + +// `Type` indicates the type of a Cloud Spanner value, as might be stored in a +// table cell or returned from an SQL query. +message Type { + // Required. The [TypeCode][google.spanner.v1.TypeCode] for this type. + TypeCode code = 1; + + // If [code][google.spanner.v1.Type.code] == [ARRAY][google.spanner.v1.TypeCode.ARRAY], then `array_element_type` + // is the type of the array elements. + Type array_element_type = 2; + + // If [code][google.spanner.v1.Type.code] == [STRUCT][google.spanner.v1.TypeCode.STRUCT], then `struct_type` + // provides type information for the struct's fields. + StructType struct_type = 3; +} + +// `StructType` defines the fields of a [STRUCT][google.spanner.v1.TypeCode.STRUCT] type. +message StructType { + // Message representing a single field of a struct. + message Field { + // The name of the field. For reads, this is the column name. For + // SQL queries, it is the column alias (e.g., `"Word"` in the + // query `"SELECT 'hello' AS Word"`), or the column name (e.g., + // `"ColName"` in the query `"SELECT ColName FROM Table"`). Some + // columns might have an empty name (e.g., !"SELECT + // UPPER(ColName)"`). Note that a query result can contain + // multiple fields with the same name. + string name = 1; + + // The type of the field. + Type type = 2; + } + + // The list of fields that make up this struct. Order is + // significant, because values of this struct type are represented as + // lists, where the order of field values matches the order of + // fields in the [StructType][google.spanner.v1.StructType]. In turn, the order of fields + // matches the order of columns in a read request, or the order of + // fields in the `SELECT` clause of a query. + repeated Field fields = 1; +} diff --git a/spanner/synth.metadata b/spanner/synth.metadata index 285778e951a2..b79fe4dbbe6b 100644 --- a/spanner/synth.metadata +++ b/spanner/synth.metadata @@ -1,19 +1,19 @@ { - "updateTime": "2019-09-27T12:29:07.043834Z", + "updateTime": "2019-10-31T15:04:36.072689Z", "sources": [ { "generator": { "name": "artman", - "version": "0.37.1", - "dockerImage": "googleapis/artman@sha256:6068f67900a3f0bdece596b97bda8fc70406ca0e137a941f4c81d3217c994a80" + "version": "0.41.0", + "dockerImage": "googleapis/artman@sha256:75b38a3b073a7b243545f2332463096624c802bb1e56b8cb6f22ba1ecd325fa9" } }, { "git": { "name": "googleapis", "remote": "https://github.com/googleapis/googleapis.git", - "sha": "cd112d8d255e0099df053643d4bd12c228ef7b1b", - "internalRef": "271468707" + "sha": "c0e494ca955a4fdd9ad460a5890a354ec3a3a0ff", + "internalRef": "277673798" } }, { diff --git a/spanner/synth.py b/spanner/synth.py index 99994a87741c..b30b82114a39 100644 --- a/spanner/synth.py +++ b/spanner/synth.py @@ -126,6 +126,13 @@ "from google.cloud.spanner_admin_database_v1.proto", ) +# Fix up proto docs that are missing summary line. +s.replace( + "google/cloud/spanner_admin_instance_v1/proto/spanner_instance_admin_pb2.py", + '"""Attributes:', + '"""Protocol buffer.\n\n Attributes:', +) + # ---------------------------------------------------------------------------- # Add templated files # ----------------------------------------------------------------------------