N1QL Queries using the C (libcouchbase) SDK with Couchbase Server

This page describes how to issue N1QL queries using the C SDK.
N1QL queries are performed using a row-based API which invokes a callback repeatedly, once for each query row.
The C SDK uses a special JSON parser to invoke row callbacks as they are read from the network - avoiding waiting for the entire response to be received.

To execute a N1QL query, first declare your handler.
The handler is called once for each JSON-encoded row, and then one last time with the LCB_RESP_F_FINAL bit set in the rflags response member, where any result metadata (including errors) is returned.
To actually make sense of the row’s content, use a JSON decoder on the row and nrow buffer/length fields.

To issue the actual query, populate an lcb_CMDN1QL structure with appropriate parameters.
Some of the internals of this structure may be populated using the lcb_N1QLPARAMS object.
The lcb_N1QLPARAMS object is provided as a higher-level means by which to construct N1QL queries and supports N1QL features such as query placeholders and prepared statements.
A named or positional parameter is a placeholder for a value in the WHERE, LIMIT or OFFSET clause of a query.
For example, to issue a query with a placeholder:

You can also utilize the encoded query directly (without using lcb_N1QLPARAMS).
This involves using a pre-encoded query per the N1QL REST API.
This example issues the same query as above, bypassing the parameters object, and encoding the query manually.

Versions prior to 2.5.3 require the content_type field to be set to application/json.
Since version 2.5.3, all queries must be in JSON, and the content_type field is ignored.

Scan Consistency

Setting a staleness parameter for queries, with scan_consistency, enables a tradeoff between latency and (eventual) consistency.
A N1QL query using the default Not Bounded Scan Consistency will not wait for any indexes to finish updating before running the query and returning results, meaning that results are returned quickly, but the query will not return any documents yet to be indexed.

With Scan Consistency set to RequestPlus, all document changes and index updates are processed before the query is run.
Select this when consistency is always more important than performance.
For a middle ground, AtPlus is a "read your own write" (RYOW) option, which means it just waits for the new documents that you specify to be indexed, rather than an entire index of multiple documents.
See the examples for how to use AtPlus for the best performance balance for many circumstances.

Prepared Statements

Since version 2.5.3, applications may optimize frequently issued statements by having the client internally prepare them.
To use prepared statements, simply set the LCB_CMDN1QL_F_PREPCACHE bit in the cmdflags field