maprdb-server.proto

syntax = "proto3";

package com.mapr.data.db;

option java_multiple_files = true;
option java_package = "com.mapr.data.db.proto";
option go_package = "mapr/private-maprdb-go-client;private_maprdb_go_client";
//=============================================//
//      RPC calls exported from the service    //
//=============================================//
service MapRDbServer {
  // Ping RPC
  rpc Ping (PingRequest) returns (PingResponse) {}

  // Admin RPCs
  rpc CreateTable (CreateTableRequest) returns (CreateTableResponse) {}
  rpc DeleteTable (DeleteTableRequest) returns (DeleteTableResponse) {}
  rpc TableExists (TableExistsRequest) returns (TableExistsResponse) {}

  // CRUD RPCs
  rpc InsertOrReplace (InsertOrReplaceRequest) returns (InsertOrReplaceResponse) {}
  rpc FindById (FindByIdRequest) returns (FindByIdResponse) {}
  rpc Find (FindRequest) returns (stream FindResponse) {}
  rpc Update (UpdateRequest) returns (UpdateResponse) {}
  rpc Delete (DeleteRequest) returns (DeleteResponse) {}
}

//=============================================//
//            Common RPC Messages              //
//=============================================//

/**
 * RPC response error codes. POSIX error codes are used where appropriate.
 *
 * Extended error codes, those that can not be mapped to a POSIX error code, begins at 256.
 */
enum ErrorCode {
  /**
   * No error, operation completed successfully.
   */
  NO_ERROR = 0;

  /**
   * Specified table does not exist
   */
  TABLE_NOT_FOUND = 2;

  /**
   * An I/O error occurred on the server(s)
   */
  IO_ERROR = 5;

  /**
   * The operation resulted in server(s) running out of memory
   */
  OUT_OF_MEMORY = 12;

  /**
   * User does not have sufficient permission to execute the operation.
   */
  ACCESS_DENIED = 13;

  /**
   * The specified table already exists.
   */
  TABLE_ALREADY_EXISTS = 17;

  /**
   * One or more request parameter was invalid.
   * This error code should be used whenever a request parameter was unrecognized or outside a valid domain.
   * For example, an unrecognized enum value was supplied for InsertMode.
   */
  INVALID_ARGUMENT = 22;

  /**
   * Requested operation is not supported by this server.
   * This error code should be used if a known, valid operation is not supported by the current service.
   */
  UNSUPPORTED_OPERATION = 38;

  /**
   * Catch-all for all undefined errors on server.
   */
  UNKNOWN_ERROR = 256;

  //
  // Extended error codes.
  //
  // TODO: renumber the error codes before release
  //
  UNKNOWN_PAYLOAD_ENCODING = 260;   // specified payload encoding is not supported
  CLUSTER_NOT_FOUND = 270;          // specified cluster does not exist
  PATH_NOT_FOUND = 271;             // parent path of the specified table does not exist
  DOCUMENT_ALREADY_EXISTS = 280;    // a document with the specified _id already exist in the store
  DOCUMENT_NOT_FOUND = 281;         // a document with the specified _id wasn't found in the store
  ENCODING_ERROR = 290;             // an error occurred while encoding an OJAI object
  DECODING_ERROR = 291;             // the supplied OJAI object could not be decoded
  ILLEGAL_MUTATION = 292;           // A mutation operation could not be applied
}

/**
 * Protobuf message that encapsulates RPC operation error, if any.
 * Each RPC response should include RpcError message, with `NO_ERROR` indicating success
 */
message RpcError {
  /**
   * Error code for the RPC. `NO_ERROR` indicates RPC completed successfully
   */
  ErrorCode err_code = 1;

  /**
   * NULL if `err` is `NO_ERROR`
   */
  string error_message = 2;

  /**
   * NULL if `err` is `NO_ERROR`
   */
  string java_stack_trace = 3;
}

/**
 * ENUM indicating the encoding scheme of the OJAI objects in RPC request/response.
 * Currently only JSON encoding is supported.
 */
enum PayloadEncoding {
  /**
   * Invalid, unknown encoding
   */
  UNKNOWN_ENCODING = 0;

  /**
   * Payload is encoded as JSON string
   */
  JSON_ENCODING = 1;
}

//=============================================//
//        RPC Request/Response Messages        //
//=============================================//

message PingRequest {
}

message PingResponse {
}

message CreateTableRequest {
  string table_path = 1;
}

message CreateTableResponse {
  /**
   * `NO_ERROR` - if the table was created successfully,
   * `TABLE_ALREADY_EXISTS` - if a table with the same path already exists
   */
  RpcError error = 1;
}

message DeleteTableRequest {
  string table_path = 1;
}

message DeleteTableResponse {
  /**
   * `NO_ERROR` - if the table exists
   * `TABLE_NOT_FOUND` - if the table does not exist
   */
  RpcError error = 1;
}

message TableExistsRequest {
  string table_path = 1;
}

message TableExistsResponse {
  /**
   * `NO_ERROR` - if the table exists
   * `TABLE_NOT_FOUND` - if the table does not exist
   */
  RpcError error = 1;
}

enum InsertMode {
  /**
   * Invalid, unknown mode
   */
  UNKNOWN_MODE = 0;

  /**
   * Insert this document WHETHER OR NOT a document with the same _id exist in the store
   */
  INSERT_OR_REPLACE = 1;

  /**
   * Insert this document ONLY IF another document with the same _id DOES NOT exist in the store
   */
  INSERT = 2;

  /**
   * Insert this document ONLY IF a document with the same _id EXISTS in the store
   */
  REPLACE = 3;
}

message InsertOrReplaceRequest {
  string table_path = 1;
  InsertMode insert_mode = 2;
  PayloadEncoding payload_encoding = 3;

  oneof condition {
    /**
     * <b>[Optional]</b><p/>
     * Contains JSON encoded OJAI QueryCondition when payload_encoding is `JSON_ENCODING`.<p/>
     * This should only be specified if the `insert_mode` == REPLACE
     */
    string json_condition = 4;
  }

  oneof data {
    /**
     * <b>[Required]</b><p/>
     * Contains JSON encoded OJAI Document if the payload_encoding is `JSON_ENCODING`
     */
    string json_document = 30;
  }
}

message InsertOrReplaceResponse {
  RpcError error = 1;
}

message FindByIdRequest {
  string table_path = 1;
  PayloadEncoding payload_encoding = 2;

  /**
   * <b>[Optional]</b><p/>
   * List of OJAI FieldPaths that should be included in the returned document
   */
  repeated string projections = 3;

  oneof condition {
    /**
     * <b>[Optional]</b><p/>
     * Contains JSON encoded OJAI QueryCondition when payload_encoding is `JSON_ENCODING`.<p/>
     */
    string json_condition = 4;
  }

  oneof document {
    /**
     * <b>[Required]</b><p/>
     * Contains JSON encoded OJAI Document with `_id` field when payload_encoding is `JSON_ENCODING`.<p/>
     */
    string json_document = 5;
  }
}

message FindByIdResponse {
  /**
   * `NO_ERROR` - if a document with the specified `_id` was found
   * `DOCUMENT_NOT_FOUND` - if the document with the specified `_id` does not exist
   */
  RpcError error = 1;

  PayloadEncoding payload_encoding = 2;

  oneof data {
    /**
     * <b>[Required]</b><p/>
     * Contains JSON encoded OJAI Document if the payload_encoding is `JSON_ENCODING`
     */
    string json_document = 30;
  }
}

message FindRequest {
  string table_path = 1;
  PayloadEncoding payload_encoding = 2;
  bool include_query_plan = 3;

  oneof data {
    /**
     * <b>[Required]</b><p/>
     * Contains JSON encoded OJAI Query if the payload_encoding is `JSON_ENCODING`
     */
    string json_query = 4;
  }
}

enum FindResponseType {
  /**
   * Invalid, unknown type
   */
  UNKNOWN_TYPE = 0;

  /**
   * Indicates that the current response contains a QueryResult Document
   */
  RESULT_DOCUMENT = 1;

  /**
   * Indicates that the current response contains a Query plan
   */
  QUERY_PLAN = 2;
}

/**
 * Results of Find() RPCs are streamed to the clients, with each FindResponse containing
 * one OJAI document. If the `include_query_plan` in FindRequest was set to true, the first
 * FindResponse will contain the query plan instead of OJAI Document
 */
message FindResponse {
  RpcError error = 1;
  PayloadEncoding payload_encoding = 2;

  /**
   * Indicates the type of this response
   */
  FindResponseType type = 3;

  oneof data {
    /**
     * Contains JSON encoded response if the payload_encoding is `JSON_ENCODING`
     */
    string json_response = 30;
  }
}

message UpdateRequest {
  string table_path = 1;
  PayloadEncoding payload_encoding = 2;

  oneof document {
    /**
     * <b>[Required]</b><p/>
     * Contains JSON encoded OJAI Document with `_id` field when payload_encoding is `JSON_ENCODING`.<p/>
     */
    string json_document = 3;
  }

  oneof condition {
    /**
     * <b>[Optional]</b><p/>
     * Contains JSON encoded OJAI QueryCondition when payload_encoding is `JSON_ENCODING`.<p/>
     */
    string json_condition = 4;
  }

  oneof mutation {
    /**
     * <b>[Required]</b><p/>
     * Contains JSON encoded OJAI DocumentMutation when payload_encoding is `JSON_ENCODING`.<p/>
     */
    string json_mutation = 30;
  }

}

message UpdateResponse {
  /**
   * `NO_ERROR` - if a document was updated successfully
   * `DOCUMENT_NOT_FOUND` - if a document with specified `_id` does not exist or the specified condition
   *                        evaluated to 'false'.
   */
  RpcError error = 1;
}

message DeleteRequest {
  string table_path = 1;
  PayloadEncoding payload_encoding = 2;

  oneof condition {
    /**
     * <b>[Optional]</b><p/>
     * Contains JSON encoded OJAI QueryCondition when payload_encoding is `JSON_ENCODING`.<p/>
     */
    string json_condition = 3;
  }

  oneof document {
    /**
     * <b>[Required]</b><p/>
     * Contains JSON encoded OJAI Document with `_id` field when payload_encoding is `JSON_ENCODING`.<p/>
     */
    string json_document = 4;
  }

}

message DeleteResponse {
  /**
   * `NO_ERROR` - if a document was deleted successfully
   */
  RpcError error = 1;
}