Analytics using the C SDK

Enterprise Edition

Parallel data management for complex queries over many records, using a familiar N1QL-like syntax.

For complex and long-running queries, involving large ad hoc join, set, aggregation, and grouping operations, Couchbase Data Platform offers the Couchbase Analytics Service (CBAS). This is the analytic counterpart to our operational data focussed Query Service. The analytics service is available in Couchbase Data Platform 6.0 and later (developer preview in 5.5).

Getting Started

After familiarizing yourself with our introductory primer, in particular creating a dataset and linking it to a bucket to shadow the operational data, try Couchbase Analytics using the Go SDK. Intentionally, the API for analytics is very similar to that of the query service. In these examples we will be using an airports dataset created on the travel-sample bucket.

In C SDK 2.x, Analytics was only available on the Bucket object; in C SDK 3.x, Analytics queries are submitted using the Cluster reference, not a Bucket or Collection:

When using a Couchbase version < 6.5 you must create a valid Bucket connection using cluster.Bucket(name) before you can use Analytics.

Here is an example of doing an analytics query :

const char *stmt = "SELECT * FROM breweries LIMIT 2";
lcb_CMDANALYTICS *cmd;
int idx = 0;
lcb_cmdanalytics_create(&cmd);
lcb_cmdanalytics_callback(cmd, row_callback);
lcb_cmdanalytics_statement(cmd, stmt, strlen(stmt));
lcb_cmdanalytics_deferred(cmd, 1);
check(lcb_analytics(instance, &idx, cmd), "schedule analytics query");
std::cout << "----> " << stmt << "\n";
lcb_cmdanalytics_destroy(cmd);
lcb_wait(instance, LCB_WAIT_DEFAULT);

For a full example, see the API documentation.

Analytics Result

When performing an analytics query, lcb_RESPANALYTICS is delivered in the lcb_ANALYTICS_CALLBACK function for each result row received.

int *idx;
const char *row;
size_t nrow;
lcb_STATUS rc = lcb_respanalytics_status(resp);

lcb_respanalytics_cookie(resp, reinterpret_cast<void **>(&idx));
lcb_respanalytics_row(resp, &row, &nrow);
if (rc != LCB_SUCCESS) {
    const lcb_RESPHTTP *http;
    std::cout << lcb_strerror_short(rc);
    lcb_respanalytics_http_response(resp, &http);

Analytics Options

The analytics service provides an array of options to customize your query. The following table lists them :

Table 1. Available Analytics options
Name	Description
`lcb_cmdanalytics_reset(command)`	Reset the structure so that it may be reused for a subsequent analytics query.
`lcb_cmdanalytics_encoded_payload(command,query,query length)`	Get the JSON-encoded analytics query payload.
`lcb_cmdanalytics_payload(command, query, query length)`	Sets the JSON-encodes analytics query payload to be executed.
`lcb_cmdanalytics_statement(command, statement, statement length )`	Sets the actual statement to be executed.
`lcb_cmdanalytics_scope_name(command, scope name, scope length)`	Associate scope name with the analytics query.
`lcb_cmdanalytics_named_param(command, argument name, name length, argument value, value length)`	Sets a named argument for the analytics query.
`lcb_cmdanalytics_positional_params(command, arguments as JSON string, argument string length)`	Adds positional arguments for the analytics query. (From C SDK 3.2.1)
`lcb_cmdanalytics_positional_param(command, argument value, argument length)`	Adds a positional argument for the analytics query. (Will be deprecated from C SDK 3.3.0)
`lcb_cmdanalytics_readonly(command, readonly)`	Marks analytics query as read-only ( set readonly value to non zero ).

Additional Resources

To learn more about using N1QL for Analytics — the first commercial implementation of SQL++ — see our Tutorial Introduction to SQL++ for SQL users.