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

resp	the analytics response
handle	pointer 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

cmd	the command
value	the arguments encoded as JSON array
value_len	the 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

cmd	the command
value	the argument value in JSON encoding
value_len	the 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

cmd	the command
scope	the name of the scope
scope_len	length 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

cmd	the command
qualifier	the string containing qualifier
qualifier_len	length 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

cmd	the command
handle	pointer 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

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

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

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

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

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

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

Enumeration Type Documentation

lcb_ANALYTICS_CONSISTENCY

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