On this page
- Query Engine
- Fluent Interface
- About the Examples In This Section
- Comparison Operators
- Logical Operators
- String Operators
- Aggregate Operators
- Filter, Sort, Limit, Unique, and Chain Queries
- About the Examples in This Section
- Sort Results
- Limit Results
- Unique Results
- Chain Queries
- Query with Realm Query Language
To filter data in your realm, use the Realm query engine.
There are two ways to access the query engine with the Java SDK:
The Java SDK uses a Fluent interface to construct multi-clause queries that are passed to the query engine.
See RealmQuery API for a complete list of available methods.
There are several types of operators available to filter a
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.
An expression consists of one of the following:
The name of a property of the object currently being evaluated.
An operator and up to two argument expression(s).
A literal string, number, or date.
The examples in this section 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,
The most straightforward operation in a search is to compare values.
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.
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':
Case-insensitive Character Limitations
Case-insensitive string operators only support the
Latin Extended A, and
Latin Extended B (UTF-8 range 0–591) character sets. Setting
the case insensitive flag in queries when using
like only works on English locale characters.
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 number of objects in the given 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.
The examples in this section use two Realm object types:
See the schema for these two classes below:
This gives you a new instance of the class RealmResults, containing teachers with the name "Ms. Langtree" or "Mrs. Jacobs".
RealmQuery includes several methods that can execute queries:
findAll() blocks until it finds all objects that meet the query conditions
findAllAsync() returns immediately and finds all objects that meet the query conditions asynchronously on a background thread
findFirst() blocks until it finds the first object that meets the query conditions
findFirstAsync() returns immediately and finds the first object that meets the query conditions asynchronously on a background thread
Queries return a list of references to the matching Realm objects using the RealmResults type.
For example, consider a query for all teachers with a student named "Wirt" or "Greg":
You can even use dot notation to query inverse relationships:
Realm applies the
limit() methods in the order you specify. Depending on the
data set this can alter the query result. Generally, you should
limit() last to avoid unintended result sets.
You can define the order of query results using the sort() method:
Sorts organize results in ascending order by default. To organize results
in descending order, pass
Sort.DESCENDING as a second argument.
You can resolve sort order ties between identical property values
by passing an array of properties instead of a single property: in the
event of a tie, Realm sorts the tied objects by subsequent
properties in order.
String Sorting Limitations
Realm uses non-standard sorting for upper and lowercase
letters, sorting them together rather than sorting uppercase first.
As a result,
'- !"#0&()*,./:;?_+<=>123aAbBcC...xXyYzZ is the
actual sorting order in Realm. Additionally, sorting
strings only supports the
Latin Extended A, and
Latin Extended B (UTF-8 range 0–591)
You can cap the number of query results to a specific maximum number using the limit() method:
Limited result collections automatically update like any other query result. Consequently, objects might drop out of the collection as underlying data changes.
Pagination is Not Necessary for Realm Optimization
Some databases encourage paginating results with limits to avoid reading unnecessary data from disk or using too much memory.
Since Realm queries are lazy, there is no need to take such measures. Realm only loads objects from query results when they are explicitly accessed.
Deleted Notifications in Limited Results
Collection notifications report objects as deleted when they drop out of the result set. This does not necessarily mean that they have been deleted from the underlying realm, just that they are no longer part of the query result.
You can reduce query results to unique values for a given field or fields using the distinct() method:
You can only call
distinct() on integer, long, short, and
fields; other field types will throw an exception. As with sorting,
you can specify multiple fields to resolve ties.
You can apply additional filters to a results collection by calling the where() method:
where() method returns a
RealmQuery that you can resolve into
RealmResults using a
find method. Filtered results can only
return objects of the same type as the original results set, but are
otherwise able to use any filters.
New in version 10.4.0.
You can also query realms using Realm Query Language, a string-based query language to constrain searches when retrieving objects from a realm.
Realm Query Language can use either the class and property names defined
in your Realm Model classes or the internal names defined with
You can combine raw predicates with other raw predicates or type-safe
predicates created with