skizze.proto

syntax = "proto2";

package protobuf;

service Skizze {
  rpc CreateSnapshot (CreateSnapshotRequest) returns (CreateSnapshotReply) {}
  rpc GetSnapshot (GetSnapshotRequest) returns (GetSnapshotReply) {}

  rpc List (ListRequest) returns (ListReply) {}
  rpc ListAll (Empty) returns (ListReply) {}
  rpc ListDomains (Empty) returns (ListDomainsReply) {}

  rpc CreateDomain (Domain) returns (Domain) {}
  rpc DeleteDomain (Domain) returns (Empty) {}
  rpc GetDomain (Domain) returns (Domain) {}

  rpc CreateSketch(Sketch) returns (Sketch) {}
  rpc DeleteSketch(Sketch) returns (Empty) {}
  rpc GetSketch(Sketch) returns (Sketch) {}

  rpc Add (AddRequest) returns (AddReply) {}

  rpc GetMembership (GetRequest) returns (GetMembershipReply) {}
  rpc GetFrequency (GetRequest) returns (GetFrequencyReply) {}
  rpc GetCardinality (GetRequest) returns (GetCardinalityReply) {}
  rpc GetRankings (GetRequest) returns (GetRankingsReply) {}
}


//
// Enums
//
enum SketchType {
  MEMB = 1;
  FREQ = 2;
  RANK = 3;
  CARD = 4;
}

enum SnapshotStatus {
  PENDING     = 1;
  IN_PROGRESS = 2;
  SUCCESSFUL  = 3;
  FAILED      = 4;
}


//
// Generic Structures
//
message Empty {
}

message SketchProperties {
  optional int64 maxUniqueItems = 1; // MEMB, FREQ
  optional float errorRate      = 2; // MEMB, FREQ
  optional int64 size           = 3; // RANK
}

message SketchState {
  optional float fillRate     = 1;  // 0.0 -> 1.0
  optional int64 lastSnapshot = 2;  // Age of last snapshot in seconds since epoch
}

// CreateDomain: name:required, propertiess:optional (array = nSketchTypes, order of types above)
// DeleteDomain: name:required
// GetDomain   : name:required
message Domain {
  required string     name       = 1;
  repeated Sketch     sketches   = 2;
}

// CreateSketch: name:required, type:required, properties:optional
// DeleteSketch: name:required, type:required
// GetSketch   : name:required, type:required
message Sketch {
  required string           name       = 1;
  required SketchType       type       = 2;
  optional SketchProperties properties = 3;
  optional SketchState      state      = 4;
}

message Membership {
  required string value    = 1;
  required bool   isMember = 2;
}

message Frequency {
  required string value  = 1;
  required int64  count  = 2;
}

message Rank {
  required string value = 1;
  required int64  count  = 2;
}


//
// Request/Reply Envelopes
// 

// Right now empty but in the future can request specific snapshot location
// (e.g. S3 or disk) and snapshot options
message CreateSnapshotRequest {
}

message CreateSnapshotReply {
  required SnapshotStatus status        = 1;
  optional string         statusMessage = 2;
}

// Empty for now, future can send in id of specific snapshot
message GetSnapshotRequest {
}

message GetSnapshotReply {
  required SnapshotStatus status        = 1;
  optional string         statusMessage = 2;
  optional int64          timestamp     = 3;
}

message ListRequest {
  required SketchType type = 1;
}

message ListReply {
  repeated Sketch sketches = 1;
}

message ListDomainsReply {
  repeated string names = 1;
}

message AddRequest {
  optional Domain domain = 1;
  optional Sketch sketch = 2;
  repeated string values = 3;
}

message AddReply {
}

// All Sketches will be of one kind
// All values will apply to all sketches (if card or ranking, values will be ignored)
message GetRequest {
  repeated Sketch sketches = 1;   // MEMB:users-20151214,MEMB:users-20151214
  repeated string values   = 2;   // "gary","michelle","ray","harpindar" // Apply to all sketches above
}

message MembershipResult {
  repeated Membership memberships = 1;
}

message FrequencyResult {
  repeated Frequency frequencies = 2;
}

message CardinalityResult {
  required int64 cardinality = 1;
}

message RankingsResult {
  repeated Rank rankings = 1;
}

message GetMembershipReply {
  repeated MembershipResult results = 1;
}

message GetFrequencyReply {
  repeated FrequencyResult results = 1;
}

message GetCardinalityReply {
  repeated CardinalityResult results = 1;
}

message GetRankingsReply {
  repeated RankingsResult results = 1;
}