Query Builder

The CBLQueryBuilder class provides a high-level interface for defining database queries, somewhat like Core Data's NSFetchRequest. Instead of thinking about map functions and key ranges, you provide "select", "where" and "order by" expressions; the query builder uses these to define a view and configure the query.

Compatibility: CBLQueryBuilder is a new class in Couchbase Lite 1.1. (An earlier version was formerly available in version 1.0.3 as an unsupported 'extra', but not built into the library.) It is iOS/Mac specific, since it's based on Cocoa classes like NSPredicate and NSSortDescriptor. Comparable functionality will be available on other platforms too, with APIs that are idiomatic for those platforms.

Overview

A CBLQueryBuilder defines a query or a family of related queries (since it can contain variables whose values can be substituted later.) It has four attributes:

1. The database to query.
2. A "where" predicate (boolean-valued function) that chooses which documents match the query.
3. An array of values to select from the matching documents. Each value is an expression based on properties of the document.
4. An optional array of sort descriptors that determine the order the results appear.

(This may look something like a SQL SELECT statement, but the details are different.)

Based on these attributes, the query builder will create a view and register its map function. You don't need to worry about this. The query builder will create a pre-configured CBLQuery object for you, and all you need to do is run it and use the result.

Often a query's predicate will depend on specific values that aren't known until runtime, such as a minimum or maximum property value. You can specify these as as placeholder variables; in a predicate string they're $-prefixed identifiers. When creating a query, you provide specific values for these variables.

The best practice is to create query builders ahead of time, keeping references to them in global variables or long-lived instance variables. This reduces the overhead of parsing the attributes and creating the views. If you're creating a query builder each time you run a query, you're probably doing it wrong.