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.

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

lcb_query_cancel

lcb_STATUS lcb_query_cancel(lcb_INSTANCE *instance, lcb_QUERY_HANDLE *handle)

Cancels an in-progress request.

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.