Results

@frozen
public struct Results<Element> : Equatable, RealmCollectionImpl where Element : RealmCollectionValue
extension Results: RealmSubscribable
extension Results: Encodable where Element: Encodable

Results is an auto-updating container type in Realm returned from object queries.

Results can be queried with the same predicates as List<Element>, and you can chain queries to further filter query results.

Results always reflect the current state of the Realm on the current thread, including during write transactions on the current thread. The one exception to this is when using for...in enumeration, which will always enumerate over the objects which matched the query when the enumeration is begun, even if some of them are deleted or modified to be excluded by the filter during the enumeration.

Results are lazily evaluated the first time they are accessed; they only run queries when the result of the query is requested. This means that chaining several temporary Results to sort and filter your data does not perform any unnecessary work processing the intermediate state.

Once the results have been evaluated or a notification block has been added, the results are eagerly kept up-to-date, with the work done to keep them up-to-date done on a background thread whenever possible.

Results instances cannot be directly instantiated.

Show on GitHub

  • A human-readable description of the objects represented by the results.

    Declaration

    Swift

    public var description: String { get }
    Show on GitHub

Object Retrieval

  • Returns the object at the given index.

    Declaration

    Swift

    public subscript(position: Int) -> Element { get }

    Parameters

    index

    The index.
    Show on GitHub

Equatable

  • Declaration

    Swift

    public static func == (lhs: Results<Element>, rhs: Results<Element>) -> Bool
    Show on GitHub

Flexible Sync

  • Creates a SyncSubscription matching the Results’ local query. After committing the subscription to the realm’s local subscription set, the method will wait for downloads according to WaitForSyncMode.

    Unnamed subscriptions

    If .subscribe() is called without a name whose query matches an unnamed subscription, another subscription is not created.

    If .subscribe() is called without a name whose query matches a named subscription, an additional unnamed subscription is created.

    Named Subscriptions

    If .subscribe() is called with a name whose query matches an unnamed subscription, an additional named subscription is created.

    Existing name and query

    If .subscribe() is called with a name whose name is taken on a different query, the old subscription is updated with the new query.

    If .subscribe() is called with a name that’s in already in use by an identical query, no new subscription is created.

    Note

    This method will wait for all data to be downloaded before returning when WaitForSyncMode.always and .onCreation (when the subscription is first created) is used. This requires an internet connection if no timeout is set.

    Note

    This method opens a update transaction that creates or updates a subscription. It’s advised to not loop over this method in order to create multiple subscriptions. This could create a performance bottleneck by opening multiple unnecessary update transactions. To create multiple subscriptions at once use SyncSubscription.update.

    Warning

    This function is only supported for main thread and actor-isolated Realms.

    Warning

    This API is currently in Preview and may be subject to changes in the future.

    Declaration

    Swift

    @available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
@_unsafeInheritExecutor
public func subscribe(name: String? = nil, waitForSync: WaitForSyncMode = .onCreation, timeout: TimeInterval? = nil) async throws -> Results<Element>

    Parameters

    name

    The name applied to the subscription
    waitForSync

    WaitForSyncMode Determines the download behavior for the subscription. Defaults to .onCreation.
    timeout

    An optional client timeout. The client will cancel waiting for subscription downloads after this time has elapsed. Reaching this timeout doesn’t imply a server error.

    Return Value

    Returns self.

    Show on GitHub

  • Removes a SyncSubscription matching the Results’ local filter.

    The method returns after committing the subscription removal to the realm’s local subscription set. Calling this method will not wait for objects to be removed from the realm.

    In order for a named subscription to be removed, the Results must have previously created the subscription. For example:

    let results1 = try await realm.objects(Dog.self).where { $0.age > 1 }.subscribe(name: "adults")
let results2 = try await realm.objects(Dog.self).where { $0.age > 1 }.subscribe(name: "overOne")
let results3 = try await realm.objects(Dog.self).where { $0.age > 1 }.subscribe()
// This will unsubscribe from the subscription named "overOne". The "adults" and unnamed
// subscription still remain.
results2.unsubscribe()

    Note

    This method opens an update transaction that removes a subscription. It is advised to not use this method to batch multiple subscription changes to the server. To unsubscribe multiple subscriptions at once use SyncSubscription.update.

    Warning

    Calling unsubscribe on a Results does not remove the local filter from the Results. After calling unsubscribe, Results may still contain objects because other subscriptions may exist in the realm’s subscription set.

    Warning

    This API is currently in Preview and may be subject to changes in the future.

    Declaration

    Swift

    public func unsubscribe()
    Show on GitHub

Results

  • A publisher that emits Void each time the collection changes.

    Despite the name, this actually emits after the collection has changed.

    Declaration

    Swift

    public var objectWillChange: RealmPublishers.WillChange<Results> { get }
    Show on GitHub