frames.proto

/*
Copyright 2018 Iguazio Systems Ltd.

Licensed under the Apache License, Version 2.0 (the "License") with
an addition restriction as set forth herein. 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.

In addition, you may not use the software for any purposes that are
illegal under applicable law, and the grant of the foregoing license
under the Apache 2.0 license is conditioned upon your compliance with
such restriction.
*/

syntax = "proto3";
package pb;

enum DType {
    NONE = 0;
    INTEGER = 1;
    FLOAT = 2;
    STRING = 3;
    TIME = 4;
    BOOLEAN = 5;
    NULL = 6;
}

message Column {
    enum Kind {
	SLICE = 0;
	LABEL = 1;
    }

    Kind kind = 1;
    string name = 2;
    DType dtype = 3;
    int64 size = 4; // used only in LABEL
    // In slice columns these arrays will be of length 1
    repeated int64 ints = 5;
    repeated double floats = 6;
    repeated string strings = 7;
    repeated int64 times = 8; // epoch nano
    repeated bool bools = 9;
}

// Union of values
message Value {
    oneof value {
	int64 ival = 1;
	double fval = 2;
	string sval = 3;
	int64 tval = 4; // epoch nano
	bool bval = 5;
    }
}

message NullValuesMap {
    map<string, bool> nullColumns = 1;
}

message Frame {
    repeated Column columns = 1;
    repeated Column indices = 2;
    map<string, Value> labels = 3;
    string error = 4; // Used in errors when reading over HTTP
    repeated NullValuesMap null_values = 5;
}

// TODO: Place these under TableSchema
message SchemaField {
    string name = 1;
    string doc = 2;
    Value default = 3;
    string type = 4;
    map<string, Value> properties = 5;
}

message SchemaKey {
    repeated string sharding_key = 1;
    repeated string sorting_key = 2;
}

// TODO: Rename to Schema?
message TableSchema {
    string type = 1;
    string namespace = 2;
    string name = 3;
    string doc = 4;
    repeated string aliases = 5;
    repeated SchemaField fields = 6;
    SchemaKey key = 7;
}

message JoinStruct {
    // TBD
}

message Session {
    string url = 1;
    string container = 2;
    string path = 3;
    string user = 4;
    string password = 5;
    string token = 6;
    string id = 7;
}

message ReadRequest {
    Session session = 1;
    string backend = 2;
    TableSchema schema = 3;
    string data_format = 4;
    bool row_layout = 5;
    bool multi_index = 6; // TSDB
    string query = 7; // TSDB - SQL Query
    string table = 8; // Table name
    repeated string columns = 9;
    string filter = 10;
    string group_by = 11; // TSDB
    repeated JoinStruct join = 12;

    int64 limit = 13;
    int64 message_limit = 14;
    string marker = 15;

    bool reset_index = 29;
    // NoSQL
    repeated int64 segments = 16;
    int64 total_segments = 17;
    repeated string sharding_keys = 18;
    string sort_key_range_start = 19;
    string sort_key_range_end = 20;

    // TSDB
    string start = 21;
    string end = 22;
    string step = 23;
    string aggregators = 24;
    string aggregation_window = 28;

    // Stream
    string seek = 25;
    string shard_id = 26;
    int64 sequence = 27;
}

message InitialWriteRequest {
    Session session = 1;
    string backend = 2;
    string table = 3;
    Frame initial_data = 4;
    string expression = 5; // NoSQL
    bool more = 6; // Stream
    repeated string partition_keys = 7; // NoSQL
    string condition = 8; // NoSQL
    string save_mode = 9; // NoSQL
}

message WriteRequest {
    oneof type {
	InitialWriteRequest request = 1;
	Frame frame = 2;
    }
}

message WriteRespose {
    int64 frames = 1;
    int64 rows = 2;
}


enum ErrorOptions {
    FAIL = 0;  // Default to fail on error
    IGNORE = 1;
}

// CreateRequest is a table creation request
message CreateRequest {
    Session session = 1;
    string backend = 2; // name of the backend
    string table = 3; // Table name (path)
    TableSchema schema = 4; // Schema (for describing unstructured/schemaless data)
    ErrorOptions if_exists = 5;
    // TSDB
    string rate = 6; //Sample rate
    string aggregates = 7;
    string aggregation_granularity = 8;
    // Stream
    int64 shards = 9;
    int64 retention_hours = 10;
}

message CreateResponse {}

// DeleteRequest is a deletion request
message DeleteRequest {
    Session session = 1;
    string backend = 2; // Name of the backend
    string table = 3; // Table name (path)
    string filter = 4; // Filter string for selective delete
    ErrorOptions if_missing = 5; // Ignore error on missing table
    // TSDB and Stream specific fields
    string start = 6;
    string end = 7;
    repeated string metrics = 8;
}

message DeleteResponse {}

message VersionRequest {}

message ExecResponse  {
    Frame frame = 1;
    int64 rows = 2;
}

message ExecRequest {
    Session session = 1;
    string backend = 2; // Name of the backend
    string table = 3; // Table name (path)
    string command = 4; // Command to execute
    map<string, Value> args = 5; // Command arguments
    string expression = 6;
}

message VersionResponse {
    string version = 1;
}

message HistoryRequest {
    Session session = 1;
    string backend = 2; // Filter by backend type
    string table = 3; // Filter by Table name
    string user = 4; // Filter by the user executed the command
    string action = 5; // Filter by Action type
    string min_start_time = 6; // Filter time range
    string max_start_time = 7; // Filter time range
    string container = 8; // Filter time range
    int64 min_duration = 9; // Filter time range
    int64 max_duration = 10; // Filter time range
}


service Frames {
    rpc Read(ReadRequest) returns (stream Frame) {}
    rpc Write(stream WriteRequest) returns (WriteRespose) {}
    rpc Create(CreateRequest) returns (CreateResponse) {}
    rpc Delete(DeleteRequest) returns (DeleteResponse) {}
    rpc Exec(ExecRequest) returns (ExecResponse) {}
    rpc History(HistoryRequest) returns (stream Frame) {}
    rpc Version(VersionRequest) returns (VersionResponse) {}
}