Amplify DataStore best practices - Amplify DataStore: Use Cases and Implementation

Amplify DataStore best practices

Clear offline data on sign-in and sign-out

We recommend that you clear out user-specific data for shared device scenarios. This prevents security and privacy issues. If the application has authentication enabled and your schema defines user-specific data, make sure to clear the data stored during a previous session. Developers can do this by calling the DataStore.clear() API method.

Immutable models

Models in DataStore are immutable. Manually forcing a synchronization with the backend is not possible. The following example shows how to create a record:

await DataStore.save( new Whitepaper({ title: "Amplify DataStore – Use cases and implementation", pages: 30, year: 2021 }) );

To update a record, you must use the copyOf function provided by your library of choice to apply updates to the item’s fields rather than mutating the instance directly.

const original = await DataStore.query(Whitepaper, "123"); await DataStore.save( Whitepaper.copyOf(original, updated => { updated.title = `title ${Date.now()}`; }) );

Start developing your application in offline mode

To avoid updating the cloud backend, it is a recommended practice to develop the application on offline mode until the developer is comfortable with the schema defined. After the model is considered stable, the cloud synchronization can be enabled, and the local data will be automatically synchronized with the backend.

Be aware of how schema changes affect offline data

If the developer decides to modify the application’s schema, Amplify DataStore will evaluate at start-up to decide if these changes impact the storage structure of the application already deployed to users. If it confirms that the schema lost its integrity, DataStore will remove the items stored and will perform a sync with the backend if cloud sync is enabled.

Sync configuration with base and delta queries

If cloud sync is enabled, at the first application start, the Sync Engine will run a GraphQL query that populates the Storage Engine from the network using a base query, which is the Sync Engine’s most basic form of synchronization that retrieves the baseline state of your records. This will replicate the current state of your backend with your client application. If your solution relies on a limited amount of data, this solution could fit your needs and you might want to continue to replicate the backend constantly.

For cases where the solution relies on large datasets and the connectivity on the client changes frequently, the base query might become cumbersome and your application could face performance issues. For this scenario, a second query can be performed, called a delta query. The delta query guarantees that, once the base query runs and hydrates the cache for the first time, on every network reconnection only the changed data is captured.

Selective sync

To download and persist only a subset of the data, developers can benefit from a selective synchronization approach. This will limit the number of records that your application collects from the backend by filtering them by expressions or by limiting the number of items that will be stored. This strategy can be applied per device and user, meaning that you can have different rules for different use cases. For example, if an application needs to display multiple alert levels that groups of users can handle separately, developers can create the following:

DataStore.configure({ syncExpressions: [ syncExpression(Post, () => { return alert => alert.level('gt', 5); }) ] });

This will guarantee that only alerts with levels that are greater than 5 will be synced to the device’s local storage.