From 6b7f2fdda0ef5de0b883101ff0d50f4a1eebb12c Mon Sep 17 00:00:00 2001 From: cbullinger <115956901+cbullinger@users.noreply.github.com> Date: Wed, 15 Feb 2023 19:39:16 -0500 Subject: [PATCH] Apply feedback --- ...ndleTest.snippet.open-from-bundled-file.kt | 1 - source/includes/synced-realm-bundling.rst | 3 +- .../realm-files/bundle-a-realm.txt | 46 +++++++++---------- 3 files changed, 24 insertions(+), 26 deletions(-) diff --git a/source/examples/generated/kotlin/BundleTest.snippet.open-from-bundled-file.kt b/source/examples/generated/kotlin/BundleTest.snippet.open-from-bundled-file.kt index d295eb2a68..0a26d82313 100644 --- a/source/examples/generated/kotlin/BundleTest.snippet.open-from-bundled-file.kt +++ b/source/examples/generated/kotlin/BundleTest.snippet.open-from-bundled-file.kt @@ -12,4 +12,3 @@ bundledRealm.writeBlocking { isComplete = true }) } -assertEquals(2, bundledRealm.query().find().size) diff --git a/source/includes/synced-realm-bundling.rst b/source/includes/synced-realm-bundling.rst index 4f8d6c06ba..8058a4c56d 100644 --- a/source/includes/synced-realm-bundling.rst +++ b/source/includes/synced-realm-bundling.rst @@ -1,7 +1,6 @@ .. warning:: Synced Realm Bundling and Client Maximum Offline Time - If your application has enabled :ref:`advanced backend compaction - ` by configuring a + If your application has enabled :ref:`client maximum offline time `, users could experience a client reset the first time they open the bundled realm file. This can happen if the bundled realm file was generated more than **client maximum offline time** days before the user syncs the realm for the first time. diff --git a/source/sdk/kotlin/realm-database/realm-files/bundle-a-realm.txt b/source/sdk/kotlin/realm-database/realm-files/bundle-a-realm.txt index 7fd3c92bdb..ed9e345480 100644 --- a/source/sdk/kotlin/realm-database/realm-files/bundle-a-realm.txt +++ b/source/sdk/kotlin/realm-database/realm-files/bundle-a-realm.txt @@ -23,8 +23,7 @@ available to users on the initial launch of the app. .. tip:: Consider Initial Data Callback You can also add data to your realm the first time an application opens it - using - `InitialDataCallback <{+kotlin-local-prefix+}io.realm.kotlin/-initial-data-callback/index.html>`__. + using `InitialDataCallback <{+kotlin-local-prefix+}io.realm.kotlin/-initial-data-callback/index.html>`__. .. _kotlin-bundle-local-realm: @@ -96,29 +95,25 @@ add code to use it. Bundle a Synced Realm --------------------- -In most cases, you should *not* bundle a synced realm. - -.. tip:: Populate Data with Sync Subscriptions - - Rather than bundling a synced realm, you can populate your application - with data using sync subscriptions. If you add data using sync - subscriptions, you do not need to be concerned with data being older than - the client maximum online time while taking advantage of Flexible Sync's :ref:`trimming ` feature. - To learn more about using sync subscriptions, refer to - :ref:`Subscriptions `. - -.. _kotlin_bundle_sync_criteria: - -Criteria for Bundling a Synced Realm -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For eligible use cases, bundling lets users only download the synced changes that -occurred since you generated the bundled file. -You should only bundle a synced realm if your use case meets all of the +Bundling a synced realm lets users only download the synced changes that occurred since +you generated the bundled file. +However, there are additional impacts to consider when bundling a synced realm. +Because of this, we recommend that you bundle a synced realm only if your use case meets all of the following criteria: -- You can ensure that the users have a version of the app with the bundled synced realm +- For applications with :ref:`client maximum offline time ` enabled, + you can ensure that the users have a version of the app with the bundled synced realm that was created more recently than the client maximum offline time. + + .. warning:: + + If the bundled realm was last updated further in the past than + client maximum offline time, the user experiences a + :ref:`client reset ` the first time they open + the bundled realm file, which causes the application to + download the full state of the realm from the application + backend. This negates the advantages of bundling a realm file. + - The initial bundled data is very large **and** the app is being used in a situation with limited internet bandwidth, so an initial data download using sync subscriptions would take too long. @@ -126,7 +121,12 @@ following criteria: If a user doesn't have permission to view this data, it will be removed from their device when the realm sync with Atlas via a compensating write error. -.. include:: /includes/synced-realm-bundling.rst +As an alternative to bundling a synced realm, you can populate your application +with data using sync subscriptions. If you add data using sync +subscriptions, you do not need to be concerned with data being older than +the client maximum online time while taking advantage of Flexible Sync's :ref:`trimming ` feature. +To learn more about using sync subscriptions, refer to +:ref:`Subscriptions `. Create a Realm File for Bundling a Synced Realm ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~