protos/engine/remote_engine.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 remote_engine;

import "engine/schema.proto";
import "engine/time_range.proto";
import "cluster.proto";
import "common.proto";
import "storage.proto";

service RemoteEngineService {
  rpc Read(ReadRequest) returns (stream ReadResponse) {}
  rpc Write(WriteRequest) returns (WriteResponse) {}
  rpc GetTableInfo(GetTableInfoRequest) returns (GetTableInfoResponse) {}
  rpc WriteBatch(WriteBatchRequest) returns (WriteResponse) {}
  rpc ExecutePhysicalPlan(ExecutePlanRequest) returns (stream ReadResponse) {}
  rpc AlterTableSchema(AlterTableSchemaRequest)
      returns (AlterTableSchemaResponse) {}
  rpc AlterTableOptions(AlterTableOptionsRequest)
      returns (AlterTableOptionsResponse) {}
}

message TableIdentifier {
  string catalog = 1;
  string schema = 2;
  string table = 3;
}

message ReadOptions {
  uint64 batch_size = 1;
  uint64 read_parallelism = 2;
  // -1 means no timeout
  int64 timeout_ms = 3;
}

message Predicate {
  repeated bytes exprs = 1;
  time_range.TimeRange time_range = 2;
}

enum ReadOrder {
  None = 0;
  Asc = 1;
  Desc = 2;
}

message TableReadRequest {
  string request_id = 1;
  ReadOptions opts = 2;
  schema.ProjectedSchema projected_schema = 3;
  Predicate predicate = 4;
  ReadOrder order = 5;
}

message ReadRequest {
  TableIdentifier table = 1;
  TableReadRequest read_request = 2;
}

message ReadResponse {
  common.ResponseHeader header = 1;
  oneof output {
    storage.ArrowPayload arrow = 2;
    // This field is used to return metric of child node when query is executed
    // in distributed mode.
    MetricPayload metric = 3;
  }
}

message MetricPayload {
  string metric = 1;
}

message ColumnDesc {
  uint32 id = 1;
  schema.DataType typ = 2;
}

message ContiguousRows {
  uint32 schema_version = 1;
  repeated bytes encoded_rows = 2;
  repeated ColumnDesc column_descs = 3;
}

message RowGroup {
  int64 min_timestamp = 1;
  int64 max_timestamp = 2;
  oneof rows {
    storage.ArrowPayload arrow = 3;
    ContiguousRows contiguous = 4;
  }
}

message WriteRequest {
  TableIdentifier table = 1;
  RowGroup row_group = 2;
}

message WriteResponse {
  common.ResponseHeader header = 1;
  uint64 affected_rows = 2;
}

message GetTableInfoRequest {
  TableIdentifier table = 1;
}

message TableInfo {
  string catalog_name = 1;
  string schema_name = 2;
  uint32 schema_id = 3;
  string table_name = 4;
  uint64 table_id = 5;
  schema.TableSchema table_schema = 6;
  string engine = 7;
  map<string, string> options = 8;
  cluster.PartitionInfo partition_info = 9;
}

message GetTableInfoResponse {
  common.ResponseHeader header = 1;
  TableInfo table_info = 2;
}

message WriteBatchRequest {
  repeated WriteRequest batch = 1;
}

message ExtensionNode {
  oneof typed_extension {
    DistSqlQueryExtensionNode dist_sql_query = 1;
  }
}

message DistSqlQueryExtensionNode {
  UnresolvedSubScan unresolved_sub_scan = 1;
}

message UnresolvedSubScan {
  TableIdentifier table = 1;
  TableScanContext table_scan_ctx = 2;
}

enum QueryPriority {
  High = 0;
  Low = 1;
}

enum Explain { Analyze = 0; }

message ExecContext {
  string request_id = 1;
  string default_catalog = 2;
  string default_schema = 3;
  // -1 means no timeout
  int64 timeout_ms = 4;
  QueryPriority priority = 5;
  string displayable_query = 6;
  optional Explain explain = 7;
}

message ExecutePlanRequest {
  ExecContext context = 1;
  oneof physical_plan {
    bytes datafusion = 2;
  }
  TableIdentifier table = 3;
}

message AlterTableSchemaRequest {
  TableIdentifier table = 1;
  schema.TableSchema table_schema = 2;
  uint32 pre_schema_version = 3;
}

message AlterTableSchemaResponse {
  common.ResponseHeader header = 1;
}

message AlterTableOptionsRequest {
  TableIdentifier table = 1;
  map<string, string> options = 2;
}

message AlterTableOptionsResponse {
  common.ResponseHeader header = 1;
}

message TableScanContext {
  uint64 batch_size = 1;
  uint64 read_parallelism = 2;
  schema.ProjectedSchema projected_schema = 3;
  Predicate predicate = 4;
}