What the heck is SUBQUERY?
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:
- A collection
- A variable name
- A predicate
The collection can be one of the two standard Cocoa collection:
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:
A keyPath expression would look like:
With the stipulation that
[self contents] (or
self.contents if you prefer) must return an
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
NSPredicate format string) take the form
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)
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.
Rule of thumb
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
Let’s say you have a bunch of
Project objects, and each
Project has a bunch of
ToDo items. A
ToDo item has a
NSDate) and a
user (a name). You want to find all projects that have a todo item that was completed by Joey (so
completionDate is not
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
user is Joey. However, they don’t have to be the same
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.
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.