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.

    Declaration

    Objective-C

    @property (readonly, nonatomic) CBLQueryParameters *_Nonnull parameters;

  • Create a query from the select and from component.

    Declaration

    Objective-C

    + (nonnull instancetype)select:(nonnull NSArray<CBLQuerySelectResult *> *)select
                          from:(nonnull CBLQueryDataSource *)from;

    Parameters

    select

    The select component reresenting the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a distinct query from the select and from component.

    Declaration

    Objective-C

    + (nonnull instancetype)selectDistinct:
                            (nonnull NSArray<CBLQuerySelectResult *> *)select
                                  from:(nonnull CBLQueryDataSource *)from;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a query from the select, from, and where component.

    Declaration

    Objective-C

    + (nonnull instancetype)select:(nonnull NSArray<CBLQuerySelectResult *> *)select
                          from:(nonnull CBLQueryDataSource *)from
                         where:(nullable CBLQueryExpression *)where;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    where

    The where component representing the WHERE clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a distinct query from the select, from, and where component.

    Declaration

    Objective-C

    + (nonnull instancetype)selectDistinct:
                            (nonnull NSArray<CBLQuerySelectResult *> *)select
                                  from:(nonnull CBLQueryDataSource *)from
                                 where:(nullable CBLQueryExpression *)where;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    where

    The where component representing the WHERE clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a query from the select, from, where, and order by component.

    Declaration

    Objective-C

    + (nonnull instancetype)select:(nonnull NSArray<CBLQuerySelectResult *> *)select
                          from:(nonnull CBLQueryDataSource *)from
                         where:(nullable CBLQueryExpression *)where
                       orderBy:
                           (nullable NSArray<CBLQueryOrdering *> *)orderings;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    where

    The where component representing the WHERE clause of the query.
    orderings

    The ordering components representing the ORDER BY clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a distinct query from the select, from, where, and order by component.

    Declaration

    Objective-C

    + (nonnull instancetype)
selectDistinct:(nonnull NSArray<CBLQuerySelectResult *> *)select
          from:(nonnull CBLQueryDataSource *)from
         where:(nullable CBLQueryExpression *)where
       orderBy:(nullable NSArray<CBLQueryOrdering *> *)orderings;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    where

    The where component representing the WHERE clause of the query.
    orderings

    The ordering components representing the ORDER BY clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a query from the select, from, where, and group by component.

    Declaration

    Objective-C

    + (nonnull instancetype)select:(nonnull NSArray<CBLQuerySelectResult *> *)select
                          from:(nonnull CBLQueryDataSource *)from
                         where:(nullable CBLQueryExpression *)where
                       groupBy:
                           (nullable NSArray<CBLQueryExpression *> *)groupBy;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    where

    The where component representing the WHERE clause of the query.
    groupBy

    The group by expressions representing the GROUP BY clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a distinct query from the select, from, where and group by component.

    Declaration

    Objective-C

    + (nonnull instancetype)
selectDistinct:(nonnull NSArray<CBLQuerySelectResult *> *)select
          from:(nonnull CBLQueryDataSource *)from
         where:(nullable CBLQueryExpression *)where
       groupBy:(nullable NSArray<CBLQueryExpression *> *)groupBy;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    where

    The where component representing the WHERE clause of the query.
    groupBy

    The group by expressions representing the GROUP BY clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a query from the select, from, where, groupby and having component.

    Declaration

    Objective-C

    + (nonnull instancetype)select:(nonnull NSArray<CBLQuerySelectResult *> *)select
                          from:(nonnull CBLQueryDataSource *)from
                         where:(nullable CBLQueryExpression *)where
                       groupBy:(nullable NSArray<CBLQueryExpression *> *)groupBy
                        having:(nullable CBLQueryExpression *)having;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    where

    The where component representing the WHERE clause of the query.
    groupBy

    The group by expressions representing the GROUP BY clause of the query.
    having

    The having component representing the HAVING clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a distinct query from the select, from, where, groupby and having component.

    Declaration

    Objective-C

    + (nonnull instancetype)
selectDistinct:(nonnull NSArray<CBLQuerySelectResult *> *)select
          from:(nonnull CBLQueryDataSource *)from
         where:(nullable CBLQueryExpression *)where
       groupBy:(nullable NSArray<CBLQueryExpression *> *)groupBy
        having:(nullable CBLQueryExpression *)having;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    where

    The where component representing the WHERE clause of the query.
    groupBy

    The group by expressions representing the GROUP BY clause of the query.
    having

    The having component representing the HAVING clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a query from the select, from, where, groupby, having, order by, and limit component.

    Declaration

    Objective-C

    + (nonnull instancetype)select:(nonnull NSArray<CBLQuerySelectResult *> *)select
                          from:(nonnull CBLQueryDataSource *)from
                         where:(nullable CBLQueryExpression *)where
                       groupBy:(nullable NSArray<CBLQueryExpression *> *)groupBy
                        having:(nullable CBLQueryExpression *)having
                       orderBy:(nullable NSArray<CBLQueryOrdering *> *)orderings
                         limit:(nullable CBLQueryLimit *)limit;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    where

    The where component representing the WHERE clause of the query.
    groupBy

    The group by expressions representing the GROUP BY clause of the query.
    having

    The having component representing the HAVING clause of the query.
    orderings

    The ordering components representing the ORDER BY clause of the query.
    limit

    The limit component representing the LIMIT clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a distinct query from the select, from, where, groupby, having, order by, and limit component.

    Declaration

    Objective-C

    + (nonnull instancetype)
selectDistinct:(nonnull NSArray<CBLQuerySelectResult *> *)select
          from:(nonnull CBLQueryDataSource *)from
         where:(nullable CBLQueryExpression *)where
       groupBy:(nullable NSArray<CBLQueryExpression *> *)groupBy
        having:(nullable CBLQueryExpression *)having
       orderBy:(nullable NSArray<CBLQueryOrdering *> *)orderings
         limit:(nullable CBLQueryLimit *)limit;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    where

    The where component representing the WHERE clause of the query.
    groupBy

    The group by expressions representing the GROUP BY clause of the query.
    having

    The having component representing the HAVING clause of the query.
    orderings

    The ordering components representing the ORDER BY clause of the query.
    limit

    The limit component representing the LIMIT clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a query from the select, from, and join component.

    Declaration

    Objective-C

    + (nonnull instancetype)select:(nonnull NSArray<CBLQuerySelectResult *> *)select
                          from:(nonnull CBLQueryDataSource *)from
                          join:(nullable NSArray<CBLQueryJoin *> *)join;

    Parameters

    select

    The select component reresenting the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    join

    The join components representing the JOIN clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a distinct query from the select from, and join component.

    Declaration

    Objective-C

    + (nonnull instancetype)selectDistinct:
                            (nonnull NSArray<CBLQuerySelectResult *> *)select
                                  from:(nonnull CBLQueryDataSource *)from
                                  join:(nullable NSArray<CBLQueryJoin *> *)join;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    join

    The join components representing the JOIN clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a query from the select, from, join and where component.

    Declaration

    Objective-C

    + (nonnull instancetype)select:(nonnull NSArray<CBLQuerySelectResult *> *)select
                          from:(nonnull CBLQueryDataSource *)from
                          join:(nullable NSArray<CBLQueryJoin *> *)join
                         where:(nullable CBLQueryExpression *)where;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    join

    The join components representing the JOIN clause of the query.
    where

    The where component representing the WHERE clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a distinct query from the select, from, join and where component.

    Declaration

    Objective-C

    + (nonnull instancetype)selectDistinct:
                            (nonnull NSArray<CBLQuerySelectResult *> *)select
                                  from:(nonnull CBLQueryDataSource *)from
                                  join:(nullable NSArray<CBLQueryJoin *> *)join
                                 where:(nullable CBLQueryExpression *)where;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    join

    The join components representing the JOIN clause of the query.
    where

    The where component representing the WHERE clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a query from the select, from, join, where, and group by component.

    Declaration

    Objective-C

    + (nonnull instancetype)select:(nonnull NSArray<CBLQuerySelectResult *> *)select
                          from:(nonnull CBLQueryDataSource *)from
                          join:(nullable NSArray<CBLQueryJoin *> *)join
                         where:(nullable CBLQueryExpression *)where
                       groupBy:
                           (nullable NSArray<CBLQueryExpression *> *)groupBy;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    join

    The join components representing the JOIN clause of the query.
    where

    The where component representing the WHERE clause of the query.
    groupBy

    The group by expressions representing the GROUP BY clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a distinct query from the select, from, join, where, and groupby component.

    Declaration

    Objective-C

    + (nonnull instancetype)
selectDistinct:(nonnull NSArray<CBLQuerySelectResult *> *)select
          from:(nonnull CBLQueryDataSource *)from
          join:(nullable NSArray<CBLQueryJoin *> *)join
         where:(nullable CBLQueryExpression *)where
       groupBy:(nullable NSArray<CBLQueryExpression *> *)groupBy;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    join

    The join components representing the JOIN clause of the query.
    where

    The where component representing the WHERE clause of the query.
    groupBy

    The group by expressions representing the GROUP BY clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a query from the select, from, join, where, grop by, and having component.

    Declaration

    Objective-C

    + (nonnull instancetype)select:(nonnull NSArray<CBLQuerySelectResult *> *)select
                          from:(nonnull CBLQueryDataSource *)from
                          join:(nullable NSArray<CBLQueryJoin *> *)join
                         where:(nullable CBLQueryExpression *)where
                       groupBy:(nullable NSArray<CBLQueryExpression *> *)groupBy
                        having:(nullable CBLQueryExpression *)having;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    join

    The join components representing the JOIN clause of the query.
    where

    The where component representing the WHERE clause of the query.
    groupBy

    The group by expressions representing the GROUP BY clause of the query.
    having

    The having component representing the HAVING clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a distinct query from the select, from, join, where, gropu by and having component.

    Declaration

    Objective-C

    + (nonnull instancetype)
selectDistinct:(nonnull NSArray<CBLQuerySelectResult *> *)select
          from:(nonnull CBLQueryDataSource *)from
          join:(nullable NSArray<CBLQueryJoin *> *)join
         where:(nullable CBLQueryExpression *)where
       groupBy:(nullable NSArray<CBLQueryExpression *> *)groupBy
        having:(nullable CBLQueryExpression *)having;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    join

    The join components representing the JOIN clause of the query.
    where

    The where component representing the WHERE clause of the query.
    groupBy

    The group by expressions representing the GROUP BY clause of the query.
    having

    The having component representing the HAVING clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a query from the select, from, join, where and order by component.

    Declaration

    Objective-C

    + (nonnull instancetype)select:(nonnull NSArray<CBLQuerySelectResult *> *)select
                          from:(nonnull CBLQueryDataSource *)from
                          join:(nullable NSArray<CBLQueryJoin *> *)join
                         where:(nullable CBLQueryExpression *)where
                       orderBy:
                           (nullable NSArray<CBLQueryOrdering *> *)orderings;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    join

    The join components representing the JOIN clause of the query.
    where

    The where component representing the WHERE clause of the query.
    orderings

    The ordering components representing the ORDER BY clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a distinct query from the select, from, join, where, and order by component.

    Declaration

    Objective-C

    + (nonnull instancetype)
selectDistinct:(nonnull NSArray<CBLQuerySelectResult *> *)select
          from:(nonnull CBLQueryDataSource *)from
          join:(nullable NSArray<CBLQueryJoin *> *)join
         where:(nullable CBLQueryExpression *)where
       orderBy:(nullable NSArray<CBLQueryOrdering *> *)orderings;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    join

    The join components representing the JOIN clause of the query.
    where

    The where component representing the WHERE clause of the query.
    orderings

    The ordering components representing the ORDER BY clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a query from the select, from, join, where, group by, having, order by, and limit component.

    Declaration

    Objective-C

    + (nonnull instancetype)select:(nonnull NSArray<CBLQuerySelectResult *> *)select
                          from:(nonnull CBLQueryDataSource *)from
                          join:(nullable NSArray<CBLQueryJoin *> *)join
                         where:(nullable CBLQueryExpression *)where
                       groupBy:(nullable NSArray<CBLQueryExpression *> *)groupBy
                        having:(nullable CBLQueryExpression *)having
                       orderBy:(nullable NSArray<CBLQueryOrdering *> *)orderings
                         limit:(nullable CBLQueryLimit *)limit;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    join

    The join components representing the JOIN clause of the query.
    where

    The where component representing the WHERE clause of the query.
    groupBy

    The group by expressions representing the GROUP BY clause of the query.
    having

    The having component representing the HAVING clause of the query.
    orderings

    The orderings components representing the ORDER BY clause of the query.
    limit

    The limit component representing the LIMIT clause of the query.

    Return Value

    The CBLQuery instance.

  • Create a distinct query from the select, from, join, where, group by, having, order by and limit component.

    Declaration

    Objective-C

    + (nonnull instancetype)
selectDistinct:(nonnull NSArray<CBLQuerySelectResult *> *)select
          from:(nonnull CBLQueryDataSource *)from
          join:(nullable NSArray<CBLQueryJoin *> *)join
         where:(nullable CBLQueryExpression *)where
       groupBy:(nullable NSArray<CBLQueryExpression *> *)groupBy
        having:(nullable CBLQueryExpression *)having
       orderBy:(nullable NSArray<CBLQueryOrdering *> *)orderings
         limit:(nullable CBLQueryLimit *)limit;

    Parameters

    select

    The select component representing the SELECT clause of the query.
    from

    The from component representing the FROM clause of the query.
    join

    The join components representing the JOIN clause of the query.
    where

    The where component representing the WHERE clause of the query.
    groupBy

    The group by expressions representing the GROUP BY clause of the query.
    having

    The having component representing the HAVING clause of the query.
    orderings

    The ordering components representing the ORDER BY clause of the query.
    limit

    The limit component representing the LIMIT clause of the query.

    Return Value

    The CBLQuery instance.

  • Checks whether the query is valid, recompiling it if necessary, without running it.

    Declaration

    Objective-C

    - (BOOL)check:(NSError *_Nullable *_Nullable)outError;

    Parameters

    outError

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

    Return Value

    YES if the query is valid, or NO if the query is not valid.

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

  • Runs 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 *)run:(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.

  • Returns a live query based on the current query.

    Declaration

    Objective-C

    - (nonnull CBLLiveQuery *)toLive;

    Return Value

    A live query object.

  • Undocumented

    Declaration

    Objective-C

    @interface CBLQuery : NSObject