Query

A CBLQuery represents a compiled database query. More...

Typedefs
typedef struct CBLQuery	CBLQuery
	A compiled database query. More...
typedef struct CBLResultSet	CBLResultSet
	An iterator over the rows resulting from running a query. More...

Change listener
Adding a change listener to a query turns it into a "live query". When changes are made to documents, the query will periodically re-run and compare its results with the prior results; if the new results are different, the listener callback will be called. Note The result set passed to the listener is the entire new result set, not just the rows that changed.
typedef void(*	CBLQueryChangeListener) (void *_cbl_nullable context, CBLQuery *query, CBLListenerToken *token)
	A callback to be invoked after the query's results have changed. More...
_cbl_warn_unused CBLListenerToken *	CBLQuery_AddChangeListener (CBLQuery *query, CBLQueryChangeListener listener, void *_cbl_nullable context)
	Registers a change listener callback with a query, turning it into a "live query" until the listener is removed (via CBLListener_Remove). More...
_cbl_warn_unused CBLResultSet *_cbl_nullable	CBLQuery_CopyCurrentResults (const CBLQuery *query, CBLListenerToken *listener, CBLError *_cbl_nullable outError)
	Returns the query's entire current result set, after it's been announced via a call to the listener's callback. More...

Query objects
_cbl_warn_unused CBLQuery *_cbl_nullable	CBLDatabase_CreateQuery (const CBLDatabase *db, CBLQueryLanguage language, FLString queryString, int *_cbl_nullable outErrorPos, CBLError *_cbl_nullable outError)
	Creates a new query by compiling the input string. More...
static const CBLQuery *	CBLQuery_Retain (const CBLQuery *t)
static void	CBLQuery_Release (const CBLQuery *t)
void	CBLQuery_SetParameters (CBLQuery *query, FLDict parameters)
	Assigns values to the query's parameters. More...
FLDict _cbl_nullable	CBLQuery_Parameters (const CBLQuery *query)
	Returns the query's current parameter bindings, if any. More...
_cbl_warn_unused CBLResultSet *_cbl_nullable	CBLQuery_Execute (CBLQuery *, CBLError *_cbl_nullable outError)
	Runs the query, returning the results. More...
_cbl_warn_unused FLSliceResult	CBLQuery_Explain (const CBLQuery *)
	Returns information about the query, including the translated SQLite form, and the search strategy. More...
unsigned	CBLQuery_ColumnCount (const CBLQuery *)
	Returns the number of columns in each result. More...
FLSlice	CBLQuery_ColumnName (const CBLQuery *, unsigned columnIndex)
	Returns the name of a column in the result. More...

Result sets
A CBLResultSet is an iterator over the results returned by a query. It exposes one result at a time – as a collection of values indexed either by position or by name – and can be stepped from one result to the next. It's important to note that the initial position of the iterator is before the first result, so CBLResultSet_Next must be called first. Example: CBLResultSet *rs = CBLQuery_Execute(query, &error); assert(rs); while (CBLResultSet_Next(rs) { FLValue aValue = CBLResultSet_ValueAtIndex(rs, 0); ... } CBLResultSet_Release(rs);
_cbl_warn_unused bool	CBLResultSet_Next (CBLResultSet *)
	Moves the result-set iterator to the next result. More...
FLValue _cbl_nullable	CBLResultSet_ValueAtIndex (const CBLResultSet *, unsigned index)
	Returns the value of a column of the current result, given its (zero-based) numeric index. More...
FLValue _cbl_nullable	CBLResultSet_ValueForKey (const CBLResultSet *, FLString key)
	Returns the value of a column of the current result, given its name. More...
FLArray	CBLResultSet_ResultArray (const CBLResultSet *)
	Returns the current result as an array of column values. More...
FLDict	CBLResultSet_ResultDict (const CBLResultSet *)
	Returns the current result as a dictionary mapping column names to values. More...
CBLQuery *	CBLResultSet_GetQuery (const CBLResultSet *rs)
	Returns the Query that created this ResultSet. More...
static const CBLResultSet *	CBLResultSet_Retain (const CBLResultSet *t)
static void	CBLResultSet_Release (const CBLResultSet *t)

Detailed Description

A CBLQuery represents a compiled database query.

The query language is a large subset of the N1QL language from Couchbase Server, which you can think of as "SQL for JSON" or "SQL++".

Supported Query languages: N1QL

JSON

JSON language resembles a parse tree of N1QL. The JSON syntax is harder for humans, but much more amenable to machine generation, if you need to create queries programmatically or translate them from some other form.

Typedef Documentation

CBLQuery

typedef struct CBLQuery CBLQuery

A compiled database query.

CBLQueryChangeListener

typedef void(* CBLQueryChangeListener) (void *_cbl_nullable context, CBLQuery *query, CBLListenerToken *token)

A callback to be invoked after the query's results have changed.

The actual result set can be obtained by calling CBLQuery_CopyCurrentResults, either during the callback or at any time thereafter.

Warning

By default, this listener may be called on arbitrary threads. If your code isn't prepared for that, you may want to use CBLDatabase_BufferNotifications so that listeners will be called in a safe context.

Parameters

context	The same context value that you passed when adding the listener.
query	The query that triggered the listener.
token	The token for obtaining the query results by calling CBLQuery_CopyCurrentResults.

CBLResultSet

typedef struct CBLResultSet CBLResultSet

An iterator over the rows resulting from running a query.

Function Documentation

CBLDatabase_CreateQuery()

_cbl_warn_unused CBLQuery *_cbl_nullable CBLDatabase_CreateQuery	(	const CBLDatabase *	db,
		CBLQueryLanguage	language,
		FLString	queryString,
		int *_cbl_nullable	outErrorPos,
		CBLError *_cbl_nullable	outError
	)

Creates a new query by compiling the input string.

This is fast, but not instantaneous. If you need to run the same query many times, keep the CBLQuery around instead of compiling it each time. If you need to run related queries with only some values different, create one query with placeholder parameter(s), and substitute the desired value(s) with CBLQuery_SetParameters each time you run the query.

Note

You must release the CBLQuery when you're finished with it.

Parameters

db	The database to query.
language	The query language, JSON or N1QL.
queryString	The query string.
outErrorPos	If non-NULL, then on a parse error the approximate byte offset in the input expression will be stored here (or -1 if not known/applicable.)
outError	On failure, the error will be written here.

Returns

The new query object.

CBLQuery_AddChangeListener()

_cbl_warn_unused CBLListenerToken * CBLQuery_AddChangeListener	(	CBLQuery *	query,
		CBLQueryChangeListener	listener,
		void *_cbl_nullable	context
	)

Registers a change listener callback with a query, turning it into a "live query" until the listener is removed (via CBLListener_Remove).

When the first change listener is added, the query will run (in the background) and notify the listener(s) of the results when ready. After that, it will run in the background after the database changes, and only notify the listeners when the result set changes.

Parameters

query	The query to observe.
listener	The callback to be invoked.
context	An opaque value that will be passed to the callback.

Returns

A token to be passed to CBLListener_Remove when it's time to remove the listener.

CBLQuery_ColumnCount()

unsigned CBLQuery_ColumnCount

(

const CBLQuery *

)

Returns the number of columns in each result.

CBLQuery_ColumnName()

FLSlice CBLQuery_ColumnName	(	const CBLQuery *	,
		unsigned	columnIndex
	)

Returns the name of a column in the result.

The column name is based on its expression in the SELECT... or WHAT: section of the query. A column that returns a property or property path will be named after that property. A column that returns an expression will have an automatically-generated name like $1. To give a column a custom name, use the AS syntax in the query. Every column is guaranteed to have a unique name.

CBLQuery_CopyCurrentResults()

_cbl_warn_unused CBLResultSet *_cbl_nullable CBLQuery_CopyCurrentResults	(	const CBLQuery *	query,
		CBLListenerToken *	listener,
		CBLError *_cbl_nullable	outError
	)

Returns the query's entire current result set, after it's been announced via a call to the listener's callback.

Note

You must release the result set when you're finished with it.

Parameters

query	The query being listened to.
listener	The query listener that was notified.
outError	If the query failed to run, the error will be stored here.

Returns

A new object containing the query's current results, or NULL if the query failed to run.

CBLQuery_Execute()

_cbl_warn_unused CBLResultSet *_cbl_nullable CBLQuery_Execute	(	CBLQuery *	,
		CBLError *_cbl_nullable	outError
	)

Runs the query, returning the results.

To obtain the results you'll typically call CBLResultSet_Next in a while loop, examining the values in the CBLResultSet each time around.

Note

You must release the result set when you're finished with it.

CBLQuery_Explain()

_cbl_warn_unused FLSliceResult CBLQuery_Explain

(

const CBLQuery *

)

Returns information about the query, including the translated SQLite form, and the search strategy.

You can use this to help optimize the query: the word SCAN in the strategy indicates a linear scan of the entire database, which should be avoided by adding an index. The strategy will also show which index(es), if any, are used.

Note

You are responsible for releasing the result by calling FLSliceResult_Release.

CBLQuery_Parameters()

FLDict _cbl_nullable CBLQuery_Parameters

(

const CBLQuery *

query

)

Returns the query's current parameter bindings, if any.

CBLQuery_Release()

static void CBLQuery_Release ( const CBLQuery *  t )

inlinestatic

CBLQuery_Retain()

static const CBLQuery * CBLQuery_Retain ( const CBLQuery *  t )

inlinestatic

CBLQuery_SetParameters()

void CBLQuery_SetParameters	(	CBLQuery *	query,
		FLDict	parameters
	)

Assigns values to the query's parameters.

These values will be substited for those parameters whenever the query is executed, until they are next assigned.

Parameters are specified in the query source as e.g. $PARAM (N1QL) or ["$PARAM"] (JSON). In this example, the parameters dictionary to this call should have a key PARAM that maps to the value of the parameter.

Parameters

query	The query.
parameters	The parameters in the form of a Fleece dictionary whose keys are the parameter names. (It's easiest to construct this by using the mutable API, i.e. calling FLMutableDict_New and adding keys/values.)

CBLResultSet_GetQuery()

CBLQuery * CBLResultSet_GetQuery

(

const CBLResultSet *

rs

)

Returns the Query that created this ResultSet.

CBLResultSet_Next()

_cbl_warn_unused bool CBLResultSet_Next

(

CBLResultSet *

)

Moves the result-set iterator to the next result.

Returns false if there are no more results.

Warning

This must be called before examining the first result.

CBLResultSet_Release()

static void CBLResultSet_Release ( const CBLResultSet *  t )

inlinestatic

CBLResultSet_ResultArray()

FLArray CBLResultSet_ResultArray

(

const CBLResultSet *

)

Returns the current result as an array of column values.

Warning

The array reference is only valid until the result-set is advanced or released. If you want to keep it for longer, call FLArray_Retain (and release it when done.)

CBLResultSet_ResultDict()

FLDict CBLResultSet_ResultDict

(

const CBLResultSet *

)

Returns the current result as a dictionary mapping column names to values.

Warning

The dict reference is only valid until the result-set is advanced or released. If you want to keep it for longer, call FLDict_Retain (and release it when done.)

CBLResultSet_Retain()

static const CBLResultSet * CBLResultSet_Retain ( const CBLResultSet *  t )

inlinestatic

CBLResultSet_ValueAtIndex()

FLValue _cbl_nullable CBLResultSet_ValueAtIndex	(	const CBLResultSet *	,
		unsigned	index
	)

Returns the value of a column of the current result, given its (zero-based) numeric index.

This may return a NULL pointer, indicating MISSING, if the value doesn't exist, e.g. if the column is a property that doesn't exist in the document.

CBLResultSet_ValueForKey()

FLValue _cbl_nullable CBLResultSet_ValueForKey	(	const CBLResultSet *	,
		FLString	key
	)

Returns the value of a column of the current result, given its name.

This may return a NULL pointer, indicating MISSING, if the value doesn't exist, e.g. if the column is a property that doesn't exist in the document. (Or, of course, if the key is not a column name in this query.)

Note

See CBLQuery_ColumnName for a discussion of column names.