One of the lesser known bits of NSPredicate
is the SUBQUERY()
function. The documentation for a subquery expression explains a little bit about what’s going on, but it takes a while to understand when it’s really useful.
Let’s break it down.
A subquery expression takes 3 arguments:
The collection can be one of the two standard Cocoa collection: NSArray
and NSSet
(or some subclass of them). This collection can be hard-coded in, or it can be the result of another expression (like a keyPath expression or the like). A hard-coded collection would look like:
SUBQUERY(%@, ...
A keyPath expression would look like:
SUBQUERY(contents, ...
With the stipulation that [self contents]
(or self.contents
if you prefer) must return an NSArray
or NSSet
.
The SUBQUERY
is going to iterate over the collection, gathering certain objects. We need a way to represent what each item in the collection is, and for that we use the variable.
Variables in an NSExpression
(or NSPredicate
format string) take the form $identifier
, where identifier
is a valid C-style identifier. Most examples of SUBQUERY
generally use $x
as the variable. It’s short and to-the-point.
It’s the second argument in the expression:
SUBQUERY(contents, $x, ...
A predicate, as we know, is a statement that evaluates to true or false. In the case of the subquery, the predicate will be evaluated for each object (represented by the variable) in the collection. If the predicate returns true, then that object will be included as part of the resulting collection.
SUBQUERY(contents, $x, $x.property = 'foo' and $x.number = 42)
A SUBQUERY()
expression is the functional equivalent of doing this:
NSPredicate * p = [NSPredicate predicateWithFormat:@"property = 'foo' and number = 4"];
NSArray * results = [[self contents] filteredArrayUsingPredicate:p];
If this were expressed as a subquery in a predicate, it would be:
NSPredicate * p = [NSPredicate predicateWithFormat:@"SUBQUERY(contents, $x, $x.property = 'foo' and $x.number = 42) ..."];
//with some operation to use the resulting collection in a comparison or something
Now that we get what the various bits of a subquery expression are, let’s ask the real question: when is this ever useful?
To be honest, the answer to this is “not often”. However, when you need it, it’s incredibly useful.
The general rule of thumb on when you should consider using SUBQUERY
is this:
If you have a collection (A
) of objects, and each object has a collection (B
) of other objects, and you’re trying to filter A
based on some varying attributes (at least 2) of the objects in B
, then you should probably be using SUBQUERY
.
Let’s say you have a bunch of Project
objects, and each Project
has a bunch of ToDo
items. A ToDo
item has a completionDate
(anNSDate
) and a user
(a name). You want to find all projects that have a todo item that was completed by Joey (so completionDate
is notnil
and user
is “Joey”). We’re going to display these in a “Joey’s Recent Projects” group (or something).
Our first reaction might be a predicate that uses ANY
in there, like:
ANY todos.completionDate != nil AND ANY todos.user == joey
Unfortunately, that would give us projects that have at least one completed ToDo
and that has a ToDo
whose user
is Joey. However, they don’t have to be the same ToDo
.
The proper predicate is:
SUBQUERY(todos, $todo, $todo.completionDate != nil AND $todo.user = 'Joey').@count > 0
This predicate will be evaluated against each Project
. First, we’ll get the collection of ToDo
objects by evaluating the todo
keyPath on the Project
. Then for each item ($todo
) in the array of ToDo
objects, we’re going to check and see if that object’s completionDate
is non-nil and if that object’s user is "Joey"
. If that’s true, then it’ll be added to the resulting collection.
When the SUBQUERY
completes, we’ll have an array of ToDo
items that were completed by Joey. At this point, we retrieve the number of items in that collection (via the @count
keyPath) and see if it’s greater than 0. If it is, then the corresponding Project
will be added to the final array. In this manner, we can retrieve all Projects that have ToDos completed by Joey.