CBLPredicateQuery

@interface CBLPredicateQuery : NSObject

A compiled database query. You create a query by calling the CBLDatabase method createQueryWhere:. The query can be further configured by setting properties before running it. Some properties alter the behavior of the query enough to trigger recompilation; it’s usually best to set these only once and then reuse the CBLQuery object. You can use NSPredicate / NSExpression variables to parameterize the query, making it flexible without needing recompilation. Then you just set the parameters property before running it.

  • The database being queried.

    Declaration

    Objective-C

    @property (readonly, nonatomic) CBLDatabase *_Nonnull database;

    Swift

    var database: CBLDatabase { get }

  • Specifies a condition (predicate) that documents have to match; corresponds to the WHERE clause of a SQL or N1QL query. This can be an NSPredicate, or an NSString (interpreted as an NSPredicate format string), or nil to return all documents. Defaults to nil. If this property is changed, the query will be recompiled the next time it is run.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) id where;

    Swift

    var `where`: Any? { get set }

  • An array of NSSortDescriptors or NSStrings, specifying properties or expressions that the result rows should be sorted by; corresponds to the ORDER BY clause of a SQL or N1QL query. These strings, or sort-descriptor names, can name key-paths or be NSExpresson format strings. If nil, no sorting occurs; this is faster but the order of rows is undefined. The default value sorts by document ID. If this property is changed, the query will be recompiled the next time it is run.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSArray *orderBy;

    Swift

    var orderBy: [Any]? { get set }

  • An array of NSExpressions (or expression format strings) describing values to include in each result row; corresponds to the SELECT clause of a SQL or N1QL query. If nil, only the document ID and sequence number will be available. Defaults to nil. If this property is changed, the query will be recompiled the next time it is run.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSArray *returning;

    Swift

    var returning: [Any]? { get set }

  • An array of NSExpressions (or expression format strings) describing how to group rows together: all documents having the same values for these expressions will be coalesced into a single row. If nil, no grouping is done. Defaults to nil.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSArray *groupBy;

    Swift

    var groupBy: [Any]? { get set }

  • Specifies a condition (predicate) that grouped rows have to match; corresponds to the HAVING clause of a SQL or N1QL query. This can be an NSPredicate, or an NSString (interpreted as an NSPredicate format string), or nil to not filter groups. Defaults to nil. If this property is changed, the query will be recompiled the next time it is run.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) id having;

    Swift

    var having: Any? { get set }

  • If YES, duplicate result rows will be removed so that all rows are unique; corresponds to the DISTINCT keyword of a SQL or N1QL query. Defaults to NO.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL distinct;

    Swift

    var distinct: Bool { get set }

  • The number of result rows to skip; corresponds to the OFFSET property of a SQL or N1QL query. This can be useful for paging through a large query, but skipping many rows is slow. Defaults to 0.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSUInteger offset;

    Swift

    var offset: UInt { get set }

  • The maximum number of rows to return; corresponds to the LIMIT property of a SQL or N1QL query. Defaults to NSUIntegerMax (i.e. unlimited.)

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) NSUInteger limit;

    Swift

    var limit: UInt { get set }

  • Values to substitute for placeholder parameters defined in the query. Defaults to nil. The dictionary’s keys are parameter names, and values are the values to use. All parameters must be given values before running the query, or it will fail.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable)
    NSDictionary<NSString *, id> *parameters;

    Swift

    var parameters: [String : Any]? { get set }

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

    Declaration

    Objective-C

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

    Swift

    func check() throws

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

    Swift

    func explain() throws -> String

  • Runs the query, using the current settings (skip, limit, parameters), 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 NSEnumerator<CBLQueryRow *> *)run:
    (NSError *_Nullable *_Nullable)error;

    Swift

    func run() throws -> NSEnumerator

  • A convenience method equivalent to -run: except that its enumerator returns CBLDocuments directly, not CBLQueryRows.

    Declaration

    Objective-C

    - (nullable NSEnumerator<CBLDocument *> *)allDocuments:
    (NSError *_Nullable *_Nullable)error;

    Swift

    func allDocuments() throws -> NSEnumerator

  • Not available.

    Declaration

    Objective-C

    - (nonnull instancetype)init;