Class RealmQuery<E>
- java.lang.Object
-
- io.realm.RealmQuery<E>
-
- Type Parameters:
E
- the class of the objects to be queried.
public class RealmQuery<E> extends Object
A RealmQuery encapsulates a query on aRealm
or aRealmResults
using the Builder pattern. The query is executed using eitherfindAll()
orfindFirst()
.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
Realm
is unordered, which means that there is no guarantee that querying a Realm will return the objects in the order they where inserted. Usesort(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 setsRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
tofalse
. This way queries will be forced to be launched from a non-UI thread. Alternatively, you can also usefindAllAsync()
orfindFirstAsync()
.- See Also:
- Builder pattern,
Realm.where(Class)
,RealmResults.where()
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description RealmQuery<E>
alwaysFalse()
This predicate will never match, resulting in the query always returning 0 results.RealmQuery<E>
alwaysTrue()
This predicate will always match.RealmQuery<E>
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.double
average(String fieldName)
Returns the average of a given field.Decimal128
averageDecimal128(String fieldName)
Returns the average of a given field.Decimal128
averageRealmAny(String fieldName)
Returns the average of a given field.RealmQuery<E>
beginGroup()
Begin grouping of conditions ("left parenthesis").RealmQuery<E>
beginsWith(String fieldName, RealmAny value)
Condition that the value of field begins with the specified string.RealmQuery<E>
beginsWith(String fieldName, RealmAny value, Case casing)
Condition that the value of field begins with the specified substring.RealmQuery<E>
beginsWith(String fieldName, String value)
Condition that the value of field begins with the specified string.RealmQuery<E>
beginsWith(String fieldName, String value, Case casing)
Condition that the value of field begins with the specified substring.RealmQuery<E>
between(String fieldName, double from, double to)
Between condition.RealmQuery<E>
between(String fieldName, float from, float to)
Between condition.RealmQuery<E>
between(String fieldName, int from, int to)
Between condition.RealmQuery<E>
between(String fieldName, long from, long to)
Between condition.RealmQuery<E>
between(String fieldName, RealmAny from, RealmAny to)
Between condition.RealmQuery<E>
between(String fieldName, Date from, Date to)
Between condition.RealmQuery<E>
between(String fieldName, Decimal128 from, Decimal128 to)
Between condition.RealmQuery<E>
contains(String fieldName, RealmAny value)
Condition that value of field contains the specified substring.RealmQuery<E>
contains(String fieldName, RealmAny value, Case casing)
Condition that value of field contains the specified substring.RealmQuery<E>
contains(String fieldName, String value)
Condition that value of field contains the specified substring.RealmQuery<E>
contains(String fieldName, String value, Case casing)
Condition that value of field contains the specified substring.RealmQuery<E>
containsEntry(String fieldName, Map.Entry<String,?> entry)
Condition that value, if a dictionary field, contains the specified entry.RealmQuery<E>
containsKey(String fieldName, String key)
Condition that value, if a dictionary field, contains the specified key.RealmQuery<E>
containsValue(String fieldName, byte[] value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, RealmAny value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, RealmModel value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, Boolean value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, Byte value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, Double value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, Float value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, Integer value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, Long value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, Short value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, String value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, Date value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, UUID value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, Decimal128 value)
Condition that value, if a dictionary field, contains the specified value.RealmQuery<E>
containsValue(String fieldName, ObjectId value)
Condition that value, if a dictionary field, contains the specified value.long
count()
Counts the number of objects that fulfill the query conditions.RealmQuery<E>
distinct(String firstFieldName, String... remainingFieldNames)
Selects a distinct set of objects of a specific class.RealmQuery<E>
endGroup()
End grouping of conditions ("right parenthesis") which was opened by a call tobeginGroup()
.RealmQuery<E>
endsWith(String fieldName, RealmAny value)
Condition that the value of field ends with the specified string.RealmQuery<E>
endsWith(String fieldName, RealmAny value, Case casing)
Condition that the value of field ends with the specified substring.RealmQuery<E>
endsWith(String fieldName, String value)
Condition that the value of field ends with the specified string.RealmQuery<E>
endsWith(String fieldName, String value, Case casing)
Condition that the value of field ends with the specified substring.RealmQuery<E>
equalTo(String fieldName, byte[] value)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, RealmAny value)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, RealmAny value, Case casing)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, Boolean value)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, Byte value)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, Double value)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, Float value)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, Integer value)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, Long value)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, Short value)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, String value)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, String value, Case casing)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, Date value)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, UUID value)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, Decimal128 value)
Equal-to comparison.RealmQuery<E>
equalTo(String fieldName, ObjectId value)
Equal-to comparison.RealmResults<E>
findAll()
Finds all objects that fulfill the query conditions.RealmResults<E>
findAllAsync()
Finds all objects that fulfill the query conditions.E
findFirst()
Finds the first object that fulfills the query conditions.E
findFirstAsync()
Similar tofindFirst()
but runs asynchronously on a worker thread.String
getDescription()
Returns a textual description of this query.long
getQueryPointer()
Returns the pointer to the underlying C++ query.Realm
getRealm()
Returns theRealm
instance to which this query belongs.String
getTypeQueried()
Returns the internal Realm name of the type being queried.RealmQuery<E>
greaterThan(String fieldName, double value)
Greater-than comparison.RealmQuery<E>
greaterThan(String fieldName, float value)
Greater-than comparison.RealmQuery<E>
greaterThan(String fieldName, int value)
Greater-than comparison.RealmQuery<E>
greaterThan(String fieldName, long value)
Greater-than comparison.RealmQuery<E>
greaterThan(String fieldName, RealmAny value)
Greater-than comparison.RealmQuery<E>
greaterThan(String fieldName, Date value)
Greater-than comparison.RealmQuery<E>
greaterThan(String fieldName, UUID value)
Greater-than comparison.RealmQuery<E>
greaterThan(String fieldName, Decimal128 value)
Greater-than comparison.RealmQuery<E>
greaterThan(String fieldName, ObjectId value)
Greater-than comparison.RealmQuery<E>
greaterThanOrEqualTo(String fieldName, double value)
Greater-than-or-equal-to comparison.RealmQuery<E>
greaterThanOrEqualTo(String fieldName, float value)
Greater-than-or-equal-to comparison.RealmQuery<E>
greaterThanOrEqualTo(String fieldName, int value)
Greater-than-or-equal-to comparison.RealmQuery<E>
greaterThanOrEqualTo(String fieldName, long value)
Greater-than-or-equal-to comparison.RealmQuery<E>
greaterThanOrEqualTo(String fieldName, RealmAny value)
Greater-than-or-equal-to comparison.RealmQuery<E>
greaterThanOrEqualTo(String fieldName, Date value)
Greater-than-or-equal-to comparison.RealmQuery<E>
greaterThanOrEqualTo(String fieldName, UUID value)
Greater-than-or-equal-to comparison.RealmQuery<E>
greaterThanOrEqualTo(String fieldName, Decimal128 value)
Greater-than-or-equal-to comparison.RealmQuery<E>
greaterThanOrEqualTo(String fieldName, ObjectId value)
Greater-than-or-equal-to comparison.RealmQuery<E>
in(String fieldName, RealmAny[] values)
In comparison.RealmQuery<E>
in(String fieldName, Boolean[] values)
In comparison.RealmQuery<E>
in(String fieldName, Byte[] values)
In comparison.RealmQuery<E>
in(String fieldName, Double[] values)
In comparison.RealmQuery<E>
in(String fieldName, Float[] values)
In comparison.RealmQuery<E>
in(String fieldName, Integer[] values)
In comparison.RealmQuery<E>
in(String fieldName, Long[] values)
In comparison.RealmQuery<E>
in(String fieldName, Short[] values)
In comparison.RealmQuery<E>
in(String fieldName, String[] values)
In comparison.RealmQuery<E>
in(String fieldName, String[] values, Case casing)
In comparison.RealmQuery<E>
in(String fieldName, Date[] values)
In comparison.RealmQuery<E>
isEmpty(String fieldName)
Condition that finds values that are considered "empty" i.e., an empty list, the 0-length string or byte array.RealmQuery<E>
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.RealmQuery<E>
isNotNull(String fieldName)
Tests if a field is notnull
.RealmQuery<E>
isNull(String fieldName)
Tests if a field isnull
.boolean
isValid()
Checks ifRealmQuery
is still valid to use i.e., theRealm
instance hasn't been closed and any parentRealmResults
is still valid.RealmQuery<E>
lessThan(String fieldName, double value)
Less-than comparison.RealmQuery<E>
lessThan(String fieldName, float value)
Less-than comparison.RealmQuery<E>
lessThan(String fieldName, int value)
Less-than comparison.RealmQuery<E>
lessThan(String fieldName, long value)
Less-than comparison.RealmQuery<E>
lessThan(String fieldName, RealmAny value)
Less-than comparison.RealmQuery<E>
lessThan(String fieldName, Date value)
Less-than comparison.RealmQuery<E>
lessThan(String fieldName, UUID value)
Less-than comparison.RealmQuery<E>
lessThan(String fieldName, Decimal128 value)
Less-than comparison.RealmQuery<E>
lessThan(String fieldName, ObjectId value)
Less-than comparison.RealmQuery<E>
lessThanOrEqualTo(String fieldName, double value)
Less-than-or-equal-to comparison.RealmQuery<E>
lessThanOrEqualTo(String fieldName, float value)
Less-than-or-equal-to comparison.RealmQuery<E>
lessThanOrEqualTo(String fieldName, int value)
Less-than-or-equal-to comparison.RealmQuery<E>
lessThanOrEqualTo(String fieldName, long value)
Less-than-or-equal-to comparison.RealmQuery<E>
lessThanOrEqualTo(String fieldName, RealmAny value)
Less-than-or-equal-to comparison.RealmQuery<E>
lessThanOrEqualTo(String fieldName, Date value)
Less-than-or-equal-to comparison.RealmQuery<E>
lessThanOrEqualTo(String fieldName, UUID value)
Less-than-or-equal-to comparison.RealmQuery<E>
lessThanOrEqualTo(String fieldName, Decimal128 value)
Less-than-or-equal-to comparison.RealmQuery<E>
lessThanOrEqualTo(String fieldName, ObjectId value)
Less-than-or-equal-to comparison.RealmQuery<E>
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.RealmQuery<E>
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.RealmQuery<E>
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.RealmQuery<E>
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.RealmQuery<E>
limit(long limit)
Limits the number of objects returned in case the query matched more objects.Number
max(String fieldName)
Finds the maximum value of a field.Date
maximumDate(String fieldName)
Finds the maximum value of a field.RealmAny
maxRealmAny(String fieldName)
Finds the maximum value of aRealmAny
field.Number
min(String fieldName)
Finds the minimum value of a field.Date
minimumDate(String fieldName)
Finds the minimum value of a field.RealmAny
minRealmAny(String fieldName)
Finds the minimum value of aRealmAny
field.RealmQuery<E>
not()
Negate condition.RealmQuery<E>
notEqualTo(String fieldName, byte[] value)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, RealmAny value)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, RealmAny value, Case casing)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, Boolean value)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, Byte value)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, Double value)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, Float value)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, Integer value)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, Long value)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, Short value)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, String value)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, String value, Case casing)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, Date value)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, UUID value)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, Decimal128 value)
Not-equal-to comparison.RealmQuery<E>
notEqualTo(String fieldName, ObjectId value)
Not-equal-to comparison.RealmQuery<E>
or()
Logical-or two conditions.RealmQuery<E>
rawPredicate(String predicate, Object... arguments)
Create a text-based predicate using the Realm Query Language.RealmQuery<E>
sort(String fieldName)
Sorts the query result by the specific field name in ascending order.RealmQuery<E>
sort(String[] fieldNames, Sort[] sortOrders)
Sorts the query result by the specific field names in the provided orders.RealmQuery<E>
sort(String fieldName, Sort sortOrder)
Sorts the query result by the specified field name and order.RealmQuery<E>
sort(String fieldName1, Sort sortOrder1, String fieldName2, Sort sortOrder2)
Sorts the query result by the specific field names in the provided orders.Number
sum(String fieldName)
Calculates the sum of a given field.
-
-
-
Method Detail
-
isValid
public boolean isValid()
Checks ifRealmQuery
is still valid to use i.e., theRealm
instance hasn't been closed and any parentRealmResults
is still valid.- Returns:
true
if still valid to use,false
otherwise.
-
isNull
public RealmQuery<E> isNull(String fieldName)
Tests if a field isnull
. Only works for nullable fields.For link queries, if any part of the link path is
null
the whole path is considered to benull
e.g.,isNull("linkField.stringField")
will be considered to benull
if eitherlinkField
orlinkField.stringField
isnull
.- Parameters:
fieldName
- the field name.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if the field is not nullable.- See Also:
for further infomation.
-
isNotNull
public RealmQuery<E> isNotNull(String fieldName)
Tests if a field is notnull
. Only works for nullable fields.- Parameters:
fieldName
- the field name.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if the field is not nullable.- See Also:
for further infomation.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable String value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable 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 toCase.INSENSITIVE
only works for Latin-1 characters.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> 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 toCase.INSENSITIVE
only works for Latin-1 characters.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable Decimal128 value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable ObjectId value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable UUID value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable Byte value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable byte[] value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable Short value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable Integer value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable Long value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable Double value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable Float value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- The query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable Boolean value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, @Nullable Date value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
equalTo
public RealmQuery<E> equalTo(String fieldName, RealmAny value)
Equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
in
public RealmQuery<E> in(String fieldName, @Nullable 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. Ifnull
or the empty array is provided the query will never match any results.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if the field isn't a String field.
-
in
public RealmQuery<E> in(String fieldName, @Nullable 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. Ifnull
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:
IllegalArgumentException
- if the field isn't a String field.
-
in
public RealmQuery<E> in(String fieldName, @Nullable 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. Ifnull
or the empty array is provided the query will never match any results.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if the field isn't a Byte field.
-
in
public RealmQuery<E> in(String fieldName, @Nullable 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. Ifnull
or the empty array is provided the query will never match any results.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if the field isn't a Short field.
-
in
public RealmQuery<E> in(String fieldName, @Nullable 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. Ifnull
or the empty array is provided the query will never match any results.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if the field isn't a Integer field.
-
in
public RealmQuery<E> in(String fieldName, @Nullable 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. Ifnull
or the empty array is provided the query will never match any results.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if the field isn't a Long field. empty.
-
in
public RealmQuery<E> in(String fieldName, @Nullable 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. Ifnull
or the empty array is provided the query will never match any results.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if the field isn't a Double field. empty.
-
in
public RealmQuery<E> in(String fieldName, @Nullable 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. Ifnull
or the empty array is provided the query will never match any results.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if the field isn't a Float field.
-
in
public RealmQuery<E> in(String fieldName, @Nullable 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. Ifnull
or the empty array is provided the query will never match any results.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if the field isn't a Boolean. or empty.
-
in
public RealmQuery<E> in(String fieldName, @Nullable 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. Ifnull
or the empty array is provided the query will never match any results.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if the field isn't a Date field.
-
in
public RealmQuery<E> in(String fieldName, 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. Ifnull
or the empty array is provided the query will never match any results.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if the field isn't a Date field.
-
notEqualTo
public RealmQuery<E> notEqualTo(String fieldName, @Nullable String value)
Not-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> notEqualTo(String fieldName, @Nullable 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> notEqualTo(String fieldName, UUID value)
Not-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> notEqualTo(String fieldName, RealmAny value)
Not-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> notEqualTo(String fieldName, @Nullable Byte value)
Not-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> notEqualTo(String fieldName, @Nullable byte[] value)
Not-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> notEqualTo(String fieldName, @Nullable Short value)
Not-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> notEqualTo(String fieldName, @Nullable Integer value)
Not-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> notEqualTo(String fieldName, @Nullable Long value)
Not-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> notEqualTo(String fieldName, @Nullable Double value)
Not-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> notEqualTo(String fieldName, @Nullable Float value)
Not-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> notEqualTo(String fieldName, @Nullable Boolean value)
Not-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
notEqualTo
public RealmQuery<E> notEqualTo(String fieldName, @Nullable Date value)
Not-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThan
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThan
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThan
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThan
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThan
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThan
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThan
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThan
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThan
public RealmQuery<E> greaterThan(String fieldName, UUID value)
Greater-than comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThanOrEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThanOrEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThanOrEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThanOrEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type
-
greaterThanOrEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThanOrEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThanOrEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThanOrEqualTo
public RealmQuery<E> greaterThanOrEqualTo(String fieldName, UUID value)
Greater-than-or-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
greaterThanOrEqualTo
public RealmQuery<E> greaterThanOrEqualTo(String fieldName, RealmAny value)
Greater-than-or-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThan
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThan
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThan
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThan
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThan
public RealmQuery<E> lessThan(String fieldName, UUID value)
Less-than comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThan
public RealmQuery<E> lessThan(String fieldName, double value)
Less-than comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThan
public RealmQuery<E> lessThan(String fieldName, float value)
Less-than comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThan
public RealmQuery<E> lessThan(String fieldName, Date value)
Less-than comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThan
public RealmQuery<E> lessThan(String fieldName, RealmAny value)
Less-than comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThanOrEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThanOrEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThanOrEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThanOrEqualTo
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThanOrEqualTo
public RealmQuery<E> lessThanOrEqualTo(String fieldName, UUID value)
Less-than-or-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThanOrEqualTo
public RealmQuery<E> lessThanOrEqualTo(String fieldName, double value)
Less-than-or-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThanOrEqualTo
public RealmQuery<E> lessThanOrEqualTo(String fieldName, float value)
Less-than-or-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThanOrEqualTo
public RealmQuery<E> lessThanOrEqualTo(String fieldName, Date value)
Less-than-or-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
lessThanOrEqualTo
public RealmQuery<E> lessThanOrEqualTo(String fieldName, RealmAny value)
Less-than-or-equal-to comparison.- Parameters:
fieldName
- the field to compare.value
- the value to compare with.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
between
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
between
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
between
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
between
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
between
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
between
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
between
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
contains
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
contains
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
contains
public RealmQuery<E> 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 toCase.INSENSITIVE
only works for Latin-1 characters.- Returns:
- The query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
contains
public RealmQuery<E> 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 toCase.INSENSITIVE
only works for Latin-1 characters.- Returns:
- The query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
beginsWith
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
beginsWith
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
beginsWith
public RealmQuery<E> 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 toCase.INSENSITIVE
only works for Latin-1 characters.- Returns:
- the query object
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
beginsWith
public RealmQuery<E> 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 toCase.INSENSITIVE
only works for Latin-1 characters.- Returns:
- the query object
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
endsWith
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
endsWith
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
endsWith
public RealmQuery<E> 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 toCase.INSENSITIVE
only works for Latin-1 characters.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
endsWith
public RealmQuery<E> 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 toCase.INSENSITIVE
only works for Latin-1 characters.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
like
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
like
public RealmQuery<E> 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:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
like
public RealmQuery<E> 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 toCase.INSENSITIVE
only works for Latin-1 characters.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
like
public RealmQuery<E> 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 toCase.INSENSITIVE
only works for Latin-1 characters.- Returns:
- the query object.
- Throws:
IllegalArgumentException
- if one or more arguments do not match class or field type.
-
beginGroup
public RealmQuery<E> beginGroup()
Begin grouping of conditions ("left parenthesis"). A group must be closed with a call toendGroup()
.- Returns:
- the query object.
- See Also:
endGroup()
-
endGroup
public RealmQuery<E> endGroup()
End grouping of conditions ("right parenthesis") which was opened by a call tobeginGroup()
.- Returns:
- the query object.
- See Also:
beginGroup()
-
or
public RealmQuery<E> or()
Logical-or two conditions.- Returns:
- the query object.
-
and
public RealmQuery<E> 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
-
not
public RealmQuery<E> not()
Negate condition.- Returns:
- the query object.
-
isEmpty
public RealmQuery<E> 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:
IllegalArgumentException
- if the field name isn't valid or its type isn't either a RealmList, String or byte array.
-
isNotEmpty
public RealmQuery<E> 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:
IllegalArgumentException
- if the field name isn't valid or its type isn't either a RealmList, String or byte array.
-
containsKey
public RealmQuery<E> containsKey(String fieldName, @Nullable 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, @Nullable 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, @Nullable 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, @Nullable 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, @Nullable 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, @Nullable 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, @Nullable 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, @Nullable 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, @Nullable 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, @Nullable 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, @Nullable 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, @Nullable 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, @Nullable 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, @Nullable UUID 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, RealmAny 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsValue
public RealmQuery<E> containsValue(String fieldName, RealmModel 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:
IllegalArgumentException
- if the field name isn't valid.
-
containsEntry
public RealmQuery<E> containsEntry(String fieldName, Map.Entry<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:
IllegalArgumentException
- if the field name isn't valid.
-
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 withnull
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 beDecimal128
. - Throws:
IllegalArgumentException
- if the field is not a number type.RealmException
- if called from the UI thread after opting out viaRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
.
-
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 withnull
values are ignored. - Throws:
IllegalArgumentException
- if the field is not a number type.RealmException
- if called from the UI thread after opting out viaRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
.
-
averageDecimal128
@Nullable 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 usingaverage(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 field0
will be returned. When computing the average, objects withnull
values are ignored. - Throws:
IllegalArgumentException
- if the field is not a Decimal128 type.RealmException
- if called from the UI thread after opting out viaRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
.
-
averageRealmAny
@Nullable 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 usingaverage(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 field0
will be returned. When computing the average, objects withnull
values are ignored. - Throws:
IllegalArgumentException
- if the field is not a RealmAny type.RealmException
- if called from the UI thread after opting out viaRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
.
-
min
@Nullable 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 withnull
values are ignored. - Throws:
IllegalArgumentException
- if the field is not a number type.RealmException
- if called from the UI thread after opting out viaRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
.
-
minimumDate
@Nullable 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 withnull
values are ignored. - Throws:
UnsupportedOperationException
- if the query is not valid ("syntax error").RealmException
- if called from the UI thread after opting out viaRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
.
-
minRealmAny
public RealmAny minRealmAny(String fieldName)
Finds the minimum value of aRealmAny
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 withnull
values are ignored. See theRealmAny
documentation for more details on how RealmAny values are compared. - Throws:
UnsupportedOperationException
- if the query is not valid ("syntax error").RealmException
- if called from the UI thread after opting out viaRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
.
-
max
@Nullable 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 withnull
values are ignored. - Throws:
IllegalArgumentException
- if the field is not a number type.RealmException
- if called from the UI thread after opting out viaRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
.
-
maximumDate
@Nullable 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 withnull
values are ignored. - Throws:
UnsupportedOperationException
- if the query is not valid ("syntax error").
-
maxRealmAny
public RealmAny maxRealmAny(String fieldName)
Finds the maximum value of aRealmAny
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 withnull
values are ignored. See theRealmAny
documentation for more details on how RealmAny values are compared. - Throws:
UnsupportedOperationException
- if the query is not valid ("syntax error").
-
count
public long count()
Counts the number of objects that fulfill the query conditions.- Returns:
- the number of matching objects.
- Throws:
UnsupportedOperationException
- if the query is not valid ("syntax error").RealmException
- if called from the UI thread after opting out viaRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
.
-
findAll
public RealmResults<E> 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 setsRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
tofalse
. This way you will be forced to launch your queries from a non-UI thread, otherwise calls to this method will throw aRealmException
. Alternatively, you can usefindAllAsync()
.- Returns:
- a
RealmResults
containing objects. If no objects match the condition, a list with zero objects is returned. - Throws:
RealmException
- if called from the UI thread after opting out viaRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
.- See Also:
RealmResults
-
findAllAsync
public RealmResults<E> 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 listenerRealmResults.addChangeListener(RealmChangeListener)
to be notified when the query completes. - See Also:
RealmResults
-
sort
public RealmQuery<E> 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:
IllegalArgumentException
- if the field name does not exist.IllegalStateException
- if a sorting order was already defined.
-
sort
public RealmQuery<E> 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:
IllegalArgumentException
- if the field name does not exist.IllegalStateException
- if a sorting order was already defined.
-
sort
public RealmQuery<E> 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 infieldName1
.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 namesortOrder1
- sort order for first fieldfieldName2
- second field namesortOrder2
- sort order for second field- Throws:
IllegalArgumentException
- if the field name does not exist.IllegalStateException
- if a sorting order was already defined.
-
sort
public RealmQuery<E> sort(String[] fieldNames, 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:
IllegalArgumentException
- if the field name does not exist.IllegalStateException
- if a sorting order was already defined.
-
distinct
public RealmQuery<E> distinct(String firstFieldName, 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:
IllegalArgumentException
- if field names is empty ornull
, does not exist, is an unsupported type, or points to a linked field.IllegalStateException
- if distinct field names were already defined.
-
limit
public RealmQuery<E> 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)
anddistinct(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:
IllegalArgumentException
- if the providedlimit
is less than 1.
-
alwaysTrue
public RealmQuery<E> alwaysTrue()
This predicate will always match.
-
alwaysFalse
public RealmQuery<E> alwaysFalse()
This predicate will never match, resulting in the query always returning 0 results.
-
rawPredicate
public RealmQuery<E> rawPredicate(String predicate, 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
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.RealmClass
orRealmField
annotations. If a class or property name contains spaces those must be escaped.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:
IllegalArgumentException
- if there is an syntax error.
-
getRealm
public Realm getRealm()
Returns theRealm
instance to which this query belongs.Calling
Closeable.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:
IllegalStateException
- if the Realm is an instance ofDynamicRealm
or theRealm
was already closed.
-
getDescription
public String getDescription()
Returns a textual description of this query.- Returns:
- the textual description of the query.
-
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.
-
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.
-
findFirst
@Nullable 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 setsRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
tofalse
. This way you will be forced to launch your queries from a non-UI thread, otherwise calls to this method will throw aRealmException
. Alternatively, you can usefindFirstAsync()
.- Returns:
- the object found or
null
if no object matches the query conditions. - Throws:
RealmException
- if called from the UI thread after opting out viaRealmConfiguration.Builder.allowQueriesOnUiThread(boolean)
.- See Also:
RealmObject
-
findFirstAsync
public E findFirstAsync()
Similar tofindFirst()
but runs asynchronously on a worker thread. An listener should be registered to the returnedRealmObject
to get the notification when query completes. The registered listener will also be triggered if there are changes made to the queriedRealmObject
. If theRealmObject
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
withisLoaded() == false
. Trying to access any field on the returned object before it is loaded will throw anIllegalStateException
. - Throws:
IllegalStateException
- if this is called on a non-looper thread.
-
-