query.proto

// This file contains all the types necessary to make
// RPC calls to Vttablet.

syntax = "proto3";

package query;

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

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

// Target describes what the client expects the tablet is.
// If the tablet does not match, an error is returned.
message Target {
  string keyspace = 1;
  string shard = 2;
  topodata.TabletType tablet_type = 3;
}

// VTGateCallerID is sent by VTGate to VTTablet to describe the
// caller. If possible, this information is secure. For instance,
// if using unique certificates that guarantee that VTGate->VTTablet
// traffic cannot be spoofed, then VTTablet can trust this information,
// and VTTablet will use it for tablet ACLs, for instance.
// Because of this security guarantee, this is different than the CallerID
// structure, which is not secure at all, because it is provided
// by the Vitess client.
message VTGateCallerID {
  string username = 1;
}

// BindVariable represents a single bind variable in a Query
message BindVariable {
  enum Type {
    TYPE_NULL = 0;
    TYPE_BYTES = 1;
    TYPE_INT = 2;
    TYPE_UINT = 3;
    TYPE_FLOAT = 4;
    TYPE_BYTES_LIST = 5;
    TYPE_INT_LIST = 6;
    TYPE_UINT_LIST = 7;
    TYPE_FLOAT_LIST = 8;

  }
  Type type = 1;

  // Depending on type, only one value below is set.
  bytes value_bytes = 2;
  int64 value_int = 3;
  uint64 value_uint = 4;
  double value_float = 5;
  repeated bytes value_bytes_list = 6;
  repeated int64 value_int_list = 7;
  repeated uint64 value_uint_list = 8;
  repeated double value_float_list = 9;
}

// BoundQuery is a query with its bind variables
message BoundQuery {
  // sql is the SQL query to execute
  string sql = 1;

  // bind_variables is a map of all bind variables to expand in the query
  map<string, BindVariable> bind_variables = 2;
}

// Field describes a single column returned by a query
message Field {
  // name of the field as returned by mysql C API
  string name = 1;

  // Type follows enum_field_types from mysql.h.
  enum Type {
    TYPE_DECIMAL = 0;
    TYPE_TINY = 1;
    TYPE_SHORT = 2;
    TYPE_LONG = 3;
    TYPE_FLOAT = 4;
    TYPE_DOUBLE = 5;
    TYPE_NULL = 6;
    TYPE_TIMESTAMP = 7;
    TYPE_LONGLONG = 8;
    TYPE_INT24 = 9;
    TYPE_DATE = 10;
    TYPE_TIME = 11;
    TYPE_DATETIME = 12;
    TYPE_YEAR = 13;
    TYPE_NEWDATE = 14;
    TYPE_VARCHAR = 15;
    TYPE_BIT = 16;
    TYPE_NEWDECIMAL = 246;
    TYPE_ENUM = 247;
    TYPE_SET = 248;
    TYPE_TINY_BLOB = 249;
    TYPE_MEDIUM_BLOB = 250;
    TYPE_LONG_BLOB = 251;
    TYPE_BLOB = 252;
    TYPE_VAR_STRING = 253;
    TYPE_STRING = 254;
    TYPE_GEOMETRY = 255;
  }
  Type type = 2;

  // Flag contains the MySQL field flags bitset values e.g. to
  // distinguish between signed and unsigned integer.  These numbers
  // should exactly match values defined in
  // dist/mysql-5.1.52/include/mysql_com.h
  enum Flag {
    // ZEROVALUE_FLAG is not part of the MySQL specification and only
    // used in unit tests.
    VT_ZEROVALUE_FLAG        = 0;
    VT_NOT_NULL_FLAG         = 1;
    VT_PRI_KEY_FLAG          = 2;
    VT_UNIQUE_KEY_FLAG       = 4;
    VT_MULTIPLE_KEY_FLAG     = 8;
    VT_BLOB_FLAG             = 16;
    VT_UNSIGNED_FLAG         = 32;
    VT_ZEROFILL_FLAG         = 64;
    VT_BINARY_FLAG           = 128;
    VT_ENUM_FLAG             = 256;
    VT_AUTO_INCREMENT_FLAG   = 512;
    VT_TIMESTAMP_FLAG        = 1024;
    VT_SET_FLAG              = 2048;
    VT_NO_DEFAULT_VALUE_FLAG = 4096;
    VT_ON_UPDATE_NOW_FLAG    = 8192;
    VT_NUM_FLAG              = 32768;
  }
  // flags is essentially a bitset<Flag>.
  int64 flags = 3;
}

// Row is a database row.
message Row {
  repeated bytes values = 1;
}

// QueryResult is returned by Execute and ExecuteStream.
//
// As returned by Execute, len(fields) is always equal to len(row)
// (for each row in rows).
//
// As returned by StreamExecute, the first QueryResult has the fields
// set, and subsequent QueryResult have rows set. And as Execute,
// len(QueryResult[0].fields) is always equal to len(row) (for each
// row in rows for each QueryResult in QueryResult[1:]).
message QueryResult {
  repeated Field fields = 1;
  uint64 rows_affected = 2;
  uint64 insert_id = 3;
  repeated Row rows = 4;
}

// GetSessionIdRequest is the payload to GetSessionId
message GetSessionIdRequest {
  vtrpc.CallerID effective_caller_id = 1;
  VTGateCallerID immediate_caller_id = 2;
  string keyspace = 3;
  string shard = 4;
}

// GetSessionIdResponse is the returned value from GetSessionId
message GetSessionIdResponse {
  int64 session_id = 1;
}

// ExecuteRequest is the payload to Execute
message ExecuteRequest {
  vtrpc.CallerID effective_caller_id = 1;
  VTGateCallerID immediate_caller_id = 2;
  Target target = 3;
  BoundQuery query = 4;
  int64 transaction_id = 5;
  int64 session_id = 6;
}

// ExecuteResponse is the returned value from Execute
message ExecuteResponse {
  QueryResult result = 1;
}

// ExecuteBatchRequest is the payload to ExecuteBatch
message ExecuteBatchRequest {
  vtrpc.CallerID effective_caller_id = 1;
  VTGateCallerID immediate_caller_id = 2;
  Target target = 3;
  repeated BoundQuery queries = 4;
  bool  as_transaction = 5;
  int64 transaction_id = 6;
  int64 session_id = 7;
}

// ExecuteBatchResponse is the returned value from ExecuteBatch
message ExecuteBatchResponse {
  repeated QueryResult results = 1;
}

// StreamExecuteRequest is the payload to StreamExecute
message StreamExecuteRequest {
  vtrpc.CallerID effective_caller_id = 1;
  VTGateCallerID immediate_caller_id = 2;
  Target target = 3;
  BoundQuery query = 4;
  int64 session_id = 5;
}

// StreamExecuteResponse is the returned value from StreamExecute
message StreamExecuteResponse {
  QueryResult result = 1;
}

// BeginRequest is the payload to Begin
message BeginRequest {
  vtrpc.CallerID effective_caller_id = 1;
  VTGateCallerID immediate_caller_id = 2;
  Target target = 3;
  int64 session_id = 4;
}

// BeginResponse is the returned value from Begin
message BeginResponse {
  int64 transaction_id = 1;
}

// CommitRequest is the payload to Commit
message CommitRequest {
  vtrpc.CallerID effective_caller_id = 1;
  VTGateCallerID immediate_caller_id = 2;
  Target target = 3;
  int64 transaction_id = 4;
  int64 session_id = 5;
}

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

// RollbackRequest is the payload to Rollback
message RollbackRequest {
  vtrpc.CallerID effective_caller_id = 1;
  VTGateCallerID immediate_caller_id = 2;
  Target target = 3;
  int64 transaction_id = 4;
  int64 session_id = 5;
}

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

// SplitQueryRequest is the payload for SplitQuery
message SplitQueryRequest {
  vtrpc.CallerID effective_caller_id = 1;
  VTGateCallerID immediate_caller_id = 2;
  Target target = 3;
  BoundQuery query = 4;
  string split_column = 5;
  int64 split_count = 6;
  int64 session_id = 7;
}

// QuerySplit represents one query to execute on the tablet
message QuerySplit {
  // query is the query to execute
  BoundQuery query = 1;

  // row_count is the approximate row count the query will return
  int64 row_count = 2;
}

// SplitQueryResponse is returned by SplitQuery and represents all the queries
// to execute in order to get the entire data set.
message SplitQueryResponse {
  repeated QuerySplit queries = 1;
}

// StreamHealthRequest is the payload for StreamHealth
message StreamHealthRequest {
}

// RealtimeStats contains information about the tablet status
message RealtimeStats {
  // health_error is the last error we got from health check,
  // or empty is the server is healthy. This is used for subset selection,
  // we do not send queries to servers that are not healthy.
  string health_error = 1;

  // seconds_behind_master is populated for slaves only. It indicates
  // how far behind on (MySQL) replication a slave currently is.  It is used
  // by clients for subset selection (so we don't try to send traffic
  // to tablets that are too far behind).
  // NOTE: This field must not be evaluated if "health_error" is not empty.
  // TODO(mberlin): Let's switch it to int64 instead?
  uint32 seconds_behind_master = 2;

  // bin_log_players_count is the number of currently running binlog players.
  // if the value is 0, it means that filtered replication is currently not
  // running on the tablet. If >0, filtered replication is running.
  // NOTE: This field must not be evaluated if "health_error" is not empty.
  int32 binlog_players_count = 3;

  // seconds_behind_master_filtered_replication is populated for the receiving
  // master of an ongoing filtered replication only.
  // It specifies how far the receiving master lags behind the sending master.
  // NOTE: This field must not be evaluated if "health_error" is not empty.
  // NOTE: This field must not be evaluated if "bin_log_players_count" is 0.
  int64 seconds_behind_master_filtered_replication = 4;

  // cpu_usage is used for load-based balancing
  double cpu_usage = 5;
}

// StreamHealthResponse is streamed by StreamHealth on a regular basis
message StreamHealthResponse {
  // target is the current server type. Only queries with that exact Target
  // record will be accepted.
  Target target = 1;

  // serving is true iff the tablet is serving. A tablet may not be serving
  // if filtered replication is enabled on a master for instance,
  // or if a replica should not be used because the keyspace is being resharded.
  bool serving = 2;

  // tablet_externally_reparented_timestamp contains the last time
  // tabletmanager.TabletExternallyReparented was called on this tablet,
  // or 0 if it was never called. This is meant to differentiate two tablets
  // that report a target.TabletType of MASTER, only the one with the latest
  // timestamp should be trusted.
  int64 tablet_externally_reparented_timestamp = 3;

  // realtime_stats contains information about the tablet status
  RealtimeStats realtime_stats = 4;
}