Couchbase C Client  3.2.2
Asynchronous C Client for Couchbase
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_callback(cmd, row_callback)
lcb_n1ql_query(instance, &cookie, cmd);

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)
 
More...
 
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)
 
More...
 
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_on_behalf_of (lcb_CMDQUERY *cmd, const char *data, size_t data_len)
 
More...
 
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
cmdpointer 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
cmdthe 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
cmdthe 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
cmdthe command
payloadpointer to a string which will contain the payload
payload_lenlength 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
cmdthe command
querythe query payload, as a JSON-encoded string.
query_lenlength 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
cmdthe command
statementthe query string. Note it can contain placeholders for positional or named parameters.
statement_lenlength 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
cmdthe command
scopethe name of the scope
scope_lenlength 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
cmdthe command
qualifierthe string containing qualifier
qualifier_lenlength 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
cmdthe command
nameThe argument name (e.g. $age)
name_lenlength of the name
valueThe argument value (e.g. 42)
value_lenlength 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
cmdthe command
valuethe arguments encoded as JSON array
value_lenthe 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
cmdthe command
valuethe argument value in JSON encoding
value_lenthe 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
cmdthe command
readonlyif 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
cmdthe command
valuechannel 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
cmdthe command
valuenon-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
cmdthe command
valuenumber 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
cmdthe command
valuenumber 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
cmdthe command
modeone 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
cmdthe command
keyspacethe keyspace (or bucket name) which this mutation token pertains to
keyspace_lenlength of the keyspace string
tokenthe 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
cmdthe command
namethe name of the option
name_lenlength of the name
valuethe value of the option
value_lenlength of the value
Examples:
example/minimal/query.c.

◆ 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
instanceThe instance
cookiePointer to application data
cmdthe 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
instancethe instance
handlethe 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;
// (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
Theinstance
Callbacktype. This is set to LCB_CALLBACK_QUERY
Theresponse.

Enumeration Type Documentation

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