Querying the Database

Data Structures
struct	C4QueryOptions
	Options for running queries. More...
struct	C4FullTextMatch
	Info about a match of a full-text query term. More...
struct	C4QueryEnumerator
	A query result enumerator. More...

Enumerations
enum	C4QueryLanguage : uint32_t { kC4JSONQuery , kC4N1QLQuery }

Functions
NODISCARD CBL_CORE_API C4Query *	c4query_new2 (C4Database *database, C4QueryLanguage language, C4String expression, int *outErrorPos, C4Error *error)
	Compiles a query from an expression given as JSON.
CBL_CORE_API C4StringResult	c4query_explain (C4Query *)
	Returns a string describing the implementation of the compiled query.
CBL_CORE_API unsigned	c4query_columnCount (C4Query *)
	Returns the number of columns (the values specified in the WHAT clause) in each row.
CBL_CORE_API FLString	c4query_columnTitle (C4Query *, unsigned column)
	Returns a suggested title for a column, which may be: An alias specified in an 'AS' modifier in the column definition A property name A function/operator that computes the column value, e.g.
CBL_CORE_API void	c4query_setParameters (C4Query *query, C4String encodedParameters)
	Sets the parameter values to use when running the query, if no parameters are given to c4query_run.
NODISCARD CBL_CORE_API C4QueryEnumerator *	c4query_run (C4Query *query, C4String encodedParameters, C4Error *outError)
	Runs a compiled query.
CBL_CORE_API C4StringResult	c4query_fullTextMatched (C4Query *query, const C4FullTextMatch *term, C4Error *outError)
	Given a C4FullTextMatch from the enumerator, returns the entire text of the property that was matched.
NODISCARD CBL_CORE_API bool	c4queryenum_next (C4QueryEnumerator *e, C4Error *outError)
	Advances a query enumerator to the next row, populating its fields.
NODISCARD CBL_CORE_API int64_t	c4queryenum_getRowCount (C4QueryEnumerator *e, C4Error *outError)
	Returns the total number of rows in the query, if known.
NODISCARD CBL_CORE_API bool	c4queryenum_seek (C4QueryEnumerator *e, int64_t rowIndex, C4Error *outError)
	Jumps to a specific row.
static NODISCARD bool	c4queryenum_restart (C4QueryEnumerator *e, C4Error *outError)
	Restarts the enumeration, as though it had just been created: the next call to c4queryenum_next will read the first row, and so on from there.
NODISCARD CBL_CORE_API C4QueryEnumerator *	c4queryenum_refresh (C4QueryEnumerator *e, C4Error *outError)
	Checks whether the query results have changed since this enumerator was created; if so, returns a new enumerator.
CBL_CORE_API void	c4queryenum_close (C4QueryEnumerator *)
	Closes an enumerator without freeing it.

Variables
CBL_CORE_API const C4QueryOptions	kC4DefaultQueryOptions
	Default query options.

Detailed Description

Enumeration Type Documentation

C4QueryLanguage

enum C4QueryLanguage : uint32_t

Enumerator
kC4JSONQuery	JSON query schema as documented in LiteCore wiki.
kC4N1QLQuery	N1QL syntax (a large subset)

Function Documentation

c4query_columnCount()

CBL_CORE_API unsigned c4query_columnCount

(

C4Query *

)

Returns the number of columns (the values specified in the WHAT clause) in each row.

Note

The caller must use a lock for Query when this function is called.

c4query_columnTitle()

CBL_CORE_API FLString c4query_columnTitle	(	C4Query *	,
		unsigned	column )

Returns a suggested title for a column, which may be: An alias specified in an 'AS' modifier in the column definition A property name A function/operator that computes the column value, e.g.

'MAX()' or '+' Each column's title is unique. If multiple columns would have the same title, the later ones (in numeric order) will have " #2", "#3", etc. appended.

Note

The caller must use a lock for Query when this function is called.

c4query_explain()

CBL_CORE_API C4StringResult c4query_explain

(

C4Query *

)

Returns a string describing the implementation of the compiled query.

This is intended to be read by a developer for purposes of optimizing the query, especially to add database indexes.

Note

The caller must use a lock for Database when this function is called.

c4query_fullTextMatched()

CBL_CORE_API C4StringResult c4query_fullTextMatched	(	C4Query *	query,
		const C4FullTextMatch *	term,
		C4Error *	outError )

Given a C4FullTextMatch from the enumerator, returns the entire text of the property that was matched.

(The result depends only on the term's dataSource and property fields, so if you get multiple matches of the same property in the same document, you can skip redundant calls with the same values.) To find the actual word that was matched, use the term's start and length fields to get a substring of the returned (UTF-8) string.

Note

The caller must use a lock for Database when this function is called.

c4query_new2()

NODISCARD CBL_CORE_API C4Query * c4query_new2	(	C4Database *	database,
		C4QueryLanguage	language,
		C4String	expression,
		int *	outErrorPos,
		C4Error *	error )

Compiles a query from an expression given as JSON.

The expression is a predicate that describes which documents should be returned. A separate, optional sort expression describes the ordering of the results.

Note

The caller must use a lock for Database when this function is called.

Parameters

database	The database to be queried.
language	The language (syntax) of the query expression.
expression	The query expression, either JSON or N1QL.
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.)
error	Error will be written here if the function fails.

Returns

A new C4Query, or NULL on failure.

c4query_run()

NODISCARD CBL_CORE_API C4QueryEnumerator * c4query_run	(	C4Query *	query,
		C4String	encodedParameters,
		C4Error *	outError )

Runs a compiled query.

NOTE: Queries will run much faster if the appropriate properties are indexed. Indexes must be created explicitly by calling c4db_createIndex.

Note

The caller must use a lock for Database when this function is called.

Parameters

query	The compiled query to run.
encodedParameters	Options parameter values; if this parameter is not NULL, it overrides the parameters assigned by c4query_setParameters.
outError	On failure, will be set to the error status.

Returns

An enumerator for reading the rows, or NULL on error.

c4query_setParameters()

CBL_CORE_API void c4query_setParameters	(	C4Query *	query,
		C4String	encodedParameters )

Sets the parameter values to use when running the query, if no parameters are given to c4query_run.

Note

This function is thread-safe.

Parameters

query	The compiled query to run.
encodedParameters	JSON- or Fleece-encoded dictionary whose keys correspond to the named parameters in the query expression, and values correspond to the values to bind. Any unbound parameters will be null.

c4queryenum_close()

CBL_CORE_API void c4queryenum_close

(

C4QueryEnumerator *

)

Closes an enumerator without freeing it.

This is optional, but can be used to free up resources if the enumeration has not reached its end, but will not be freed for a while.

c4queryenum_getRowCount()

NODISCARD CBL_CORE_API int64_t c4queryenum_getRowCount	(	C4QueryEnumerator *	e,
		C4Error *	outError )

Returns the total number of rows in the query, if known.

Not all query enumerators may support this (but the current implementation does.)

Note

The caller must use a lock for QueryEnumerator when this function is called.

Parameters

e	The query enumerator
outError	On failure, an error will be stored here (probably kC4ErrorUnsupported.)

Returns

The number of rows, or -1 on failure.

c4queryenum_next()

NODISCARD CBL_CORE_API bool c4queryenum_next	(	C4QueryEnumerator *	e,
		C4Error *	outError )

Advances a query enumerator to the next row, populating its fields.

Note

The caller must use a lock for QueryEnumerator when this function is called.

Returns

true on success, false at the end of enumeration or on error.

c4queryenum_refresh()

NODISCARD CBL_CORE_API C4QueryEnumerator * c4queryenum_refresh	(	C4QueryEnumerator *	e,
		C4Error *	outError )

Checks whether the query results have changed since this enumerator was created; if so, returns a new enumerator.

Otherwise returns NULL.

Note

The caller must use a lock for Database when this function is called.

c4queryenum_restart()

static NODISCARD bool c4queryenum_restart ( C4QueryEnumerator * e, C4Error * outError )

inlinestatic

Restarts the enumeration, as though it had just been created: the next call to c4queryenum_next will read the first row, and so on from there.

Note

The caller must use a lock for Database when this function is called.

c4queryenum_seek()

NODISCARD CBL_CORE_API bool c4queryenum_seek	(	C4QueryEnumerator *	e,
		int64_t	rowIndex,
		C4Error *	outError )

Jumps to a specific row.

Not all query enumerators may support this (but the current implementation does.)

Note

The caller must use a lock for QueryEnumerator when this function is called.

Parameters

e	The query enumerator
rowIndex	The number of the row, starting at 0, or -1 to restart before first row
outError	On failure, an error will be stored here (probably kC4ErrorUnsupported.)

Returns

True on success, false on failure.

Variable Documentation

kC4DefaultQueryOptions

CBL_CORE_API const C4QueryOptions kC4DefaultQueryOptions

extern

Default query options.

Has skip=0, limit=UINT_MAX, rankFullText=true.