CBLQuery.h File Reference

#include "CBLBase.h"
#include "fleece/Fleece.h"

Go to the source code of this file.

Data Structures
struct	CBLValueIndexConfiguration
	Value Index Configuration. More...
struct	CBLFullTextIndexConfiguration
	Full-Text Index Configuration. More...

Enumerations
enum	CBLQueryLanguage : uint32_t { kCBLJSONLanguage , kCBLN1QLLanguage }
	Query languages. More...

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

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