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 {
    INTEGER = 0;
    FLOAT = 1;
    STRING = 2;
    TIME = 3;
    BOOLEAN = 4;
}

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 Frame {
    repeated Column columns = 1;
    repeated Column indices = 2;
    map<string, Value> labels = 3;
    string error = 4; // Used in errors when reading over HTTP
}

// 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;
    string query = 7; // SQL Query
    string table = 8; // Table name
    repeated string columns = 9;
    string filter = 10;
    string group_by = 11;
    repeated JoinStruct join = 12;

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

    // 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 aggragators = 24;

    // 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;
    bool more = 6;
    repeated string partition_keys = 7;
}

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)
    map<string, Value> attribute_map = 4; // List of attributes used for creating the table
    TableSchema schema = 5; // Schema (for describing unstructured/schemaless data)
    ErrorOptions if_exists = 6;
}

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;
}

message DeleteResponse {}

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 ExecResponse {}

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