E
- the class of the objects to be queried.public class RealmQuery<E> extends Object
Realm
or a 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 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.
Realm.where(Class)
,
RealmResults.where()
Modifier and Type | Method and 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.
|
RealmQuery<E> |
beginGroup()
Begin grouping of conditions ("left parenthesis").
|
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,
Date from,
Date to)
Between condition.
|
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> |
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.
|
long |
count()
Counts the number of objects that fulfill the query conditions.
|
RealmQuery<E> |
distinct(String fieldName)
Selects a distinct set of objects of a specific class.
|
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 to
beginGroup() . |
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,
Boolean value)
Equal-to comparison.
|
RealmQuery<E> |
equalTo(String fieldName,
Byte value)
Equal-to comparison.
|
RealmQuery<E> |
equalTo(String fieldName,
byte[] value)
Equal-to comparison.
|
RealmQuery<E> |
equalTo(String fieldName,
Date 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.
|
RealmResults<E> |
findAll()
Finds all objects that fulfill the query conditions.
|
RealmResults<E> |
findAllAsync()
Finds all objects that fulfill the query conditions.
|
RealmResults<E> |
findAllAsync(String subscriptionName)
Finds all objects that fulfill the query condition(s).
|
E |
findFirst()
Finds the first object that fulfills the query conditions.
|
E |
findFirstAsync()
Similar to
findFirst() but runs asynchronously on a worker thread. |
String |
getDescription()
Returns a textual description of this query.
|
Realm |
getRealm()
Returns the
Realm instance to which this query belongs. |
RealmQuery<E> |
greaterThan(String fieldName,
Date value)
Greater-than comparison.
|
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> |
greaterThanOrEqualTo(String fieldName,
Date value)
Greater-than-or-equal-to 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> |
in(String fieldName,
Boolean[] values)
In comparison.
|
RealmQuery<E> |
in(String fieldName,
Byte[] values)
In comparison.
|
RealmQuery<E> |
in(String fieldName,
Date[] 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> |
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 not
null . |
RealmQuery<E> |
isNull(String fieldName)
Tests if a field is
null . |
boolean |
isValid()
Checks if
RealmQuery is still valid to use i.e., the Realm instance hasn't been
closed and any parent RealmResults is still valid. |
RealmQuery<E> |
lessThan(String fieldName,
Date value)
Less-than comparison.
|
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> |
lessThanOrEqualTo(String fieldName,
Date value)
Less-than-or-equal-to 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> |
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.
|
Number |
min(String fieldName)
Finds the minimum value of a field.
|
Date |
minimumDate(String fieldName)
Finds the minimum value of a field.
|
RealmQuery<E> |
not()
Negate condition.
|
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,
byte[] value)
Not-equal-to comparison.
|
RealmQuery<E> |
notEqualTo(String fieldName,
Date 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> |
or()
Logical-or two conditions.
|
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.
|
Subscription |
subscribe()
Creates an anonymous subscription from this query or returns the existing Subscription if
one already existed.
|
Subscription |
subscribe(String name)
Creates an anonymous subscription from this query or returns the existing Subscription if
one already existed.
|
Number |
sum(String fieldName)
Calculates the sum of a given field.
|
public boolean isValid()
RealmQuery
is still valid to use i.e., the Realm
instance hasn't been
closed and any parent RealmResults
is still valid.true
if still valid to use, false
otherwise.public RealmQuery<E> isNull(String fieldName)
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
.
fieldName
- the field name.IllegalArgumentException
- if the field is not nullable.for further infomation.
public RealmQuery<E> isNotNull(String fieldName)
null
. Only works for nullable fields.fieldName
- the field name.IllegalArgumentException
- if the field is not nullable.for further infomation.
public RealmQuery<E> equalTo(String fieldName, String value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> equalTo(String fieldName, String value, Case casing)
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.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> equalTo(String fieldName, Byte value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> equalTo(String fieldName, byte[] value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> equalTo(String fieldName, Short value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> equalTo(String fieldName, Integer value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> equalTo(String fieldName, Long value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> equalTo(String fieldName, Double value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> equalTo(String fieldName, Float value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> equalTo(String fieldName, Boolean value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> equalTo(String fieldName, Date value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> in(String fieldName, String[] values)
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.IllegalArgumentException
- if the field isn't a String field.public RealmQuery<E> in(String fieldName, String[] values, Case casing)
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.IllegalArgumentException
- if the field isn't a String field.public RealmQuery<E> in(String fieldName, Byte[] values)
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.IllegalArgumentException
- if the field isn't a Byte field.public RealmQuery<E> in(String fieldName, Short[] values)
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.IllegalArgumentException
- if the field isn't a Short field.public RealmQuery<E> in(String fieldName, Integer[] values)
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.IllegalArgumentException
- if the field isn't a Integer field.public RealmQuery<E> in(String fieldName, Long[] values)
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.IllegalArgumentException
- if the field isn't a Long field.
empty.public RealmQuery<E> in(String fieldName, Double[] values)
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.IllegalArgumentException
- if the field isn't a Double field.
empty.public RealmQuery<E> in(String fieldName, Float[] values)
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.IllegalArgumentException
- if the field isn't a Float field.public RealmQuery<E> in(String fieldName, Boolean[] values)
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.IllegalArgumentException
- if the field isn't a Boolean.
or empty.public RealmQuery<E> in(String fieldName, Date[] values)
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.IllegalArgumentException
- if the field isn't a Date field.public RealmQuery<E> notEqualTo(String fieldName, String value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> notEqualTo(String fieldName, String value, Case casing)
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.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> notEqualTo(String fieldName, Byte value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> notEqualTo(String fieldName, byte[] value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> notEqualTo(String fieldName, Short value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> notEqualTo(String fieldName, Integer value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> notEqualTo(String fieldName, Long value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> notEqualTo(String fieldName, Double value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> notEqualTo(String fieldName, Float value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> notEqualTo(String fieldName, Boolean value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> notEqualTo(String fieldName, Date value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> greaterThan(String fieldName, int value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> greaterThan(String fieldName, long value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> greaterThan(String fieldName, double value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> greaterThan(String fieldName, float value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> greaterThan(String fieldName, Date value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> greaterThanOrEqualTo(String fieldName, int value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> greaterThanOrEqualTo(String fieldName, long value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> greaterThanOrEqualTo(String fieldName, double value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> greaterThanOrEqualTo(String fieldName, float value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field typepublic RealmQuery<E> greaterThanOrEqualTo(String fieldName, Date value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> lessThan(String fieldName, int value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> lessThan(String fieldName, long value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> lessThan(String fieldName, double value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> lessThan(String fieldName, float value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> lessThan(String fieldName, Date value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> lessThanOrEqualTo(String fieldName, int value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> lessThanOrEqualTo(String fieldName, long value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> lessThanOrEqualTo(String fieldName, double value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> lessThanOrEqualTo(String fieldName, float value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> lessThanOrEqualTo(String fieldName, Date value)
fieldName
- the field to compare.value
- the value to compare with.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> between(String fieldName, int from, int to)
fieldName
- the field to compare.from
- lowest value (inclusive).to
- highest value (inclusive).IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> between(String fieldName, long from, long to)
fieldName
- the field to compare.from
- lowest value (inclusive).to
- highest value (inclusive).IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> between(String fieldName, double from, double to)
fieldName
- the field to compare.from
- lowest value (inclusive).to
- highest value (inclusive).IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> between(String fieldName, float from, float to)
fieldName
- the field to compare.from
- lowest value (inclusive).to
- highest value (inclusive).IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> between(String fieldName, Date from, Date to)
fieldName
- the field to compare.from
- lowest value (inclusive).to
- highest value (inclusive).IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> contains(String fieldName, String value)
fieldName
- the field to compare.value
- the substring.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> contains(String fieldName, String value, Case casing)
fieldName
- the field to compare.value
- the substring.casing
- how to handle casing. Setting this to Case.INSENSITIVE
only works for Latin-1 characters.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> beginsWith(String fieldName, String value)
fieldName
- the field to compare.value
- the string.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> beginsWith(String fieldName, String value, Case casing)
fieldName
- the field to compare.value
- the substring.casing
- how to handle casing. Setting this to Case.INSENSITIVE
only works for Latin-1 characters.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> endsWith(String fieldName, String value)
fieldName
- the field to compare.value
- the string.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> endsWith(String fieldName, String value, Case casing)
fieldName
- the field to compare.value
- the substring.casing
- how to handle casing. Setting this to Case.INSENSITIVE
only works for Latin-1 characters.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> like(String fieldName, String value)
fieldName
- the field to compare.value
- the wildcard string.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> like(String fieldName, String value, Case casing)
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.IllegalArgumentException
- if one or more arguments do not match class or field type.public RealmQuery<E> beginGroup()
endGroup()
.endGroup()
public RealmQuery<E> endGroup()
beginGroup()
.beginGroup()
public RealmQuery<E> or()
public RealmQuery<E> and()
public RealmQuery<E> not()
public RealmQuery<E> isEmpty(String fieldName)
fieldName
- the field to compare.IllegalArgumentException
- if the field name isn't valid or its type isn't either a RealmList,
String or byte array.public RealmQuery<E> isNotEmpty(String fieldName)
fieldName
- the field to compare.IllegalArgumentException
- if the field name isn't valid or its type isn't either a RealmList,
String or byte array.public Number sum(String fieldName)
fieldName
- the field to sum. Only number fields are supported.null
as the value
for the given field, 0
will be returned. When computing the sum, objects with null
values
are ignored.IllegalArgumentException
- if the field is not a number type.public double average(String fieldName)
fieldName
- the field to calculate average on. Only number fields are supported.null
as the value for the given field,
0
will be returned. When computing the average, objects with null
values are ignored.IllegalArgumentException
- if the field is not a number type.public Number min(String fieldName)
fieldName
- the field to look for a minimum on. Only number fields are supported.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.IllegalArgumentException
- if the field is not a number type.public Date minimumDate(String fieldName)
fieldName
- the field namenull
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.UnsupportedOperationException
- if the query is not valid ("syntax error").public Number max(String fieldName)
fieldName
- the field to look for a maximum on. Only number fields are supported.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.IllegalArgumentException
- if the field is not a number type.public Date maximumDate(String fieldName)
fieldName
- the field name.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.UnsupportedOperationException
- if the query is not valid ("syntax error").public long count()
UnsupportedOperationException
- if the query is not valid ("syntax error").public RealmResults<E> findAll()
RealmResults
containing objects. If no objects match the condition, a list with zero
objects is returned.RealmResults
public RealmResults<E> findAllAsync()
If the Realm is a Query-based synchronized Realms, this method will also create an anonymous subscription that will download all server data matching the query.
RealmResults
. Users need to register a listener
RealmResults.addChangeListener(RealmChangeListener)
to be notified when the query completes.RealmResults
public RealmResults<E> findAllAsync(String subscriptionName)
This method is only available on query-based synchronized Realms and will also create a named subscription
that will synchronize all server data matching the query. Named subscriptions can be removed again by
calling Realm.unsubscribe(subscriptionName
.
RealmResults
. Users need to register a listener
RealmResults.addChangeListener(RealmChangeListener)
to be notified when the query completes.IllegalStateException
- If the Realm is a not a query-based synchronized Realm.RealmResults
public RealmQuery<E> sort(String fieldName)
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.
fieldName
- the field name to sort by.IllegalArgumentException
- if the field name does not exist.IllegalStateException
- if a sorting order was already defined.public RealmQuery<E> sort(String fieldName, Sort sortOrder)
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.
fieldName
- the field name to sort by.sortOrder
- how to sort the results.IllegalArgumentException
- if the field name does not exist.IllegalStateException
- if a sorting order was already defined.public RealmQuery<E> sort(String fieldName1, Sort sortOrder1, String fieldName2, Sort sortOrder2)
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.
fieldName1
- first field namesortOrder1
- sort order for first fieldfieldName2
- second field namesortOrder2
- sort order for second fieldIllegalArgumentException
- if the field name does not exist.IllegalStateException
- if a sorting order was already defined.public RealmQuery<E> sort(String[] fieldNames, Sort[] sortOrders)
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.
fieldNames
- an array of field names to sort by.sortOrders
- how to sort the field names.IllegalArgumentException
- if the field name does not exist.IllegalStateException
- if a sorting order was already defined.public RealmQuery<E> distinct(String fieldName)
Adding Index
to the corresponding field will make this operation much faster.
fieldName
- the field name.IllegalArgumentException
- if a field is null
, does not exist, is an unsupported type, or points
to linked fields.IllegalStateException
- if distinct field names were already defined.public RealmQuery<E> distinct(String firstFieldName, String... remainingFieldNames)
firstFieldName
- first field name to use when finding distinct objects.remainingFieldNames
- remaining field names when determining all unique combinations of field values.IllegalArgumentException
- if field names is empty or null
, does not exist,
is an unsupported type, or points to a linked field.IllegalStateException
- if distinct field names were already defined.public RealmQuery<E> limit(long limit)
Note that when using this method in combination with sort(String)
and
distinct(String)
they will be executed in the order they where added which can
affect the end result.
limit
- a limit that is ≥ 1
.IllegalArgumentException
- if the provided limit
is less than 1.public RealmQuery<E> alwaysTrue()
public RealmQuery<E> alwaysFalse()
public Realm getRealm()
Realm
instance to which this query belongs.
Calling BaseRealm.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.
Realm
instance this query belongs to.IllegalStateException
- if the Realm is an instance of DynamicRealm
or the
Realm
was already closed.public Subscription subscribe()
IllegalStateException
- if this method is not called inside a write transaction or if
the query is on a DynamicRealm
public Subscription subscribe(String name)
IllegalStateException
- if this method is not called inside a write transaction, if
the query is on a DynamicRealm
or a RealmList
.IllegalArgumentException
- if a subscription for a different query with the same name
already exists.public String getDescription()
public E findFirst()
null
if no object matches the query conditions.RealmObject
public E findFirstAsync()
findFirst()
but runs asynchronously on a worker thread. An 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.RealmObject
with isLoaded() == false
. Trying to access any field on
the returned object before it is loaded will throw an IllegalStateException
.IllegalStateException
- if this is called on a non-looper thread.