Couchbase C Client  2.5.6
N1QL

Detailed Description

Execute N1QL queries and receive resultant rows.

Typedefs

typedef struct lcb_N1QLREQ * lcb_N1QLHANDLE
 
typedef void(* lcb_N1QLCALLBACK) (lcb_t, int, const lcb_RESPN1QL *)
 Callback to be invoked for each row. More...
 

N1QL Parameters

The following APIs simply provide wrappers for creating the proper HTTP form parameters for N1QL requests.

The general flow is to create a parameters (lcb_N1QLPARAMS) object, set various options and properties on it, and populate an lcb_CMDN1QL object using the lcb_n1p_mkcmd() function.

typedef struct lcb_N1QLPARAMS_st lcb_N1QLPARAMS
 Opaque object representing N1QL parameters. More...
 
lcb_N1QLPARAMSlcb_n1p_new (void)
 Create a new N1QL Parameters object. More...
 
void lcb_n1p_reset (lcb_N1QLPARAMS *params)
 Reset the parameters structure so that it may be reused for a subsequent query. More...
 
void lcb_n1p_free (lcb_N1QLPARAMS *params)
 Free the parameters structure. More...
 
lcb_error_t lcb_n1p_setquery (lcb_N1QLPARAMS *params, const char *qstr, size_t nqstr, int type)
 Sets the actual statement to be executed. More...
 
lcb_error_t lcb_n1p_namedparam (lcb_N1QLPARAMS *params, const char *name, size_t n_name, const char *value, size_t n_value)
 Sets a named argument for the query. More...
 
lcb_error_t lcb_n1p_posparam (lcb_N1QLPARAMS *params, const char *value, size_t n_value)
 Adds a positional argument for the query. More...
 
lcb_error_t lcb_n1p_setopt (lcb_N1QLPARAMS *params, const char *name, size_t n_name, const char *value, size_t n_value)
 Set a query option. More...
 
lcb_error_t lcb_n1p_setconsistency (lcb_N1QLPARAMS *params, int mode)
 Sets the consistency mode for the request. More...
 
lcb_error_t lcb_n1p_setconsistent_token (lcb_N1QLPARAMS *params, const char *keyspace, const lcb_MUTATION_TOKEN *st)
 Indicate that the query should synchronize its internal snapshot to reflect the changes indicated by the given mutation token (ss). More...
 
lcb_error_t lcb_n1p_setconsistent_handle (lcb_N1QLPARAMS *params, lcb_t instance)
 Indicate that the query should synchronize its internal snapshot to reflect any past changes made by the given instance instance. More...
 
const char * lcb_n1p_encode (lcb_N1QLPARAMS *params, lcb_error_t *rc)
 Encodes the request and returns it as a string. More...
 
lcb_error_t lcb_n1p_mkcmd (lcb_N1QLPARAMS *params, lcb_CMDN1QL *cmd)
 Populates the given low-level lcb_CMDN1QL structure with the relevant fields from the params structure. More...
 
#define LCB_N1P_QUERY_STATEMENT
 Query is a statement string.
 
#define LCB_N1P_QUERY_PREPARED
 
#define lcb_n1p_setstmtz(params, qstr)
 
#define lcb_n1p_namedparamz(params, name, value)
 
#define lcb_n1p_setoptz(params, key, value)
 Convenience function to set a string parameter with a string value. More...
 
#define LCB_N1P_CONSISTENCY_NONE
 No consistency constraints.
 
#define LCB_N1P_CONSISTENCY_RYOW
 This is implicitly set by the lcb_n1p_synctok() family of functions. More...
 
#define LCB_N1P_CONSISTENCY_REQUEST
 Refresh the snapshot for each request.
 
#define LCB_N1P_CONSISTENCY_STATEMENT
 Refresh the snapshot for each statement.
 

Low-level N1QL interface

lcb_error_t lcb_n1ql_query (lcb_t instance, const void *cookie, const lcb_CMDN1QL *cmd)
 
void lcb_n1ql_cancel (lcb_t instance, lcb_N1QLHANDLE handle)
 Cancels an in-progress request. More...
 
#define LCB_CMDN1QL_F_PREPCACHE
 Prepare and cache the query if required. More...
 
#define LCB_CMDN1QL_F_JSONQUERY
 The lcb_CMDN1QL::query member is an internal JSON structure.
 

Function Documentation

lcb_N1QLPARAMS* lcb_n1p_new ( void  )

Create a new N1QL Parameters object.

The returned object is an opaque pointer which may be used to set various properties on a N1QL query. This may then be used to populate relevant fields of an lcb_CMDN1QL structure.

void lcb_n1p_reset ( lcb_N1QLPARAMS params)

Reset the parameters structure so that it may be reused for a subsequent query.

Internally this resets the buffer positions to 0, but does not free them, making this function optimal for issusing subsequent queries.

Parameters
paramsthe object to reset
void lcb_n1p_free ( lcb_N1QLPARAMS params)

Free the parameters structure.

This should be done when it is no longer needed

Parameters
paramsthe object to reset
lcb_error_t lcb_n1p_setquery ( lcb_N1QLPARAMS params,
const char *  qstr,
size_t  nqstr,
int  type 
)

Sets the actual statement to be executed.

Parameters
paramsthe params object
qstrthe query string (either N1QL statement or prepared JSON)
nqstrthe length of the string. Set to -1 if NUL-terminated
typethe type of statement. Should be LCB_N1P_QUERY_STATEMENT, currently.
lcb_error_t lcb_n1p_namedparam ( lcb_N1QLPARAMS params,
const char *  name,
size_t  n_name,
const char *  value,
size_t  n_value 
)

Sets a named argument for the query.

Parameters
paramsthe object
nameThe argument name (e.g. $age)
n_name
valueThe argument value (e.g. 42)
n_value
lcb_error_t lcb_n1p_posparam ( lcb_N1QLPARAMS params,
const char *  value,
size_t  n_value 
)

Adds a positional argument for the query.

Parameters
paramsthe params object
valuethe argument
n_valuethe length of the argument.
lcb_error_t lcb_n1p_setopt ( lcb_N1QLPARAMS params,
const char *  name,
size_t  n_name,
const char *  value,
size_t  n_value 
)

Set a query option.

Parameters
paramsthe params object
namethe name of the option
n_name
valuethe value of the option
n_value
lcb_error_t lcb_n1p_setconsistency ( lcb_N1QLPARAMS params,
int  mode 
)

Sets the consistency mode for the request.

By default results are read from a potentially stale snapshot of the data. This may be good for most cases; however at times you want the absolutely most recent data.

Parameters
paramsthe parameters object
modeone of the LCB_N1P_CONSISTENT_* constants.
lcb_error_t lcb_n1p_setconsistent_token ( lcb_N1QLPARAMS params,
const char *  keyspace,
const lcb_MUTATION_TOKEN st 
)

Indicate that the query should synchronize its internal snapshot to reflect the changes indicated by the given mutation token (ss).

Parameters
paramsthe parameters object
keyspacethe keyspace (or bucket name) which this mutation token pertains to
stthe mutation token
lcb_error_t lcb_n1p_setconsistent_handle ( lcb_N1QLPARAMS params,
lcb_t  instance 
)

Indicate that the query should synchronize its internal snapshot to reflect any past changes made by the given instance instance.

This iterates over all the vbuckets for the given instance and inserts the relevant mutation token, using lcb_get_mutation_token

const char* lcb_n1p_encode ( lcb_N1QLPARAMS params,
lcb_error_t rc 
)

Encodes the request and returns it as a string.

The string is valid until the next call to the params function.

Parameters
paramsthe parameter object
[out]rcan error code if there was an issue in encoding
Returns
the NUL-terminated query string.
Note
Calling this function regenerates the query string internally, and is implicitly called by lcb_n1p_mkcmd().
lcb_error_t lcb_n1p_mkcmd ( lcb_N1QLPARAMS params,
lcb_CMDN1QL cmd 
)

Populates the given low-level lcb_CMDN1QL structure with the relevant fields from the params structure.

If this function returns successfuly, you must ensure that the params object is not modified until the command is submitted.

Note
This may also set some lcb_CMDN1QL::cmdflags fields. If setting your own flags, ensure that those flags do not replace the existing ones set by this function.
lcb_error_t lcb_n1ql_query ( lcb_t  instance,
const void *  cookie,
const lcb_CMDN1QL cmd 
)
Stability
Volatile:

Execute a N1QL query.

This function will send the query to a query server in the cluster and will invoke the callback (lcb_CMDN1QL::callback) for each result returned.

Parameters
instanceThe instance
cookiePointer to application data
cmdthe command
Returns
Scheduling success or failure.
void lcb_n1ql_cancel ( lcb_t  instance,
lcb_N1QLHANDLE  handle 
)

Cancels an in-progress request.

This will ensure that further callbacks for the given request are not delivered.

Parameters
instancethe instance
handlethe handle for the request. This is obtained during the request as an 'out' parameter (see lcb_CMDN1QL::handle)

Data Structure Documentation

struct lcb_CMDN1QL

Command structure for N1QL queries.

Typically an application will use the lcb_N1QLPARAMS structure to populate the query and content_type fields.

The callback field must be specified, and indicates the function the library should call when more response data has arrived.

Data Fields
lcb_U32 cmdflags
const char * query Query to be placed in the POST request.

The library will not perform any conversions or validation on this string, so it is up to the user (or wrapping library) to ensure that the string is well formed.

If using the lcb_N1QLPARAMS structure, the lcb_n1p_mkcmd() function will properly populate this field.

In general the string should either be JSON (in which case, the content_type field should be application/json) or url-encoded (in which case the content_type field should be application/x-www-form-urlencoded)

size_t nquery Length of the query data.
const char * host Ignored since version 2.5.3.
const char * content_type Ignored since version 2.5.3.
lcb_N1QLCALLBACK callback Callback to be invoked for each row.
lcb_N1QLHANDLE * handle Request handle.

Will be set to the handle which may be passed to lcb_n1ql_cancel()

struct lcb_RESPN1QL

Response for a N1QL query.

This is delivered in the lcb_N1QLCALLBACK callback function for each result row received. The callback is also called one last time when all

Data Fields
lcb_U16 rflags Flags for response structure.
const char * row Current result row.

If rflags has the LCB_RESP_F_FINAL bit set, then this field does not contain the actual row, but the remainder of the data not included with the resultset; e.g. the JSON surrounding the "results" field with any errors or metadata for the response.

size_t nrow Length of the row.
const lcb_RESPHTTP * htresp Raw HTTP response, if applicable.

Macro Definition Documentation

#define lcb_n1p_setoptz (   params,
  key,
  value 
)

Convenience function to set a string parameter with a string value.

Parameters
paramsthe parameter object
keythe NUL-terminated option name
valuethe NUL-terminated option value
#define LCB_N1P_CONSISTENCY_RYOW

This is implicitly set by the lcb_n1p_synctok() family of functions.

This will ensure that mutations up to the vector indicated by the mutation token passed to lcb_n1p_synctok() are used.

#define LCB_CMDN1QL_F_PREPCACHE

Prepare and cache the query if required.

This may be used on frequently issued queries, so they perform better.

Typedef Documentation

typedef void(* lcb_N1QLCALLBACK) (lcb_t, int, const lcb_RESPN1QL *)

Callback to be invoked for each row.

Parameters
Theinstance
Callbacktype. This is set to LCB_CALLBACK_N1QL
Theresponse.
typedef struct lcb_N1QLPARAMS_st lcb_N1QLPARAMS

Opaque object representing N1QL parameters.

This object is created via lcb_n1p_new(), may be cleared (for use with another query) via lcb_n1p_reset(), and may be freed via lcb_n1p_free().