Page updated Jan 16, 2024

Observe in real time

Amplify iOS v1 is now in Maintenance Mode until May 31st, 2024. This means that we will continue to include updates to ensure compatibility with backend services and security. No new features will be introduced in v1.

Please use the latest version (v2) of Amplify Library for Swift to get started.

If you are currently using v1, follow these instructions to upgrade to v2.

Amplify libraries should be used for all new cloud connected applications. If you are currently using the AWS Mobile SDK for iOS, you can access the documentation here.

Observe model mutations in real-time

You can subscribe to changes on your Models. This reacts dynamically to updates of data to the underlying Storage Engine, which could be the result of GraphQL Subscriptions as well as Queries or Mutations that run against the backing AppSync API if you are synchronizing with the cloud.

1// In your type declaration, declare a cancellable to hold onto the subscription
2var postsSubscription: AnyCancellable?
3
4// Then in the body of your code, subscribe to the publisher
5func subscribeToPosts() {
6 postsSubscription = Amplify.DataStore.publisher(for: Todo.self)
7 .sink {
8 if case let .failure(error) = $0 {
9 print("Subscription received error - \(error.localizedDescription)")
10 }
11 }
12 receiveValue: { changes in
13 // handle incoming changes
14 print("Subscription received mutation: \(changes)")
15 }
16}
17
18// Then, when you're finished observing, cancel the subscription
19func unsubscribeFromPosts() {
20 postsSubscription?.cancel()
21}

DataStore.clear() and DataStore.stop() will stop the DataStore sync engine and keep any subscriptions connected. There will not be any additional subscription events received by the subscriber until DataStore is started (DataStore.start()) or the sync engine is re-initiated upon performing a DataStore operation (query/save/delete/publisher()).

This API is built on top of the Combine framework; therefore, it is only available on iOS 13 or higher.

The publisher(for:) API returns a standard AnyPublisher.

Observe query results in real-time

observeQuery(...) returns an initial data set, similar to query(...), and also automatically subscribes to subsequent changes to the query.

The first snapshot returned from observeQuery will contain the same results as calling query directly on your Model - a collection of all the locally-available records. Subsequent snapshots will be emitted as updates to the dataset are received in the local store.

While data is syncing from the cloud, snapshots will contain all of the items synced so far and an isSynced status of false. When the sync process is complete, a snapshot will be emitted with all the records in the local store and an isSynced status of true.

In addition to typical real-time use cases, observeQuery can be used on app launch to show your customers an initial data set from the local store while new data is being synced from cloud.

observeQuery also accepts the same predicates and sorting options as query.

1// In your type declaration, declare a cancellable to hold onto the subscription
2var postsSubscription: AnyCancellable?
3
4func subscribeToPosts() {
5 let post = Post.keys
6 self.postsSubscription = Amplify.DataStore.observeQuery(
7 for: Post.self,
8 where: post.title.beginsWith("post") && post.rating > 10.0,
9 sort: .ascending(post.rating)
10 )
11 .sink { completed in
12 switch completed {
13 case .finished:
14 print("finished")
15 case .failure(let error):
16 print("Error \(error)")
17 }
18 } receiveValue: { querySnapshot in
19 print("[Snapshot] item count: \(querySnapshot.items.count), isSynced: \(querySnapshot.isSynced)")
20 }
21}
22
23// Then, when you're finished observing, cancel the subscription
24func unsubscribeFromPosts() {
25 postsSubscription?.cancel()
26}