suguo
/
googleapis
0
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Synchronize new proto/yaml changes. 

PiperOrigin-RevId: 277673798
This commit is contained in:
Google APIs 2019-10-31 01:41:37 -07:00 committed by Copybara-Service
parent 4e952e7e2b
commit c0e494ca95
18 changed files with 930 additions and 498 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
google/spanner/admin/database/artman_spanner_admin_database.yaml
View File

@ -2,8 +2,9 @@ common:
api_name: spanner-admin-database
api_version: v1
organization_name: google-cloud
service_yaml: spanner_admin_database.yaml
service_yaml: v1/spanner_admin_database.yaml
gapic_yaml: v1/spanner_admin_database_gapic.yaml
proto_package: google.spanner.admin.database.v1
src_proto_paths:
- v1
proto_deps:

0
google/spanner/admin/database/spanner_admin_database.yaml → google/spanner/admin/database/v1/spanner_admin_database.yaml
View File

59
google/spanner/admin/database/v1/spanner_admin_database_grpc_service_config.json Executable file
View File

@ -0,0 +1,59 @@
{
"methodConfig": [
{
"name": [
{
"service": "google.spanner.admin.database.v1.DatabaseAdmin",
"method": "ListDatabases"
},
{
"service": "google.spanner.admin.database.v1.DatabaseAdmin",
"method": "GetDatabase"
},
{
"service": "google.spanner.admin.database.v1.DatabaseAdmin",
"method": "UpdateDatabaseDdl"
},
{
"service": "google.spanner.admin.database.v1.DatabaseAdmin",
"method": "DropDatabase"
},
{
"service": "google.spanner.admin.database.v1.DatabaseAdmin",
"method": "GetDatabaseDdl"
},
{
"service": "google.spanner.admin.database.v1.DatabaseAdmin",
"method": "GetIamPolicy"
}
],
"timeout": "3600s",
"retryPolicy": {
"initialBackoff": "1s",
"maxBackoff": "32s",
"backoffMultiplier": 1.3,
"retryableStatusCodes": [
"UNAVAILABLE",
"DEADLINE_EXCEEDED"
]
}
},
{
"name": [
{
"service": "google.spanner.admin.database.v1.DatabaseAdmin",
"method": "CreateDatabase"
},
{
"service": "google.spanner.admin.database.v1.DatabaseAdmin",
"method": "SetIamPolicy"
},
{
"service": "google.spanner.admin.database.v1.DatabaseAdmin",
"method": "TestIamPermissions"
}
],
"timeout": "3600s"
}
]
}

200
google/spanner/admin/database/v1/spanner_database_admin.proto
View File

@ -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 `<database_name>/operations/<operation_id>` 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 `<database_name>/operations/<operation_id>` 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/<project>/instances/<instance>`.
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/<project>/instances/<instance>`.
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/<project>/instances/<instance>/databases/<database>`.
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]:
// `<database>/operations/<operation_id>`.
// [longrunning.Operation][google.longrunning.Operation]: `<database>/operations/<operation_id>`.
//
// `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}"
};

3
google/spanner/admin/instance/artman_spanner_admin_instance.yaml
View File

@ -2,8 +2,9 @@ common:
api_name: spanner-admin-instance
api_version: v1
organization_name: google-cloud
service_yaml: spanner_admin_instance.yaml
service_yaml: v1/spanner_admin_instance.yaml
gapic_yaml: v1/spanner_admin_instance_gapic.yaml
proto_package: google.spanner.admin.instance.v1
src_proto_paths:
- v1
proto_deps:

0
google/spanner/admin/instance/spanner_admin_instance.yaml → google/spanner/admin/instance/v1/spanner_admin_instance.yaml
View File

63
google/spanner/admin/instance/v1/spanner_admin_instance_grpc_service_config.json Executable file
View File

@ -0,0 +1,63 @@
{
"methodConfig": [
{
"name": [
{
"service": "google.spanner.admin.instance.v1.InstanceAdmin",
"method": "ListInstanceConfigs"
},
{
"service": "google.spanner.admin.instance.v1.InstanceAdmin",
"method": "GetInstanceConfig"
},
{
"service": "google.spanner.admin.instance.v1.InstanceAdmin",
"method": "ListInstances"
},
{
"service": "google.spanner.admin.instance.v1.InstanceAdmin",
"method": "GetInstance"
},
{
"service": "google.spanner.admin.instance.v1.InstanceAdmin",
"method": "DeleteInstance"
},
{
"service": "google.spanner.admin.instance.v1.InstanceAdmin",
"method": "GetIamPolicy"
}
],
"timeout": "3600s",
"retryPolicy": {
"initialBackoff": "1s",
"maxBackoff": "32s",
"backoffMultiplier": 1.3,
"retryableStatusCodes": [
"UNAVAILABLE",
"DEADLINE_EXCEEDED"
]
}
},
{
"name": [
{
"service": "google.spanner.admin.instance.v1.InstanceAdmin",
"method": "CreateInstance"
},
{
"service": "google.spanner.admin.instance.v1.InstanceAdmin",
"method": "UpdateInstance"
},
{
"service": "google.spanner.admin.instance.v1.InstanceAdmin",
"method": "SetIamPolicy"
},
{
"service": "google.spanner.admin.instance.v1.InstanceAdmin",
"method": "TestIamPermissions"
}
],
"timeout": "3600s"
}
]
}

242
google/spanner/admin/instance/v1/spanner_instance_admin.proto
View File

@ -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/<project>/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/<project>/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/<project>/instanceConfigs/<configuration>`. 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<string, string> 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/<project>`.
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/<project>/instanceConfigs/<config>`.
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/<project>/instances/<instance>`.
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/<project>`.
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 `<parent>/instances/<instance_id>`.
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/<project>`.
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;
// 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;
// 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/<project>/instances/<instance>`
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;

3
google/spanner/artman_spanner.yaml
View File

@ -2,8 +2,9 @@ common:
api_name: spanner
api_version: v1
organization_name: google-cloud
service_yaml: spanner.yaml
service_yaml: v1/spanner.yaml
gapic_yaml: v1/spanner_gapic.yaml
proto_package: google.spanner.v1
src_proto_paths:
- v1
proto_deps:

9
google/spanner/v1/keys.proto
View File

@ -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

51
google/spanner/v1/mutation.proto
View File

@ -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

44
google/spanner/v1/query_plan.proto
View File

@ -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<string, int32> 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;
}

47
google/spanner/v1/result_set.proto
View File

@ -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

488
google/spanner/v1/spanner.proto
View File

@ -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.
// 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.
//
// 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) {
// 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;
// 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 transaction to use. Must be a read-write transaction.
//
// REQUIRES: statements_size() > 0.
repeated Statement statements = 3;
// 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];
// 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. The list of statements to execute in this batch. Statements are executed
// serially, such that the effects of statement `i` are visible to statement
// `i+1`. Each statement must be a DML statement. Execution stops at the
// first failed statement; the remaining statements are not executed.
//
// Callers must provide at least one statement.
repeated Statement statements = 3 [(google.api.field_behavior) = REQUIRED];
// Required. A per-transaction sequence number used to identify this request. This field
// makes each request idempotent such that if the request is received multiple
// times, at most one will succeed.
//
// 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.
//
// 1. Check if 'status' field is OkStatus.
// 2. Check if result_sets_size() equals the number of statements in
// [ExecuteBatchDmlRequest][Spanner.ExecuteBatchDmlRequest].
// To check for DML statements that failed, use the following approach:
//
// 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.
// 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 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.
// Example 1:
//
// * 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.
// 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
// 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;
string table = 3 [(google.api.field_behavior) = REQUIRED];
// If non-empty, the name of an index on
// [table][google.spanner.v1.PartitionReadRequest.table]. This index is used
// instead of the table primary key when interpreting
// [key_set][google.spanner.v1.PartitionReadRequest.key_set] and sorting
// result rows. See [key_set][google.spanner.v1.PartitionReadRequest.key_set]
// for further information.
// If non-empty, the name of an index on [table][google.spanner.v1.PartitionReadRequest.table]. This index is
// used instead of the table primary key when interpreting [key_set][google.spanner.v1.PartitionReadRequest.key_set]
// and sorting result rows. See [key_set][google.spanner.v1.PartitionReadRequest.key_set] for further information.
string index = 4;
// The columns of [table][google.spanner.v1.PartitionReadRequest.table] to be
// returned for each row matching this request.
// The columns of [table][google.spanner.v1.PartitionReadRequest.table] to be returned for each row matching
// this request.
repeated string columns = 5;
// Required. `key_set` identifies the rows to be yielded. `key_set` names the
// primary keys of the rows in
// [table][google.spanner.v1.PartitionReadRequest.table] to be yielded, unless
// [index][google.spanner.v1.PartitionReadRequest.index] is present. If
// [index][google.spanner.v1.PartitionReadRequest.index] is present, then
// [key_set][google.spanner.v1.PartitionReadRequest.key_set] instead names
// primary keys of the rows in [table][google.spanner.v1.PartitionReadRequest.table] to be yielded, unless [index][google.spanner.v1.PartitionReadRequest.index]
// is present. If [index][google.spanner.v1.PartitionReadRequest.index] is present, then [key_set][google.spanner.v1.PartitionReadRequest.key_set] instead names
// index keys in [index][google.spanner.v1.PartitionReadRequest.index].
//
// It is not an error for the `key_set` to name rows that do not
// 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;
string table = 3 [(google.api.field_behavior) = REQUIRED];
// If non-empty, the name of an index on
// [table][google.spanner.v1.ReadRequest.table]. This index is used instead of
// the table primary key when interpreting
// [key_set][google.spanner.v1.ReadRequest.key_set] and sorting result rows.
// See [key_set][google.spanner.v1.ReadRequest.key_set] for further
// information.
// If non-empty, the name of an index on [table][google.spanner.v1.ReadRequest.table]. This index is
// used instead of the table primary key when interpreting [key_set][google.spanner.v1.ReadRequest.key_set]
// and sorting result rows. See [key_set][google.spanner.v1.ReadRequest.key_set] for further information.
string index = 4;
// 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].
// 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.
// 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}"
};

0
google/spanner/spanner.yaml → google/spanner/v1/spanner.yaml
View File

95
google/spanner/v1/spanner_grpc_service_config.json Executable file
View File

@ -0,0 +1,95 @@
{
"methodConfig": [
{
"name": [
{
"service": "google.spanner.v1.Spanner",
"method": "ExecuteStreamingSql"
},
{
"service": "google.spanner.v1.Spanner",
"method": "StreamingRead"
}
],
"timeout": "3600s"
},
{
"name": [
{
"service": "google.spanner.v1.Spanner",
"method": "Commit"
}
],
"timeout": "3600s",
"retryPolicy": {
"initialBackoff": "0.250s",
"maxBackoff": "32s",
"backoffMultiplier": 1.3,
"retryableStatusCodes": [
"UNAVAILABLE"
]
}
},
{
"name": [
{
"service": "google.spanner.v1.Spanner",
"method": "CreateSession"
},
{
"service": "google.spanner.v1.Spanner",
"method": "BatchCreateSessions"
},
{
"service": "google.spanner.v1.Spanner",
"method": "GetSession"
},
{
"service": "google.spanner.v1.Spanner",
"method": "ListSessions"
},
{
"service": "google.spanner.v1.Spanner",
"method": "DeleteSession"
},
{
"service": "google.spanner.v1.Spanner",
"method": "ExecuteSql"
},
{
"service": "google.spanner.v1.Spanner",
"method": "ExecuteBatchDml"
},
{
"service": "google.spanner.v1.Spanner",
"method": "Read"
},
{
"service": "google.spanner.v1.Spanner",
"method": "BeginTransaction"
},
{
"service": "google.spanner.v1.Spanner",
"method": "Rollback"
},
{
"service": "google.spanner.v1.Spanner",
"method": "PartitionQuery"
},
{
"service": "google.spanner.v1.Spanner",
"method": "PartitionRead"
}
],
"timeout": "30s",
"retryPolicy": {
"initialBackoff": "0.250s",
"maxBackoff": "32s",
"backoffMultiplier": 1.3,
"retryableStatusCodes": [
"UNAVAILABLE"
]
}
}
]
}

33
google/spanner/v1/transaction.proto
View File

@ -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;
}
}

88
google/spanner/v1/type.proto
View File

@ -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;
}