CBLQuery

@interface CBLQuery : NSObject

A database query. A CBLQuery instance can be constructed by calling one of the select methods.

  • A CBLQueryParameters object used for setting values to the query parameters defined in the query. All parameters defined in the query must be given values before running the query, or the query will fail.

    The returned CBLQueryParameters object will be readonly. an NSInternalInconsistencyException exception will be thrown if the parameters object is modified.

    Declaration

    Objective-C

    @property (copy, nullable) CBLQueryParameters *parameters;

  • 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. It’s not machine-readable and its format may change.

    As currently implemented, the result is two or more lines separated by newline characters:

    • The first line is the SQLite SELECT statement.

    • The subsequent lines are the output of SQLite’s “EXPLAIN QUERY PLAN” command applied to that statement; for help interpreting this, see https://www.sqlite.org/eqp.html . The most important thing to know is that if you see “SCAN TABLE”, it means that SQLite is doing a slow linear scan of the documents instead of using an index.

    Declaration

    Objective-C

    - (nullable NSString *)explain:(NSError *_Nullable *_Nullable)outError;

    Parameters

    outError

    If an error occurs, it will be stored here if this parameter is non-NULL.

    Return Value

    A string describing the implementation of the compiled query.

  • Executes the query. The returning an enumerator that returns result rows one at a time. You can run the query any number of times, and you can even have multiple enumerators active at once. The results come from a snapshot of the database taken at the moment -run: is called, so they will not reflect any changes made to the database afterwards.

    Declaration

    Objective-C

    - (nullable CBLQueryResultSet *)execute:(NSError *_Nullable *_Nullable)outError;

    Parameters

    outError

    If an error occurs, it will be stored here if this parameter is non-NULL.

    Return Value

    An enumerator of the query result.

  • Adds a query change listener. Changes will be posted on the main queue.

    Declaration

    Objective-C

    - (nonnull id<CBLListenerToken>)addChangeListener:
    (nonnull void (^)(CBLQueryChange *_Nonnull))listener;

    Parameters

    listener

    The listener to post changes.

    Return Value

    An opaque listener token object for removing the listener.

  • Adds a query change listener with the dispatch queue on which changes will be posted. If the dispatch queue is not specified, the changes will be posted on the main queue.

    Declaration

    Objective-C

    - (nonnull id<CBLListenerToken>)
    addChangeListenerWithQueue:(nullable dispatch_queue_t)queue
                      listener:
                          (nonnull void (^)(CBLQueryChange *_Nonnull))listener;

    Parameters

    queue

    The dispatch queue.
    listener

    The listener to post changes.

    Return Value

    An opaque listener token object for removing the listener.

  • Removes a change listener wih the given listener token.

    Declaration

    Objective-C

    - (void)removeChangeListenerWithToken:(nonnull id<CBLListenerToken>)token;

    Parameters

    token

    The listener token.

  • Not available

    Declaration

    Objective-C

    - (nonnull instancetype)init;