Couchbase C Client
2.5.6
|
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. | |
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.
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
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.
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.
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.
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.
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.
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
).
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.
params | the parameter object | |
[out] | rc | an error code if there was an issue in encoding |
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.
lcb_error_t lcb_n1ql_query | ( | lcb_t | instance, |
const void * | cookie, | ||
const lcb_CMDN1QL * | cmd | ||
) |
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.
instance | The instance |
cookie | Pointer to application data |
cmd | the command |
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.
instance | the instance |
handle | the handle for the request. This is obtained during the request as an 'out' parameter (see lcb_CMDN1QL::handle) |
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 |
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. |
#define lcb_n1p_setoptz | ( | params, | |
key, | |||
value | |||
) |
Convenience function to set a string parameter with a string value.
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 void(* lcb_N1QLCALLBACK) (lcb_t, int, const lcb_RESPN1QL *) |
Callback to be invoked for each row.
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().