vitess-gh/proto/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;
}

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

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

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

// 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 {
    // xid_type is the type of the entity's value. Can be NULL.
    query.Type xid_type = 1;

    // xid_value is the value for the entity. Not set if xid_type is NULL.
    bytes xid_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;
}

// 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 make all the requests inside its own transaction.
  bool as_transaction = 5;
}

// 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 make all the requests inside its own transaction.
  bool as_transaction = 5;
}

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

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

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

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

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

  // query is the query and bind variables to produce splits for.
  query.BoundQuery query = 3;

  // split_column is an optional hint on the column to use to split the query.
  string split_column = 4;

  // split_count describes how many splits we want for this query.
  int64 split_count = 5;
}

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