Merge pull request #1054 from alainjobart/replication

Adding comments to the proto definition, and API groups.

Author: alainjobart

proto/vtgateservice.proto

@@ -9,55 +9,75 @@ package vtgateservice;
 
 import "vtgate.proto";
 
+// Vitess is the main service to access a Vitess cluster. It is the API that vtgate
+// exposes to serve all queries.
 service Vitess {
-  // Execute executes tries to route the query to the right shard.
-  // (this is a vtgate v3 API, use carefully)
+  // Execute tries to route the query to the right shard.
+  // It depends on the query and bind variables to provide enough
+  // information in conjonction with the vindexes to route the query.
+  // API group: v3 API (alpha)
   rpc Execute(vtgate.ExecuteRequest) returns (vtgate.ExecuteResponse) {};
 
   // ExecuteShards executes the query on the specified shards.
+  // API group: Custom Sharding
   rpc ExecuteShards(vtgate.ExecuteShardsRequest) returns (vtgate.ExecuteShardsResponse) {};
 
   // ExecuteKeyspaceIds executes the query based on the specified keyspace ids.
+  // API group: Range Based Sharding
   rpc ExecuteKeyspaceIds(vtgate.ExecuteKeyspaceIdsRequest) returns (vtgate.ExecuteKeyspaceIdsResponse) {};
 
   // ExecuteKeyRanges executes the query based on the specified key ranges.
+  // API group: Range Based Sharding
   rpc ExecuteKeyRanges(vtgate.ExecuteKeyRangesRequest) returns (vtgate.ExecuteKeyRangesResponse) {};
 
   // ExecuteEntityIds executes the query based on the specified external id to keyspace id map.
+  // API group: Range Based Sharding
   rpc ExecuteEntityIds(vtgate.ExecuteEntityIdsRequest) returns (vtgate.ExecuteEntityIdsResponse) {};
 
   // ExecuteBatchShards executes the list of queries on the specified shards.
+  // API group: Custom Sharding
   rpc ExecuteBatchShards(vtgate.ExecuteBatchShardsRequest) returns (vtgate.ExecuteBatchShardsResponse) {};
 
   // ExecuteBatchKeyspaceIds executes the list of queries based on the specified keyspace ids.
+  // API group: Range Based Sharding
   rpc ExecuteBatchKeyspaceIds(vtgate.ExecuteBatchKeyspaceIdsRequest) returns (vtgate.ExecuteBatchKeyspaceIdsResponse) {};
 
-  // StreamExecute exectures a streaming query based on shards.
-  // (this is a vtgate v3 API, use carefully)
+  // StreamExecute executes a streaming query based on shards.
+  // It depends on the query and bind variables to provide enough
+  // information in conjonction with the vindexes to route the query.
+  // Use this method if the query returns a large number of rows.
+  // API group: v3 API (alpha)
   rpc StreamExecute(vtgate.StreamExecuteRequest) returns (stream vtgate.StreamExecuteResponse) {};
 
-  // StreamExecuteShard exectures a streaming query based on shards.
+  // StreamExecuteShards executes a streaming query based on shards.
   // Use this method if the query returns a large number of rows.
+  // API group: Custom Sharding
   rpc StreamExecuteShards(vtgate.StreamExecuteShardsRequest) returns (stream vtgate.StreamExecuteShardsResponse) {};
 
-  // StreamExecuteKeyspaceIds exectures a streaming query based on keyspace ids.
+  // StreamExecuteKeyspaceIds executes a streaming query based on keyspace ids.
   // Use this method if the query returns a large number of rows.
+  // API group: Range Based Sharding
   rpc StreamExecuteKeyspaceIds(vtgate.StreamExecuteKeyspaceIdsRequest) returns (stream vtgate.StreamExecuteKeyspaceIdsResponse) {};
 
-  // StreamExecuteKeyRanges exectures a streaming query based on key ranges.
+  // StreamExecuteKeyRanges executes a streaming query based on key ranges.
   // Use this method if the query returns a large number of rows.
+  // API group: Range Based Sharding
   rpc StreamExecuteKeyRanges(vtgate.StreamExecuteKeyRangesRequest) returns (stream vtgate.StreamExecuteKeyRangesResponse) {};
 
   // Begin a transaction.
+  // API group: Transactions
   rpc Begin(vtgate.BeginRequest) returns (vtgate.BeginResponse) {};
 
   // Commit a transaction.
+  // API group: Transactions
   rpc Commit(vtgate.CommitRequest) returns (vtgate.CommitResponse) {};
 
   // Rollback a transaction.
+  // API group: Transactions
   rpc Rollback(vtgate.RollbackRequest) returns (vtgate.RollbackResponse) {};
 
   // Split a query into non-overlapping sub queries
+  // API group: Map Reduce
   rpc SplitQuery(vtgate.SplitQueryRequest) returns (vtgate.SplitQueryResponse) {};
 
   // GetSrvKeyspace returns a SrvKeyspace object (as seen by this vtgate).
@@ -67,5 +87,6 @@ service Vitess {
   // information may change, use the Execute calls for that).
   // It is convenient for monitoring applications for instance, or if
   // using custom sharding.
+  // API group: Topology
   rpc GetSrvKeyspace(vtgate.GetSrvKeyspaceRequest) returns (vtgate.GetSrvKeyspaceResponse) {};
 }