riak.proto

/* -------------------------------------------------------------------
**
** riak.proto: Protocol buffers for Riak
**
** Copyright (c) 2007-2010 Basho Technologies, Inc.  All Rights Reserved.
**
** This file is provided 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.
**
** -------------------------------------------------------------------
*/

/*
** Revision: 1.4
*/

// Go package specifiers
option go_package = "riago";

// Java package specifiers
option java_package = "com.basho.riak.protobuf";
option java_outer_classname = "RiakPB";


// Error response - may be generated for any Req
message RpbErrorResp {
    required bytes errmsg = 1;
    required uint32 errcode = 2;
}

// Get server info request - no message defined, just send RpbGetServerInfoReq message code
message RpbGetServerInfoResp {
    optional bytes node = 1;
    optional bytes server_version = 2;
}

// Key/value pair - used for user metadata, indexes, search doc fields
message RpbPair {
    required bytes key = 1;
    optional bytes value = 2;
}


// Get bucket properties request
message RpbGetBucketReq {
    required bytes bucket = 1;
    optional bytes type = 2;
}

// Get bucket properties response
message RpbGetBucketResp {
    required RpbBucketProps props = 1;
}

// Set bucket properties request
message RpbSetBucketReq {
    required bytes bucket = 1;
    required RpbBucketProps props = 2;
    optional bytes type = 3;
}

// Set bucket properties response - no message defined, just send
// RpbSetBucketResp

// Reset bucket properties request
message RpbResetBucketReq {
    required bytes bucket = 1;
    optional bytes type = 2;
}

// Get bucket properties request
message RpbGetBucketTypeReq {
    required bytes type = 1;
}

// Set bucket properties request
message RpbSetBucketTypeReq {
    required bytes type = 1;
    required RpbBucketProps props = 2;
}

// Set bucket properties response - no message defined, just send
// RpbSetBucketResp

// Module-Function pairs for commit hooks and other bucket properties
// that take functions
message RpbModFun {
    required bytes module = 1;
    required bytes function = 2;
}

// A commit hook, which may either be a modfun or a JavaScript named
// function
message RpbCommitHook {
    optional RpbModFun modfun = 1;
    optional bytes name = 2;
}

// Bucket properties
message RpbBucketProps {
    // Declared in riak_core_app
    optional uint32 n_val = 1;
    optional bool allow_mult = 2;
    optional bool last_write_wins = 3;
    repeated RpbCommitHook precommit = 4;
    optional bool has_precommit = 5 [default = false];
    repeated RpbCommitHook postcommit = 6;
    optional bool has_postcommit = 7 [default = false];
    optional RpbModFun chash_keyfun = 8;

    // Declared in riak_kv_app
    optional RpbModFun linkfun = 9;
    optional uint32 old_vclock = 10;
    optional uint32 young_vclock = 11;
    optional uint32 big_vclock = 12;
    optional uint32 small_vclock = 13;
    optional uint32 pr = 14;
    optional uint32 r = 15;
    optional uint32 w = 16;
    optional uint32 pw = 17;
    optional uint32 dw = 18;
    optional uint32 rw = 19;
    optional bool basic_quorum = 20;
    optional bool notfound_ok = 21;

    // Used by riak_kv_multi_backend
    optional bytes backend = 22;

    // Used by riak_search bucket fixup
    optional bool search = 23;

    // Used by riak_repl bucket fixup
    enum RpbReplMode {
        FALSE = 0;
        REALTIME = 1;
        FULLSYNC = 2;
        TRUE = 3;
    }
    optional RpbReplMode repl = 24;

    // Search index
    optional bytes search_index = 25;

    // KV Datatypes
    optional bytes datatype = 26;

    // KV strong consistency
    optional bool consistent = 27;
}

// Authentication request
message RpbAuthReq {
    required bytes user = 1;
    required bytes password = 2;
}


/*
 * Begin riak_dt.proto
 */

/*
 * =============== DATA STRUCTURES =================
 */

/*
 * Field names in maps are composed of a binary identifier and a type.
 * This is so that two clients can create fields with the same name
 * but different types, and they converge independently.
 */
message MapField {
    /*
     * The types that can be stored in a map are limited to counters,
     * sets, registers, flags, and maps.
     */
    enum MapFieldType {
        COUNTER  = 1;
        SET      = 2;
        REGISTER = 3;
        FLAG     = 4;
        MAP      = 5;
    }

    required bytes        name = 1;
    required MapFieldType type = 2;
}


/*
 * An entry in a map is a pair of a field-name and value. The type
 * defined in the field determines which value type is expected.
 */
message MapEntry {
    required MapField field = 1;
    optional sint64   counter_value  = 2;
    repeated bytes    set_value      = 3;
    optional bytes    register_value = 4;
    optional bool     flag_value     = 5;
    repeated MapEntry map_value      = 6;
}

/*
 * =============== FETCH =================
 */

/*
 * The equivalent of KV's "RpbGetReq", results in a DtFetchResp. The
 * request-time options are limited to ones that are relevant to
 * structured data-types.
 */
message DtFetchReq {
    // The identifier: bucket, key and bucket-type
    required bytes bucket = 1;
    required bytes key    = 2;
    required bytes type  = 3;

    // Request options
    optional uint32 r             =  4;
    optional uint32 pr            =  5;
    optional bool   basic_quorum  =  6;
    optional bool   notfound_ok   =  7;
    optional uint32 timeout       =  8;
    optional bool   sloppy_quorum =  9;  // Experimental, may change/disappear
    optional uint32 n_val         = 10;  // Experimental, may change/disappear

    // For read-only requests or context-free operations, you can set
    // this to false to reduce the size of the response payload.
    optional bool include_context = 11 [default=true];
}


/*
 * The value of the fetched data type. If present in the response,
 * then empty values (sets, maps) should be treated as such.
 */
message DtValue {
    optional sint64   counter_value = 1;
    repeated bytes    set_value     = 2;
    repeated MapEntry map_value     = 3;
}


/*
 * The response to a "Fetch" request. If the `include_context` option
 * is specified, an opaque "context" value will be returned along with
 * the user-friendly data. When sending an "Update" request, the
 * client should send this context as well, similar to how one would
 * send a vclock for KV updates. The `type` field indicates which
 * value type to expect. When the `value` field is missing from the
 * message, the client should interpret it as a "not found".
 */
message DtFetchResp {
    enum DataType {
        COUNTER = 1;
        SET     = 2;
        MAP     = 3;
    }

    optional bytes    context = 1;
    required DataType type    = 2;
    optional DtValue  value   = 3;
}

/*
 * =============== UPDATE =================
 */

/*
 * An operation to update a Counter, either on its own or inside a
 * Map. The `increment` field can be positive or negative. When absent,
 * the meaning is an increment by 1.
 */
message CounterOp {
    optional sint64 increment = 1;
}

/*
 * An operation to update a Set, either on its own or inside a Map.
 * Set members are opaque binary values, you can only add or remove
 * them from a Set.
 */
message SetOp {
    repeated bytes adds    = 1;
    repeated bytes removes = 2;
}

/*
 * An operation to be applied to a value stored in a Map -- the
 * contents of an UPDATE operation. The operation field that is
 * present depends on the type of the field to which it is applied.
 */
message MapUpdate {
    /*
     * Flags only exist inside Maps and can only be enabled or
     * disabled, and there are no arguments to the operations.
     */
    enum FlagOp {
        ENABLE  = 1;
        DISABLE = 2;
    }

    required MapField  field       = 1;

    optional CounterOp counter_op  = 2;
    optional SetOp     set_op      = 3;

    /*
     * There is only one operation on a register, which is to set its
     * value, therefore the "operation" is the new value.
     */
    optional bytes     register_op = 4;
    optional FlagOp    flag_op     = 5;
    optional MapOp     map_op      = 6;
}

/*
 * An operation to update a Map. All operations apply to individual
 * fields in the Map.
 */
message MapOp {
    /*
     * ADD creates a new, "empty" value under a field. REMOVE removes
     * a field and value from the Map. UPDATE applies type-specific
     * operations to the values stored in the Map.
     */
    repeated MapField  adds    = 1;
    repeated MapField  removes = 2;
    repeated MapUpdate updates = 3;
}

/*
 * A "union" type for update operations. The included operation
 * depends on the datatype being updated.
 */
message DtOp {
    optional CounterOp counter_op = 1;
    optional SetOp     set_op     = 2;
    optional MapOp     map_op     = 3;
}

/*
 * The equivalent of KV's "RpbPutReq", results in an empty response or
 * "DtUpdateResp" if `return_body` is specified, or the key is
 * assigned by the server. The request-time options are limited to
 * ones that are relevant to structured data-types.
 */
message DtUpdateReq {
    // The identifier
    required bytes bucket = 1;
    optional bytes key    = 2; // missing key results in server-assigned key, like KV
    required bytes type   = 3; // bucket type, not data-type (but the data-type is constrained per bucket-type)

    // Opaque update-context
    optional bytes context = 4;

    // The operations
    required DtOp  op = 5;

    // Request options
    optional uint32 w               =  6;
    optional uint32 dw              =  7;
    optional uint32 pw              =  8;
    optional bool   return_body     =  9 [default=false];
    optional uint32 timeout         = 10;
    optional bool   sloppy_quorum   = 11;  // Experimental, may change/disappear
    optional uint32 n_val           = 12;  // Experimental, may change/disappear
    optional bool   include_context = 13 [default=true]; // When return_body is true, should the context be returned too?
}


/*
 * The equivalent of KV's "RpbPutResp", contains the assigned key if
 * it was assigned by the server, and the resulting value and context
 * if return_body was set.
 */
message DtUpdateResp {
    // The key, if assigned by the server
    optional bytes    key           = 1;

    // The opaque update context and value, if return_body was set.
    optional bytes    context       = 2;
    optional sint64   counter_value = 3;
    repeated bytes    set_value     = 4;
    repeated MapEntry map_value     = 5;
}


/*
 * Begin riak_kv.proto
 */

// Get ClientId Request - no message defined, just send RpbGetClientIdReq message code
message RpbGetClientIdResp {
    required bytes client_id = 1; // Client id in use for this connection
}

message RpbSetClientIdReq {
    required bytes client_id = 1; // Client id to use for this connection
}
// Set ClientId Request - no message defined, just send RpbSetClientIdReq message code


// Get Request - retrieve bucket/key
message RpbGetReq {
    required bytes bucket = 1;
    required bytes key = 2;
    optional uint32 r = 3;
    optional uint32 pr = 4;
    optional bool basic_quorum = 5;
    optional bool notfound_ok = 6;
    optional bytes if_modified = 7;     // fail if the supplied vclock does not match
    optional bool head = 8;             // return everything but the value
    optional bool deletedvclock = 9;    // return the tombstone's vclock, if applicable
    optional uint32 timeout = 10;
    optional bool sloppy_quorum = 11;   // Experimental, may change/disappear
    optional uint32 n_val = 12;         // Experimental, may change/disappear
    optional bytes type = 13;           // Bucket type, if not set we assume the 'default' type
}

// Get Response - if the record was not found there will be no content/vclock
message RpbGetResp {
    repeated RpbContent content = 1;
    optional bytes vclock = 2;        // the opaque vector clock for the object
    optional bool unchanged = 3;
}


// Put request - if options.return_body is set then the updated metadata/data for
//               the key will be returned.
message RpbPutReq {
    required bytes bucket = 1;
    optional bytes key = 2;
    optional bytes vclock = 3;
    required RpbContent content = 4;
    optional uint32 w = 5;
    optional uint32 dw = 6;
    optional bool return_body = 7;
    optional uint32 pw = 8;
    optional bool if_not_modified = 9;
    optional bool if_none_match = 10;
    optional bool return_head = 11;
    optional uint32 timeout = 12;
    optional bool asis = 13;
    optional bool sloppy_quorum = 14; // Experimental, may change/disappear
    optional uint32 n_val = 15;       // Experimental, may change/disappear
    optional bytes type = 16;         // Bucket type, if not set we assume the 'default' type
}

// Put response - same as get response with optional key if one was generated
message RpbPutResp {
    repeated RpbContent content = 1;
    optional bytes vclock = 2;        // the opaque vector clock for the object
    optional bytes key = 3;           // the key generated, if any
}


// Delete request
message RpbDelReq {
    required bytes bucket = 1;
    required bytes key = 2;
    optional uint32 rw = 3;
    optional bytes vclock = 4;
    optional uint32 r = 5;
    optional uint32 w = 6;
    optional uint32 pr = 7;
    optional uint32 pw = 8;
    optional uint32 dw = 9;
    optional uint32 timeout = 10;
    optional bool sloppy_quorum = 11; // Experimental, may change/disappear
    optional uint32 n_val = 12;       // Experimental, may change/disappear
    optional bytes type = 13;         // Bucket type, if not set we assume the 'default' type
}

// Delete response - not defined, will return a RpbDelResp on success or RpbErrorResp on failure

// List buckets request
message RpbListBucketsReq {
    optional uint32 timeout = 1;
    optional bool stream = 2;
    optional bytes type = 3;         // Bucket type, if not set we assume the 'default' type
}

// List buckets response - one or more of these packets will be sent
// the last one will have done set true (and may not have any buckets in it)
message RpbListBucketsResp {
    repeated bytes buckets = 1;
    optional bool done = 2;
}


// List keys in bucket request
message RpbListKeysReq {
    required bytes bucket = 1;
    optional uint32 timeout = 2;
    optional bytes type = 3;         // Bucket type, if not set we assume the 'default' type
}

// List keys in bucket response - one or more of these packets will be sent
// the last one will have done set true (and may not have any keys in it)
message RpbListKeysResp {
    repeated bytes keys = 1;
    optional bool done = 2;
}


// Map/Reduce request
message RpbMapRedReq {
    required bytes request = 1;
    required bytes content_type = 2;
}

// Map/Reduce response
// one or more of these packets will be sent the last one will have done set
// true (and may not have phase/data in it)
message RpbMapRedResp {
    optional uint32 phase = 1;
    optional bytes response = 2;
    optional bool done = 3;
}

// Secondary Index query request
message RpbIndexReq {
    enum IndexQueryType {
        eq = 0;
        range = 1;
    }

    required bytes bucket = 1;
    required bytes index = 2;
    required IndexQueryType qtype = 3;
    optional bytes key = 4; // key here means equals value for index?
    optional bytes range_min = 5;
    optional bytes range_max = 6;
    optional bool return_terms = 7;
    optional bool stream = 8;
    optional uint32 max_results = 9;
    optional bytes continuation = 10;
    optional uint32 timeout = 11;
    optional bytes type = 12;         // Bucket type, if not set we assume the 'default' type
    optional bytes term_regex = 13;
    // Whether to use pagination sort for non-paginated queries
    optional bool pagination_sort = 14;
}

// Secondary Index query response
message RpbIndexResp {
    repeated bytes keys = 1;
    repeated RpbPair results = 2;
    optional bytes continuation = 3;
    optional bool done = 4;
}

// added solely for riak_cs currently
// for folding over a bucket and returning
// objects.
message RpbCSBucketReq {
    required bytes bucket = 1;
    required bytes start_key = 2;
    optional bytes end_key = 3;
    optional bool start_incl = 4 [default = true];
    optional bool end_incl = 5 [default = false];
    optional bytes continuation = 6;
    optional uint32 max_results = 7;
    optional uint32 timeout = 8;
    optional bytes type = 9;         // Bucket type, if not set we assume the 'default' type
}

// return for CS bucket fold
message RpbCSBucketResp {
    repeated RpbIndexObject objects = 1;
    optional bytes continuation = 2;
    optional bool done = 3;
}

message RpbIndexObject {
    required bytes key = 1;
    required RpbGetResp object = 2;
}

// Content message included in get/put responses
// Holds the value and associated metadata
message RpbContent {
    required bytes value = 1;
    optional bytes content_type = 2;     // the media type/format
    optional bytes charset = 3;
    optional bytes content_encoding = 4;
    optional bytes vtag = 5;
    repeated RpbLink links = 6;          // links to other resources
    optional uint32 last_mod = 7;
    optional uint32 last_mod_usecs = 8;
    repeated RpbPair usermeta = 9;       // user metadata stored with the object
    repeated RpbPair indexes = 10;       // user metadata stored with the object
    optional bool deleted = 11;
}

// Link metadata
message RpbLink {
    optional bytes bucket = 1;
    optional bytes key = 2;
    optional bytes tag = 3;
}

// Counter update request
message RpbCounterUpdateReq {
    required bytes bucket = 1;
    required bytes key = 2;
    required sint64 amount = 3;
    optional uint32 w = 4;
    optional uint32 dw = 5;
    optional uint32 pw = 6;
    optional bool returnvalue = 7;
}

// Counter update response? No message | error response
message RpbCounterUpdateResp {
        optional sint64 value = 1;
}

// counter value
message RpbCounterGetReq {
    required bytes bucket = 1;
    required bytes key = 2;
    optional uint32 r = 3;
    optional uint32 pr = 4;
    optional bool basic_quorum = 5;
    optional bool notfound_ok = 6;
}

// Counter value response
message RpbCounterGetResp {
    optional sint64 value = 1;
}


/*
 * Begin riak_search.proto
 */

message RpbSearchDoc {
  repeated RpbPair fields = 1;
}

message RpbSearchQueryReq {
  required bytes  q      =  1;  // Query string
  required bytes  index  =  2;  // Index
  optional uint32 rows   =  3;  // Limit rows
  optional uint32 start  =  4;  // Starting offset
  optional bytes  sort   =  5;  // Sort order
  optional bytes  filter =  6;  // Inline fields filtering query
  optional bytes  df     =  7;  // Default field
  optional bytes  op     =  8;  // Default op
  repeated bytes  fl     =  9;  // Return fields limit (for ids only, generally)
  optional bytes  presort = 10; // Presort (key / score)
}

message RpbSearchQueryResp {
  repeated RpbSearchDoc docs      = 1; // Result documents
  optional float        max_score = 2; // Maximum score
  optional uint32       num_found = 3; // Number of results
}


/*
 * Begin riak_yokozuna.proto
 */

// Index queries

message RpbYokozunaIndex {
    required bytes name   =  1;  // Index name
    optional bytes schema =  2;  // Schema name
    optional uint32 n_val =  3;  // N value
}

// GET request - If a name is given, return matching index, else return all
message RpbYokozunaIndexGetReq {
    optional bytes name  =  1;  // Index name
}

message RpbYokozunaIndexGetResp {
    repeated RpbYokozunaIndex index  =  1;
}

// PUT request - Create a new index
message RpbYokozunaIndexPutReq {
    required RpbYokozunaIndex index  =  1;
}

// DELETE request - Remove an index
message RpbYokozunaIndexDeleteReq {
    required bytes name  =  1;  // Index name
}

// Schema queries

message RpbYokozunaSchema {
    required bytes name    =  1;  // Index name
    optional bytes content =  2;  // Schema data
}

// PUT request - create or potentially update a new schema
message RpbYokozunaSchemaPutReq {
    required RpbYokozunaSchema schema =  1;
}

// GET request - Return matching schema by name
message RpbYokozunaSchemaGetReq {
    required bytes name  =  1;  // Schema name
}

message RpbYokozunaSchemaGetResp {
  required RpbYokozunaSchema schema =  1;
}