Filter Data - Java SDK
On this page
About the Examples on This Page
The examples in this page use two Realm object types: Teacher
and Student
.
See the schema for these two classes below:
Filters
You can build filters using the operator methods of the fluent interface exposed by the RealmQuery class:
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.
Link Queries
When referring to an object property, you can use dot notation to refer to child properties of that object. You can refer to the properties of embedded objects and relationships with dot notation.
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:
Sort Results
Realm Database applies the distinct()
, sort()
and
limit()
methods in the order you specify. Depending on the
data set this can alter the query result. Generally, you should
apply 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 Database sorts the tied objects by subsequent
properties in order.
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 Database. Additionally, sorting
strings only supports the Latin Basic
, Latin Supplement
,
Latin Extended A
, and Latin Extended B (UTF-8 range 0–591)
character sets.
Limit Results
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.
Some databases encourage paginating results with limits to avoid reading unnecessary data from disk or using too much memory.
Since Realm Database queries are lazy, there is no need to take such measures. Realm Database only loads objects from query results when they are explicitly accessed.
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.
Unique Results
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 String
fields; other field types will throw an exception. As with sorting,
you can specify multiple fields to resolve ties.
Chain Queries
You can apply additional filters to a results collection by calling the where() method:
The where()
method returns a RealmQuery
that you can resolve into
a 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.
Query with Realm Query Language
New in version 10.4.0.
You can use RealmQuery.rawPredicate() to query realms using Realm Query Language, a string-based query language to constrain searches when retrieving objects from a realm. For more information about syntax, usage and limitations, refer to the Realm Query Language reference.
Realm Query Language can use either the class and property names defined
in your Realm Model classes or the internal names defined with @RealmField
.
You can combine raw predicates with other raw predicates or type-safe
predicates created with RealmQuery
:
You can also find useful Realm Query Language examples on the following pages: