Filter Data - iOS SDK¶
To filter data in your realm, you can leverage Realm Database's query engine. Realm Database's query engine supports common predicates of NSPredicate. For an introduction to NSPredicate in general, See Apple’s Predicates Programming Guide.
About the Examples on This Page¶
The examples in this page use a simple data set for a
task list app. The two Realm object types are
Task has a name, assignee's name, and
completed flag. There is also an arbitrary number for
priority -- higher is more important -- and a count of
minutes spent working on it. A
Project has zero or more
See the schema for these two classes,
You can set up the realm for these examples with the following code:
You can build a filter with NSPredicate:
Filters consist of expressions in an NSPredicate. An expression consists of one of the following:
- The name (keypath) of a property of the object currently being evaluated.
- An operator and up to two argument expression(s).
- A value, such as a string (
'hello') or a number (
When referring to an object property, you can use dot notation to refer to child properties of that object. You can even refer to the properties of embedded objects and relationships with dot notation.
For example, consider a query on an object with a
workplace property that
refers to a Workplace object. The Workplace object has an embedded object
address. You can chain dot notations to refer to the zipcode
property of that address:
workplace.address.zipcode == 10012
You can use the following substitutions in your predicate format strings:
%@to specify values
%Kto specify keypaths
You can iterate through a collection property with another query using the
SUBQUERY() predicate function.
SUBQUERY() has the following signature:
SUBQUERY(<collection>, <variableName>, <predicate>)
collection: the name of the list property to iterate through
variableName: a variable name of the current element to use in the subquery
predicate: a string that contains the subquery predicate. You can use the variable name specified by
variableNameto refer to the currently-iterated element.
Running the following filter on a projects collect returns projects with tasks that have not been completed by a user named Alex.
There are several types of operators available to filter a
Realm collection. Filters
work by evaluating an operator expression for every
object in the collection being
filtered. If the expression resolves to
Database includes the object in the results collection.
The most straightforward operation in a search is to compare values.
The type on both sides of the operator must be equivalent. For
example, comparing an ObjectId with string will result in a precondition failure with a
"Expected object of type object id for property 'id'
on object of type 'User', but received: 11223344556677889900aabb
You can compare any numeric type with any other numeric type.
The following example uses the query engine's comparison operators to:
- Find high priority tasks by comparing the value of the
priorityproperty value with a threshold number, above which priority can be considered high.
- Find just-started or short-running tasks by seeing if the
progressMinutesproperty falls within a certain range.
- Find unassigned tasks by finding tasks where the
assigneeproperty is equal to
- Find tasks assigned to specific teammates Ali or Jamie by seeing if the
assigneeproperty is in a list of names.
You can make compound predicates using logical operators.
Negates the result of the given expression.
We can use the query language's logical operators to find
all of Ali's completed tasks. That is, we find all tasks
assignee property value is equal to 'Ali' AND
isComplete property value is
You can compare string values using these string operators. Regex-like wildcards allow more flexibility in search.
You can use the following modifiers with the string operators:
[c]for case insensitivity.
[NSPredicate predicateWithFormat: @"name CONTAINS[c] 'f'"]
[d]for diacritic insensitivity: Realm treats special characters as the base character (e.g.
[NSPredicate predicateWithFormat: @"name CONTAINS[d] 'e'"]
For example, the wildcard string "d?g" matches "dog", "dig", and "dug", but not "ding", "dg", or "a dog".
We use the query engine's string operators to find projects with a name starting with the letter 'e' and projects with names that contain 'ie':
String sorting and case-insensitive queries are only supported for character sets in 'Latin Basic', 'Latin Supplement', 'Latin Extended A', and 'Latin Extended B' (UTF-8 range 0-591).
You can apply an aggregate operator to a collection property of a Realm object. Aggregate operators traverse a collection and reduce it to a single value.
Evaluates to the average value of a given numerical property across a collection.
Evaluates to the highest value of a given numerical property across a collection.
Evaluates to the lowest value of a given numerical property across a collection.
Evaluates to the sum of a given numerical property across a collection.
We create a couple of filters to show different facets of the data:
- Projects with average tasks priority above 5.
- Long running projects.
A set operator uses specific rules to determine whether to pass each input collection object to the output collection by applying a given predicate to every element of a given list property of the object.
Returns objects where the predicate evaluates to
Returns objects where the predicate evaluates to
Returns objects where the predicate evaluates to false for all objects in the collection.
We use the query engine's set operators to find:
- Projects with no complete tasks.
- Projects with any top priority tasks.