Docs Menu

Class RealmResults

On this page

java.lang.Object
io.realm.OrderedRealmCollectionImpl
io.realm.RealmResults

This class holds all the matches of a RealmQuery for a given Realm. The objects are not copied from the Realm to the RealmResults list, but are just referenced from the RealmResult instead. This saves memory and increases speed.

RealmResults are live views, which means that if it is on an Looper thread, it will automatically update its query results after a transaction has been committed. If on a non-looper thread, Realm.refresh() must be called to update the results.

Updates to RealmObjects from a RealmResults list must be done from within a transaction and the modified objects are persisted to the Realm file during the commit of the transaction.

A RealmResults object cannot be passed between different threads.

Notice that a RealmResults is never null not even in the case where it contains no objects. You should always use the RealmResults.size() method to check if a RealmResults is empty or not.

If a RealmResults is built on RealmList through RealmList.where() , it will become empty when the source RealmList gets deleted.

RealmResults can contain more elements than Integer.MAX_VALUE . In that case, you can access only first Integer.MAX_VALUE elements in it.

Tip
See also:
Modifier and Type
Method and Description
public void
public void
public <any>

Returns an Rx Observable that monitors changes to this RealmResults.

public <any>

Returns an Rx Flowable that monitors changes to this RealmResults.

public String

Returns a JSON representation of the matches of a RealmQuery .

Returns a frozen snapshot of this collection.

public boolean

Returns whether or not this object is frozen.

public boolean

Returns false if the results are not yet loaded, true if they are loaded.

public boolean
load ()

Makes an asynchronous query blocking.

public void

Removes all user-defined change listeners.

public void
public void

Removes the specified change listener.

public void
String fieldName,
byte[] value
)

Sets the binary value of the given field in all of the objects in the collection.

public void
String fieldName,
boolean value
)

Sets the boolean value of the given field in all of the objects in the collection.

public void
String fieldName,
byte value
)

Sets the byte value of the given field in all of the objects in the collection.

public void
String fieldName,
Date value
)

Sets the Date value of the given field in all of the objects in the collection.

public void
String fieldName,
Decimal128 value
)

Sets the Decimal128 value of the given field in all of the objects in the collection.

public void
String fieldName,
double value
)

Sets the double value of the given field in all of the objects in the collection.

public void
String fieldName,
float value
)

Sets the float value of the given field in all of the objects in the collection.

public void
String fieldName,
int value
)

Sets the int value of the given field in all of the objects in the collection.

public void
setList <T >(
)

Replaces the RealmList at the given field on all objects in this collection.

public void
String fieldName,
long value
)

Sets the long value of the given field in all of the objects in the collection.

public void
String fieldName
)

Sets the value to null for the given field in all of the objects in the collection.

public void
String fieldName,
)

Sets a reference to another object on the given field in all of the objects in the collection.

public void
String fieldName,
ObjectId value
)

Sets the ObjectId value of the given field in all of the objects in the collection.

public void
String fieldName,
short value
)

Sets the short value of the given field in all of the objects in the collection.

public void
String fieldName,
String value
)

Sets the String value of the given field in all of the objects in the collection.

public void
String fieldName,
Object value
)

Updates the field given by fieldName in all objects inside the query result.

String fieldName1,
Sort sortOrder1,
String fieldName2,
Sort sortOrder2
)

Sorts a collection based on the provided fields and sort orders.

public RealmQuery

Returns a RealmQuery , which can be used to query for specific objects from this collection.

  • Methods inherited from class java.lang.Object : getClass , hashCode , equals , clone , toString , notify , notifyAll , wait , wait , wait , finalize
  • Methods inherited from class java.util.AbstractCollection : iterator , size , isEmpty , contains , toArray , toArray , add , remove , containsAll , addAll , removeAll , retainAll , clear , toString
  • Methods inherited from class java.util.AbstractList : add , get , set , add , remove , indexOf , lastIndexOf , clear , addAll , iterator , listIterator , listIterator , subList , equals , hashCode , removeRange
  • Methods inherited from class io.realm.OrderedRealmCollectionImpl: isValid , isManaged , contains , get , first , first , last , last , deleteFromRealm , deleteAllFromRealm , iterator , listIterator , listIterator , sort , sort , sort , sort , size , min , minDate , max , maxDate , sum , average , remove , remove , removeAll , set , retainAll , deleteLastFromRealm , deleteFirstFromRealm , clear , add , add , addAll , addAll , createSnapshot , getRealm

Adds a change listener to this RealmResults .

Registering a change listener will not prevent the underlying RealmResults from being garbage collected. If the RealmResults is garbage collected, the change listener will stop being triggered. To avoid this, keep a strong reference for as long as appropriate e.g. in a class variable.

public class MyActivity extends Activity {
private RealmResults<Person> results; // Strong reference to keep listeners alive
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
results = realm.where(Person.class).findAllAsync();
results.addChangeListener(new OrderedRealmCollectionChangeListener<RealmResults<Person>>() {
@Override
public void onChange(RealmResults<Person> persons, OrderedCollectionChangeSet changeSet) {
// React to change
}
});
}
}

Parameters

  • listener - the change listener to be notified.

Throws

Adds a change listener to this RealmResults .

Registering a change listener will not prevent the underlying RealmResults from being garbage collected. If the RealmResults is garbage collected, the change listener will stop being triggered. To avoid this, keep a strong reference for as long as appropriate e.g. in a class variable.

public class MyActivity extends Activity {
private RealmResults<Person> results; // Strong reference to keep listeners alive
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
results = realm.where(Person.class).findAllAsync();
results.addChangeListener(new RealmChangeListener<RealmResults<Person>>() {
@Override
public void onChange(RealmResults<Person> persons) {
// React to change
}
});
}
}

Parameters

  • listener - the change listener to be notified.

Throws

public <any> asChangesetObservable ()

Returns an Rx Observable that monitors changes to this RealmResults. It will emit the current RealmResults when subscribed. For each update to the RealmResult a pair consisting of the RealmResults and the OrderedCollectionChangeSet will be sent. The changeset will be null the first time an RealmResults is emitted.

RealmResults will continually be emitted as the RealmResults are updated - onComplete will never be called.

Items emitted from Realm Observables are frozen (See freeze() . This means that they are immutable and can be read on any thread.

Realm Observables always emit items from the thread holding the live Realm. This means that if you need to do further processing, it is recommend to observe the values on a computation scheduler:

realm.where(Foo.class).findAllAsync().asChangesetObservable()
.observeOn(Schedulers.computation())
.map((rxResults, changes) -> doExpensiveWork(rxResults, changes))
.observeOn(AndroidSchedulers.mainThread())
.subscribe( ... );

Returns

RxJava Observable that only calls onNext . It will never call onComplete or OnError .

Throws

Tip
public <any> asFlowable ()

Returns an Rx Flowable that monitors changes to this RealmResults. It will emit the current RealmResults when subscribed to. RealmResults will continually be emitted as the RealmResults are updated - onComplete will never be called.

Items emitted from Realm Flowables are frozen (See freeze() . This means that they are immutable and can be read on any thread.

Realm Flowables always emit items from the thread holding the live RealmResults. This means that if you need to do further processing, it is recommend to observe the values on a computation scheduler:

realm.where(Foo.class).findAllAsync().asFlowable()
.observeOn(Schedulers.computation())
.map(rxResults -> doExpensiveWork(rxResults))
.observeOn(AndroidSchedulers.mainThread())
.subscribe( ... );

If you would like the asFlowable() to stop emitting items you can instruct RxJava to only emit only the first item by using the first() operator:

realm.where(Foo.class).findAllAsync().asFlowable()
.filter(results -> results.isLoaded())
.first()
.subscribe( ... ) // You only get the results once

Returns

RxJava Observable that only calls onNext . It will never call onComplete or OnError .

Throws

Tip
public String asJSON ()

Returns a JSON representation of the matches of a RealmQuery . Cycles will be returned as row indices. This is a helper method used to inspect data, or for debugging purpose, this method could pull a large string which could cause an OutOfMemory error.

Returns

string representation of a JSON array containing entries of the resulting RealmQuery .

Returns a frozen snapshot of this collection. The frozen copy can be read and queried from any thread without throwing an IllegalStateException .

Freezing a collection also creates a Realm which has its own lifecycle, but if the live Realm that spawned the original collection is fully closed (i.e. all instances across all threads are closed), the frozen Realm and this collection will be closed as well.

Frozen collections can be queried as normal, but trying to mutate it in any way or attempting to register a listener will throw an IllegalStateException .

Note: Keeping a large number of frozen collections with different versions alive can have a negative impact on the filesize of the Realm. In order to avoid such a situation, it is possible to set RealmConfiguration.Builder.maxNumberOfActiveVersions(long) .

Returns

a frozen copy of this collection.

public boolean isFrozen ()

Returns whether or not this object is frozen.

Returns

true if the object is frozen, false if it is not.

public boolean isLoaded ()

Returns false if the results are not yet loaded, true if they are loaded.

Returns

true if the query has completed and the data is available, false if the query is still running in the background.

public boolean load ()

Makes an asynchronous query blocking. This will also trigger any registered RealmChangeListener when the query completes.

Returns

true if it successfully completed the query, false otherwise.

Removes all user-defined change listeners.

Throws

Removes the specified change listener.

Parameters

  • listener - the change listener to be removed.

Throws

Removes the specified change listener.

Parameters

  • listener - the change listener to be removed.

Throws

public void setBlob (
String fieldName,
byte[] value
)

Sets the binary value of the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.
  • value - new value for the field.

Throws

public void setBoolean (
String fieldName,
boolean value
)

Sets the boolean value of the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.
  • value - new value for the field.

Throws

public void setByte (
String fieldName,
byte value
)

Sets the byte value of the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.
  • value - new value for the field.

Throws

public void setDate (
String fieldName,
Date value
)

Sets the Date value of the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.
  • value - new value for the field.

Throws

public void setDecimal128 (
String fieldName,
Decimal128 value
)

Sets the Decimal128 value of the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.
  • value - new value for the field.

Throws

public void setDouble (
String fieldName,
double value
)

Sets the double value of the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.
  • value - new value for the field.

Throws

public void setFloat (
String fieldName,
float value
)

Sets the float value of the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.
  • value - new value for the field.

Throws

public void setInt (
String fieldName,
int value
)

Sets the int value of the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.
  • value - new value for the field.

Throws

public void setList <T >(
)

Replaces the RealmList at the given field on all objects in this collection.

Parameters

  • fieldName - name of the field to update.
  • list - new value for the field.

Throws

  • IllegalArgumentException - if field name doesn't exist, isn't a RealmList field , if the objects in the list are not managed or the type of the objects in the list are wrong.
public void setLong (
String fieldName,
long value
)

Sets the long value of the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.
  • value - new value for the field.

Throws

public void setNull (
String fieldName
)

Sets the value to null for the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.

Throws

public void setObject (
String fieldName,
)

Sets a reference to another object on the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.
  • value - new object referenced by this field.

Throws

public void setObjectId (
String fieldName,
ObjectId value
)

Sets the ObjectId value of the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.
  • value - new value for the field.

Throws

public void setShort (
String fieldName,
short value
)

Sets the short value of the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.
  • value - new value for the field.

Throws

public void setString (
String fieldName,
String value
)

Sets the String value of the given field in all of the objects in the collection.

Parameters

  • fieldName - name of the field to update.
  • value - new value for the field.

Throws

public void setValue (
String fieldName,
Object value
)

Updates the field given by fieldName in all objects inside the query result.

This method will automatically try to convert numbers and booleans that are given as String to their appropriate type. For example "10" will be converted to 10 if the field type is RealmFieldType.INTEGER .

Using the typed setters like setInt(String, int) will be faster than using this method.

Parameters

  • fieldName - field to update
  • value - value to update with.

Throws

  • IllegalArgumentException - if the field could not be found, could not be updated or the argument didn't match the field type or could not be converted to match the underlying field type.
String fieldName1,
Sort sortOrder1,
String fieldName2,
Sort sortOrder2
)

Sorts a collection based on the provided fields and sort orders.

Returns

a new sorted RealmResults will be created and returned. The original collection stays unchanged.

Overrides

sort in class OrderedRealmCollectionImpl

public RealmQuery where ()

Returns a RealmQuery , which can be used to query for specific objects from this collection.

Returns

a RealmQuery object.

←  Class RealmQueryClass RealmSchema →
Give Feedback
© 2022 MongoDB, Inc.

About

  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.