Couchbase C Client  2.10.6
Asynchronous C Client for Couchbase
N1QL/Analytics

Detailed Description

Execute N1QL/Analytics queries.

Query language based on SQL, but designed for structured and flexible JSON documents. Querying can solve typical programming tasks such as finding a user profile by email address, performing aggregations etc.

const char *query = "{\"statement\":\"SELECT * FROM breweries LIMIT 10\"}";
lcb_CMDN1QL cmd = {0};
int idx = 0;
// NOTE: with this flag, the request will be issued to Analytics service
cmd.callback = row_callback;
cmd.query = query;
cmd.nquery = strlen(query);
lcb_n1ql_query(instance, &idx, &cmd);
lcb_wait(instance);

Where row_callback might be implemented like this:

static void row_callback(lcb_t instance, int type, const lcb_RESPN1QL *resp)
{
int *idx = (int *)resp->cookie;
if (resp->rc != LCB_SUCCESS) {
printf("failed to execute query: %s\n", lcb_strerror_short(resp->rc));
exit(EXIT_FAILURE);
}
if (resp->rflags & LCB_RESP_F_FINAL) {
printf("META: ");
} else {
printf("ROW #%d: ", (*idx)++);
}
printf("%.*s\n", (int)resp->nrow, (char *)resp->row);
}
See also
more details on lcb_n1ql_query and lcb_CMDN1QL.

Also there is a query builder available for N1QL queries: lcb_n1p_new/ lcb_n1p_mkcmd.

Functions

lcb_CMDANALYTICS * lcb_analytics_new (void)
 
void lcb_analytics_reset (lcb_CMDANALYTICS *cmd)
 
void lcb_analytics_free (lcb_CMDANALYTICS *cmd)
 
lcb_error_t lcb_analytics_setcallback (lcb_CMDANALYTICS *cmd, lcb_ANALYTICSCALLBACK callback)
 
lcb_error_t lcb_analytics_setquery (lcb_CMDANALYTICS *cmd, const char *query, size_t nquery)
 
lcb_error_t lcb_analytics_setstatement (lcb_CMDANALYTICS *cmd, const char *statement, size_t nstatement)
 
lcb_error_t lcb_analytics_namedparam (lcb_CMDANALYTICS *cmd, const char *name, size_t nname, const char *value, size_t nvalue)
 
lcb_error_t lcb_analytics_posparam (lcb_CMDANALYTICS *cmd, const char *value, size_t nvalue)
 
lcb_error_t lcb_analytics_setopt (lcb_CMDANALYTICS *cmd, const char *name, size_t nname, const char *value, size_t nvalue)
 
lcb_error_t lcb_analytics_setdeferred (lcb_CMDANALYTICS *cmd, int deferred)
 
lcb_error_t lcb_analytics_ingest_setmethod (lcb_CMDANALYTICS *cmd, lcb_ANALYTICSINGESTMETHOD method)
 
lcb_error_t lcb_analytics_ingest_setexptime (lcb_CMDANALYTICS *cmd, lcb_U32 exptime)
 
lcb_error_t lcb_analytics_ingest_ignoreingesterror (lcb_CMDANALYTICS *cmd, int ignore)
 
lcb_error_t lcb_analytics_ingest_setidgenerator (lcb_CMDANALYTICS *cmd, lcb_ANALYTICSINGESTIDGENERATOR generator)
 
lcb_error_t lcb_analytics_ingest_setdataconverter (lcb_CMDANALYTICS *cmd, lcb_ANALYTICSINGESTDATACONVERTER converter)
 
lcb_error_t lcb_analytics_query (lcb_t instance, const void *cookie, lcb_CMDANALYTICS *cmd)
 
lcb_ANALYTICSDEFERREDHANDLE * lcb_analytics_defhnd_extract (const lcb_RESPANALYTICS *response)
 
void lcb_analytics_defhnd_free (lcb_ANALYTICSDEFERREDHANDLE *handle)
 
const char * lcb_analytics_defhnd_status (lcb_ANALYTICSDEFERREDHANDLE *handle)
 
lcb_error_t lcb_analytics_defhnd_setcallback (lcb_ANALYTICSDEFERREDHANDLE *handle, lcb_ANALYTICSCALLBACK callback)
 
lcb_error_t lcb_analytics_defhnd_poll (lcb_t instance, const void *cookie, lcb_ANALYTICSDEFERREDHANDLE *handle)
 
void lcb_analytics_cancel (lcb_t instance, lcb_ANALYTICSHANDLE handle)
 Cancels an in-progress request. More...
 

Macros

#define lcb_analytics_setqueryz(cmd, qstr)
 
#define lcb_analytics_setstatementz(cmd, sstr)
 
#define lcb_analytics_namedparamz(cmd, name, value)
 
#define lcb_analytics_setoptz(cmd, key, value)
 

Typedefs

typedef struct lcb_CMDANALYTICS_st lcb_CMDANALYTICS
 
typedef struct lcb_ANALYTICSREQ * lcb_ANALYTICSHANDLE
 
typedef void(* lcb_ANALYTICSCALLBACK) (lcb_t, int, const lcb_RESPANALYTICS *)
 
typedef lcb_ANALYTICSINGESTSTATUS(* lcb_ANALYTICSINGESTIDGENERATOR) (lcb_t, const void *, lcb_ANALYTICSINGESTIDGENERATORPARAM *)
 
typedef lcb_ANALYTICSINGESTSTATUS(* lcb_ANALYTICSINGESTDATACONVERTER) (lcb_t, const void *, lcb_ANALYTICSINGESTDATACONVERTERPARAM *)
 
typedef struct lcb_ANALYTICSDEFERREDHANDLE_st lcb_ANALYTICSDEFERREDHANDLE
 
typedef struct lcb_N1QLREQ * lcb_N1QLHANDLE
 Pointer for request instance.
 
typedef void(* lcb_N1QLCALLBACK) (lcb_t, int, const lcb_RESPN1QL *)
 Callback to be invoked for each row. More...
 

Enumerations

enum  lcb_ANALYTICSINGESTMETHOD
 
enum  lcb_ANALYTICSINGESTSTATUS
 

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_readonly (lcb_N1QLPARAMS *params, int readonly)
 Marks query as read-only. More...
 
lcb_error_t lcb_n1p_scancap (lcb_N1QLPARAMS *params, int scancap)
 Sets maximum buffered channel size between the indexer client and the query service for index scans. More...
 
lcb_error_t lcb_n1p_pipelinecap (lcb_N1QLPARAMS *params, int pipelinecap)
 Sets maximum number of items each execution operator can buffer between various operators. More...
 
lcb_error_t lcb_n1p_pipelinebatch (lcb_N1QLPARAMS *params, int pipelinebatch)
 Sets the number of items execution operators can batch for fetch from the KV. 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)
 Shortcut to set NUL-terminated string as statement via lcb_n1p_setquery.
 
#define lcb_n1p_namedparamz(params, name, value)
 Shortcut to set NUL-terminated string as named param via lcb_n1p_namedparam.
 
#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. More...
 
#define LCB_CMDN1QL_F_ANALYTICSQUERY
 This is an Analytics query. More...
 
#define LCB_CMDN1QL_F_CBASQUERY
 

Function Documentation

◆ lcb_analytics_query()

lcb_error_t lcb_analytics_query ( lcb_t  instance,
const void *  cookie,
lcb_CMDANALYTICS *  cmd 
)
Stability
Volatile:

Execute a Analytics query.

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

Parameters
instanceThe instance
cookiePointer to application data
cmdthe command
Returns
Scheduling success or failure.
Examples
example/analytics/analytics.c.

◆ lcb_analytics_cancel()

void lcb_analytics_cancel ( lcb_t  instance,
lcb_ANALYTICSHANDLE  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_CMDANALYTICS::handle)

To obtain the handle parameter, do something like this:

lcb_CMDANALYTICS *cmd;
// (Initialize command...)
lcb_n1ql_query(instance, cookie, &cmd);
lcb_ANALYTICSHANDLE handle = lcb_analytics_gethandle(cmd);
lcb_analytics_free(cmd);

.

If the lcb_analytics_query() function returns LCB_SUCCESS then the handle above is populated with the opaque handle. You can then use this handle to cancel the query at a later point, such as within the callback.

lcb_analytics_cancel(instance, handle);

◆ lcb_n1p_new()

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.

Examples
example/minimal/query.c, and example/subdoc/subdoc-xattrs.c.

◆ lcb_n1p_reset()

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

◆ lcb_n1p_free()

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
Examples
example/minimal/query.c.

◆ lcb_n1p_setquery()

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

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

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.
Examples
example/minimal/query.c.

◆ lcb_n1p_readonly()

lcb_error_t lcb_n1p_readonly ( lcb_N1QLPARAMS params,
int  readonly 
)

Marks query as read-only.

If the user knows the request is only ever a select, for security reasons it can make sense to tell the server this thing is readonly and it will prevent mutations from happening.

If readonly is set, then the following statements are not allowed:

  • CREATE INDEX
  • DROP INDEX
  • INSERT
  • MERGE
  • UPDATE
  • UPSERT
  • DELETE
Parameters
paramsthe params object
readonlyif non-zero, the query will be read-only

◆ lcb_n1p_scancap()

lcb_error_t lcb_n1p_scancap ( lcb_N1QLPARAMS params,
int  scancap 
)

Sets maximum buffered channel size between the indexer client and the query service for index scans.

This parameter controls when to use scan backfill. Use 0 or a negative number to disable.

Parameters
paramsthe params object
scancapchannel size

◆ lcb_n1p_pipelinecap()

lcb_error_t lcb_n1p_pipelinecap ( lcb_N1QLPARAMS params,
int  pipelinecap 
)

Sets maximum number of items each execution operator can buffer between various operators.

Parameters
paramsthe params object
pipelinecapnumber of items

◆ lcb_n1p_pipelinebatch()

lcb_error_t lcb_n1p_pipelinebatch ( lcb_N1QLPARAMS params,
int  pipelinebatch 
)

Sets the number of items execution operators can batch for fetch from the KV.

Parameters
paramsthe params object
pipelinebatchnumber of items

◆ lcb_n1p_setopt()

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
Examples
example/minimal/query.c.

◆ lcb_n1p_setconsistency()

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

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

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

◆ lcb_n1p_encode()

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_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.
Examples
example/minimal/query.c, and example/subdoc/subdoc-xattrs.c.

◆ lcb_n1ql_query()

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. By default it will run query as N1QL flavour, for Analytics set LCB_CMDN1QL_F_ANALYTICSQUERY flag in cmdflags of lcb_CMDN1QL argument.

Parameters
instanceThe instance
cookiePointer to application data
cmdthe command
Returns
Scheduling success or failure.
Examples
example/minimal/query.c, and example/subdoc/subdoc-xattrs.c.

◆ lcb_n1ql_cancel()

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)

To obtain the handle parameter, do something like this:

// (Initialize command...)
cmd.handle = &handle;
lcb_n1ql_query(instance, cookie, &cmd);

.

If the lcb_n1ql_query() function returns LCB_SUCCESS then the handle above is populated with the opaque handle. You can then use this handle to cancel the query at a later point, such as within the callback.

lcb_n1ql_cancel(instance, handle);

Data Structure Documentation

◆ lcb_RESPANALYTICS

struct lcb_RESPANALYTICS

Response for a Analytics query.

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

Examples
example/analytics/analytics.c.
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.

◆ lcb_CMDN1QL

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.

Examples
example/minimal/query.c, and example/subdoc/subdoc-xattrs.c.
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.

Starting from version 2.7.3, is used for experimental CBAS support

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

◆ lcb_RESPN1QL

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

Examples
example/minimal/query.c, and example/subdoc/subdoc-xattrs.c.
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

◆ LCB_N1P_QUERY_PREPARED

#define LCB_N1P_QUERY_PREPARED
Stability
Internal:

◆ lcb_n1p_setoptz

#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

◆ LCB_N1P_CONSISTENCY_RYOW

#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.

◆ LCB_CMDN1QL_F_PREPCACHE

#define LCB_CMDN1QL_F_PREPCACHE

Prepare and cache the query if required.

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

◆ LCB_CMDN1QL_F_JSONQUERY

#define LCB_CMDN1QL_F_JSONQUERY

The lcb_CMDN1QL::query member is an internal JSON structure.

Stability
Internal:

◆ LCB_CMDN1QL_F_ANALYTICSQUERY

#define LCB_CMDN1QL_F_ANALYTICSQUERY

This is an Analytics query.

Stability
Committed:

Typedef Documentation

◆ lcb_N1QLCALLBACK

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.

◆ lcb_N1QLPARAMS

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