Couchbase C Client  2.10.0
Asynchronous C Client for Couchbase
Views (Map-Reduce)

Detailed Description

Higher level API which splits view results into rows.

Functions

lcb_error_t lcb_view_query (lcb_t instance, const void *cookie, const lcb_CMDVIEWQUERY *cmd)
 
More...
 
void lcb_view_query_initcmd (lcb_CMDVIEWQUERY *vq, const char *design, const char *view, const char *options, lcb_VIEWQUERYCALLBACK callback)
 
More...
 
void lcb_view_cancel (lcb_t instance, lcb_VIEWHANDLE handle)
 
More...
 

Macros

#define LCB_CMDVIEWQUERY_F_INCLUDE_DOCS
 Set this flag to execute an actual get with each response.
 
#define LCB_CMDVIEWQUERY_F_NOROWPARSE
 Set this flag to only parse the top level row, and not its constituent parts. More...
 
#define LCB_CMDVIEWQUERY_F_SPATIAL
 This view is spatial. More...
 

Typedefs

typedef struct lcbview_REQUEST_st * lcb_VIEWHANDLE
 Pointer for request instance.
 
typedef void(* lcb_VIEWQUERYCALLBACK) (lcb_t instance, int cbtype, const lcb_RESPVIEWQUERY *row)
 Callback function invoked for each row returned from the view. More...
 

Function Documentation

◆ lcb_view_query()

lcb_error_t lcb_view_query ( lcb_t  instance,
const void *  cookie,
const lcb_CMDVIEWQUERY cmd 
)


Stability
Volatile:

Initiate a view query. This will execute a view (MapReduce) request against a view endpoint within the cluster. For each row emitted by the view functions (i.e. the map, and possibly reduce functions) the callback specified in the lcb_CMDVIEWQUERY::callback field will be invoked.

Here is a functional example:

static void rowCallback(lcb_t instance, int ignoreme, const lcb_RESPVIEWQUERY *response) {
if (response->rflags & LCB_RESP_F_FINAL) {
printf("View is done!\n");
if (response->nvalue) {
printf("Raw JSON metadata: %.*s\n", (int)response->nvalue, response->value);
}
if (response->rc != LCB_SUCCESS) {
printf("Query failed: %s\n", lcb_sterror(instance, response->rc));
}
return;
}
// Key and value always exist:
printf("Emitted key: %.*s\n", (int)resp->nkey, resp-key);
printf("Emitted value: %s.*s\n", (int)resp->nvalue, resp->value);
// Document IDs are only present for non-reduce queries
if (resp->docid) {
printf("Document ID: %.*s\n", (int)resp->docid, resp->ndocid);
// If LCB_CMDVIEWQUERY_F_INCLUDE_DOCS was specified, this might
// contain the actual document value
if (resp->docresp) {
const lcb_RESPGET *rg = resp->docresp;
if (rg->rc == LCB_SUCCESS) {
printf("Document contents: %.*s\n", (int)rg->value, rg->nvalue);
printf("CAS: 0x%lx\n", rg->cas);
} else {
printf("Couldn't fetch document: %s\n", lcb_strerror(instance, rg->rc));
}
}
}
}
static void doViewRequest(lcb_t instance) {
lcb_CMDVIEWQUERY cmd = { 0 };
vq.ddoc = "beer";
vq.nddoc = strlen(vq.ddoc);
vq.view = "brewery_beers";
vq.nview = strlen(vq.view);
vq.optstr = "limit=10&descending=true";
vq.noptstr = strlen(vq.optstr);
vq.callback = rowCallback;
// If you want to perform an implicit lcb_get3() on each row's `docid`
if (includeDocs) {
}
lcb_error_t rc = lcb_view_query(instance, NULL, &cmd);
// handle error
lcb_wait(instance);
}
Parameters
instanceThe library handle
cookieuser pointer included in every response
cmdthe command detailing the type of query to perform
Returns
LCB_SUCCESS on scheduling success, or an error code on scheduling failure.
Examples:
example/tracing/views.c.

◆ lcb_view_query_initcmd()

void lcb_view_query_initcmd ( lcb_CMDVIEWQUERY vq,
const char *  design,
const char *  view,
const char *  options,
lcb_VIEWQUERYCALLBACK  callback 
)


Stability
Volatile:

Initialize a command object. This is a convenience function.

Parameters
vqthe command to initialize
designthe name of the design. Required and should be NUL-terminated
viewthe name of the view. Required and should be NUL-terminated
optionsa string of options. Optional. If provided, should be NUL-terminated
callbackthe callback to invoke. Required

◆ lcb_view_cancel()

void lcb_view_cancel ( lcb_t  instance,
lcb_VIEWHANDLE  handle 
)


Stability
Volatile:

Cancels the ongoing request. This ensures the callback will never be invoked. This should be used only in situations where the lcb_t itself may be destroyed to avoid leaking any application allocated memory. This does not guarantee the view internals will not leak, however.


Data Structure Documentation

◆ lcb_CMDVIEWQUERY

struct lcb_CMDVIEWQUERY

Command structure for querying a view.

Examples:
example/tracing/views.c.
Data Fields
lcb_U32 cmdflags Common command flags; e.g.

LCB_CMDVIEWQUERY_F_INCLUDE_DOCS

const char * ddoc The design document as a string; e.g.

"beer"

size_t nddoc Length of design document name.
const char * view The name of the view as a string; e.g.

"brewery_beers"

size_t nview Length of the view name.
const char * optstr Any URL parameters to be passed to the view should be specified here.

The library will internally insert a ? character before the options (if specified), so do not place one yourself.

The format of the options follows the standard for passing parameters via HTTP requests; thus e.g. key1=value1&key2=value2. This string is itself not parsed by the library but simply appended to the URL.

size_t noptstr Length of the option string.
const char * postdata Some query parameters (in particular; 'keys') may be send via a POST request within the request body, since it might be too long for the URI itself.

If you have such data, place it here.

size_t npostdata
unsigned docs_concurrent_max The maximum number of internal get requests to issue concurrently for F_INCLUDE_DOCS.

This is useful for large view responses where there is a potential for a large number of responses resulting in a large number of get requests; increasing memory usage.

Setting this value will attempt to throttle the number of get requests, so that no more than this number of requests will be in progress at any given time.

lcb_VIEWQUERYCALLBACK callback Callback to invoke for each row.

If not provided, LCB_EINVAL will be returned from lcb_view_query()

lcb_VIEWHANDLE * handle If not NULL, this will be set to a handle which may be passed to lcb_view_cancel().

See that function for more details

◆ lcb_RESPVIEW_st

struct lcb_RESPVIEW_st

Response structure representing a row.

This is provided for each invocation of the lcb_CMDVIEWQUERY::callback invocation. The key and nkey fields here refer to the first argument passed to the emit function by the map function.

This response structure may be used as-is, in case the values are simple, or may be relayed over to a more advanced JSON parser to decode the individual key and value properties.

Note
The key and value fields are JSON encoded. This means that if they are bare strings, they will be surrounded by quotes. On the other hand, the docid is not JSON encoded and is provided with any surrounding quotes stripped out (this is because the document ID is always a string). Please take note of this if doing any form of string comparison/processing.
If the LCB_CMDVIEWQUERY_F_NOROWPARSE flag has been set, the value field will contain the raw row contents, rather than the constituent elements.
Data Fields
void * cookie User data associated with request.
const void * key Emitted key.
lcb_SIZE nkey Length of emitted key.
lcb_cas_t cas unused
lcb_error_t rc Status code.
lcb_U16 version unused
lcb_U16 rflags Response specific flags.

see lcb_RESPFLAGS

const char * docid Document ID (i.e.

memcached key) associated with this row

size_t ndocid Length of document ID.
const char * value Emitted value.

If rflags & LCB_RESP_F_FINAL is true then this will contain the metadata of the view response itself. This includes the total_rows field among other things, and should be parsed as JSON

size_t nvalue Length of emitted value.
const char * geometry If this is a spatial view, the GeoJSON geometry fields will be here.
size_t ngeometry
const lcb_RESPHTTP * htresp If the request failed, this will contain the raw underlying request.

You may inspect this request and perform some other processing on the underlying HTTP data. Note that this may not necessarily contain the entire response body; just the chunk at which processing failed.

const lcb_RESPGET * docresp If LCB_CMDVIEWQUERY_F_INCLUDE_DOCS was specified in the request, this will contain the response for the GET command.

This is the same response as would be received in the LCB_CALLBACK_GET for lcb_get3().

Note that this field should be checked for various errors as well, as it is remotely possible the get request did not succeed.

If the LCB_CMDVIEWQUERY_F_INCLUDE_DOCS flag was not specified, this field will be NULL.

Macro Definition Documentation

◆ LCB_CMDVIEWQUERY_F_NOROWPARSE

#define LCB_CMDVIEWQUERY_F_NOROWPARSE

Set this flag to only parse the top level row, and not its constituent parts.

Note this is incompatible with F_INCLUDE_DOCS

◆ LCB_CMDVIEWQUERY_F_SPATIAL

#define LCB_CMDVIEWQUERY_F_SPATIAL

This view is spatial.

Modifies how the final view path will be constructed

Typedef Documentation

◆ lcb_VIEWQUERYCALLBACK

typedef void(* lcb_VIEWQUERYCALLBACK) (lcb_t instance, int cbtype, const lcb_RESPVIEWQUERY *row)

Callback function invoked for each row returned from the view.

Parameters
instancethe library handle
cbtypethe callback type. This is set to LCB_CALLBACK_VIEWQUERY
rowInformation about the current row

Note that this callback's row->rflags will contain the LCB_RESP_F_FINAL flag set after all rows have been returned. Applications should check for the presence of this flag. If this flag is present, the row itself will contain the raw response metadata in its lcb_RESPVIEWQUERY::value field.