vitess-gh/proto/vtgate.proto

/*
Copyright 2019 The Vitess Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
*/

// Data definitions for service vtgateservice.

syntax = "proto3";
option go_package = "vitess.io/vitess/go/vt/proto/vtgate";

package vtgate;

option java_package="io.vitess.proto";

import "binlogdata.proto";
import "query.proto";
import "topodata.proto";
import "vtrpc.proto";

// TransactionMode controls the execution of distributed transaction
// across multiple shards.
enum TransactionMode {
  // UNSPECIFIED uses the transaction mode set by the VTGate flag 'transaction_mode'.
  UNSPECIFIED = 0;
  // SINGLE disallows distributed transactions.
  SINGLE = 1;
  // MULTI allows distributed transactions with best effort commit.
  MULTI = 2;
  // TWOPC is for distributed transactions with atomic commits.
  TWOPC = 3;
}


// CommitOrder is used to designate which of the ShardSessions
// get used for transactions.
enum CommitOrder {
  // NORMAL is the default commit order.
  NORMAL = 0;
  // PRE is used to designate pre_sessions.
  PRE = 1;
  // POST is used to designate post_sessions.
  POST = 2;
  // AUTOCOMMIT is used to run the statement as autocommitted transaction.
  AUTOCOMMIT = 3;
}

// Session objects are exchanged like cookies through various
// calls to VTGate. The behavior differs between V2 & V3 APIs.
// V3 APIs are Execute, ExecuteBatch and StreamExecute. All
// other APIs are V2. For the V3 APIs, the session
// must be sent with every call to Execute or ExecuteBatch.
// For the V2 APIs, Begin does not accept a session. It instead
// returns a brand new one with in_transaction set to true.
// After a call to Commit or Rollback, the session can be
// discarded. If you're not in a transaction, Session is
// an optional parameter for the V2 APIs.
message Session {
  // in_transaction is set to true if the session is in a transaction.
  bool in_transaction = 1;

  message ShardSession {
    query.Target target = 1;
    int64 transaction_id = 2;
  }
  // shard_sessions keep track of per-shard transaction info.
  repeated ShardSession shard_sessions = 2;

  // single_db is deprecated. Use transaction_mode instead.
  // The value specifies if the transaction should be restricted
  // to a single shard.
  // TODO(sougou): remove in 3.1
  bool single_db = 3;

  // autocommit specifies if the session is in autocommit mode.
  // This is used only for V3.
  bool autocommit = 4;

  // target_string is the target expressed as a string. Valid
  // names are: keyspace:shard@target, keyspace@target or @target.
  // This is used only for V3.
  string target_string = 5;

  // options is used only for V3.
  query.ExecuteOptions options = 6;

  // transaction_mode specifies the current transaction mode.
  TransactionMode transaction_mode = 7;

  // warnings contains non-fatal warnings from the previous query
  repeated query.QueryWarning warnings = 8;

  // pre_sessions contains sessions that have to be committed first.
  repeated ShardSession pre_sessions = 9;

  // post_sessions contains sessions that have to be committed last.
  repeated ShardSession post_sessions = 10;

 // last_insert_id keeps track of the last seen insert_id for this session
  uint64 last_insert_id = 11;
}

// ExecuteRequest is the payload to Execute.
message ExecuteRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the session state.
  Session session = 2;

  // query is the query and bind variables to execute.
  query.BoundQuery query = 3;

  // These values are deprecated. Use session instead.
  // TODO(sougou): remove in 3.1
  topodata.TabletType tablet_type = 4;
  bool not_in_transaction = 5;
  string keyspace_shard = 6;
  query.ExecuteOptions options = 7;
}

// ExecuteResponse is the returned value from Execute.
message ExecuteResponse {
  // error contains an application level error if necessary. Note the
  // session may have changed, even when an error is returned (for
  // instance if a database integrity error happened).
  vtrpc.RPCError error = 1;

  // session is the updated session information.
  Session session = 2;

  // result contains the query result, only set if error is unset.
  query.QueryResult result = 3;
}

// ExecuteShardsRequest is the payload to ExecuteShards.
message ExecuteShardsRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the current transaction data. It is returned by Begin.
  // Do not fill it in if outside of a transaction.
  Session session = 2;

  // query is the query and bind variables to execute.
  query.BoundQuery query = 3;

  // keyspace to target the query to.
  string keyspace = 4;

  // shards to target the query to. A DML can only target one shard.
  repeated string shards = 5;

  // tablet_type is the type of tablets that this query is targeted to.
  topodata.TabletType tablet_type = 6;

  // not_in_transaction is deprecated.
  bool not_in_transaction = 7;

  // options
  query.ExecuteOptions options = 8;
}

// ExecuteShardsResponse is the returned value from ExecuteShards.
message ExecuteShardsResponse {
  // error contains an application level error if necessary. Note the
  // session may have changed, even when an error is returned (for
  // instance if a database integrity error happened).
  vtrpc.RPCError error = 1;

  // session is the updated session information (only returned inside a transaction).
  Session session = 2;

  // result contains the query result, only set if error is unset.
  query.QueryResult result = 3;
}

// ExecuteKeyspaceIdsRequest is the payload to ExecuteKeyspaceIds.
message ExecuteKeyspaceIdsRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the current transaction data. It is returned by Begin.
  // Do not fill it in if outside of a transaction.
  Session session = 2;

  // query is the query and bind variables to execute.
  query.BoundQuery query = 3;

  // keyspace to target the query to.
  string keyspace = 4;

  // keyspace_ids contains the list of keyspace_ids affected by this query.
  // Will be used to find the shards to send the query to.
  repeated bytes keyspace_ids = 5;

  // tablet_type is the type of tablets that this query is targeted to.
  topodata.TabletType tablet_type = 6;

  // not_in_transaction is deprecated.
  bool not_in_transaction = 7;

  // options
  query.ExecuteOptions options = 8;
}

// ExecuteKeyspaceIdsResponse is the returned value from ExecuteKeyspaceIds.
message ExecuteKeyspaceIdsResponse {
  // error contains an application level error if necessary. Note the
  // session may have changed, even when an error is returned (for
  // instance if a database integrity error happened).
  vtrpc.RPCError error = 1;

  // session is the updated session information (only returned inside a transaction).
  Session session = 2;

  // result contains the query result, only set if error is unset.
  query.QueryResult result = 3;
}

// ExecuteKeyRangesRequest is the payload to ExecuteKeyRanges.
message ExecuteKeyRangesRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the current transaction data. It is returned by Begin.
  // Do not fill it in if outside of a transaction.
  Session session = 2;

  // query is the query and bind variables to execute.
  query.BoundQuery query = 3;

  // keyspace to target the query to
  string keyspace = 4;

  // key_ranges contains the list of key ranges affected by this query.
  // Will be used to find the shards to send the query to.
  repeated topodata.KeyRange key_ranges = 5;

  // tablet_type is the type of tablets that this query is targeted to.
  topodata.TabletType tablet_type = 6;

  // not_in_transaction is deprecated.
  bool not_in_transaction = 7;

  // options
  query.ExecuteOptions options = 8;
}

// ExecuteKeyRangesResponse is the returned value from ExecuteKeyRanges.
message ExecuteKeyRangesResponse {
  // error contains an application level error if necessary. Note the
  // session may have changed, even when an error is returned (for
  // instance if a database integrity error happened).
  vtrpc.RPCError error = 1;

  // session is the updated session information (only returned inside a transaction).
  Session session = 2;

  // result contains the query result, only set if error is unset.
  query.QueryResult result = 3;
}

// ExecuteEntityIdsRequest is the payload to ExecuteEntityIds.
message ExecuteEntityIdsRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the current transaction data. It is returned by Begin.
  // Do not fill it in if outside of a transaction.
  Session session = 2;

  // query is the query and bind variables to execute.
  query.BoundQuery query = 3;

  // keyspace to target the query to.
  string keyspace = 4;

  // entity_column_name is the column name to use.
  string entity_column_name = 5;

  message EntityId {
    // type is the type of the entity's value. Can be NULL_TYPE.
    query.Type type = 1;

    // value is the value for the entity. Not set if type is NULL_TYPE.
    bytes value = 2;

    // keyspace_id is the associated keyspace_id for the entity.
    bytes keyspace_id = 3;
  }

  // entity_keyspace_ids are pairs of entity_column_name values
  // associated with its corresponding keyspace_id.
  repeated EntityId entity_keyspace_ids = 6;

  // tablet_type is the type of tablets that this query is targeted to.
  topodata.TabletType tablet_type = 7;

  // not_in_transaction is deprecated.
  bool not_in_transaction = 8;

  // options
  query.ExecuteOptions options = 9;
}

// ExecuteEntityIdsResponse is the returned value from ExecuteEntityIds.
message ExecuteEntityIdsResponse {
  // error contains an application level error if necessary. Note the
  // session may have changed, even when an error is returned (for
  // instance if a database integrity error happened).
  vtrpc.RPCError error = 1;

  // session is the updated session information (only returned inside a transaction).
  Session session = 2;

  // result contains the query result, only set if error is unset.
  query.QueryResult result = 3;
}

// ExecuteBatchRequest is the payload to ExecuteBatch.
message ExecuteBatchRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the session state.
  Session session = 2;

  // queries is a list of query and bind variables to execute.
  repeated query.BoundQuery queries = 3;

  // These values are deprecated. Use session instead.
  // TODO(sougou): remove in 3.1
  topodata.TabletType tablet_type = 4;
  bool as_transaction = 5;
  string keyspace_shard = 6;
  query.ExecuteOptions options = 7;
}


// ExecuteBatchResponse is the returned value from ExecuteBatch.
message ExecuteBatchResponse {
  // error contains an application level error if necessary. Note the
  // session may have changed, even when an error is returned (for
  // instance if a database integrity error happened).
  vtrpc.RPCError error = 1;

  // session is the updated session information.
  Session session = 2;

  // results contains the query results, only set if application level error is unset.
  repeated query.ResultWithError results = 3;
}

// BoundShardQuery represents a single query request for the
// specified list of shards. This is used in a list for
// ExecuteBatchShardsRequest.
message BoundShardQuery {
  // query is the query and bind variables to execute.
  query.BoundQuery query = 1;

  // keyspace to target the query to.
  string keyspace = 2;

  // shards to target the query to. A DML can only target one shard.
  repeated string shards = 3;
}

// ExecuteBatchShardsRequest is the payload to ExecuteBatchShards
message ExecuteBatchShardsRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the current transaction data. It is returned by Begin.
  // Do not fill it in if outside of a transaction.
  Session session = 2;

  // queries carries all the queries to execute.
  repeated BoundShardQuery queries = 3;

  // tablet_type is the type of tablets that this query is targeted to.
  topodata.TabletType tablet_type = 4;

  // as_transaction will execute the queries in this batch in a single transaction per shard, created for this purpose.
  // (this can be seen as adding a 'begin' before and 'commit' after the queries).
  // Only makes sense if tablet_type is master. If set, the Session is ignored.
  bool as_transaction = 5;

  // options
  query.ExecuteOptions options = 6;
}

// ExecuteBatchShardsResponse is the returned value from ExecuteBatchShards.
message ExecuteBatchShardsResponse {
  // error contains an application level error if necessary. Note the
  // session may have changed, even when an error is returned (for
  // instance if a database integrity error happened).
  vtrpc.RPCError error = 1;

  // session is the updated session information (only returned inside a transaction).
  Session session = 2;

  // result contains the query result, only set if error is unset.
  repeated query.QueryResult results = 3;
}

// BoundKeyspaceIdQuery represents a single query request for the
// specified list of keyspace ids. This is used in a list for
// ExecuteBatchKeyspaceIdsRequest.
message BoundKeyspaceIdQuery {
  // query is the query and bind variables to execute.
  query.BoundQuery query = 1;

  // keyspace to target the query to.
  string keyspace = 2;

  // keyspace_ids contains the list of keyspace_ids affected by this query.
  // Will be used to find the shards to send the query to.
  repeated bytes keyspace_ids = 3;
}

// ExecuteBatchKeyspaceIdsRequest is the payload to ExecuteBatchKeyspaceId.
message ExecuteBatchKeyspaceIdsRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the current transaction data. It is returned by Begin.
  // Do not fill it in if outside of a transaction.
  Session session = 2;

  repeated BoundKeyspaceIdQuery queries = 3;

  // tablet_type is the type of tablets that this query is targeted to.
  topodata.TabletType tablet_type = 4;

  // as_transaction will execute the queries in this batch in a single transaction per shard, created for this purpose.
  // (this can be seen as adding a 'begin' before and 'commit' after the queries).
  // Only makes sense if tablet_type is master. If set, the Session is ignored.
  bool as_transaction = 5;

  // options
  query.ExecuteOptions options = 6;
}

// ExecuteBatchKeyspaceIdsResponse is the returned value from ExecuteBatchKeyspaceId.
message ExecuteBatchKeyspaceIdsResponse {
  // error contains an application level error if necessary. Note the
  // session may have changed, even when an error is returned (for
  // instance if a database integrity error happened).
  vtrpc.RPCError error = 1;

  // session is the updated session information (only returned inside a transaction).
  Session session = 2;

  // result contains the query result, only set if error is unset.
  repeated query.QueryResult results = 3;
}

// StreamExecuteRequest is the payload to StreamExecute.
message StreamExecuteRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // query is the query and bind variables to execute.
  query.BoundQuery query = 2;

  // These values are deprecated. Use session instead.
  // TODO(sougou): remove in 3.1
  topodata.TabletType tablet_type = 3;
  string keyspace_shard = 4;
  query.ExecuteOptions options = 5;

  // session carries the session state.
  Session session = 6;
}

// StreamExecuteResponse is the returned value from StreamExecute.
// The session is currently not returned because StreamExecute is
// not expected to modify it.
message StreamExecuteResponse {
  // result contains the result data.
  // The first value contains only Fields information.
  // The next values contain the actual rows, a few values per result.
  query.QueryResult result = 1;
}

// StreamExecuteShardsRequest is the payload to StreamExecuteShards.
message StreamExecuteShardsRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // query is the query and bind variables to execute.
  query.BoundQuery query = 2;

  // keyspace to target the query to.
  string keyspace = 3;

  // shards to target the query to.
  repeated string shards = 4;

  // tablet_type is the type of tablets that this query is targeted to.
  topodata.TabletType tablet_type = 5;

  // options
  query.ExecuteOptions options = 6;
}

// StreamExecuteShardsResponse is the returned value from StreamExecuteShards.
message StreamExecuteShardsResponse {
  // result contains the result data.
  // The first value contains only Fields information.
  // The next values contain the actual rows, a few values per result.
  query.QueryResult result = 1;
}

// StreamExecuteKeyspaceIdsRequest is the payload to StreamExecuteKeyspaceIds.
message StreamExecuteKeyspaceIdsRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // query is the query and bind variables to execute.
  query.BoundQuery query = 2;

  // keyspace to target the query to.
  string keyspace = 3;

  // keyspace_ids contains the list of keyspace_ids affected by this query.
  // Will be used to find the shards to send the query to.
  repeated bytes keyspace_ids = 4;

  // tablet_type is the type of tablets that this query is targeted to.
  topodata.TabletType tablet_type = 5;

  // options
  query.ExecuteOptions options = 6;
}

// StreamExecuteKeyspaceIdsResponse is the returned value from StreamExecuteKeyspaceIds.
message StreamExecuteKeyspaceIdsResponse {
  // result contains the result data.
  // The first value contains only Fields information.
  // The next values contain the actual rows, a few values per result.
  query.QueryResult result = 1;
}

// StreamExecuteKeyRangesRequest is the payload to StreamExecuteKeyRanges.
message StreamExecuteKeyRangesRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // query is the query and bind variables to execute.
  query.BoundQuery query = 2;

  // keyspace to target the query to.
  string keyspace = 3;

  // key_ranges contains the list of key ranges affected by this query.
  // Will be used to find the shards to send the query to.
  repeated topodata.KeyRange key_ranges = 4;

  // tablet_type is the type of tablets that this query is targeted to.
  topodata.TabletType tablet_type = 5;

  // options
  query.ExecuteOptions options = 6;
}

// StreamExecuteKeyRangesResponse is the returned value from StreamExecuteKeyRanges.
message StreamExecuteKeyRangesResponse {
  // result contains the result data.
  // The first value contains only Fields information.
  // The next values contain the actual rows, a few values per result.
  query.QueryResult result = 1;
}

// BeginRequest is the payload to Begin.
message BeginRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // single_db is deprecated. Use transaction_mode instead.
  // The value specifies if the transaction should be restricted
  // to a single database.
  // TODO(sougou): remove in 3.1
  bool single_db = 2;
}

// BeginResponse is the returned value from Begin.
message BeginResponse {
  // session is the initial session information to use for subsequent queries.
  Session session = 1;
}

// CommitRequest is the payload to Commit.
message CommitRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the current transaction data to commit.
  Session session = 2;

  // atomic is deprecated. Use transaction_mode instead.
  // The value specifies if the commit should go through the
  // 2PC workflow to ensure atomicity.
  // TODO(sougou): remove in 3.1
  bool atomic = 3;
}

// CommitResponse is the returned value from Commit.
message CommitResponse {
}

// RollbackRequest is the payload to Rollback.
message RollbackRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // session carries the current transaction data to rollback.
  Session session = 2;
}

// RollbackResponse is the returned value from Rollback.
message RollbackResponse {
}

// ResolveTransactionRequest is the payload to ResolveTransaction.
message ResolveTransactionRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // dtid is the dtid of the transaction to be resolved.
  string dtid = 2;
}

// MessageStreamRequest is the request payload for MessageStream.
message MessageStreamRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // keyspace to target the query to.
  string keyspace = 2;

  // shard to target the query to, for unsharded keyspaces.
  string shard = 3;

  // KeyRange to target the query to, for sharded keyspaces.
  topodata.KeyRange key_range = 4;

  // name is the message table name.
  string name = 5;
}

// MessageAckRequest is the request payload for MessageAck.
message MessageAckRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // keyspace to target the message to.
  string keyspace = 2;

  // name is the message table name.
  string name = 3;
  // ids is the list of ids to ack.
  repeated query.Value ids = 4;
}

// IdKeyspaceId represents an id and keyspace_id pair.
// The kesypace_id represents the routing info for id.
message IdKeyspaceId {
  // id represents the message id.
  query.Value id = 1;

  // keyspace_id is the associated keyspace_id for the id.
  bytes keyspace_id = 2;
}

// MessageAckKeyspaceIdsRequest is the payload to MessageAckKeyspaceIds.
message MessageAckKeyspaceIdsRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // Optional keyspace for message table.
  string keyspace = 2;

  // name is the message table name.
  string name = 3;

  repeated IdKeyspaceId id_keyspace_ids = 4;
}

// ResolveTransactionResponse is the returned value from Rollback.
message ResolveTransactionResponse {
}

// SplitQueryRequest is the payload to SplitQuery.
//
// SplitQuery takes a "SELECT" query and generates a list of queries called
// "query-parts". Each query-part consists of the original query with an
// added WHERE clause that restricts the query-part to operate only on
// rows whose values in the columns listed in the "split_column" field
// of the request (see below) are in a particular range.
//
// It is guaranteed that the set of rows obtained from
// executing each query-part on a database snapshot
// and merging (without deduping) the results is equal to the set of rows
// obtained from executing the original query on the same snapshot
// with the rows containing NULL values in any of the split_column's excluded.
//
// This is typically called by the MapReduce master when reading from Vitess.
// There it's desirable that the sets of rows returned by the query-parts
// have roughly the same size.
message SplitQueryRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // keyspace to target the query to.
  string keyspace = 2;

  // The query and bind variables to produce splits for.
  // The given query must be a simple query of the form
  // SELECT <cols> FROM <table> WHERE <filter>.
  // It must not contain subqueries nor any of the keywords
  // JOIN, GROUP BY, ORDER BY, LIMIT, DISTINCT.
  // Furthermore, <table> must be a single "concrete" table.
  // It cannot be a view.
  query.BoundQuery query = 3;

  // Each generated query-part will be restricted to rows whose values
  // in the columns listed in this field are in a particular range.
  // The list of columns named here must be a prefix of the list of
  // columns defining some index or primary key of the table
  // referenced in 'query'. For many tables using the primary key columns
  // (in order) is sufficient and this is the default if this field is omitted.
  // See the comment on the 'algorithm' field for more restrictions and
  // information.
  repeated string split_column = 4;

  // You can specify either an estimate of the number of query-parts to
  // generate or an estimate of the number of rows each query-part should
  // return.
  // Thus, exactly one of split_count or num_rows_per_query_part
  // should be nonzero.
  // The non-given parameter is calculated from the given parameter
  // using the formula: split_count * num_rows_per_query_pary = table_size,
  // where table_size is an approximation of the number of rows in the
  // table.
  // Note that if "split_count" is given it is regarded as an estimate.
  // The number of query-parts returned may differ slightly (in particular,
  // if it's not a whole multiple of the number of vitess shards).
  int64 split_count = 5;
  int64 num_rows_per_query_part = 6;

  // The algorithm to use to split the query. The split algorithm is performed
  // on each database shard in parallel. The lists of query-parts generated
  // by the shards are merged and returned to the caller.
  // Two algorithms are supported:
  //  EQUAL_SPLITS
  //    If this algorithm is selected then only the first 'split_column' given
  //    is used (or the first primary key column if the 'split_column' field is
  //    empty). In the rest of this algorithm's description, we refer to
  //    this column as "the split column".
  //    The split column must have numeric type (integral or floating point).
  //    The algorithm works by taking the interval [min, max], where min and
  //    max are the minimum and maximum values of the split column in
  //    the table-shard, respectively, and partitioning it into 'split_count'
  //    sub-intervals of equal size. The added WHERE clause of each query-part
  //    restricts that part to rows whose value in the split column belongs to
  //    a particular sub-interval. This is fast, but requires that the
  //    distribution of values of the split column be uniform in [min, max]
  //    for the number of rows returned by each query part to be roughly the
  //    same.
  //  FULL_SCAN
  //    If this algorithm is used then the split_column must be the primary key
  //    columns (in order).
  //    This algorithm performs a full-scan of the table-shard referenced
  //    in 'query' to get "boundary" rows that are num_rows_per_query_part
  //    apart when the table is ordered by the columns listed in
  //    'split_column'. It then restricts each query-part to the rows
  //    located between two successive boundary rows.
  //    This algorithm supports multiple split_column's of any type,
  //    but is slower than EQUAL_SPLITS.
  query.SplitQueryRequest.Algorithm algorithm = 7;
  // TODO(erez): This field is no longer used by the server code.
  // Remove this field after this new server code is released to prod.
  // We must keep it for now, so that clients can still send it to the old
  // server code currently in production.
  bool use_split_query_v2 = 8;
}

// SplitQueryResponse is the returned value from SplitQuery.
message SplitQueryResponse {
  message KeyRangePart {
    // keyspace to target the query to.
    string keyspace = 1;

    // key ranges to target the query to.
    repeated topodata.KeyRange key_ranges = 2;
  }
  message ShardPart {
    // keyspace to target the query to.
    string keyspace = 1;

    // shards to target the query to.
    repeated string shards = 2;
  }
  message Part {
    // query is the query and bind variables to execute.
    query.BoundQuery query = 1;

    // key_range_part is set if the query should be executed by
    // ExecuteKeyRanges.
    KeyRangePart key_range_part = 2;

    // shard_part is set if the query should be executed by ExecuteShards.
    ShardPart shard_part = 3;

    // size is the approximate number of rows this query will return.
    int64 size = 4;
  }

  // splits contains the queries to run to fetch the entire data set.
  repeated Part splits = 1;
}

// GetSrvKeyspaceRequest is the payload to GetSrvKeyspace.
message GetSrvKeyspaceRequest {
  // keyspace name to fetch.
  string keyspace = 1;
}

// GetSrvKeyspaceResponse is the returned value from GetSrvKeyspace.
message GetSrvKeyspaceResponse {
  // srv_keyspace is the topology object for the SrvKeyspace.
  topodata.SrvKeyspace srv_keyspace = 1;
}

// VStreamRequest is the payload for VStream.
message VStreamRequest {
  vtrpc.CallerID caller_id = 1;

  topodata.TabletType tablet_type = 2;

  // position specifies the starting point of the bin log positions
  // as well as the keyspace-shards to pull events from.
  // position is of the form 'ks1:0@MySQL56/<mysql_pos>|ks2:-80@MySQL56/<mysql_pos>'.
  binlogdata.VGtid vgtid = 3;
  binlogdata.Filter filter = 4;
}

// VStreamResponse is streamed by VStream.
message VStreamResponse {
  repeated binlogdata.VEvent events = 1;
}

// UpdateStreamRequest is the payload to UpdateStream.
message UpdateStreamRequest {
  // caller_id identifies the caller. This is the effective caller ID,
  // set by the application to further identify the caller.
  vtrpc.CallerID caller_id = 1;

  // keyspace to target the query to.
  string keyspace = 2;

  // shard to target the query to, for unsharded keyspaces.
  string shard = 3;

  // KeyRange to target the query to, for sharded keyspaces.
  topodata.KeyRange key_range = 4;

  // tablet_type is the type of tablets that this request is targeted to.
  topodata.TabletType tablet_type = 5;

  // timestamp is the timestamp to start the stream from.  It is
  // unused is event is set, and we are only streaming from the shard
  // described by event.shard.
  int64 timestamp = 6;

  // event is the event to start the stream from.
  // Note it is only used if we are streaming from exactly the same shard
  // as this event was coming from. Otherwise we can't use this event,
  // and will use the timestamp as a starting point.
  query.EventToken event = 7;
}

// UpdateStreamResponse is streamed by UpdateStream.
message UpdateStreamResponse {
  // event is one event from the stream.
  query.StreamEvent event = 1;

  // resume_timestamp is the timestamp to resume streaming from if the
  // client is interrupted. If the Update Stream only goes to one
  // shard, this is equal to event.timestamp. If the Update Stream
  // goes to multiple shards and aggregates, this is the minimum value
  // of the current timestamp for all shards.
  int64 resume_timestamp = 2;
}