vtgate.proto

// Data definitions for service vtgateservice.

syntax = "proto3";

package vtgate;

option java_package="com.youtube.vitess.proto";

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

// Session objects are session cookies and are invalidated on
// use. Query results will contain updated session values.
// Their content should be opaque to the user.
message Session {
  bool in_transaction = 1;

  message ShardSession {
    query.Target target = 1;
    int64 transaction_id = 2;
  }
  repeated ShardSession shard_sessions = 2;
}

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

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

  // not_in_transaction is deprecated and should not be used.
  bool not_in_transaction = 5;

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

  // options
  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 (only returned inside a transaction).
  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 and should not be used.
  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 and should not be used.
  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 and should not be used.
  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 and should not be used.
  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;
}

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

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

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

  // options
  query.ExecuteOptions options = 5;
}

// StreamExecuteResponse is the returned value from StreamExecute.
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;
}

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

// 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 {
}

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

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

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