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_N1QLPARAMS *	lcb_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

params the 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

params the 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

params	the params object
qstr	the query string (either N1QL statement or prepared JSON)
nqstr	the length of the string. Set to -1 if NUL-terminated
type	the 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

params	the object
name	The argument name (e.g. `$age`)
n_name
value	The 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

params	the params object
value	the argument
n_value	the 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

params	the params object
name	the name of the option
n_name
value	the 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

params	the parameters object
mode	one 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

params	the parameters object
keyspace	the keyspace (or bucket name) which this mutation token pertains to
st	the 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

	params	the parameter object
[out]	rc	an 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

instance	The instance
cookie	Pointer to application data
cmd	the 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

instance	the instance
handle	the 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

params	the parameter object
key	the NUL-terminated option name
value	the 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

The	instance
Callback	type. This is set to LCB_CALLBACK_N1QL
The	response.

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().

Detailed Description

Typedefs

N1QL Parameters

Low-level N1QL interface

Function Documentation

Data Structure Documentation

Macro Definition Documentation

Typedef Documentation