hugegraph-pd/hg-pd-grpc/src/main/proto/pdpb.proto

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You 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.
 */

syntax = "proto3";
package pdpb;

import "metapb.proto";
import "metaTask.proto";

option java_package = "org.apache.hugegraph.pd.grpc";

service PD {
  // Register store, the first registration will generate a new store_id, store_id is the unique identifier of the store
  rpc RegisterStore(RegisterStoreRequest) returns (RegisterStoreResponse) {}
  rpc GetStore(GetStoreRequest) returns (GetStoreResponse) {}
  // Modify Store status and other information.
  rpc SetStore(SetStoreRequest) returns (SetStoreResponse) {}
  // Look up the partition based on the key
  rpc DelStore(DetStoreRequest) returns (DetStoreResponse) {}
  rpc GetAllStores(GetAllStoresRequest) returns (GetAllStoresResponse) {}
  rpc StoreHeartbeat(StoreHeartbeatRequest) returns (StoreHeartbeatResponse) {}

  // Look up the partition based on the key
  rpc GetPartition(GetPartitionRequest) returns (GetPartitionResponse) {}

  // Look up the partition based on HashCode
  rpc GetPartitionByCode(GetPartitionByCodeRequest) returns (GetPartitionResponse) {}
  // Return partition by PartitionID
  rpc GetPartitionByID(GetPartitionByIDRequest) returns (GetPartitionResponse) {}
  rpc ScanPartitions(ScanPartitionsRequest) returns (ScanPartitionsResponse) {}
  // Update partition information, mainly used to update partition key range, call this interface carefully, otherwise data loss will occur.
  rpc UpdatePartition(UpdatePartitionRequest) returns (UpdatePartitionResponse) {}
  // Look up the partition based on the key
  rpc DelPartition(DelPartitionRequest) returns (DelPartitionResponse) {}
  // Query partition information based on conditions, including Store, Graph and other conditions
  rpc QueryPartitions(QueryPartitionsRequest) returns (QueryPartitionsResponse){}
  // Read graph information
  rpc GetGraph(GetGraphRequest) returns (GetGraphResponse){}
  // Modify graph information
  rpc SetGraph(SetGraphRequest) returns (SetGraphResponse){}
  rpc DelGraph(DelGraphRequest) returns (DelGraphResponse){}
  // Global unique incremental ID
  rpc GetId(GetIdRequest) returns (GetIdResponse){}
  rpc ResetId(ResetIdRequest) returns (ResetIdResponse){}
  // PD cluster list
  rpc GetMembers(GetMembersRequest) returns (GetMembersResponse) {}
  rpc GetStoreStatus(GetAllStoresRequest) returns (GetAllStoresResponse) {}
  rpc GetPDConfig(GetPDConfigRequest) returns (GetPDConfigResponse){}
  rpc SetPDConfig(SetPDConfigRequest) returns (SetPDConfigResponse){}
  rpc GetGraphSpace(GetGraphSpaceRequest) returns (GetGraphSpaceResponse){}
  rpc SetGraphSpace(SetGraphSpaceRequest) returns (SetGraphSpaceResponse){}
  // Get cluster health status
  rpc GetClusterStats(GetClusterStatsRequest) returns (GetClusterStatsResponse){}
  // Replace PD cluster nodes
  rpc ChangePeerList(ChangePeerListRequest) returns (getChangePeerListResponse) {}
  // Data splitting
  rpc SplitData(SplitDataRequest) returns (SplitDataResponse){}

  rpc SplitGraphData(SplitGraphDataRequest) returns (SplitDataResponse) {}
  // Data migration
  rpc MovePartition(MovePartitionRequest) returns (MovePartitionResponse){}
  // Report partition splitting and other task execution results
  rpc ReportTask(ReportTaskRequest) returns (ReportTaskResponse){}

  rpc GetPartitionStats(GetPartitionStatsRequest) returns (GetPartitionStatsResponse){}
  // Balance the number of partition leaders in the store
  rpc BalanceLeaders(BalanceLeadersRequest) returns (BalanceLeadersResponse){}

  // Replace license file
  rpc PutLicense(PutLicenseRequest) returns (PutLicenseResponse){}

  // Notify rocksdb to perform compaction
  rpc DbCompaction(DbCompactionRequest) returns (DbCompactionResponse){}

  // Merge partitions
  rpc CombineCluster(CombineClusterRequest) returns (CombineClusterResponse){}
  // Shrink a single graph
  rpc CombineGraph(CombineGraphRequest) returns (CombineGraphResponse) {}

  // shard group
  rpc GetShardGroup(GetShardGroupRequest) returns (GetShardGroupResponse){}
  rpc UpdateShardGroup(UpdateShardGroupRequest) returns (UpdateShardGroupResponse){}
  // Delete shard group
  rpc DeleteShardGroup(DeleteShardGroupRequest) returns (DeleteShardGroupResponse) {}
  // shard group operation related to operation
  rpc UpdateShardGroupOp(ChangeShardRequest) returns (ChangeShardResponse){}
  // Change shard
  rpc ChangeShard(ChangeShardRequest) returns (ChangeShardResponse) {}
  // Update pd raft
  rpc updatePdRaft(UpdatePdRaftRequest) returns (UpdatePdRaftResponse)  {}

  rpc getCache(GetGraphRequest) returns (CacheResponse)  {}
  rpc getPartitions(GetGraphRequest) returns (CachePartitionResponse)  {}
}

message RequestHeader {
  uint64 cluster_id = 1;
  uint64 sender_id = 2;
}

message ResponseHeader {
  // cluster_id is the ID of the cluster which sent the response.
  uint64 cluster_id = 1;
  Error error = 2;
}

enum ErrorType {
  OK = 0;
  UNKNOWN = 1;

  NOT_LEADER = 100;
  STORE_ID_NOT_EXIST = 101;
  NO_ACTIVE_STORE = 102;
  NOT_FOUND = 103;
  PD_UNREACHABLE = 104;
  LESS_ACTIVE_STORE = 105;
  STORE_HAS_BEEN_REMOVED = 106;
  STORE_PROHIBIT_DELETION = 111;
  SET_CONFIG_SHARD_COUNT_ERROR = 112;
  UPDATE_STORE_STATE_ERROR = 113;
  STORE_PROHIBIT_DUPLICATE = 114;
  ROCKSDB_READ_ERROR = 1002;
  ROCKSDB_WRITE_ERROR = 1003;
  ROCKSDB_DEL_ERROR = 1004;
  ROCKSDB_SAVE_SNAPSHOT_ERROR = 1005;
  ROCKSDB_LOAD_SNAPSHOT_ERROR = 1006;

  // Current cluster state prohibits splitting
  Cluster_State_Forbid_Splitting = 1007;
  // Currently splitting
  Split_Partition_Doing = 1008;
  // The number of partitions on the store exceeds the limit
  Too_Many_Partitions_Per_Store = 1009;
  // License error
  LICENSE_ERROR = 107;
  // License authentication error
  LICENSE_VERIFY_ERROR = 108;

  // Partition offline is in progress
  Store_Tombstone_Doing = 1010;

  // Invalid number of splits
  Invalid_Split_Partition_Count = 1011;
}

message Error {
  ErrorType type = 1;
  string message = 2;
}
message GetStoreRequest {
  RequestHeader header = 1;
  uint64 store_id = 2;
}

message GetStoreResponse {
  ResponseHeader header = 1;

  metapb.Store store = 2;
  metapb.StoreStats stats = 3;
}

message DetStoreRequest {
  RequestHeader header = 1;
  uint64 store_id = 2;
}

message DetStoreResponse {
  ResponseHeader header = 1;
  metapb.Store store = 2;
}

message RegisterStoreRequest {
  RequestHeader header = 1;
  metapb.Store store = 2;
}


message RegisterStoreResponse {
  ResponseHeader header = 1;
  // Upon initial registration, returns the new store_id
  uint64 store_id = 2;
}

message SetStoreRequest {
  RequestHeader header = 1;
  metapb.Store store = 2;
}

message SetStoreResponse {
  ResponseHeader header = 1;
  // Returns the modified Store
  metapb.Store store = 2;
}

// Returns all stores where graph_name is located. If graph_name is empty, returns all system stores.
message GetAllStoresRequest {
  RequestHeader header = 1;
  string graph_name = 2;
  // Whether to exclude offline stores
  bool exclude_offline_stores = 3;
}

message GetAllStoresResponse {
  ResponseHeader header = 1;

  repeated metapb.Store stores = 2;
}


message StoreHeartbeatRequest {
  RequestHeader header = 1;

  metapb.StoreStats stats = 2;
}

message StoreHeartbeatResponse {
  ResponseHeader header = 1;
  string cluster_version = 3;
  metapb.ClusterStats clusterStats = 4;
}

message GetPartitionRequest {
  RequestHeader header = 1;
  string graph_name = 2;
  bytes key = 3;
}


message GetPartitionByCodeRequest {
  RequestHeader header = 1;
  string graph_name = 2;
  uint64 code = 3;
}


message GetPartitionResponse {
  ResponseHeader header = 1;
  metapb.Partition partition = 2;
  metapb.Shard leader = 3;
  // Offline Shards
  repeated metapb.Shard offline_shards = 4;
}

message GetPartitionByIDRequest {
  RequestHeader header = 1;
  string graph_name = 2;
  uint32 partition_id = 3;
}

message DelPartitionRequest {
  RequestHeader header = 1;
  string graph_name = 2;
  uint32 partition_id = 3;
}
message DelPartitionResponse {
  ResponseHeader header = 1;
  metapb.Partition partition = 2;
}

message UpdatePartitionRequest{
  RequestHeader header = 1;
  repeated metapb.Partition partition = 2;
}

message UpdatePartitionResponse{
  ResponseHeader header = 1;
  repeated metapb.Partition partition = 2;
}
// Use GetPartitionResponse as the response of GetPartitionByIDRequest.

message ScanPartitionsRequest {
  RequestHeader header = 1;
  string graph_name = 2;
  bytes start_key = 3;
  bytes end_key = 4; // end_key is +inf when it is empty.
}



message ScanPartitionsResponse {
  ResponseHeader header = 1;
  repeated metapb.PartitionShard partitions = 4;
}



message QueryPartitionsRequest{
  RequestHeader header = 1;
  metapb.PartitionQuery query = 2;
}

message QueryPartitionsResponse {
  ResponseHeader header = 1;
  repeated metapb.Partition partitions = 4;
}



message GetGraphRequest{
  RequestHeader header = 1;
  string graph_name = 2;
}

message GetGraphResponse{
  ResponseHeader header = 1;
  metapb.Graph graph = 2;
}

message SetGraphRequest{
  RequestHeader header = 1;
  metapb.Graph graph = 2;
}

message SetGraphResponse{
  ResponseHeader header = 1;
  metapb.Graph graph = 2;
}

message DelGraphRequest{
  RequestHeader header = 1;
  string graph_name = 2;
}

message DelGraphResponse{
  ResponseHeader header = 1;
  metapb.Graph graph = 2;
}

message GetIdRequest{
  RequestHeader header = 1;
  string key = 2;
  int32 delta = 3;
}

message GetIdResponse{
  ResponseHeader header = 1;
  int64 id = 2;
  int32 delta = 3;
}

message ResetIdRequest{
  RequestHeader header = 1;
  string key = 2;
}

message ResetIdResponse{
  ResponseHeader header = 1;
  int32 result = 2;
}

message GetMembersRequest{
  RequestHeader header = 1;
}

message GetMembersResponse{
  ResponseHeader header = 1;
  repeated metapb.Member members = 2;
  metapb.Member leader = 3;
}

message GetPDConfigRequest{
  RequestHeader header = 1;
  uint64 version = 2 ;
}

message GetPDConfigResponse{
  ResponseHeader header = 1;
  metapb.PDConfig pd_config = 2;
}

message SetPDConfigRequest{
  RequestHeader header = 1;
  metapb.PDConfig pd_config = 2;
}

message SetPDConfigResponse{
  ResponseHeader header = 1;
}


message GetGraphSpaceRequest{
  RequestHeader header = 1;
  string graph_Space_Name = 2;
}

message GetGraphSpaceResponse{
  ResponseHeader header = 1;
  repeated metapb.GraphSpace graph_space = 2;
}

message SetGraphSpaceRequest{
  RequestHeader header = 1;
  metapb.GraphSpace graph_space = 2;
}

message SetGraphSpaceResponse{
  ResponseHeader header = 1;
}

message GetClusterStatsRequest{
  RequestHeader header = 1;
}

message GetClusterStatsResponse{
  ResponseHeader header = 1;
  metapb.ClusterStats cluster = 2;
}
message ChangePeerListRequest{
  RequestHeader header = 1;
  string peer_List = 2;
}
message getChangePeerListResponse{
  ResponseHeader header = 1;
}

enum OperationMode {
  Auto = 0;
  Expert = 1;
}

message SplitDataParam {
  // ID of the source partition being split
  uint32 partition_id = 1;
  // Number of target partitions
  uint32 count = 2;
}

message SplitDataRequest {
  RequestHeader header = 1;
  // Operation mode
  //  Auto: Automatic splitting, when the number of partitions on each Store reaches the maximum value
  //  Expert: Expert mode, requires specifying splitParams
  OperationMode mode = 2;
  repeated SplitDataParam param = 3;
}

message SplitGraphDataRequest {
  RequestHeader header = 1;
  // Operation mode
  string graph_name = 2;
  uint32 to_count = 3;
}

message SplitDataResponse {
  ResponseHeader header = 1;
}

message MovePartitionParam {
  uint32 partition_id = 1;
  uint64 src_store_id = 2;
  uint64 dst_store_id = 3;
}

message MovePartitionRequest {
  RequestHeader header = 1;
  // Operation mode
  //  Auto: Automatic transfer, aiming for equal number of partitions on each Store
  //  Expert: Expert mode, requires specifying transferParams
  OperationMode mode = 2;
  repeated MovePartitionParam param = 3;
}

message MovePartitionResponse {
  ResponseHeader header = 1;
}

message ReportTaskRequest {
  RequestHeader header = 1;
  metaTask.Task task = 2;
}

message ReportTaskResponse {
  ResponseHeader header = 1;
}

message GetPartitionStatsRequest {
  RequestHeader header = 1;
  uint32 partition_id = 2;
  // If empty, returns the same partition ID for all graphs
  string graph_name = 4;
}

message GetPartitionStatsResponse{
  ResponseHeader header = 1;
  metapb.PartitionStats partition_stats = 2;
}

message BalanceLeadersRequest{
  RequestHeader header = 1;
}

message BalanceLeadersResponse{
  ResponseHeader header = 1;
}

message PutLicenseRequest{
  RequestHeader header = 1;
  bytes content = 2;
}

message PutLicenseResponse{
  ResponseHeader header = 1;
}

message DbCompactionRequest{
  RequestHeader header = 1;
  string tableName = 2;
}

message DbCompactionResponse{
  ResponseHeader header = 1;
}

message CombineClusterRequest {
  RequestHeader header = 1;
  uint32 toCount = 2;
}

message CombineClusterResponse {
  ResponseHeader header = 1;
}

message CombineGraphRequest {
  RequestHeader header = 1;
  string graphName = 2;
  uint32 toCount = 3;
}

message CombineGraphResponse {
  ResponseHeader header = 1;
}

message DeleteShardGroupRequest {
  RequestHeader header = 1;
  uint32 groupId = 2;
}

message DeleteShardGroupResponse {
  ResponseHeader header = 1;
}

message GetShardGroupRequest{
  RequestHeader header = 1;
  uint32 group_id = 2 ;
}

message GetShardGroupResponse{
  ResponseHeader header = 1;
  metapb.ShardGroup shardGroup = 2;
}

message UpdateShardGroupRequest{
  RequestHeader header = 1;
  metapb.ShardGroup shardGroup = 2;
}

message UpdateShardGroupResponse{
  ResponseHeader header = 1;
}

message ChangeShardRequest{
  RequestHeader header = 1;
  uint32 groupId = 2;
  repeated metapb.Shard shards = 3;
}

message ChangeShardResponse {
  ResponseHeader header = 1;
}

message UpdatePdRaftRequest{
  RequestHeader header = 1;
  string config = 3;
}

message UpdatePdRaftResponse{
  ResponseHeader header = 1;
  string message = 2;
}
message CacheResponse {
  ResponseHeader header = 1;
  // Returns the modified Store
  repeated metapb.Store stores = 2;
  repeated metapb.ShardGroup shards = 3;
  repeated metapb.Graph graphs = 4;
}
message CachePartitionResponse {
  ResponseHeader header = 1;
  repeated metapb.Partition partitions = 2;
}