Introduction to Predicates Programming Guide
Predicates provide a general means of specifying queries in Cocoa. The predicate system is capable of handling a large number of domains, including Core Data and Spotlight. This document describes predicates in general, their use, their syntax, and their limitations.
At a Glance
A predicate is a logical operator that returns a Boolean value (true or false). There are two types of predicate; comparison predicates, and compound predicates:
A comparison predicate compares two expressions using an operator. The expressions are referred to as the left hand side and the right hand side of the predicate (with the operator in the middle). A comparison predicate returns the result of invoking the operator with the results of evaluating the expressions.
A compound predicate compares the results of evaluating two or more other predicates, or negates another predicate.
Cocoa supports a wide range of types of predicate, including the following:
Simple comparisons, such as
grade == 7or
firstName like 'Mark'
Case or diacritic insensitive lookups, such as
name contains[cd] 'citroen'
Logical operations, such as
(firstName beginswith 'M') AND (lastName like 'Adderley')
You can also create predicates for relationships—such as
group.name matches 'work.*',
ALL children.age > 12, and
ANY children.age > 12—and for operations such as
@sum.items.price < 1000.
Cocoa predicates provide a means of encoding queries in a manner that is independent of the store used to hold the data being searched. You use predicates to represent logical conditions used for constraining the set of objects retrieved by Spotlight and Core Data, and for in-memory filtering of objects.
You can use predicates with any class of object, but a class must be key-value coding compliant for the keys you want to use in a predicate.
Cocoa provides three predicate classes:
NSPredicate, and two subclasses of
NSPredicate provides—amongst others—methods to evaluate a predicate, and to create a predicate from a string (such as
firstName like 'Mark'). In many cases you simply use
NSPredicate. When you create a predicate using a string,
NSPredicate creates the appropriate predicate and expression instances for you. In some situations, you want to create comparison or compound predicates yourself, in which case you can use
Predicate expressions in Cocoa are represented by instances of
NSExpression. The simplest expression simply represents a constant value. Frequently, though, you use expressions that retrieve the value for a key path of the object currently being evaluated in the predicate. You can also create an expression to represent the object currently being evaluated in the predicate, to serve as a placeholder for a variable, or to return the result of performing an operation on an array.
How you create predicates and expressions is discussed in more detail in “Creating Predicates.”
Constraints and Limitations
If you use predicates with Core Data or Spotlight, you should take care that they will work with the corresponding data store. There is no specific implementation language for predicate queries—a predicate query may be translated into SQL, XML, or another format, depending on the requirements of the backing store (if indeed there is one).
The predicate system is intended to support a useful range of operators, so provides neither the set union nor the set intersection of all operators supported by all backing stores. Therefore, not all possible predicate queries are supported by all backing stores, and not all operations supported by all backing stores can be expressed with
NSExpression. The back end may downgrade the predicate (for example it may make a case-sensitive comparison case-insensitive) or raise an exception if you try to use an unsupported operator. For example:
regex, so is not supported by Core Data’s SQL store— although it does work with in-memory filtering.
The Core Data SQL store supports only one to-many operation per query; therefore in any predicate sent to the SQL store, there may be only one operator (and one instance of that operator) from
You cannot necessarily translate “arbitrary” SQL queries into predicates.
ANYKEYoperator can only be used with Spotlight.
Spotlight does not support relationships.
How to Use This Document
The following articles explain the basics of predicates in Cocoa, explain how to create and use predicate objects, and define the predicate syntax:
“Creating Predicates” describes how to correctly instantiate predicates programmatically and how to retrieve them from a managed object model.
“Using Predicates” explains how to use predicates and discusses some issues related to performance.
“Comparison of NSPredicate and Spotlight Query Strings” compares NSPredicate and Spotlight queries.
“Predicate Format String Syntax” describes the syntax of the predicate format string.
“BNF Definition of Cocoa Predicates” provides a definition of Cocoa predicates in Backus-Naur Form notation.
© 2005, 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-06-14)