cbl::Query Class Reference

A database query. More...

#include <cbl++/Query.hh>

Inheritance diagram for cbl::Query:

Classes
class	Change
	The change passed to a live query's listener callback, giving access to the updated results. More...
class	ChangeListener
	The token returned by Query::addChangeListener for a live query. More...

Public Member Functions
	Query (const Database &db, CBLQueryLanguage language, std::string_view queryString)
	Creates a new query by compiling the input string.
std::vector< std::string >	columnNames () const
	Returns the column names that will appear in the query results.
void	setParameters (fleece::Dict parameters)
	Assigns values to the query's parameters.
fleece::Dict	parameters () const
	Returns the query's current parameter bindings, if any.
ResultSet	execute ()
	Runs the query, returning the results.
std::string	explain ()
	Returns information about the query, including the translated SQLite form, and the search strategy.
ChangeListener	addChangeListener (ListenerToken< Change >::Callback callback)
	Registers a change listener callback to the query, turning it into a "live query" until the listener is removed (via ListenerToken::remove() ).
	Query () noexcept
	Constructs a null reference (one that points to no object).
Query &	operator= (std::nullptr_t)
	Releases the underlying object and resets this to a null reference.
bool	valid () const
	Returns true if this references an object, or false if it is a null reference.
	operator bool () const
	Returns true if this references an object (same as valid).
bool	operator== (const Query &other) const
	Returns true if both sides reference the same object, or are both null references.
bool	operator!= (const Query &other) const
	Returns true if the two sides reference different objects.
CBLQuery *_Nullable	ref () const
	Returns a pointer to the underlying C object (CBLQuery), or NULL if this is a null reference.
	Query (const Query &other) noexcept
	Copy constructor: creates another reference to the same object as other.
	Query (Query &&other) noexcept
	Move constructor: takes over the reference from other, leaving it a null reference.
Query &	operator= (const Query &other) noexcept
	Copy assignment: replaces this reference with a reference to other's object.
Query &	operator= (Query &&other) noexcept
	Move assignment: replaces this reference with other's, leaving other a null reference.

Protected Member Functions
	Query (CBLQuery *_Nullable ref)
	(Internal) Constructs a reference wrapping, and retaining, a C object pointer.

Detailed Description

A database query.

Constructor & Destructor Documentation

Query() [1/5]

cbl::Query::Query ( const Database & db, CBLQueryLanguage language, std::string_view queryString )

inline

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 Query object 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 Query::setParameters(fleece::Dict parameters) each time you run the query.

Warning

Deprecated : Use Database::createQuery instead.

Note

The JSON query language is a volatile API. Volatile APIs are experimental and may likely be changed. They may also be used to indicate inherently private APIs that may be exposed, but "YMMV" (your mileage may vary) principles apply.

Parameters

db	The database the query runs against.
language	The query language
queryString	The query string.

Query() [2/5]

cbl::Query::Query ( )

inlinenoexcept

Constructs a null reference (one that points to no object).

Query() [3/5]

cbl::Query::Query ( CBLQuery *_Nullable ref )

inlineexplicitprotected

(Internal) Constructs a reference wrapping, and retaining, a C object pointer.

Query() [4/5]

cbl::Query::Query ( const Query & other )

inlinenoexcept

Copy constructor: creates another reference to the same object as other.

Query() [5/5]

cbl::Query::Query ( Query && other )

inlinenoexcept

Move constructor: takes over the reference from other, leaving it a null reference.

Member Function Documentation

addChangeListener()

Query::ChangeListener cbl::Query::addChangeListener ( ListenerToken< Change >::Callback callback )

inlinenodiscard

Registers a change listener callback to the query, turning it into a "live query" until the listener is removed (via ListenerToken::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

callback

The callback to be invoked.

Returns

A Change Listener Token. Call ListenerToken::remove() method to remove the listener.

columnNames()

std::vector< std::string > cbl::Query::columnNames ( ) const

inline

Returns the column names that will appear in the query results.

The column names are based on their 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.

execute()

ResultSet cbl::Query::execute ( )

inline

Runs the query, returning the results.

explain()

std::string cbl::Query::explain ( )

inline

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.

operator bool()

cbl::Query::operator bool ( ) const

inlineexplicit

Returns true if this references an object (same as valid).

operator!=()

bool cbl::Query::operator!= ( const Query & other ) const

inline

Returns true if the two sides reference different objects.

operator=() [1/3]

Query & cbl::Query::operator= ( const Query & other )

inlinenoexcept

Copy assignment: replaces this reference with a reference to other's object.

operator=() [2/3]

Query & cbl::Query::operator= ( Query && other )

inlinenoexcept

Move assignment: replaces this reference with other's, leaving other a null reference.

operator=() [3/3]

Query & cbl::Query::operator= ( std::nullptr_t )

inline

Releases the underlying object and resets this to a null reference.

operator==()

bool cbl::Query::operator== ( const Query & other ) const

inline

Returns true if both sides reference the same object, or are both null references.

parameters()

fleece::Dict cbl::Query::parameters ( ) const

inline

Returns the query's current parameter bindings, if any.

ref()

CBLQuery *_Nullable cbl::Query::ref ( ) const

inline

Returns a pointer to the underlying C object (CBLQuery), or NULL if this is a null reference.

setParameters()

void cbl::Query::setParameters ( fleece::Dict parameters )

inline

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

parameters

The parameters in the form of a Fleece Dict (dictionary) whose keys are the parameter names. (It's easiest to construct this by using the fleece::MutableDict)

valid()

bool cbl::Query::valid ( ) const

inline

Returns true if this references an object, or false if it is a null reference.

---

The documentation for this class was generated from the following file:

• include/cbl++/Query.hh