Queries

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

Data Structures
struct	CBLValueIndexConfiguration
	Value Index Configuration. More...
struct	CBLFullTextIndexConfiguration
	Full-Text Index Configuration. 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...

Enumerations
enum	CBLQueryLanguage : uint32_t { kCBLJSONLanguage , kCBLN1QLLanguage }
	Query languages. 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	CBLResultSet_ValueAtIndex (const CBLResultSet *, unsigned index)
	Returns the value of a column of the current result, given its (zero-based) numeric index. More...
FLValue	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)

Database Indexes
Indexes are used to speed up queries by allowing fast – O(log n) – lookup of documents that have specific values or ranges of values. The values may be properties, or expressions based on properties. An index will speed up queries that use the expression it indexes, but it takes up space in the database file, and it slows down document saves slightly because it needs to be kept up to date when documents change. Tuning a database with indexes can be a tricky task. Fortunately, a lot has been written about it in the relational-database (SQL) realm, and much of that advice holds for Couchbase Lite. You may find SQLite's documentation particularly helpful since Couchbase Lite's querying is based on SQLite. Two types of indexes are currently supported: Value indexes speed up queries by making it possible to look up property (or expression) values without scanning every document. They're just like regular indexes in SQL or N1QL. Multiple expressions are supported; the first is the primary key, second is secondary. Expressions must evaluate to scalar types (boolean, number, string). Full-Text Search (FTS) indexes enable fast search of natural-language words or phrases by using the MATCH operator in a query. A FTS index is required for full-text search: a query with a MATCH operator will fail to compile unless there is already a FTS index for the property/expression being matched. Only a single expression is currently allowed, and it must evaluate to a string.
bool	CBLDatabase_CreateValueIndex (CBLDatabase *db, FLString name, CBLValueIndexConfiguration config, CBLError *_cbl_nullable outError)
	Creates a value index. More...
bool	CBLDatabase_CreateFullTextIndex (CBLDatabase *db, FLString name, CBLFullTextIndexConfiguration config, CBLError *_cbl_nullable outError)
	Creates a full-text index. More...
bool	CBLDatabase_DeleteIndex (CBLDatabase *db, FLString name, CBLError *_cbl_nullable outError)
	Deletes an index given its name. More...
_cbl_warn_unused FLArray	CBLDatabase_GetIndexNames (CBLDatabase *db)
	Returns the names of the indexes on this database, as a Fleece array of strings. More...

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++".

Queries may be given either in N1QL syntax, or in JSON using a schema that 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.

Enumeration Type Documentation

CBLQueryLanguage

enum CBLQueryLanguage : uint32_t

Query languages.

Enumerator
kCBLJSONLanguage	JSON query schema
kCBLN1QLLanguage	N1QL syntax

Function Documentation

CBLDatabase_CreateFullTextIndex()

bool CBLDatabase_CreateFullTextIndex	(	CBLDatabase *	db,
		FLString	name,
		CBLFullTextIndexConfiguration	config,
		CBLError *_cbl_nullable	outError
	)

Creates a full-text index.

Indexes are persistent. If an identical index with that name already exists, nothing happens (and no error is returned.) If a non-identical index with that name already exists, it is deleted and re-created.

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.

CBLDatabase_CreateValueIndex()

bool CBLDatabase_CreateValueIndex	(	CBLDatabase *	db,
		FLString	name,
		CBLValueIndexConfiguration	config,
		CBLError *_cbl_nullable	outError
	)

Creates a value index.

Indexes are persistent. If an identical index with that name already exists, nothing happens (and no error is returned.) If a non-identical index with that name already exists, it is deleted and re-created.

CBLDatabase_DeleteIndex()

bool CBLDatabase_DeleteIndex	(	CBLDatabase *	db,
		FLString	name,
		CBLError *_cbl_nullable	outError
	)

Deletes an index given its name.

CBLDatabase_GetIndexNames()

_cbl_warn_unused FLArray CBLDatabase_GetIndexNames

(

CBLDatabase *

db

)

Returns the names of the indexes on this database, as a Fleece array of strings.

Note

You are responsible for releasing the returned Fleece array.

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