Protocol Buffers Client API

This is an overview of the operations you can perform using the Protocol Buffers Client (PBC) interface to Riak, and can be used as a guide for developing a PBC-compliant Riak client.

Protocol

Riak listens on a TCP port (8087 by default) for incoming connections. Once connected, the client can send a stream of requests on the same connection.

Each operation consists of a request message and one or more response messages. Messages are all encoded the same way, consisting of:

  • 32-bit length of message code + Protocol Buffers message in network order
  • 8-bit message code to identify the Protocol Buffers message
  • N bytes of Protocol Buffers-encoded message

Example

00 00 00 07 09 0A 01 62 12 01 6B
|----Len---|MC|----Message-----|

Len = 0x07
Message Code (MC) = 0x09 = RpbGetReq
RpbGetReq Message = 0x0A 0x01 0x62 0x12 0x01 0x6B

Decoded Message:
bucket: "b"
key: "k"

Message Codes

Code Message
0 RpbErrorResp
1 RpbPingReq
2 RpbPingResp
3 RpbGetClientIdReq
4 RpbGetClientIdResp
5 RpbSetClientIdReq
6 RpbSetClientIdResp
7 RpbGetServerInfoReq
8 RpbGetServerInfoResp
9 RpbGetReq
10 RpbGetResp
11 RpbPutReq
12 RpbPutResp
13 RpbDelReq
14 RpbDelResp
15 RpbListBucketsReq
16 RpbListBucketsResp
17 RpbListKeysReq
18 RpbListKeysResp
19 RpbGetBucketReq
20 RpbGetBucketResp
21 RpbSetBucketReq
22 RpbSetBucketResp
23 RpbMapRedReq
24 RpbMapRedResp
25 RpbIndexReq
26 RpbIndexResp
29 RpbResetBucketReq
30 RpbResetBucketResp
31 RpbGetBucketTypeReq
32 RpbSetBucketTypeResp
40 RpbCSBucketReq
41 RpbCSUpdateReq
50 RpbCounterUpdateReq
51 RpbCounterUpdateResp
52 RpbCounterGetReq
53 RpbCounterGetResp
80 DtFetchReq
81 DtFetchResp
82 DtUpdateReq
83 DtUpdateResp
253 RpbAuthReq
254 RpbAuthResp
255 RpbStartTls
Message Definitions

All Protocol Buffers messages are defined in the riak.proto and other .proto files in the /src directory of the RiakPB project.

Error Response

If the request does not result in an error, Riak will return one of a variety of response messages, e.g. RpbGetResp or RpbPutResp, depending on which request message is sent.

If the server experiences an error processing a request, however, it will return an RpbErrorResp message instead of the response expected for the given request (e.g. RbpGetResp is the expected response to RbpGetReq). Error messages contain an error string and an error code, like this:

message RpbErrorResp {
    required bytes errmsg = 1;
    required uint32 errcode = 2;
}

Values

  • errmsg - A string representation of what went wrong
  • errcode - A numeric code. Currently, only RIAKC_ERR_GENERAL=1 is defined.

Bucket Operations

Object/Key Operations

Query Operations

Server Operations

Bucket Type Operations

Data Type Operations