CBLQuery.h File Reference

#include "CBLBase.h"
#include "CBLQueryTypes.h"

Go to the source code of this file.

Functions
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.
CBLINLINE const CBLQuery *	CBLQuery_Retain (const CBLQuery *_cbl_nullable t)
CBLINLINE void	CBLQuery_Release (const CBLQuery *_cbl_nullable t)
void	CBLQuery_SetParameters (CBLQuery *query, FLDict parameters)
	Assigns values to the query's parameters.
FLDict _cbl_nullable	CBLQuery_Parameters (const CBLQuery *query)
	Returns the query's current parameter bindings, if any.
_cbl_warn_unused CBLResultSet *_cbl_nullable	CBLQuery_Execute (CBLQuery *, CBLError *_cbl_nullable outError)
	Runs the query, returning the results.
_cbl_warn_unused FLSliceResult	CBLQuery_Explain (const CBLQuery *)
	Returns information about the query, including the translated SQLite form, and the search strategy.
unsigned	CBLQuery_ColumnCount (const CBLQuery *)
	Returns the number of columns in each result.
FLSlice	CBLQuery_ColumnName (const CBLQuery *, unsigned columnIndex)
	Returns the name of a column in the result.
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.
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.
FLValue _cbl_nullable	CBLResultSet_ValueForKey (const CBLResultSet *, FLString key)
	Returns the value of a column of the current result, given its name.
FLArray	CBLResultSet_ResultArray (const CBLResultSet *)
	Returns the current result as an array of column values.
FLDict	CBLResultSet_ResultDict (const CBLResultSet *)
	Returns the current result as a dictionary mapping column names to values.
CBLQuery *	CBLResultSet_GetQuery (const CBLResultSet *rs)
	Returns the Query that created this ResultSet.
CBLINLINE const CBLResultSet *	CBLResultSet_Retain (const CBLResultSet *_cbl_nullable t)
CBLINLINE void	CBLResultSet_Release (const CBLResultSet *_cbl_nullable t)

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.
_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).
_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.