Couchbase C Client
2.5.6
|
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) |
void | lcb_view_query_initcmd (lcb_CMDVIEWQUERY *vq, const char *design, const char *view, const char *options, lcb_VIEWQUERYCALLBACK callback) |
void | lcb_view_cancel (lcb_t instance, lcb_VIEWHANDLE handle) |
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 |
typedef void(* | lcb_VIEWQUERYCALLBACK) (lcb_t instance, int cbtype, const lcb_RESPVIEWQUERY *row) |
Callback function invoked for each row returned from the view. More... | |
lcb_error_t lcb_view_query | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDVIEWQUERY * | cmd | ||
) |
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:
instance | The library handle |
cookie | user pointer included in every response |
cmd | the command detailing the type of query to perform |
void lcb_view_query_initcmd | ( | lcb_CMDVIEWQUERY * | vq, |
const char * | design, | ||
const char * | view, | ||
const char * | options, | ||
lcb_VIEWQUERYCALLBACK | callback | ||
) |
Initialize a command object. This is a convenience function.
vq | the command to initialize |
design | the name of the design. Required and should be NUL-terminated |
view | the name of the view. Required and should be NUL-terminated |
options | a string of options. Optional. If provided, should be NUL-terminated |
callback | the callback to invoke. Required |
void lcb_view_cancel | ( | lcb_t | instance, |
lcb_VIEWHANDLE | handle | ||
) |
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.
struct lcb_CMDVIEWQUERY |
Command structure for querying a view.
Data Fields | ||
---|---|---|
lcb_U32 | cmdflags | Common command flags; e.g. |
const char * | ddoc |
The design document as a string; e.g.
|
size_t | nddoc | Length of design document name. |
const char * | view |
The name of the view as a string; e.g.
|
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 The format of the options follows the standard for passing parameters via HTTP requests; thus e.g. |
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 |
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.
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 |
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 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 |
#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
#define LCB_CMDVIEWQUERY_F_SPATIAL |
This view is spatial.
Modifies how the final view path will be constructed
typedef void(* lcb_VIEWQUERYCALLBACK) (lcb_t instance, int cbtype, const lcb_RESPVIEWQUERY *row) |
Callback function invoked for each row returned from the view.
instance | the library handle |
cbtype | the callback type. This is set to LCB_CALLBACK_VIEWQUERY |
row | Information 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.