N1QL Queries

Detailed Description

Execute N1QL 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_CMDQUERY* cmd = NULL;
int cookie = 0;
lcb_cmdquery_create(&cmd);
lcb_cmdquery_callback(cmd, row_callback)
lcb_n1ql_query(instance, &cookie, cmd);
lcb_wait(instance, LCB_WAIT_DEFAULT);

Where row_callback might be implemented like this:

static void row_callback(lcb_INSTANCE *instance, int type, const lcb_RESPQUERY *resp)
{
    int* idx = NULL;
    int row_len = 0;
    char* row = NULL;
 
    int rc = lcb_respquery_status(resp);
    if (rc != LCB_SUCCESS) {
        printf("failed to execute query: %s\n", lcb_strerror_short(rc));
        exit(EXIT_FAILURE);
    }
    lcb_respquery_cookie(resp, (void**)(&idx))
    if (lcb_respquery_is_final(resp)) {
        printf("META: ");
    } else {
        printf("ROW #%d: ", (*idx)++);
    }
    lcb_respquery_row(resp, &row_len, &row);
    printf("%.*s\n", row_len, row);
}

See also

more details on lcb_query and lcb_CMDQUERY.

Functions
lcb_STATUS	lcb_respquery_status (const lcb_RESPQUERY *resp)
lcb_STATUS	lcb_respquery_cookie (const lcb_RESPQUERY *resp, void **cookie)
lcb_STATUS	lcb_respquery_row (const lcb_RESPQUERY *resp, const char **row, size_t *row_len)
lcb_STATUS	lcb_respquery_http_response (const lcb_RESPQUERY *resp, const lcb_RESPHTTP **http)
lcb_STATUS	lcb_respquery_handle (const lcb_RESPQUERY *resp, lcb_QUERY_HANDLE **handle)
lcb_STATUS	lcb_respquery_error_context (const lcb_RESPQUERY *resp, const lcb_QUERY_ERROR_CONTEXT **ctx)
int	lcb_respquery_is_final (const lcb_RESPQUERY *resp)
lcb_STATUS	lcb_cmdquery_create (lcb_CMDQUERY **cmd)
	Create a new lcb_CMDQUERY object. More...
lcb_STATUS	lcb_cmdquery_destroy (lcb_CMDQUERY *cmd)
	Free the command structure. More...
lcb_STATUS	lcb_cmdquery_reset (lcb_CMDQUERY *cmd)
	Reset the lcb_CMDQUERY structure so that it may be reused for a subsequent query. More...
lcb_STATUS	lcb_cmdquery_encoded_payload (lcb_CMDQUERY *cmd, const char **payload, size_t *payload_len)
	Get the JSON-encoded query payload. More...
lcb_STATUS	lcb_cmdquery_callback (lcb_CMDQUERY *cmd, lcb_QUERY_CALLBACK callback)
lcb_STATUS	lcb_cmdquery_payload (lcb_CMDQUERY *cmd, const char *query, size_t query_len)
	Sets the JSON-encodes query payload to be executed. More...
lcb_STATUS	lcb_cmdquery_statement (lcb_CMDQUERY *cmd, const char *statement, size_t statement_len)
	Sets the actual statement to be executed. More...
lcb_STATUS	lcb_cmdquery_scope_name (lcb_CMDQUERY *cmd, const char *scope, size_t scope_len)
	Associate scope name with the query. More...
lcb_STATUS	lcb_cmdquery_scope_qualifier (lcb_CMDQUERY *cmd, const char *qualifier, size_t qualifier_len)
lcb_STATUS	lcb_cmdquery_named_param (lcb_CMDQUERY *cmd, const char *name, size_t name_len, const char *value, size_t value_len)
	Sets a named argument for the query. More...
lcb_STATUS	lcb_cmdquery_positional_params (lcb_CMDQUERY *cmd, const char *value, size_t value_len)
	Sets the positional arguments for the query. More...
lcb_STATUS	lcb_cmdquery_positional_param (lcb_CMDQUERY *cmd, const char *value, size_t value_len)
lcb_STATUS	lcb_cmdquery_adhoc (lcb_CMDQUERY *cmd, int adhoc)
lcb_STATUS	lcb_cmdquery_client_context_id (lcb_CMDQUERY *cmd, const char *value, size_t value_len)
lcb_STATUS	lcb_cmdquery_pretty (lcb_CMDQUERY *cmd, int pretty)
lcb_STATUS	lcb_cmdquery_readonly (lcb_CMDQUERY *cmd, int readonly)
	Marks query as read-only. More...
lcb_STATUS	lcb_cmdquery_metrics (lcb_CMDQUERY *cmd, int metrics)
lcb_STATUS	lcb_cmdquery_scan_cap (lcb_CMDQUERY *cmd, int value)
	Sets maximum buffered channel size between the indexer client and the query service for index scans. More...
lcb_STATUS	lcb_cmdquery_scan_wait (lcb_CMDQUERY *cmd, uint32_t us)
lcb_STATUS	lcb_cmdquery_flex_index (lcb_CMDQUERY *cmd, int value)
lcb_STATUS	lcb_cmdquery_profile (lcb_CMDQUERY *cmd, lcb_QUERY_PROFILE mode)
lcb_STATUS	lcb_cmdquery_pipeline_cap (lcb_CMDQUERY *cmd, int value)
	Sets maximum number of items each execution operator can buffer between various operators. More...
lcb_STATUS	lcb_cmdquery_pipeline_batch (lcb_CMDQUERY *cmd, int value)
	Sets the number of items execution operators can batch for fetch from the KV. More...
lcb_STATUS	lcb_cmdquery_max_parallelism (lcb_CMDQUERY *cmd, int value)
lcb_STATUS	lcb_cmdquery_consistency (lcb_CMDQUERY *cmd, lcb_QUERY_CONSISTENCY mode)
	Sets the consistency mode for the request. More...
lcb_STATUS	lcb_cmdquery_consistency_token_for_keyspace (lcb_CMDQUERY *cmd, const char *keyspace, size_t keyspace_len, const lcb_MUTATION_TOKEN *token)
	Indicate that the query should synchronize its internal snapshot to reflect the changes indicated by the given mutation token (ss). More...
lcb_STATUS	lcb_cmdquery_consistency_tokens (lcb_CMDQUERY *cmd, lcb_INSTANCE *instance)
lcb_STATUS	lcb_cmdquery_option (lcb_CMDQUERY *cmd, const char *name, size_t name_len, const char *value, size_t value_len)
	Set a query option. More...
lcb_STATUS	lcb_cmdquery_handle (lcb_CMDQUERY *cmd, lcb_QUERY_HANDLE **handle)
lcb_STATUS	lcb_cmdquery_timeout (lcb_CMDQUERY *cmd, uint32_t timeout)
lcb_STATUS	lcb_cmdquery_preserve_expiry (lcb_CMDQUERY *cmd, int preserve_expiry)
lcb_STATUS	lcb_cmdquery_on_behalf_of (lcb_CMDQUERY *cmd, const char *data, size_t data_len)
lcb_STATUS	lcb_query (lcb_INSTANCE *instance, void *cookie, const lcb_CMDQUERY *cmd)
	Execute a N1QL query. More...
lcb_STATUS	lcb_query_cancel (lcb_INSTANCE *instance, lcb_QUERY_HANDLE *handle)
	Cancels an in-progress request. More...

Typedefs
typedef struct lcb_RESPQUERY_	lcb_RESPQUERY
	Opaque query response structure.
typedef struct lcb_CMDQUERY_	lcb_CMDQUERY
	Opaque query command structure.
typedef struct lcb_QUERY_HANDLE_	lcb_QUERY_HANDLE
	Pointer for request instance.
typedef void(*	lcb_QUERY_CALLBACK) (lcb_INSTANCE *, int, const lcb_RESPQUERY *)
	Callback to be invoked for each row. More...

Enumerations
enum	lcb_QUERY_CONSISTENCY
enum	lcb_QUERY_PROFILE

Function Documentation

lcb_cmdquery_create()

lcb_STATUS lcb_cmdquery_create

(

lcb_CMDQUERY **

cmd

)

Create a new lcb_CMDQUERY object.

The returned object is an opaque pointer which may be used to set various properties on a N1QL query.

Parameters

cmd	pointer to an lcb_CMDQUERY* which will be allocated

Returns

LCB_SUCCESS when successful, otherwise an error code

Examples

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

lcb_cmdquery_destroy()

lcb_STATUS lcb_cmdquery_destroy

(

lcb_CMDQUERY *

cmd

)

Free the command structure.

This should be done when it is no longer needed

Parameters

cmd	the command to destroy

Examples

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

lcb_cmdquery_reset()

lcb_STATUS lcb_cmdquery_reset

(

lcb_CMDQUERY *

cmd

)

Reset the lcb_CMDQUERY structure so that it may be reused for a subsequent query.

Results in less memory allocator overhead that creating a cmd each time you need one.

Parameters

cmd	the command

Returns

LCB_SUCCESS when successful, otherwise an error code.

lcb_cmdquery_encoded_payload()

lcb_STATUS lcb_cmdquery_encoded_payload	(	lcb_CMDQUERY *	cmd,
		const char **	payload,
		size_t *	payload_len
	)

Get the JSON-encoded query payload.

Helpful for re-issuing a query using lcb_cmdquery_payload.

Parameters

cmd	the command
payload	pointer to a string which will contain the payload
payload_len	length of the payload string.

lcb_cmdquery_payload()

lcb_STATUS lcb_cmdquery_payload	(	lcb_CMDQUERY *	cmd,
		const char *	query,
		size_t	query_len
	)

Sets the JSON-encodes query payload to be executed.

Parameters

cmd	the command
query	the query payload, as a JSON-encoded string.
query_len	length of the query payload string.

lcb_cmdquery_statement()

lcb_STATUS lcb_cmdquery_statement	(	lcb_CMDQUERY *	cmd,
		const char *	statement,
		size_t	statement_len
	)

Sets the actual statement to be executed.

Parameters

cmd	the command
statement	the query string. Note it can contain placeholders for positional or named parameters.
statement_len	length of the statement string.

Examples

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

lcb_cmdquery_scope_name()

lcb_STATUS lcb_cmdquery_scope_name	(	lcb_CMDQUERY *	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_cmdquery_scope_qualifier()

lcb_STATUS lcb_cmdquery_scope_qualifier	(	lcb_CMDQUERY *	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 ${bucket_name}.${scope_name} or default:${bucket_name}.${scope_name}.

Parameters

cmd	the command
qualifier	the string containing qualifier
qualifier_len	length of the qualifier

lcb_cmdquery_named_param()

lcb_STATUS lcb_cmdquery_named_param	(	lcb_CMDQUERY *	cmd,
		const char *	name,
		size_t	name_len,
		const char *	value,
		size_t	value_len
	)

Sets a named argument for the query.

Parameters

cmd	the command
name	The argument name (e.g. $age)
name_len	length of the name
value	The argument value (e.g. 42)
value_len	length of the value

lcb_cmdquery_positional_params()

lcb_STATUS lcb_cmdquery_positional_params	(	lcb_CMDQUERY *	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.

Examples

example/minimal/query.c.

lcb_cmdquery_positional_param()

lcb_STATUS lcb_cmdquery_positional_param	(	lcb_CMDQUERY *	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_cmdquery_positional_params instead.

Parameters

cmd	the command
value	the argument value in JSON encoding
value_len	the length of the encoded value

lcb_cmdquery_readonly()

lcb_STATUS lcb_cmdquery_readonly	(	lcb_CMDQUERY *	cmd,
		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

cmd	the command
readonly	if non-zero, the query will be read-only

lcb_cmdquery_scan_cap()

lcb_STATUS lcb_cmdquery_scan_cap	(	lcb_CMDQUERY *	cmd,
		int	value
	)

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

cmd	the command
value	channel size

lcb_cmdquery_flex_index()

lcb_STATUS lcb_cmdquery_flex_index	(	lcb_CMDQUERY *	cmd,
		int	value
	)

Stability

Uncommitted:

Tells the query engine to use a flex index (utilizing the search service).

Parameters

cmd	the command
value	non-zero if a flex index should be used, zero is the default

lcb_cmdquery_pipeline_cap()

lcb_STATUS lcb_cmdquery_pipeline_cap	(	lcb_CMDQUERY *	cmd,
		int	value
	)

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

Parameters

cmd	the command
value	number of items

lcb_cmdquery_pipeline_batch()

lcb_STATUS lcb_cmdquery_pipeline_batch	(	lcb_CMDQUERY *	cmd,
		int	value
	)

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

Parameters

cmd	the command
value	number of items

lcb_cmdquery_consistency()

lcb_STATUS lcb_cmdquery_consistency	(	lcb_CMDQUERY *	cmd,
		lcb_QUERY_CONSISTENCY	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

cmd	the command
mode	one of the lcb_QUERY_CONSISTENCY values

lcb_cmdquery_consistency_token_for_keyspace()

lcb_STATUS lcb_cmdquery_consistency_token_for_keyspace	(	lcb_CMDQUERY *	cmd,
		const char *	keyspace,
		size_t	keyspace_len,
		const lcb_MUTATION_TOKEN *	token
	)

Indicate that the query should synchronize its internal snapshot to reflect the changes indicated by the given mutation token (ss).

Parameters

cmd	the command
keyspace	the keyspace (or bucket name) which this mutation token pertains to
keyspace_len	length of the keyspace string
token	the mutation token

lcb_cmdquery_option()

lcb_STATUS lcb_cmdquery_option	(	lcb_CMDQUERY *	cmd,
		const char *	name,
		size_t	name_len,
		const char *	value,
		size_t	value_len
	)

Set a query option.

Parameters

cmd	the command
name	the name of the option
name_len	length of the name
value	the value of the option
value_len	length of the value

Examples

example/minimal/query.c.

lcb_cmdquery_preserve_expiry()

lcb_STATUS lcb_cmdquery_preserve_expiry	(	lcb_CMDQUERY *	cmd,
		int	preserve_expiry
	)

Stability

Uncommitted:

Indicates that the query engine to preserve expiration values set on any documents modified by this query.

Parameters

cmd	the command
preserve_expiry	if non-zero, the query will preserve expiration values

lcb_cmdquery_on_behalf_of()

lcb_STATUS lcb_cmdquery_on_behalf_of	(	lcb_CMDQUERY *	cmd,
		const char *	data,
		size_t	data_len
	)

Stability

Internal:

Internal: This should never be used and is not supported.

lcb_query()

lcb_STATUS lcb_query	(	lcb_INSTANCE *	instance,
		void *	cookie,
		const lcb_CMDQUERY *	cmd
	)

Execute a N1QL query.

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

Parameters

instance	The instance
cookie	Pointer to application data
cmd	the command

Returns

LCB_SUCCESS if successfully scheduled, or a failure code.

Examples

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

lcb_query_cancel()

lcb_STATUS lcb_query_cancel	(	lcb_INSTANCE *	instance,
		lcb_QUERY_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 is obtained during the request as an 'out' parameter (see lcb_CMDN1QL::handle)

To obtain the handle parameter, do something like this:

lcb_QUERYHANDLE* handle;
lcb_CMDQUERY* cmd;
lcb_cmdquery_create(&cmd);
// (Initialize command...)
lcb_cmdquery_handle(cmd, &handle);
lcb_query(instance, cookie, &cmd);

.

If the lcb_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. You can also get the handle from the response object using lcb_respquery_handle

lcb_query_cancel(instance, handle);

Typedef Documentation

lcb_QUERY_CALLBACK

typedef void(* lcb_QUERY_CALLBACK) (lcb_INSTANCE *, int, const lcb_RESPQUERY *)

Callback to be invoked for each row.

Parameters

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

Enumeration Type Documentation

lcb_QUERY_CONSISTENCY

enum lcb_QUERY_CONSISTENCY

Enumerator
LCB_QUERY_CONSISTENCY_NONE	No consistency constraints.
LCB_QUERY_CONSISTENCY_RYOW	This is implicitly set by lcb_cmdquery_consistency_token_for_keyspace. This will ensure that mutations up to the vector indicated by the mutation token passed to lcb_cmdquery_consistency_token_for_keyspace are used.
LCB_QUERY_CONSISTENCY_REQUEST	Refresh the snapshot for each request.
LCB_QUERY_CONSISTENCY_STATEMENT	Refresh the snapshot for each statement.