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

// Service definition for vtgateservice.
// This is the main entry point to Vitess.

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

option java_package="io.vitess.proto.grpc";

package vtgateservice;

import "vtgate.proto";
import "query.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 tries to route the query to the right shard.
  // It depends on the query and bind variables to provide enough
  // information in conjunction with the vindexes to route the query.
  // API group: v3
  rpc Execute(vtgate.ExecuteRequest) returns (vtgate.ExecuteResponse) {};

  // ExecuteBatch tries to route the list of queries on the right shards.
  // It depends on the query and bind variables to provide enough
  // information in conjunction with the vindexes to route the query.
  // API group: v3
  rpc ExecuteBatch(vtgate.ExecuteBatchRequest) returns (vtgate.ExecuteBatchResponse) {};

  // StreamExecute executes a streaming query based on shards.
  // It depends on the query and bind variables to provide enough
  // information in conjunction with the vindexes to route the query.
  // Use this method if the query returns a large number of rows.
  // API group: v3
  rpc StreamExecute(vtgate.StreamExecuteRequest) returns (stream vtgate.StreamExecuteResponse) {};

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

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

  // ResolveTransaction resolves a transaction.
  // API group: Transactions
  rpc ResolveTransaction(vtgate.ResolveTransactionRequest) returns (vtgate.ResolveTransactionResponse) {};

  // MessageStream streams messages from a message table.
  rpc MessageStream(vtgate.MessageStreamRequest) returns (stream query.MessageStreamResponse) {};

  // MessageAck acks messages for a table.
  rpc MessageAck(vtgate.MessageAckRequest) returns (query.MessageAckResponse) {};

  // MessageAckKeyspaceIds routes Message Acks using the associated
  // keyspace ids.
  rpc MessageAckKeyspaceIds(vtgate.MessageAckKeyspaceIdsRequest) returns (query.MessageAckResponse) {};

  // 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).
  // This method is provided as a convenient way for clients to take a
  // look at the sharding configuration for a Keyspace. Looking at the
  // sharding information should not be used for routing queries (as the
  // 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) {};

  // VStream streams binlog events from the requested sources.
  rpc VStream(vtgate.VStreamRequest) returns (stream vtgate.VStreamResponse) {};

  // UpdateStream asks the server for a stream of StreamEvent objects.
  // API group: Update Stream
  rpc UpdateStream(vtgate.UpdateStreamRequest) returns (stream vtgate.UpdateStreamResponse) {};
}