Analytics Queries

Detailed Description

Execute Analytics N1QL Queries.

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.