PBC Secondary Indexes

Request a set of keys that match a 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;
    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;
    optional bytes term_regex = 13;
    optional bool pagination_sort = 14;
    optional bytes cover_context = 15;
    optional bool return_body = 16;
}

Required Parameters

Parameter Description
bucket The name of the bucket in which the Data Type is stored
index The name of the index to be queried
qtype The type of index query to be performed. This can take either of the two possible values of the IndexQueryType enum: eq for an exact index match for the given key or range for a range query

Optional Parameters

Parameter Description
key The name of the index to be queried if qtype is set to eq
range_min and range_max The minimum and maximum values for a range query if qtype is set to range
return_terms If set to true, the response will include matched indexed values (for range queries only)
stream If set to true, keys matching the index query will be streamed to the client instead of waiting for max_results or the full result to be tabulated
max_results If pagination is turned on, the number of results to be returned to the client
continuation If set to true, values are returned in a paginated response
timeout The timeout duration, in milliseconds, after which Riak will return an error message
type The bucket type of the bucket that is being queried. If not set, the bucket type default will be used. Learn more about using bucket types.
term_regex If set to a regular expression (as a binary), a term filter will be applied to the index query
pagination_sort If set to true, paginated results will be sorted, first by index value, then by key
cover_context Opaque binary used to target a vnode. Requested via [a coverage query][../coverage-queries/]
return_body Return values with keys. Only worked when using the system indexes $bucket or $key

Response

The results of a Secondary Index query are returned as a repeating list of 0 or more keys that match the given request parameters.

message RpbIndexResp {
    repeated bytes keys = 1;
    repeated RpbPair results = 2;
    optional bytes continuation = 3;
    optional bool done = 4;
}

Values

Parameter Description
keys A list of keys that match the index request
results If return_terms is specified with range queries, used to return matched index values as key/value pairs in RpbPair messages. More on RpbPair messages can be found in PBC Fetch Object.
continuation Used for paginated responses
done Used for streaming. The value will be true when the current stream is done (either max_results has been reached or there are no more results).

Example

Request

Here we look for any exact matches of chicken on an animal_bin index for a bucket named farm.

RpbIndexReq protoc decode:
bucket: "farm"
index: "animal_bin"
qtype: 0
key: "chicken"

Hex     00 00 00 1E 19 0A 04 66 61 72 6D 12 0A 61 6E 69
        6D 61 6C 5F 62 69 6E 18 00 22 07 63 68 69 63 6B 65 6E
Erlang  <<0,0,0,30,25,10,10,4,102,97,114,109,18,10,97,110,105,
          109,97,108,95,98,105,110,24,0,34,7,99,104,105,99,107,
          101,110>>

Response

Hex     00 00 00 0F 1A 0A 03 68 65 6E 0A 07 72 6F 6F 73 74 65 72
Erlang  <<0,0,0,15,26,10,3,104,101,110,10,7,114,111,111,115,116,101,114>>

RpbIndexResp protoc decode:
keys: "hen"
keys: "rooster"