Docs Menu

Docs Home → Develop Applications → Atlas Device SDKs

Class RealmQuery

On this page

  • io.realm
  • Method Summary
  • Inherited Methods
  • Method Detail
  • alwaysFalse
  • alwaysTrue
  • and
  • average
  • averageDecimal128
  • averageRealmAny
  • beginGroup
  • beginsWith
  • between
  • contains
  • containsEntry
  • containsKey
  • containsValue
  • count
  • distinct
  • endGroup
  • endsWith
  • equalTo
  • findAll
  • findAllAsync
  • findFirst
  • findFirstAsync
  • getDescription
  • getQueryPointer
  • getRealm
  • getTypeQueried
  • greaterThan
  • greaterThanOrEqualTo
  • in
  • isEmpty
  • isNotEmpty
  • isNotNull
  • isNull
  • isValid
  • lessThan
  • lessThanOrEqualTo
  • like
  • limit
  • max
  • maxRealmAny
  • maximumDate
  • min
  • minRealmAny
  • minimumDate
  • not
  • notEqualTo
  • or
  • rawPredicate
  • sort
  • sum

io.realm

java.lang.Object
io.realm.RealmQuery

A RealmQuery encapsulates a query on a io.realm.Realm or a io.realm.RealmResults using the Builder pattern. The query is executed using either findAll() or findFirst() .

The input to many of the query functions take a field name as String. Note that this is not type safe. If a RealmObject class is refactored care has to be taken to not break any queries.

A io.realm.Realm is unordered, which means that there is no guarantee that querying a Realm will return the objects in the order they where inserted. Use sort(String) (String)} and similar methods if a specific order is required.

A RealmQuery cannot be passed between different threads.

Results are obtained quickly most of the times. However, launching heavy queries from the UI thread may result in a drop of frames or even ANRs. If you want to prevent these behaviors, you can instantiate a Realm using a RealmConfiguration that explicitly sets RealmConfiguration.Builder.allowQueriesOnUiThread(boolean) to false . This way queries will be forced to be launched from a non-UI thread. Alternatively, you can also use findAllAsync() or findFirstAsync() .

Tip

See also:

Method Summary

Modifier and Type
Method and Description
public RealmQuery
alwaysFalse ()

This predicate will never match, resulting in the query always returning 0 results.

public RealmQuery
alwaysTrue ()

This predicate will always match.

public RealmQuery
and ()

Logical-and two conditions Realm automatically applies logical-and between all query statements, so this is intended only as a mean to increase readability.

public double
average (
String fieldName
)

Returns the average of a given field.

public Decimal128
averageDecimal128 (
String fieldName
)

Returns the average of a given field.

public Decimal128
averageRealmAny (
String fieldName
)

Returns the average of a given field.

public RealmQuery
beginGroup ()

Begin grouping of conditions ("left parenthesis").

public RealmQuery
beginsWith (
String fieldName,
RealmAny value,
Case casing
)

Condition that the value of field begins with the specified substring.

public RealmQuery
beginsWith (
String fieldName,
String value,
Case casing
)

Condition that the value of field begins with the specified substring.

public RealmQuery
beginsWith (
String fieldName,
RealmAny value
)

Condition that the value of field begins with the specified string.

public RealmQuery
beginsWith (
String fieldName,
String value
)

Condition that the value of field begins with the specified string.

public RealmQuery
between (
String fieldName,
Decimal128 from,
Decimal128 to
)

Between condition.

public RealmQuery
between (
String fieldName,
RealmAny from,
RealmAny to
)

Between condition.

public RealmQuery
between (
String fieldName,
Date from,
Date to
)

Between condition.

public RealmQuery
between (
String fieldName,
float from,
float to
)

Between condition.

public RealmQuery
between (
String fieldName,
double from,
double to
)

Between condition.

public RealmQuery
between (
String fieldName,
long from,
long to
)

Between condition.

public RealmQuery
between (
String fieldName,
int from,
int to
)

Between condition.

public RealmQuery
contains (
String fieldName,
RealmAny value,
Case casing
)

Condition that value of field contains the specified substring.

public RealmQuery
contains (
String fieldName,
String value,
Case casing
)

Condition that value of field contains the specified substring.

public RealmQuery
contains (
String fieldName,
RealmAny value
)

Condition that value of field contains the specified substring.

public RealmQuery
contains (
String fieldName,
String value
)

Condition that value of field contains the specified substring.

public RealmQuery
containsEntry (
String fieldName,
java.util.Map.Entry<java.lang.String, ?> entry
)

Condition that value, if a dictionary field, contains the specified entry.

public RealmQuery
containsKey (
String fieldName,
String key
)

Condition that value, if a dictionary field, contains the specified key.

public RealmQuery
containsValue (
String fieldName,
ObjectId value
)

Condition that value, if a dictionary field, contains the specified value.

public RealmQuery
containsValue (
String fieldName,
Decimal128 value
)

Condition that value, if a dictionary field, contains the specified value.

public RealmQuery
containsValue (
String fieldName,
Date value
)

Condition that value, if a dictionary field, contains the specified value.

public RealmQuery
containsValue (
String fieldName,
byte[] value
)

Condition that value, if a dictionary field, contains the specified value.

public RealmQuery
containsValue (
String fieldName,
String value
)

Condition that value, if a dictionary field, contains the specified value.

public RealmQuery
containsValue (
String fieldName,
Float value
)

Condition that value, if a dictionary field, contains the specified value.

public RealmQuery
containsValue (
String fieldName,
Double value
)

Condition that value, if a dictionary field, contains the specified value.

public RealmQuery
containsValue (
String fieldName,
Long value
)

Condition that value, if a dictionary field, contains the specified value.

public RealmQuery
containsValue (
String fieldName,
Integer value
)

Condition that value, if a dictionary field, contains the specified value.

public RealmQuery
containsValue (
String fieldName,
Short value
)

Condition that value, if a dictionary field, contains the specified value.

public RealmQuery
containsValue (
String fieldName,
Byte value
)

Condition that value, if a dictionary field, contains the specified value.

public RealmQuery
containsValue (
String fieldName,
Boolean value
)

Condition that value, if a dictionary field, contains the specified value.

public long
count ()

Counts the number of objects that fulfill the query conditions.

public RealmQuery
distinct (
String firstFieldName,
java.lang.String[] remainingFieldNames
)

Selects a distinct set of objects of a specific class.

public RealmQuery
endGroup ()

End grouping of conditions ("right parenthesis") which was opened by a call to beginGroup() .

public RealmQuery
endsWith (
String fieldName,
RealmAny value,
Case casing
)

Condition that the value of field ends with the specified substring.

public RealmQuery
endsWith (
String fieldName,
String value,
Case casing
)

Condition that the value of field ends with the specified substring.

public RealmQuery
endsWith (
String fieldName,
RealmAny value
)

Condition that the value of field ends with the specified string.

public RealmQuery
endsWith (
String fieldName,
String value
)

Condition that the value of field ends with the specified string.

public RealmQuery
equalTo (
String fieldName,
ObjectId value
)

Equal-to comparison.

public RealmQuery
equalTo (
String fieldName,
Decimal128 value
)

Equal-to comparison.

public RealmQuery
equalTo (
String fieldName,
RealmAny value,
Case casing
)

Equal-to comparison.

public RealmQuery
equalTo (
String fieldName,
String value,
Case casing
)

Equal-to comparison.

public RealmQuery
equalTo (
String fieldName,
String value
)

Equal-to comparison.

public RealmResults
findAll ()

Finds all objects that fulfill the query conditions.

public RealmResults
findAllAsync ()

Finds all objects that fulfill the query conditions.

public E
findFirst ()

Finds the first object that fulfills the query conditions.

public E
findFirstAsync ()

Similar to findFirst() but runs asynchronously on a worker thread.

public String
getDescription ()

Returns a textual description of this query.

public long
getQueryPointer ()

Returns the pointer to the underlying C++ query.

public Realm
getRealm ()

Returns the Realm instance to which this query belongs.

public String
getTypeQueried ()

Returns the internal Realm name of the type being queried.

public RealmQuery
greaterThan (
String fieldName,
ObjectId value
)

Greater-than comparison.

public RealmQuery
greaterThan (
String fieldName,
Decimal128 value
)

Greater-than comparison.

public RealmQuery
greaterThan (
String fieldName,
RealmAny value
)

Greater-than comparison.

public RealmQuery
greaterThan (
String fieldName,
Date value
)

Greater-than comparison.

public RealmQuery
greaterThan (
String fieldName,
float value
)

Greater-than comparison.

public RealmQuery
greaterThan (
String fieldName,
double value
)

Greater-than comparison.

public RealmQuery
greaterThan (
String fieldName,
long value
)

Greater-than comparison.

public RealmQuery
greaterThan (
String fieldName,
int value
)

Greater-than comparison.

public RealmQuery
greaterThanOrEqualTo (
String fieldName,
ObjectId value
)

Greater-than-or-equal-to comparison.

public RealmQuery
greaterThanOrEqualTo (
String fieldName,
Decimal128 value
)

Greater-than-or-equal-to comparison.

public RealmQuery
greaterThanOrEqualTo (
String fieldName,
Date value
)

Greater-than-or-equal-to comparison.

public RealmQuery
greaterThanOrEqualTo (
String fieldName,
float value
)

Greater-than-or-equal-to comparison.

public RealmQuery
greaterThanOrEqualTo (
String fieldName,
double value
)

Greater-than-or-equal-to comparison.

public RealmQuery
greaterThanOrEqualTo (
String fieldName,
long value
)

Greater-than-or-equal-to comparison.

public RealmQuery
greaterThanOrEqualTo (
String fieldName,
int value
)

Greater-than-or-equal-to comparison.

public RealmQuery
in (
String fieldName,
io.realm.RealmAny[] values
)

In comparison.

public RealmQuery
in (
String fieldName,
java.util.Date[] values
)

In comparison.

public RealmQuery
in (
String fieldName,
java.lang.Boolean[] values
)

In comparison.

public RealmQuery
in (
String fieldName,
java.lang.Float[] values
)

In comparison.

public RealmQuery
in (
String fieldName,
java.lang.Double[] values
)

In comparison.

public RealmQuery
in (
String fieldName,
java.lang.Long[] values
)

In comparison.

public RealmQuery
in (
String fieldName,
java.lang.Integer[] values
)

In comparison.

public RealmQuery
in (
String fieldName,
java.lang.Short[] values
)

In comparison.

public RealmQuery
in (
String fieldName,
java.lang.Byte[] values
)

In comparison.

public RealmQuery
in (
String fieldName,
java.lang.String[] values,
Case casing
)

In comparison.

public RealmQuery
in (
String fieldName,
java.lang.String[] values
)

In comparison.

public RealmQuery
isEmpty (
String fieldName
)

Condition that finds values that are considered "empty" i.e., an empty list, the 0-length string or byte array.

public RealmQuery
isNotEmpty (
String fieldName
)

Condition that finds values that are considered "Not-empty" i.e., a list, a string or a byte array with not-empty values.

public RealmQuery
isNotNull (
String fieldName
)

Tests if a field is not null .

public RealmQuery
isNull (
String fieldName
)

Tests if a field is null .

public boolean
isValid ()

Checks if io.realm.RealmQuery is still valid to use i.e., the io.realm.Realm instance hasn't been closed and any parent io.realm.RealmResults is still valid.

public RealmQuery
lessThan (
String fieldName,
ObjectId value
)

Less-than comparison.

public RealmQuery
lessThan (
String fieldName,
Decimal128 value
)

Less-than comparison.

public RealmQuery
lessThan (
String fieldName,
long value
)

Less-than comparison.

public RealmQuery
lessThan (
String fieldName,
int value
)

Less-than comparison.

public RealmQuery
lessThanOrEqualTo (
String fieldName,
ObjectId value
)

Less-than-or-equal-to comparison.

public RealmQuery
lessThanOrEqualTo (
String fieldName,
Decimal128 value
)

Less-than-or-equal-to comparison.

public RealmQuery
lessThanOrEqualTo (
String fieldName,
long value
)

Less-than-or-equal-to comparison.

public RealmQuery
lessThanOrEqualTo (
String fieldName,
int value
)

Less-than-or-equal-to comparison.

public RealmQuery
like (
String fieldName,
RealmAny value,
Case casing
)

Condition that the value of field matches with the specified substring, with wildcards:

  • '*' matches [0, n] unicode chars

  • '?' matches a single unicode char.

public RealmQuery
like (
String fieldName,
String value,
Case casing
)

Condition that the value of field matches with the specified substring, with wildcards:

  • '*' matches [0, n] unicode chars

  • '?' matches a single unicode char.

public RealmQuery
like (
String fieldName,
RealmAny value
)

Condition that the value of field matches with the specified substring, with wildcards:

  • '*' matches [0, n] unicode chars

  • '?' matches a single unicode char.

public RealmQuery
like (
String fieldName,
String value
)

Condition that the value of field matches with the specified substring, with wildcards:

  • '*' matches [0, n] unicode chars

  • '?' matches a single unicode char.

public RealmQuery
limit (
long limit
)

Limits the number of objects returned in case the query matched more objects.

public Number
max (
String fieldName
)

Finds the maximum value of a field.

public RealmAny
maxRealmAny (
String fieldName
)

Finds the maximum value of a RealmAny field.

public Date
maximumDate (
String fieldName
)

Finds the maximum value of a field.

public Number
min (
String fieldName
)

Finds the minimum value of a field.

public RealmAny
minRealmAny (
String fieldName
)

Finds the minimum value of a RealmAny field.

public Date
minimumDate (
String fieldName
)

Finds the minimum value of a field.

public RealmQuery
not ()

Negate condition.

public RealmQuery
notEqualTo (
String fieldName,
ObjectId value
)

Not-equal-to comparison.

public RealmQuery
notEqualTo (
String fieldName,
Decimal128 value
)

Not-equal-to comparison.

public RealmQuery
notEqualTo (
String fieldName,
RealmAny value,
Case casing
)

Not-equal-to comparison.

public RealmQuery
notEqualTo (
String fieldName,
String value,
Case casing
)

Not-equal-to comparison.

public RealmQuery
notEqualTo (
String fieldName,
String value
)

Not-equal-to comparison.

public RealmQuery
or ()

Logical-or two conditions.

public RealmQuery
rawPredicate (
String predicate,
java.lang.Object[] arguments
)

Create a text-based predicate using the Realm Query Language.

public RealmQuery
sort (
java.lang.String[] fieldNames,
io.realm.Sort[] sortOrders
)

Sorts the query result by the specific field names in the provided orders.

public RealmQuery
sort (
String fieldName1,
Sort sortOrder1,
String fieldName2,
Sort sortOrder2
)

Sorts the query result by the specific field names in the provided orders.

public RealmQuery
sort (
String fieldName,
Sort sortOrder
)

Sorts the query result by the specified field name and order.

public RealmQuery
sort (
String fieldName
)

Sorts the query result by the specific field name in ascending order.

public Number
sum (
String fieldName
)

Calculates the sum of a given field.

Inherited Methods

  • Methods inherited from class java.lang.Object : getClass , hashCode , equals , clone , toString , notify , notifyAll , wait , wait , wait , finalize

Method Detail

alwaysFalse

public RealmQuery alwaysFalse ()

This predicate will never match, resulting in the query always returning 0 results.

alwaysTrue

public RealmQuery alwaysTrue ()

This predicate will always match.

and

public RealmQuery and ()

Logical-and two conditions Realm automatically applies logical-and between all query statements, so this is intended only as a mean to increase readability.

Returns

the query object

average

public double average (
String fieldName
)

Returns the average of a given field. Does not support dotted field notation.

Parameters

  • fieldName - the field to calculate average on. Only number fields are supported.

Returns

the average for the given field amongst objects in query results. This will be of type double for all types of number fields. If no objects exist or they all have null as the value for the given field, 0 will be returned. When computing the average, objects with null values are ignored.

Throws

averageDecimal128

public Decimal128 averageDecimal128 (
String fieldName
)

Returns the average of a given field. Does not support dotted field notation.

Parameters

  • fieldName - the field to calculate average on. Only Decimal128 fields is supported. For other number types consider using average(String) .

Returns

the average for the given field amongst objects in query results. This will be of type Decimal128. If no objects exist or they all have null as the value for the given field 0 will be returned. When computing the average, objects with null values are ignored.

Throws

averageRealmAny

public Decimal128 averageRealmAny (
String fieldName
)

Returns the average of a given field. Does not support dotted field notation.

Parameters

  • fieldName - the field to calculate average on. Only RealmAny fields are supported. For other types consider using average(String) .

Returns

the average for the given field amongst objects in query results. This will be of type Decimal128. If no objects exist or they all have null as the value for the given field 0 will be returned. When computing the average, objects with null values are ignored.

Throws

beginGroup

public RealmQuery beginGroup ()

Begin grouping of conditions ("left parenthesis"). A group must be closed with a call to endGroup() .

Returns

the query object.

Tip

See also:

beginsWith

public RealmQuery beginsWith (
String fieldName,
RealmAny value,
Case casing
)

Condition that the value of field begins with the specified substring.

Parameters

  • fieldName - the field to compare.

  • value - the substring.

  • casing - how to handle casing. Setting this to Case.INSENSITIVE only works for Latin-1 characters.

Returns

the query object

Throws

public RealmQuery beginsWith (
String fieldName,
String value,
Case casing
)

Condition that the value of field begins with the specified substring.

Parameters

  • fieldName - the field to compare.

  • value - the substring.

  • casing - how to handle casing. Setting this to Case.INSENSITIVE only works for Latin-1 characters.

Returns

the query object

Throws

public RealmQuery beginsWith (
String fieldName,
RealmAny value
)

Condition that the value of field begins with the specified string.

Parameters

  • fieldName - the field to compare.

  • value - the string.

Returns

the query object.

Throws

public RealmQuery beginsWith (
String fieldName,
String value
)

Condition that the value of field begins with the specified string.

Parameters

  • fieldName - the field to compare.

  • value - the string.

Returns

the query object.

Throws

between

public RealmQuery between (
String fieldName,
Decimal128 from,
Decimal128 to
)

Between condition.

Parameters

  • fieldName - the field to compare.

  • from - lowest value (inclusive).

  • to - highest value (inclusive).

Returns

the query object.

Throws

public RealmQuery between (
String fieldName,
RealmAny from,
RealmAny to
)

Between condition.

Parameters

  • fieldName - the field to compare.

  • from - lowest value (inclusive).

  • to - highest value (inclusive).

Returns

the query object.

Throws

public RealmQuery between (
String fieldName,
Date from,
Date to
)

Between condition.

Parameters

  • fieldName - the field to compare.

  • from - lowest value (inclusive).

  • to - highest value (inclusive).

Returns

the query object.

Throws

public RealmQuery between (
String fieldName,
float from,
float to
)

Between condition.

Parameters

  • fieldName - the field to compare.

  • from - lowest value (inclusive).

  • to - highest value (inclusive).

Returns

the query object.

Throws

public RealmQuery between (
String fieldName,
double from,
double to
)

Between condition.

Parameters

  • fieldName - the field to compare.

  • from - lowest value (inclusive).

  • to - highest value (inclusive).

Returns

the query object.

Throws

public RealmQuery between (
String fieldName,
long from,
long to
)

Between condition.

Parameters

  • fieldName - the field to compare.

  • from - lowest value (inclusive).

  • to - highest value (inclusive).

Returns

the query object.

Throws

public RealmQuery between (
String fieldName,
int from,
int to
)

Between condition.

Parameters

  • fieldName - the field to compare.

  • from - lowest value (inclusive).

  • to - highest value (inclusive).

Returns

the query object.

Throws

contains

public RealmQuery contains (
String fieldName,
RealmAny value,
Case casing
)

Condition that value of field contains the specified substring.

Parameters

  • fieldName - the field to compare.

  • value - the substring.

  • casing - how to handle casing. Setting this to Case.INSENSITIVE only works for Latin-1 characters.

Returns

The query object.

Throws

public RealmQuery contains (
String fieldName,
String value,
Case casing
)

Condition that value of field contains the specified substring.

Parameters

  • fieldName - the field to compare.

  • value - the substring.

  • casing - how to handle casing. Setting this to Case.INSENSITIVE only works for Latin-1 characters.

Returns

The query object.

Throws

public RealmQuery contains (
String fieldName,
RealmAny value
)

Condition that value of field contains the specified substring.

Parameters

  • fieldName - the field to compare.

  • value - the substring.

Returns

the query object.

Throws

public RealmQuery contains (
String fieldName,
String value
)

Condition that value of field contains the specified substring.

Parameters

  • fieldName - the field to compare.

  • value - the substring.

Returns

the query object.

Throws

containsEntry

public RealmQuery containsEntry (
String fieldName,
java.util.Map.Entry<java.lang.String, ?> entry
)

Condition that value, if a dictionary field, contains the specified entry.

Parameters

  • fieldName - the field to compare.

  • entry - the entry to search for.

Returns

the query object.

Throws

containsKey

public RealmQuery containsKey (
String fieldName,
String key
)

Condition that value, if a dictionary field, contains the specified key.

Parameters

  • fieldName - the field to compare.

  • key - the key to search for.

Returns

the query object.

Throws

containsValue

public RealmQuery containsValue (
String fieldName,
ObjectId value
)

Condition that value, if a dictionary field, contains the specified value.

Parameters

  • fieldName - the field to compare.

  • value - the value to search for.

Returns

the query object.

Throws

public RealmQuery containsValue (
String fieldName,
Decimal128 value
)

Condition that value, if a dictionary field, contains the specified value.

Parameters

  • fieldName - the field to compare.

  • value - the value to search for.

Returns

the query object.

Throws

public RealmQuery containsValue (
String fieldName,
Date value
)

Condition that value, if a dictionary field, contains the specified value.

Parameters

  • fieldName - the field to compare.

  • value - the value to search for.

Returns

the query object.

Throws

public RealmQuery containsValue (
String fieldName,
byte[] value
)

Condition that value, if a dictionary field, contains the specified value.

Parameters

  • fieldName - the field to compare.

  • value - the value to search for.

Returns

the query object.

Throws

public RealmQuery containsValue (
String fieldName,
String value
)

Condition that value, if a dictionary field, contains the specified value.

Parameters

  • fieldName - the field to compare.

  • value - the value to search for.

Returns

the query object.

Throws

public RealmQuery containsValue (
String fieldName,
Float value
)

Condition that value, if a dictionary field, contains the specified value.

Parameters

  • fieldName - the field to compare.

  • value - the value to search for.

Returns

the query object.

Throws

public RealmQuery containsValue (
String fieldName,
Double value
)

Condition that value, if a dictionary field, contains the specified value.

Parameters

  • fieldName - the field to compare.

  • value - the value to search for.

Returns

the query object.

Throws

public RealmQuery containsValue (
String fieldName,
Long value
)

Condition that value, if a dictionary field, contains the specified value.

Parameters

  • fieldName - the field to compare.

  • value - the value to search for.

Returns

the query object.

Throws

public RealmQuery containsValue (
String fieldName,
Integer value
)

Condition that value, if a dictionary field, contains the specified value.

Parameters

  • fieldName - the field to compare.

  • value - the value to search for

Returns

the query object.

Throws

public RealmQuery containsValue (
String fieldName,
Short value
)

Condition that value, if a dictionary field, contains the specified value.

Parameters

  • fieldName - the field to compare.

  • value - the value to search for.

Returns

the query object.

Throws

public RealmQuery containsValue (
String fieldName,
Byte value
)

Condition that value, if a dictionary field, contains the specified value.

Parameters

  • fieldName - the field to compare.

  • value - the value to search for.

Returns

the query object.

Throws

public RealmQuery containsValue (
String fieldName,
Boolean value
)

Condition that value, if a dictionary field, contains the specified value.

Parameters

  • fieldName - the field to compare.

  • value - the value to search for.

Returns

the query object.

Throws

count

public long count ()

Counts the number of objects that fulfill the query conditions.

Returns

the number of matching objects.

Throws

distinct

public RealmQuery distinct (
String firstFieldName,
java.lang.String[] remainingFieldNames
)

Selects a distinct set of objects of a specific class. When multiple distinct fields are given, all unique combinations of values in the fields will be returned. In case of multiple matches, it is undefined which object is returned. Unless the result is sorted, then the first object will be returned.

Parameters

  • firstFieldName - first field name to use when finding distinct objects.

  • remainingFieldNames - remaining field names when determining all unique combinations of field values.

Throws

endGroup

public RealmQuery endGroup ()

End grouping of conditions ("right parenthesis") which was opened by a call to beginGroup() .

Returns

the query object.

Tip

See also:

endsWith

public RealmQuery endsWith (
String fieldName,
RealmAny value,
Case casing
)

Condition that the value of field ends with the specified substring.

Parameters

  • fieldName - the field to compare.

  • value - the substring.

  • casing - how to handle casing. Setting this to Case.INSENSITIVE only works for Latin-1 characters.

Returns

the query object.

Throws

public RealmQuery endsWith (
String fieldName,
String value,
Case casing
)

Condition that the value of field ends with the specified substring.

Parameters

  • fieldName - the field to compare.

  • value - the substring.

  • casing - how to handle casing. Setting this to Case.INSENSITIVE only works for Latin-1 characters.

Returns

the query object.

Throws

public RealmQuery endsWith (
String fieldName,
RealmAny value
)

Condition that the value of field ends with the specified string.

Parameters

  • fieldName - the field to compare.

  • value - the string.

Returns

the query object.

Throws

public RealmQuery endsWith (
String fieldName,
String value
)

Condition that the value of field ends with the specified string.

Parameters

  • fieldName - the field to compare.

  • value - the string.

Returns

the query object.

Throws

equalTo

public RealmQuery equalTo (
String fieldName,
ObjectId value
)

Equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery equalTo (
String fieldName,
Decimal128 value
)

Equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery equalTo (
String fieldName,
RealmAny value,
Case casing
)

Equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

  • casing - how to handle casing. Setting this to Case.INSENSITIVE only works for Latin-1 characters.

Returns

the query object.

Throws

public RealmQuery equalTo (
String fieldName,
String value,
Case casing
)

Equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

  • casing - how to handle casing. Setting this to Case.INSENSITIVE only works for Latin-1 characters.

Returns

the query object.

Throws

public RealmQuery equalTo (
String fieldName,
String value
)

Equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

findAll

public RealmResults findAll ()

Finds all objects that fulfill the query conditions.Launching heavy queries from the UI thread may result in a drop of frames or even ANRs. We do not recommend doing so and therefore it is not allowed by default. If you want to prevent these behaviors you can obtain a Realm using a RealmConfiguration that explicitly sets RealmConfiguration.Builder.allowQueriesOnUiThread(boolean) to false . This way you will be forced to launch your queries from a non-UI thread, otherwise calls to this method will throw a RealmException . Alternatively, you can use findAllAsync() .

Returns

a io.realm.RealmResults containing objects. If no objects match the condition, a list with zero objects is returned.

Throws

Tip

See also:

findAllAsync

public RealmResults findAllAsync ()

Finds all objects that fulfill the query conditions. This method is only available from a Looper thread.

Returns

immediately an empty RealmResults . Users need to register a listener io.realm.RealmResults.addChangeListener(RealmChangeListener) to be notified when the query completes.

Tip

See also:

findFirst

public E findFirst ()

Finds the first object that fulfills the query conditions.Launching heavy queries from the UI thread may result in a drop of frames or even ANRs. We do not recommend doing so, but it is allowed by default. If you want to prevent these behaviors you can obtain a Realm using a RealmConfiguration that explicitly sets RealmConfiguration.Builder.allowQueriesOnUiThread(boolean) to false . This way you will be forced to launch your queries from a non-UI thread, otherwise calls to this method will throw a RealmException . Alternatively, you can use findFirstAsync() .

Returns

the object found or null if no object matches the query conditions.

Throws

Tip

See also:

findFirstAsync

public E findFirstAsync ()

Similar to findFirst() but runs asynchronously on a worker thread. A listener should be registered to the returned RealmObject to get the notification when query completes. The registered listener will also be triggered if there are changes made to the queried RealmObject . If the RealmObject is deleted, the listener will be called one last time and then stop. The query will not be re-run.

Returns

immediately an empty RealmObject with isLoaded() == false . Trying to access any field on the returned object before it is loaded will throw an IllegalStateException .

Throws

getDescription

public String getDescription ()

Returns a textual description of this query.

Returns

the textual description of the query.

getQueryPointer

public long getQueryPointer ()

Returns the pointer to the underlying C++ query. This method is only public due to architectural design choices that are hard to work around and should be considered internal and can change without warning.

Returns

the pointer to the underlying C++ query.

getRealm

public Realm getRealm ()

Returns the Realm instance to which this query belongs.

Calling Realm.close() on the returned instance is discouraged as it is the same as calling it on the original Realm instance which may cause the Realm to fully close invalidating the query.

Returns

Realm instance this query belongs to.

Throws

getTypeQueried

public String getTypeQueried ()

Returns the internal Realm name of the type being queried.

Returns

the internal name of the Realm model class being queried.

greaterThan

public RealmQuery greaterThan (
String fieldName,
ObjectId value
)

Greater-than comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery greaterThan (
String fieldName,
Decimal128 value
)

Greater-than comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery greaterThan (
String fieldName,
RealmAny value
)

Greater-than comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery greaterThan (
String fieldName,
Date value
)

Greater-than comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery greaterThan (
String fieldName,
float value
)

Greater-than comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery greaterThan (
String fieldName,
double value
)

Greater-than comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery greaterThan (
String fieldName,
long value
)

Greater-than comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery greaterThan (
String fieldName,
int value
)

Greater-than comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

greaterThanOrEqualTo

public RealmQuery greaterThanOrEqualTo (
String fieldName,
ObjectId value
)

Greater-than-or-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery greaterThanOrEqualTo (
String fieldName,
Decimal128 value
)

Greater-than-or-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery greaterThanOrEqualTo (
String fieldName,
Date value
)

Greater-than-or-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery greaterThanOrEqualTo (
String fieldName,
float value
)

Greater-than-or-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery greaterThanOrEqualTo (
String fieldName,
double value
)

Greater-than-or-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery greaterThanOrEqualTo (
String fieldName,
long value
)

Greater-than-or-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery greaterThanOrEqualTo (
String fieldName,
int value
)

Greater-than-or-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

in

public RealmQuery in (
String fieldName,
io.realm.RealmAny[] values
)

In comparison. This allows you to test if objects match any value in an array of values.

Parameters

  • fieldName - the field to compare.

  • values - array of values to compare with. If null or the empty array is provided the query will never match any results.

Returns

the query object.

Throws

public RealmQuery in (
String fieldName,
java.util.Date[] values
)

In comparison. This allows you to test if objects match any value in an array of values.

Parameters

  • fieldName - the field to compare.

  • values - array of values to compare with. If null or the empty array is provided the query will never match any results.

Returns

the query object.

Throws

public RealmQuery in (
String fieldName,
java.lang.Boolean[] values
)

In comparison. This allows you to test if objects match any value in an array of values.

Parameters

  • fieldName - the field to compare.

  • values - array of values to compare with. If null or the empty array is provided the query will never match any results.

Returns

the query object.

Throws

public RealmQuery in (
String fieldName,
java.lang.Float[] values
)

In comparison. This allows you to test if objects match any value in an array of values.

Parameters

  • fieldName - the field to compare.

  • values - array of values to compare with. If null or the empty array is provided the query will never match any results.

Returns

the query object.

Throws

public RealmQuery in (
String fieldName,
java.lang.Double[] values
)

In comparison. This allows you to test if objects match any value in an array of values.

Parameters

  • fieldName - the field to compare.

  • values - array of values to compare with. If null or the empty array is provided the query will never match any results.

Returns

the query object.

Throws

public RealmQuery in (
String fieldName,
java.lang.Long[] values
)

In comparison. This allows you to test if objects match any value in an array of values.

Parameters

  • fieldName - the field to compare.

  • values - array of values to compare with. If null or the empty array is provided the query will never match any results.

Returns

the query object.

Throws

public RealmQuery in (
String fieldName,
java.lang.Integer[] values
)

In comparison. This allows you to test if objects match any value in an array of values.

Parameters

  • fieldName - the field to compare.

  • values - array of values to compare with. If null or the empty array is provided the query will never match any results.

Returns

the query object.

Throws

public RealmQuery in (
String fieldName,
java.lang.Short[] values
)

In comparison. This allows you to test if objects match any value in an array of values.

Parameters

  • fieldName - the field to compare.

  • values - array of values to compare with. If null or the empty array is provided the query will never match any results.

Returns

the query object.

Throws

public RealmQuery in (
String fieldName,
java.lang.Byte[] values
)

In comparison. This allows you to test if objects match any value in an array of values.

Parameters

  • fieldName - the field to compare.

  • values - array of values to compare with. If null or the empty array is provided the query will never match any results.

Returns

the query object.

Throws

public RealmQuery in (
String fieldName,
java.lang.String[] values,
Case casing
)

In comparison. This allows you to test if objects match any value in an array of values.

Parameters

  • fieldName - the field to compare.

  • values - array of values to compare with. If null or the empty array is provided the query will never match any results.

  • casing - how casing is handled. Case.INSENSITIVE works only for the Latin-1 characters.

Returns

the query object.

Throws

public RealmQuery in (
String fieldName,
java.lang.String[] values
)

In comparison. This allows you to test if objects match any value in an array of values.

Parameters

  • fieldName - the field to compare.

  • values - array of values to compare with. If null or the empty array is provided the query will never match any results.

Returns

the query object.

Throws

isEmpty

public RealmQuery isEmpty (
String fieldName
)

Condition that finds values that are considered "empty" i.e., an empty list, the 0-length string or byte array.

Parameters

  • fieldName - the field to compare.

Returns

the query object.

Throws

isNotEmpty

public RealmQuery isNotEmpty (
String fieldName
)

Condition that finds values that are considered "Not-empty" i.e., a list, a string or a byte array with not-empty values.

Parameters

  • fieldName - the field to compare.

Returns

the query object.

Throws

isNotNull

public RealmQuery isNotNull (
String fieldName
)

Tests if a field is not null . Only works for nullable fields.

Parameters

  • fieldName - the field name.

Returns

the query object.

Throws

Tip

See also:

isNull

public RealmQuery isNull (
String fieldName
)

Tests if a field is null . Only works for nullable fields.

For link queries, if any part of the link path is null the whole path is considered to be null e.g., isNull("linkField.stringField") will be considered to be null if either linkField or linkField.stringField is null .

Parameters

  • fieldName - the field name.

Returns

the query object.

Throws

Tip

See also:

isValid

public boolean isValid ()

Checks if io.realm.RealmQuery is still valid to use i.e., the io.realm.Realm instance hasn't been closed and any parent io.realm.RealmResults is still valid.

Returns

true if still valid to use, false otherwise.

lessThan

public RealmQuery lessThan (
String fieldName,
ObjectId value
)

Less-than comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery lessThan (
String fieldName,
Decimal128 value
)

Less-than comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery lessThan (
String fieldName,
long value
)

Less-than comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery lessThan (
String fieldName,
int value
)

Less-than comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

lessThanOrEqualTo

public RealmQuery lessThanOrEqualTo (
String fieldName,
ObjectId value
)

Less-than-or-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery lessThanOrEqualTo (
String fieldName,
Decimal128 value
)

Less-than-or-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery lessThanOrEqualTo (
String fieldName,
long value
)

Less-than-or-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery lessThanOrEqualTo (
String fieldName,
int value
)

Less-than-or-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

like

public RealmQuery like (
String fieldName,
RealmAny value,
Case casing
)

Condition that the value of field matches with the specified substring, with wildcards:

  • '*' matches [0, n] unicode chars

  • '?' matches a single unicode char.

Parameters

  • fieldName - the field to compare.

  • value - the wildcard string.

  • casing - how to handle casing. Setting this to Case.INSENSITIVE only works for Latin-1 characters.

Returns

the query object.

Throws

public RealmQuery like (
String fieldName,
String value,
Case casing
)

Condition that the value of field matches with the specified substring, with wildcards:

  • '*' matches [0, n] unicode chars

  • '?' matches a single unicode char.

Parameters

  • fieldName - the field to compare.

  • value - the wildcard string.

  • casing - how to handle casing. Setting this to Case.INSENSITIVE only works for Latin-1 characters.

Returns

the query object.

Throws

public RealmQuery like (
String fieldName,
RealmAny value
)

Condition that the value of field matches with the specified substring, with wildcards:

  • '*' matches [0, n] unicode chars

  • '?' matches a single unicode char.

Parameters

  • fieldName - the field to compare.

  • value - the wildcard string.

Returns

the query object.

Throws

public RealmQuery like (
String fieldName,
String value
)

Condition that the value of field matches with the specified substring, with wildcards:

  • '*' matches [0, n] unicode chars

  • '?' matches a single unicode char.

Parameters

  • fieldName - the field to compare.

  • value - the wildcard string.

Returns

the query object.

Throws

limit

public RealmQuery limit (
long limit
)

Limits the number of objects returned in case the query matched more objects.Note that when using this method in combination with sort(String) and distinct(String, String...) they will be executed in the order they where added which can affect the end result.

Parameters

  • limit - a limit that is ≥ 1 .

Throws

max

public Number max (
String fieldName
)

Finds the maximum value of a field.

Parameters

  • fieldName - the field to look for a maximum on. Only number fields are supported.

Returns

if no objects exist or they all have null as the value for the given field, null will be returned. Otherwise the maximum value is returned. When determining the maximum value, objects with null values are ignored.

Throws

maxRealmAny

public RealmAny maxRealmAny (
String fieldName
)

Finds the maximum value of a RealmAny field.

Parameters

  • fieldName - the field containing a RealmAny value.

Returns

if no objects exist or they all have null as the value for the given RealmAny field, RealmAny.Type.NULL will be returned. Otherwise the maximum RealmAny is returned. When determining the maximum RealmAny, objects with null values are ignored. See the RealmAny documentation for more details on how RealmAny values are compared.

Throws

maximumDate

public Date maximumDate (
String fieldName
)

Finds the maximum value of a field.

Parameters

  • fieldName - the field name.

Returns

if no objects exist or they all have null as the value for the given date field, null will be returned. Otherwise the maximum date is returned. When determining the maximum date, objects with null values are ignored.

Throws

min

public Number min (
String fieldName
)

Finds the minimum value of a field.

Parameters

  • fieldName - the field to look for a minimum on. Only number fields are supported.

Returns

if no objects exist or they all have null as the value for the given field, null will be returned. Otherwise the minimum value is returned. When determining the minimum value, objects with null values are ignored.

Throws

minRealmAny

public RealmAny minRealmAny (
String fieldName
)

Finds the minimum value of a RealmAny field.

Parameters

  • fieldName - the field containing a RealmAny value.

Returns

if no objects exist or they all have null as the value for the given RealmAny field, RealmAny.Type.NULL will be returned. Otherwise the minimum RealmAny is returned. When determining the minimum RealmAny, objects with null values are ignored. See the RealmAny documentation for more details on how RealmAny values are compared.

Throws

minimumDate

public Date minimumDate (
String fieldName
)

Finds the minimum value of a field.

Parameters

  • fieldName - the field name

Returns

if no objects exist or they all have null as the value for the given date field, null will be returned. Otherwise the minimum date is returned. When determining the minimum date, objects with null values are ignored.

Throws

not

public RealmQuery not ()

Negate condition.

Returns

the query object.

notEqualTo

public RealmQuery notEqualTo (
String fieldName,
ObjectId value
)

Not-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery notEqualTo (
String fieldName,
Decimal128 value
)

Not-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

public RealmQuery notEqualTo (
String fieldName,
RealmAny value,
Case casing
)

Not-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

  • casing - how casing is handled. Case.INSENSITIVE works only for the Latin-1 characters.

Returns

the query object.

Throws

public RealmQuery notEqualTo (
String fieldName,
String value,
Case casing
)

Not-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

  • casing - how casing is handled. Case.INSENSITIVE works only for the Latin-1 characters.

Returns

the query object.

Throws

public RealmQuery notEqualTo (
String fieldName,
String value
)

Not-equal-to comparison.

Parameters

  • fieldName - the field to compare.

  • value - the value to compare with.

Returns

the query object.

Throws

or

public RealmQuery or ()

Logical-or two conditions.

Returns

the query object.

rawPredicate

public RealmQuery rawPredicate (
String predicate,
java.lang.Object[] arguments
)

Create a text-based predicate using the Realm Query Language. This predicate can be combined with other raw or type safe predicates, it accepts Realm values as arguments.Class and property names used in the raw predicate can be either the names defined in the Realm Model classes or the internal names defined using the io.realm.annotations.RealmClass or io.realm.annotations.RealmField annotations. If a class or property name contains spaces those must be escaped.

Arguments are defined in the string predicate as $argument_index, where $argument_index is a decimal integer that specifies the position of the argument in the argument list. The first argument is referenced by $0, the second by $1, etc.See these docs for a more detailed description of the Realm Query Language.

Examples:

RealmQuery<Person> query = realm.where(Person.class);
// Simple query
query.rawPredicate("name = 'Jane'");
// Spaces in property name
query.rawPredicate("my\ property = 'Jane'");
// Multiple predicates
query.rawPredicate("name = 'Jane' OR name = 'John'")
// Collection queries
query.rawPredicate("children.@count > 3")
query.rawPredicate("ALL children.age > 18")
// Sub queries
query.rawPredicate("SUBQUERY(children, $child, $child.age > 21 AND $child.gender = 'male').@count > 0");
// Sort, Distinct, Limit
query.rawPredicate("name = 'Jane' SORT(lastName ASC) DISTINCT(city) LIMIT(5)");
// Arguments
query.rawPredicate("name = $0 AND age > $1", "Jane", 18);

Parameters

  • predicate - a Realm Query Language predicate.

  • arguments - Realm values for the predicate.

Throws

sort

public RealmQuery sort (
java.lang.String[] fieldNames,
io.realm.Sort[] sortOrders
)

Sorts the query result by the specific field names in the provided orders. Later fields will only be used if the previous field values are equal.Sorting is currently limited to character sets in 'Latin Basic', 'Latin Supplement', 'Latin Extended A', 'Latin Extended B' (UTF-8 range 0-591). For other character sets, sorting will have no effect.

Parameters

  • fieldNames - an array of field names to sort by.

  • sortOrders - how to sort the field names.

Throws

public RealmQuery sort (
String fieldName1,
Sort sortOrder1,
String fieldName2,
Sort sortOrder2
)

Sorts the query result by the specific field names in the provided orders. fieldName2 is only used in case of equal values in fieldName1 .

Sorting is currently limited to character sets in 'Latin Basic', 'Latin Supplement', 'Latin Extended A', 'Latin Extended B' (UTF-8 range 0-591). For other character sets, sorting will have no effect.

Parameters

  • fieldName1 - first field name

  • sortOrder1 - sort order for first field

  • fieldName2 - second field name

  • sortOrder2 - sort order for second field

Throws

public RealmQuery sort (
String fieldName,
Sort sortOrder
)

Sorts the query result by the specified field name and order.Sorting is currently limited to character sets in 'Latin Basic', 'Latin Supplement', 'Latin Extended A', 'Latin Extended B' (UTF-8 range 0-591). For other character sets, sorting will have no effect.

Parameters

  • fieldName - the field name to sort by.

  • sortOrder - how to sort the results.

Throws

public RealmQuery sort (
String fieldName
)

Sorts the query result by the specific field name in ascending order.Sorting is currently limited to character sets in 'Latin Basic', 'Latin Supplement', 'Latin Extended A', 'Latin Extended B' (UTF-8 range 0-591). For other character sets, sorting will have no effect.

Parameters

  • fieldName - the field name to sort by.

Throws

sum

public Number sum (
String fieldName
)

Calculates the sum of a given field.

Parameters

  • fieldName - the field to sum. Only number and RealmAny fields are supported.

Returns

the sum of fields of the matching objects. If no objects exist or they all have null as the value for the given field, 0 will be returned. When computing the sum, objects with null values are ignored. When applied to a RealmAny field, only numeric values will be summed up (Byte/Integer/Integer/Long/Float/Double/Decimal128) and the returning type will be Decimal128 .

Throws

← Interface RealmObjectSchema.Function
Class RealmResults →

On this page