Couchbase Lite C
Couchbase Lite C API
Data Structures | Typedefs | Enumerations
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 CBLListenerTokenCBLQuery_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 CBLQueryCBLQuery_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) {
...
}
_cbl_warn_unused CBLResultSet *_cbl_nullable CBLQuery_Execute(CBLQuery *, CBLError *_cbl_nullable outError)
Runs the query, returning the results.
_cbl_warn_unused bool CBLResultSet_Next(CBLResultSet *)
Moves the result-set iterator to the next result.
struct CBLResultSet CBLResultSet
An iterator over the rows resulting from running a query.
Definition: CBLBase.h:206
static void CBLResultSet_Release(const CBLResultSet *t)
Definition: CBLQuery.h:179
FLValue CBLResultSet_ValueAtIndex(const CBLResultSet *, unsigned index)
Returns the value of a column of the current result, given its (zero-based) numeric index.
const struct _FLValue * FLValue
A reference to a value of any type.
Definition: Fleece.h:49
_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...
 
CBLQueryCBLResultSet_GetQuery (const CBLResultSet *rs)
 Returns the Query that created this ResultSet. More...
 
static const CBLResultSetCBLResultSet_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
contextThe same context value that you passed when adding the listener.
queryThe query that triggered the listener.
tokenThe 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
dbThe database to query.
languageThe query language, JSON or N1QL.
queryStringThe query string.
outErrorPosIf 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.)
outErrorOn 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
queryThe query to observe.
listenerThe callback to be invoked.
contextAn 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
queryThe query being listened to.
listenerThe query listener that was notified.
outErrorIf 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
queryThe query.
parametersThe 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.