Couchbase C Client  3.3.10
Asynchronous C Client for Couchbase
Analytics Queries

Detailed Description

Execute Analytics N1QL Queries.

Functions

lcb_STATUS lcb_respanalytics_status (const lcb_RESPANALYTICS *resp)
 
lcb_STATUS lcb_respanalytics_cookie (const lcb_RESPANALYTICS *resp, void **cookie)
 
lcb_STATUS lcb_respanalytics_row (const lcb_RESPANALYTICS *resp, const char **row, size_t *row_len)
 
lcb_STATUS lcb_respanalytics_http_response (const lcb_RESPANALYTICS *resp, const lcb_RESPHTTP **http)
 
lcb_STATUS lcb_respanalytics_handle (const lcb_RESPANALYTICS *resp, lcb_ANALYTICS_HANDLE **handle)
 Get handle to analytics query. More...
 
lcb_STATUS lcb_respanalytics_error_context (const lcb_RESPANALYTICS *resp, const lcb_ANALYTICS_ERROR_CONTEXT **ctx)
 
int lcb_respanalytics_is_final (const lcb_RESPANALYTICS *resp)
 
lcb_STATUS lcb_respanalytics_deferred_handle_extract (const lcb_RESPANALYTICS *resp, lcb_DEFERRED_HANDLE **handle)
 
lcb_STATUS lcb_deferred_handle_destroy (lcb_DEFERRED_HANDLE *handle)
 
lcb_STATUS lcb_deferred_handle_status (lcb_DEFERRED_HANDLE *handle, const char **status, size_t *status_len)
 
lcb_STATUS lcb_deferred_handle_callback (lcb_DEFERRED_HANDLE *handle, lcb_ANALYTICS_CALLBACK callback)
 
lcb_STATUS lcb_deferred_handle_poll (lcb_INSTANCE *instance, void *cookie, lcb_DEFERRED_HANDLE *handle)
 
lcb_STATUS lcb_ingest_options_create (lcb_INGEST_OPTIONS **options)
 
lcb_STATUS lcb_ingest_options_destroy (lcb_INGEST_OPTIONS *options)
 
lcb_STATUS lcb_ingest_options_method (lcb_INGEST_OPTIONS *options, lcb_INGEST_METHOD method)
 
lcb_STATUS lcb_ingest_options_expiry (lcb_INGEST_OPTIONS *options, uint32_t expiration)
 
lcb_STATUS lcb_ingest_options_ignore_error (lcb_INGEST_OPTIONS *options, int flag)
 
lcb_STATUS lcb_ingest_options_data_converter (lcb_INGEST_OPTIONS *options, lcb_INGEST_DATACONVERTER_CALLBACK callback)
 
lcb_STATUS lcb_ingest_dataconverter_param_cookie (lcb_INGEST_PARAM *param, void **cookie)
 
lcb_STATUS lcb_ingest_dataconverter_param_row (lcb_INGEST_PARAM *param, const char **row, size_t *row_len)
 
lcb_STATUS lcb_ingest_dataconverter_param_method (lcb_INGEST_PARAM *param, lcb_INGEST_METHOD *method)
 
lcb_STATUS lcb_ingest_dataconverter_param_set_id (lcb_INGEST_PARAM *param, const char *id, size_t id_len, void(*id_dtor)(const char *))
 
lcb_STATUS lcb_ingest_dataconverter_param_set_out (lcb_INGEST_PARAM *param, const char *out, size_t out_len, void(*out_dtor)(const char *))
 
lcb_STATUS lcb_cmdanalytics_create (lcb_CMDANALYTICS **cmd)
 
lcb_STATUS lcb_cmdanalytics_destroy (lcb_CMDANALYTICS *cmd)
 
lcb_STATUS lcb_cmdanalytics_reset (lcb_CMDANALYTICS *cmd)
 
lcb_STATUS lcb_cmdanalytics_callback (lcb_CMDANALYTICS *cmd, lcb_ANALYTICS_CALLBACK callback)
 
lcb_STATUS lcb_cmdanalytics_encoded_payload (lcb_CMDANALYTICS *cmd, const char **query, size_t *query_len)
 
lcb_STATUS lcb_cmdanalytics_payload (lcb_CMDANALYTICS *cmd, const char *query, size_t query_len)
 
lcb_STATUS lcb_cmdanalytics_statement (lcb_CMDANALYTICS *cmd, const char *statement, size_t statement_len)
 
lcb_STATUS lcb_cmdanalytics_named_param (lcb_CMDANALYTICS *cmd, const char *name, size_t name_len, const char *value, size_t value_len)
 
lcb_STATUS lcb_cmdanalytics_positional_params (lcb_CMDANALYTICS *cmd, const char *value, size_t value_len)
 Sets the positional arguments for the query. More...
 
lcb_STATUS lcb_cmdanalytics_positional_param (lcb_CMDANALYTICS *cmd, const char *value, size_t value_len)
 
lcb_STATUS lcb_cmdanalytics_ingest_options (lcb_CMDANALYTICS *cmd, lcb_INGEST_OPTIONS *options)
 
lcb_STATUS lcb_cmdanalytics_deferred (lcb_CMDANALYTICS *cmd, int deferred)
 
lcb_STATUS lcb_cmdanalytics_client_context_id (lcb_CMDANALYTICS *cmd, const char *value, size_t value_len)
 
lcb_STATUS lcb_cmdanalytics_readonly (lcb_CMDANALYTICS *cmd, int readonly)
 
lcb_STATUS lcb_cmdanalytics_priority (lcb_CMDANALYTICS *cmd, int priority)
 
lcb_STATUS lcb_cmdanalytics_consistency (lcb_CMDANALYTICS *cmd, lcb_ANALYTICS_CONSISTENCY level)
 
lcb_STATUS lcb_cmdanalytics_option (lcb_CMDANALYTICS *cmd, const char *name, size_t name_len, const char *value, size_t value_len)
 
lcb_STATUS lcb_cmdanalytics_scope_name (lcb_CMDANALYTICS *cmd, const char *scope, size_t scope_len)
 Associate scope name with the query. More...
 
lcb_STATUS lcb_cmdanalytics_scope_qualifier (lcb_CMDANALYTICS *cmd, const char *qualifier, size_t qualifier_len)
 
lcb_STATUS lcb_cmdanalytics_handle (lcb_CMDANALYTICS *cmd, lcb_ANALYTICS_HANDLE **handle)
 Get handle to analytics query. More...
 
lcb_STATUS lcb_cmdanalytics_timeout (lcb_CMDANALYTICS *cmd, uint32_t timeout)
 
lcb_STATUS lcb_cmdanalytics_on_behalf_of (lcb_CMDANALYTICS *cmd, const char *data, size_t data_len)
 
lcb_STATUS lcb_analytics (lcb_INSTANCE *instance, void *cookie, const lcb_CMDANALYTICS *cmd)
 Execute a Analytics query. More...
 
lcb_STATUS lcb_analytics_cancel (lcb_INSTANCE *instance, lcb_ANALYTICS_HANDLE *handle)
 Cancels an in-progress request. More...
 

Typedefs

typedef struct lcb_ANALYTICS_HANDLE_ lcb_ANALYTICS_HANDLE
 
typedef struct lcb_DEFERRED_HANDLE_ lcb_DEFERRED_HANDLE
 
typedef struct lcb_RESPANALYTICS_ lcb_RESPANALYTICS
 Response for a Analytics query. More...
 
typedef void(* lcb_ANALYTICS_CALLBACK) (lcb_INSTANCE *, int, const lcb_RESPANALYTICS *)
 Callback to be invoked for each row. More...
 
typedef struct lcb_CMDANALYTICS_ lcb_CMDANALYTICS
 
typedef struct lcb_INGEST_OPTIONS_ lcb_INGEST_OPTIONS
 
typedef struct lcb_INGEST_PARAM_ lcb_INGEST_PARAM
 
typedef lcb_INGEST_STATUS(* lcb_INGEST_DATACONVERTER_CALLBACK) (lcb_INSTANCE *instance, lcb_INGEST_PARAM *param)
 

Enumerations

enum  lcb_INGEST_METHOD
 
enum  lcb_ANALYTICS_CONSISTENCY
 
enum  lcb_INGEST_STATUS
 

Function Documentation

◆ lcb_respanalytics_handle()

lcb_STATUS lcb_respanalytics_handle ( const lcb_RESPANALYTICS resp,
lcb_ANALYTICS_HANDLE **  handle 
)

Get handle to analytics query.

Used when canceling analytics request. See lcb_cmdanalytics_handle also

Parameters
respthe analytics response
handlepointer to handle pointer
Returns
LCB_SUCCESS if successful, otherwise an error code

◆ lcb_cmdanalytics_positional_params()

lcb_STATUS lcb_cmdanalytics_positional_params ( lcb_CMDANALYTICS *  cmd,
const char *  value,
size_t  value_len 
)

Sets the positional arguments for the query.

Parameters
cmdthe command
valuethe arguments encoded as JSON array
value_lenthe length of the argument.

◆ lcb_cmdanalytics_positional_param()

lcb_STATUS lcb_cmdanalytics_positional_param ( lcb_CMDANALYTICS *  cmd,
const char *  value,
size_t  value_len 
)
Deprecated:
This function will be marked as deprecated in 3.3.0, and will start emitting compiler warning.

Use lcb_cmdanalytics_positional_params instead.

Parameters
cmdthe command
valuethe argument value in JSON encoding
value_lenthe length of the encoded value

◆ lcb_cmdanalytics_scope_name()

lcb_STATUS lcb_cmdanalytics_scope_name ( lcb_CMDANALYTICS *  cmd,
const char *  scope,
size_t  scope_len 
)

Associate scope name with the query.

Parameters
cmdthe command
scopethe name of the scope
scope_lenlength of the scope name string.

◆ lcb_cmdanalytics_scope_qualifier()

lcb_STATUS lcb_cmdanalytics_scope_qualifier ( lcb_CMDANALYTICS *  cmd,
const char *  qualifier,
size_t  qualifier_len 
)
Stability
Uncommitted:

Associate scope_qualifier (also known as query_context) with the query.

The qualifier must be in form default:${bucket_name}.${scope_name}.

See also
REST API definition at https://docs.couchbase.com/server/current/analytics/rest-service.html
Parameters
cmdthe command
qualifierthe string containing qualifier
qualifier_lenlength of the qualifier

◆ lcb_cmdanalytics_handle()

lcb_STATUS lcb_cmdanalytics_handle ( lcb_CMDANALYTICS *  cmd,
lcb_ANALYTICS_HANDLE **  handle 
)

Get handle to analytics query.

Used when canceling a request. See lcb_respanalytics_handle as well

Parameters
cmdthe command
handlepointer to handle pointer
Returns
LCB_SUCCESS if successful, otherwise an error code

◆ lcb_cmdanalytics_on_behalf_of()

lcb_STATUS lcb_cmdanalytics_on_behalf_of ( lcb_CMDANALYTICS *  cmd,
const char *  data,
size_t  data_len 
)
Stability
Internal:
Internal: This should never be used and is not supported.

◆ lcb_analytics()

lcb_STATUS lcb_analytics ( lcb_INSTANCE instance,
void *  cookie,
const lcb_CMDANALYTICS *  cmd 
)

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
LCB_SUCCESS if successfully scheduled otherwise a failure.
Examples
example/analytics/analytics.c.

◆ lcb_analytics_cancel()

lcb_STATUS lcb_analytics_cancel ( lcb_INSTANCE instance,
lcb_ANALYTICS_HANDLE *  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 can be obtained from the command (see lcb_cmdanalytics_handle), or from the response (see lcb_respanalytics_handle)

To obtain the handle parameter, do something like this:

lcb_CMDANALYTICS *cmd;
// (Initialize command...)
lcb_analytics(instance, cookie, &cmd);
lcb_ANALYTICS_HANDLE* handle;
lcb_cmdanalytics_gethandle(cmd, &handle);
lcb_STATUS lcb_analytics(lcb_INSTANCE *instance, void *cookie, const lcb_CMDANALYTICS *cmd)
Execute a Analytics query.

If you happen to only have the lcb_RESPANALYTICS handy, say you are in the callback:

lcb_ANALYTICS_HANDLE* handle;
lcb_respanalytics_handle(resp, &handle);
lcb_STATUS lcb_respanalytics_handle(const lcb_RESPANALYTICS *resp, lcb_ANALYTICS_HANDLE **handle)
Get handle to analytics query.

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_STATUS lcb_analytics_cancel(lcb_INSTANCE *instance, lcb_ANALYTICS_HANDLE *handle)
Cancels an in-progress request.

Typedef Documentation

◆ lcb_RESPANALYTICS

typedef struct lcb_RESPANALYTICS_ 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

◆ lcb_ANALYTICS_CALLBACK

typedef void(* lcb_ANALYTICS_CALLBACK) (lcb_INSTANCE *, int, const lcb_RESPANALYTICS *)

Callback to be invoked for each row.

Parameters
Theinstance
Callbacktype. This is set to LCB_CALLBACK_ANALYTICS
Theresponse.

Enumeration Type Documentation

◆ lcb_ANALYTICS_CONSISTENCY

Enumerator
LCB_ANALYTICS_CONSISTENCY_NOT_BOUNDED 

No consistency constraints.

The default. When you are not concerned about the consistency of this query with regards to other queries.

LCB_ANALYTICS_CONSISTENCY_REQUEST_PLUS 

Strong consistency.

Ensures that the query won't execute until any pending indexing at the time of the request has completed.