What is SUBQUERY?

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.

The Syntax

A subquery expression takes 3 arguments:

1. A collection
2. A variable name
3. A predicate

The Collection

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 Variable

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

The Predicate

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)

TL;DR

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

So what?

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

Example

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.