Page updated Jan 16, 2024

Conflict resolution

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.

If data synchronization is enabled via AppSync, there can be different versions of the same object on the client and server. Multiple clients may have updated their respective copies of an object. DataStore will converge different object versions by applying conflict detection and resolution strategies. The default resolution is called Auto Merge. This strategy allows collections to grow, and prefers server-side versions of single-field data. Other strategies include Optimistic Concurrency control and Custom Lambda functions. For more information, see the AWS AppSync documentation on conflict handling.

Custom conflict resolution

To select a different conflict resolution strategy, navigate into your project from a terminal and run amplify update api. Choose Conflict resolution strategy to change the conflict detection and resolution strategies.

1? Please select from one of the below mentioned services:
2 `GraphQL`
3...
4? Select a setting to edit
5 `Conflict resolution strategy`
6? Select the default resolution strategy
7 Auto Merge
8❯ Optimistic Concurrency
9 Custom Lambda
10 Learn More

Per model configuration

Note that this flow will also allow you to change the strategy on each individual GraphQL type, though it is recommended to use the same strategy for your whole schema unless you have an advanced use case:

1? Do you want to override default per model settings? Yes
2? Select the models from below:
3❯◉ Post
4PostEditor
5User
6
7? Select the resolution strategy for Post model Custom Lambda
8? Select from the options below (Use arrow keys)
9Create a new Lambda Function
10 Existing Lambda Function

Custom configuration

DataStore has a few optional configurations, such as the ability to specify a custom handler for error messages that take place in any part of the system. You can also specify a custom conflict handler that runs if a mutation is rejected by AWS AppSync during one of the conflict resolution strategies.

Finally you can configure the number of records to sync as an upper bound on items (per-Model) which will be stored locally on the device, as well as a custom interval in minutes which is an override of the default 24 hour "base query" which runs as part of the Delta Sync process.

Custom configuration fields

  • errorHandler - handler function executed when Datastore encounters an unhandled error during its background operations
  • conflictHandler - handler function that decides how to resolve conflicts between local and remote model instances in a sync operation
  • syncMaxRecords - the maximum number of records to sync per execution
  • syncPageSize - the page size of each sync execution
  • syncInterval - the maximum interval (in seconds) for which the system will continue to perform delta queries. After this interval expires, the system performs a base query to retrieve all data.
  • syncExpression - sets a sync expression for a particular model to filter which data is synced locally. The expression is evaluated each time DataStore is started.
  • authModeStrategyType - the authorization mode strategy used to interface with AppSync backend

Example

The code below illustrates a conflict resolution handler for the Post model that retries a mutation with the same title, but the most recent remote data for all other fields. The conflict resolution handler discards conflicts for all other models (by passing .applyRemote to the resolve function).

1// custom conflict resolution configuration
2let dataStorePlugin = AWSDataStorePlugin(
3 modelRegistration: AmplifyModels(),
4 configuration: .custom(
5 errorHandler: { error in Amplify.Logging.error(error: error) },
6 conflictHandler: { (data, resolve) in
7 guard let localPost = data.local as? Post,
8 let remotePost = data.remote as? Post
9 else {
10 resolve(.applyRemote)
11 return
12 }
13
14 // always favor the title from the local post
15 let mergedModel = Post(
16 title: localPost.title,
17 rating: remotePost.rating,
18 status: remotePost.status
19 )
20 resolve(.retry(mergedModel))
21 },
22 // Sync configuration defaults:
23 syncInterval: .hours(24),
24 syncMaxRecords: 10_000,
25 syncPageSize: 1_000
26 )
27)