Skip to content
This repository was archived by the owner on Mar 4, 2026. It is now read-only.

feature: batch queries #132

Merged
stephenplusplus merged 4 commits into from
Mar 1, 2018
Merged

feature: batch queries #132

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
afe35cd
feature: batch queries
alexander-fenster Jan 22, 2018
df0116e
fix linting errors
callmehiphop Feb 26, 2018
093a80c
fix documentation errors per pr feedback
callmehiphop Feb 28, 2018
fca9c6e
update executeStream example
callmehiphop Feb 28, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 164 additions & 6 deletions protos/google/spanner/v1/spanner.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright 2017 Google Inc.
// Copyright 2018 Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
Expand Down Expand Up @@ -31,6 +31,7 @@ option go_package = "google.golang.org/genproto/googleapis/spanner/v1;spanner";
option java_multiple_files = true;
option java_outer_classname = "SpannerProto";
option java_package = "com.google.spanner.v1";
option php_namespace = "Google\\Cloud\\Spanner\\V1";


// Cloud Spanner API
Expand Down Expand Up @@ -159,6 +160,30 @@ service Spanner {
rpc Rollback(RollbackRequest) returns (google.protobuf.Empty) {
option (google.api.http) = { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:rollback" body: "*" };
}

// 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.
// Partition tokens become invalid when the session used to create them
// is deleted or begins a new transaction.
rpc PartitionQuery(PartitionQueryRequest) returns (PartitionResponse) {
option (google.api.http) = { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:partitionQuery" body: "*" };
}

// 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.
// Partition tokens become invalid when the session used to create them
// is deleted or begins a new transaction.
rpc PartitionRead(PartitionReadRequest) returns (PartitionResponse) {
option (google.api.http) = { post: "/v1/{session=projects/*/instances/*/databases/*/sessions/*}:partitionRead" body: "*" };
}
}

// The request for [CreateSession][google.spanner.v1.Spanner.CreateSession].
Expand All @@ -172,7 +197,8 @@ message CreateSessionRequest {

// A session in the Cloud Spanner API.
message Session {
// The name of the session.
// The name of the session. This is always system-assigned; values provided
// when creating a session are ignored.
string name = 1;

// The labels for the session.
Expand Down Expand Up @@ -307,8 +333,131 @@ message ExecuteSqlRequest {
bytes resume_token = 6;

// Used to control the amount of debugging information returned in
// [ResultSetStats][google.spanner.v1.ResultSetStats].
// [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
// previously created using PartitionQuery(). There must be an exact
// match for the values of fields common to this message and the
// PartitionQueryRequest message used to create this partition_token.
bytes partition_token = 8;
}

// Options for a PartitionQueryRequest and
// PartitionReadRequest.
message PartitionOptions {
// The desired data size for each partition generated. The default for this
// option is currently 1 GiB. This is only a hint. The actual size of each
// partition may be smaller or larger than this size request.
int64 partition_size_bytes = 1;

// The desired maximum number of partitions to return. For example, this may
// be set to the number of workers available. The default for this option
// is currently 10,000. The maximum value is currently 200,000. This is only
// a hint. The actual number of partitions returned may be smaller or larger
// than this maximum count request.
int64 max_partitions = 2;
}

// The request for [PartitionQuery][google.spanner.v1.Spanner.PartitionQuery]
message PartitionQueryRequest {
// Required. The session used to create the partitions.
string session = 1;

// 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
// the query is not root partitionable. The query plan of a root
// partitionable query has a single distributed union operator. A distributed
// union operator conceptually divides one or more tables into multiple
// splits, remotely evaluates a subquery independently on each split, and
// then unions all results.
string sql = 3;

// The SQL query string can contain parameter placeholders. A parameter
// placeholder consists of `'@'` followed by the parameter
// name. Parameter names consist of any combination of letters,
// numbers, and underscores.
//
// Parameters can appear anywhere that a literal value is expected. The same
// parameter name can be used more than once, for example:
// `"WHERE id > @msg_id AND id < @msg_id + 100"`
//
// It is an error to execute an SQL query with unbound parameters.
//
// Parameter values are specified using `params`, which is a JSON
// object whose keys are parameter names, and whose values are the
// corresponding parameter values.
google.protobuf.Struct params = 4;

// It is not always possible for Cloud Spanner to infer the right SQL type
// from a JSON value. For example, values of type `BYTES` and values
// of type `STRING` both appear in [params][google.spanner.v1.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
// definition of [Type][google.spanner.v1.Type] for more information
// about SQL types.
map<string, Type> param_types = 5;

// Additional options that affect how many partitions are created.
PartitionOptions partition_options = 6;
}

// The request for [PartitionRead][google.spanner.v1.Spanner.PartitionRead]
message PartitionReadRequest {
// Required. The session used to create the partitions.
string session = 1;

// Read only snapshot transactions are supported, read/write and single use
// transactions are not.
TransactionSelector transaction = 2;

// Required. The name of the table in the database to be read.
string table = 3;

// If non-empty, the name of an index on [table][google.spanner.v1.PartitionReadRequest.table]. This index is
// used instead of the table primary key when interpreting [key_set][google.spanner.v1.PartitionReadRequest.key_set]
// and sorting result rows. See [key_set][google.spanner.v1.PartitionReadRequest.key_set] for further information.
string index = 4;

// 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
// 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;

// Additional options that affect how many partitions are created.
PartitionOptions partition_options = 9;
}

// Information returned for each partition returned in a
// PartitionResponse.
message Partition {
// This token can be passed to Read, StreamingRead, ExecuteSql, or
// ExecuteStreamingSql requests to restrict the results to those identified by
// this partition token.
bytes partition_token = 1;
}

// The response for [PartitionQuery][google.spanner.v1.Spanner.PartitionQuery]
// or [PartitionRead][google.spanner.v1.Spanner.PartitionRead]
message PartitionResponse {
// Partitions created by this request.
repeated Partition partitions = 1;

// Transaction created by this request.
Transaction transaction = 2;
}

// The request for [Read][google.spanner.v1.Spanner.Read] and
Expand Down Expand Up @@ -338,15 +487,18 @@ message ReadRequest {
// is present. If [index][google.spanner.v1.ReadRequest.index] is present, then [key_set][google.spanner.v1.ReadRequest.key_set] instead names
// index keys in [index][google.spanner.v1.ReadRequest.index].
//
// Rows are yielded in table primary key order (if [index][google.spanner.v1.ReadRequest.index] is empty)
// or index key order (if [index][google.spanner.v1.ReadRequest.index] is non-empty).
// 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;

// If greater than zero, only the first `limit` rows are yielded. If `limit`
// is zero, the default is no limit.
// is zero, the default is no limit. A limit cannot be specified if
// `partition_token` is set.
int64 limit = 8;

// If this request is resuming a previously interrupted read,
Expand All @@ -356,6 +508,12 @@ message ReadRequest {
// rest of the request parameters must exactly match the request
// that yielded this token.
bytes resume_token = 9;

// If present, results will be restricted to the specified partition
// previously created using PartitionRead(). There must be an exact
// match for the values of fields common to this message and the
// PartitionReadRequest message used to create this partition_token.
bytes partition_token = 10;
}

// The request for [BeginTransaction][google.spanner.v1.Spanner.BeginTransaction].
Expand Down
Loading