diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-access-subscription-set-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-access-subscription-set-description.rst new file mode 100644 index 0000000000..a4f70e5e3b --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-access-subscription-set-description.rst @@ -0,0 +1,7 @@ +You can access the subscription set through the ``subscriptions()`` public +member function of a :cpp-sdk:`realm `. This +provides the :cpp-sdk:`sync_subscription_set +` where you can use the +``size()``, ``find()``, or ``update()`` member functions. You perform all +operations to add, find, update, remove, or watch subscriptions through this +property. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-add-subscription-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-add-subscription-description.rst new file mode 100644 index 0000000000..6b5e2e0206 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-add-subscription-description.rst @@ -0,0 +1,10 @@ +To add a subscription: + +1. Open the synced database. +#. Access the database's ``subscriptions`` property. +#. Open a subscription ``update`` block. +#. Call the ``add`` method with the object type to append the new subscription + to the subscription set. Optionally, add a query to subscribe to only a + subset of the objects that match the query. + +.. include:: /includes/note-cpp-supports-subset-of-rql.rst diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-named-subscription-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-named-subscription-description.rst new file mode 100644 index 0000000000..2906771174 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-named-subscription-description.rst @@ -0,0 +1,8 @@ +To update a subscription set, use the ``subscription().updates()`` function. +This gives you access to a :cpp-sdk:`mutable_sync_subscription_set +` where you can use the +``update_subscription()`` function to update a specific :cpp-sdk:`sync_subscription +`. + +You can change a ``sync_subscription``'s query in an update. You can add, remove, +or update the query string for a given ``sync_subscription``. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..65de4b06e9 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst @@ -0,0 +1,7 @@ +C++ does not provide the ability to change an unnamed subscription. If you know +in advance that your app may need to change subscriptions, :ref:`create the +subscription with a name `. + +Alternately, you can :ref:`remove all subscriptions +`, and :ref:`create new subscriptions +` with the desired query. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-find-subscription-description.rst new file mode 100644 index 0000000000..d066d646b6 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -0,0 +1,4 @@ +To find a specific subscription, call the ``subscriptions().find()`` method +with the name of a subscription. + +You cannot find unnamed subscriptions in C++. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst new file mode 100644 index 0000000000..7328eaf1a8 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst @@ -0,0 +1,6 @@ +After you update subscriptions, call ``refresh()`` on the :cpp-sdk:`realm +`. This updates the database and outstanding objects +managed by the database to point to the most recent data. + +.. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.refresh-the-realm.cpp + :language: cpp diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst new file mode 100644 index 0000000000..f1a3ed12ff --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst @@ -0,0 +1,2 @@ +You can remove all subscriptions in a subscription set using the ``clear()`` +function. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-not-supported.rst new file mode 100644 index 0000000000..cbdaf4abf7 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-not-supported.rst @@ -0,0 +1,8 @@ +C++ does not provide the ability to remove all subscriptions to a specific +object type. If you know in advance that your app may need to remove +subscriptions, :ref:`create the subscription with a name +`. + +Alternately, you can :ref:`remove all subscriptions +`, and then :ref:`add subscriptions +` that your app still needs. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst new file mode 100644 index 0000000000..1352044012 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst @@ -0,0 +1,5 @@ +C++ does not provide the ability to remove all unnamed subscriptions. + +Instead, you can :ref:`remove all subscriptions +`, and then :ref:`add subscriptions +` that your app still needs. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..1cd8a4af8a --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,4 @@ +You can remove a specific subscription by name using the ``remove()`` function +inside a ``subscription().updates()`` block. Removing a subscription by name +throws an error if the subscription does not exist, so you should check for a +subscription before removing it. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-subscription-by-reference-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-subscription-by-reference-not-supported.rst new file mode 100644 index 0000000000..8f03828d03 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-subscription-by-reference-not-supported.rst @@ -0,0 +1,7 @@ +C++ does not provide the ability to remove a subscription by reference. If +you know in advance that your app may need to remove subscriptions, +:ref:`create the subscription with a name `. + +Alternately, you can :ref:`remove all subscriptions +`, and then :ref:`add subscriptions +` that your app still needs. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..fe09a2d741 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst @@ -0,0 +1,7 @@ +C++ does not provide the ability to remove a single unnamed subscription. If +you know in advance that your app may need to remove subscriptions, +:ref:`create the subscription with a name `. + +Alternately, you can :ref:`remove all subscriptions +`, and then :ref:`add subscriptions +` that your app still needs. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-subscription-set-state-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-subscription-set-state-not-supported.rst new file mode 100644 index 0000000000..39726ed371 --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-subscription-set-state-not-supported.rst @@ -0,0 +1 @@ +C++ does not currently provide an API to check the state of a subscription set. diff --git a/source/includes/api-details/cpp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-not-supported.rst b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-not-supported.rst new file mode 100644 index 0000000000..3dfc9d778b --- /dev/null +++ b/source/includes/api-details/cpp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-not-supported.rst @@ -0,0 +1 @@ +C++ does not currently provide an API to wait for subscription changes to sync. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-access-subscription-set-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-access-subscription-set-description.rst new file mode 100644 index 0000000000..a0db7d17f2 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-access-subscription-set-description.rst @@ -0,0 +1,5 @@ +You can access the :dotnet-sdk:`SubscriptionSet +` through the database +:dotnet-sdk:`Subscriptions ` +property. You perform all operations to add, find, update, remove, or watch +subscriptions through this property. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription-description.rst new file mode 100644 index 0000000000..4d094bc13a --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription-description.rst @@ -0,0 +1,20 @@ +To add a subscription: + +1. Open the synced database. +#. Access the database's :dotnet-sdk:`Realm.Subscriptions ` + property. +#. Open a subscription ``Update`` block. +#. Create a subscription to a specific object type. Optionally add a query to + subscribe to only a subset of the objects that match the query. +#. Call the ``Subscriptions.Add`` method with the subscription you just created + to append the new subscription to the subscription set. + +Alternately, to add a subscription to an existing subscription set, create +the query and then call :dotnet-sdk:`IQueryable.SubscribeAsync() +`. + +The ``SubscribeAsync`` method is shorthand for using :dotnet-sdk:`SubscriptionSet.Update() +` +to create an update block, and then calling the :dotnet-sdk:`SubscriptionSet.Add() +` +method on the ``SubscriptionSet``. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-named-subscription-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-named-subscription-description.rst new file mode 100644 index 0000000000..8c706fa020 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-named-subscription-description.rst @@ -0,0 +1,12 @@ +You can update a named subscription with a new query. To update a subscription's +query, pass the new query and a subscription option with the name of the +subscription that you want to update to the +``SubscriptionSet.Add()`` method. Like adding a new subscription, +you must update a subscription within an update block by calling +``SubscriptionSet.Update()`` method. + +The ``SubscriptionOptions.UpdateExisting`` field must be set to ``true``, or +else attempting to change the subscription throws an exception. + +In the following example, long running tasks are re-defined to be any tasks that +have taken more than 130 minutes. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..a992561df3 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst @@ -0,0 +1,7 @@ +C# does not provide the ability to change an unnamed subscription. If you know +in advance that your app may need to change subscriptions, :ref:`create the +subscription with a name `. + +Alternately, you can :ref:`delete the unnamed subscription +`, and :ref:`create a new subscription +` with the desired query. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst new file mode 100644 index 0000000000..bfcf602047 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -0,0 +1,8 @@ +To find a specific subscription by name, call the +:dotnet-sdk:`Find() ` +method with the name of a subscription. + +You can also find a subscription matching a specific query by calling the +:dotnet-sdk:`Find() +` +method with an IQueryable argument. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst new file mode 100644 index 0000000000..ece7173f0e --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst @@ -0,0 +1,8 @@ +Within an update block, you can remove all subscriptions from the +subscriptions set. Call the :dotnet-sdk:`RemoveAll() +` +method on the ``SubscriptionSet``. + +By default, the ``RemoveAll()`` method only removes unnamed subscriptions. +Set the optional ``removedName`` boolean to ``true`` to also remove named +subscriptions. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst new file mode 100644 index 0000000000..8aecf715e7 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst @@ -0,0 +1,14 @@ +Within an update block, you can remove remove all unnamed subscriptions of a +class by passing the class name as a string to the +:dotnet-sdk:`RemoveAll("ClassName") +` +method. The ``RemoveAll()`` method has an optional second argument that is a +boolean, ``removedName``, which also removes the named subscriptions if it is +set to ``true``. ``removedName`` is set to false by default. + +Alternatively, you can remove all unnamed subscriptions of an object type +with :dotnet-sdk:`RemoveAll() +`. +The ``RemoveAll()`` method has an optional boolean ``removedName`` argument +that also removes the named subscriptions if it is set to ``true``. The ``removedName`` +argument is set to false by default. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst new file mode 100644 index 0000000000..40e1d2267a --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst @@ -0,0 +1,5 @@ +Within an update block, you can remove all unnamed subscriptions from the +subscriptions set. Call the :dotnet-sdk:`RemoveAll() +` +method on the ``SubscriptionSet``, with the optional boolean ``removedName`` +argument set to false. This removes only unnamed subscriptions. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..12c9660706 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,4 @@ +Within an update block, you can remove a specific subscription by name. Pass the +name to the :dotnet-sdk:`Remove() +` +method on the ``SubscriptionSet``. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst new file mode 100644 index 0000000000..89a887081b --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst @@ -0,0 +1,4 @@ +Within an update block, you can remove a specific subscription by reference. +Pass the subscription to the :dotnet-sdk:`Remove() +` +method on the ``SubscriptionSet``. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst new file mode 100644 index 0000000000..190c5885e8 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst @@ -0,0 +1,7 @@ +Within an update block, you can remove an unnamed subscription by its query. +Pass the query to the :dotnet-sdk:`Remove() +` +method on the ``SubscriptionSet``. + +In the following example, the subscription to tasks with an owner named 'Ben' is +removed from the subscriptions set. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst new file mode 100644 index 0000000000..096ded9576 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst @@ -0,0 +1,8 @@ +You can bootstrap the database with an initial subscription set +when you open it with a :dotnet-sdk:`FlexibleSyncConfiguration +`. Set the +:dotnet-sdk:`PopulateInitialSubscriptions +` +parameter to a callback that is invoked when the database instance is created. +Add the queries you want to use to bootstrap the database, as shown in the +following example. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-subscription-set-state-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-subscription-set-state-description.rst new file mode 100644 index 0000000000..970bb40b92 --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-subscription-set-state-description.rst @@ -0,0 +1,9 @@ +Use the :dotnet-sdk:`SubscriptionSet.State +` +property to read the current state of the subscription set. + +The ``Superseded`` state is a :dotnet-sdk:`SubscriptionSetState +` that can occur when another +thread updates a subscription on a different instance of the subscription set. +If the state becomes ``Superseded``, you must obtain a new instance of the +subscription set before you can update it. diff --git a/source/includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst new file mode 100644 index 0000000000..fe50bbc2ab --- /dev/null +++ b/source/includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst @@ -0,0 +1,17 @@ +Use the :dotnet-sdk:`SubscriptionSet.WaitForSynchronizationAsync() +` +method to wait for the server to acknowledge this set of subscriptions. If the +server rejects the change, the :dotnet-sdk:`SubscriptionSetState +` will be an error state, and +an exception will be thrown. + +An exception may occur if: + +- An unsupported query is subscribed to. Subscribing to an unsupported query + will pause synchronization. To resume synchronization, :ref:`remove the + unsupported query `. + +- You are performing an invalid action, such as adding an object that does not + match a subscription. This triggers a :ref:`client reset `: + data is erased from the device, and a new copy of the data is created without + any subscriptions in the set. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-access-subscription-set-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-access-subscription-set-description.rst new file mode 100644 index 0000000000..a75798c3c8 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-access-subscription-set-description.rst @@ -0,0 +1,5 @@ +you can access a +:flutter-sdk:`SubscriptionSet `, a +collection of subscriptions, through the ``Realm.subscriptions`` property. +You perform all operations to add, find, update, remove, or watch +subscriptions through this property. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-add-subscription-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-add-subscription-description.rst new file mode 100644 index 0000000000..3cf9f96457 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-add-subscription-description.rst @@ -0,0 +1,11 @@ +To add a subscription: + +1. Open the synced database. +#. Access the database's ``subscriptions`` property to interact with the + :flutter-sdk:`SubscriptionSet `. +#. Open a subscription ``update`` block by calling + :flutter-sdk:`SubscriptionSet.update() `. +#. Call the ``add`` method to append the new subscription to the + subscription set. +#. Pass a ``RealmResults`` query that you can create using the + :ref:`Realm Query Language query `. Optionally, add a query name. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-change-named-subscription-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-change-named-subscription-description.rst new file mode 100644 index 0000000000..4539d167ee --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-change-named-subscription-description.rst @@ -0,0 +1,10 @@ +You can update a named subscription with a new query. To update a subscription's +query, open an update block with ``SubscriptionSet.update()``. +In the callback function of the update block, pass the following arguments to ``MutableSubscriptionSet.add()``: + +- The new query +- The name of the subscription that you want to update +- ``update: true`` + +In the following example, long trains are re-defined to be any trains that +have more than 10 cars. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..77d9e230dd --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst @@ -0,0 +1,7 @@ +Dart does not provide the ability to change an unnamed subscription. If you +know in advance that your app may need to change subscriptions, :ref:`create +the subscription with a name `. + +Alternately, you can :ref:`delete the unnamed subscription +`, and :ref:`create a new subscription +` with the desired query. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst new file mode 100644 index 0000000000..f6dcfc1c71 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst @@ -0,0 +1,3 @@ +If you add a duplicate **unnamed** subscription with the same query, the SDK +automatically removes it; adding an identical **named** subscription is a +no-op. Therefore, in both cases, duplicate subscriptions are ignored. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst new file mode 100644 index 0000000000..79cbe7901a --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -0,0 +1,7 @@ +To find a specific subscription by name, call the +:flutter-sdk:`findByName() ` +method with the name of a subscription. + +You can also find a subscription matching a specific query by calling the +:flutter-sdk:`find() ` method with an +RQL query. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst new file mode 100644 index 0000000000..e4e2bef0ea --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst @@ -0,0 +1,2 @@ +Within a subscription update block, you can remove all subscriptions from the +subscriptions set with :flutter-sdk:`MutableSubscriptionSet.clear() `. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst new file mode 100644 index 0000000000..48af685b31 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst @@ -0,0 +1,3 @@ +You can remove all subscriptions for a given SDK object type. Within a +subscription update block, call +:flutter-sdk:`MutableSubscriptionSet.removeByType() `. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst new file mode 100644 index 0000000000..2cf97aa4c8 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst @@ -0,0 +1,4 @@ +Within a subscription update block, you can remove all unnamed subscriptions +from the subscriptions set by calling :flutter-sdk:`MutableSubscriptionSet.clear() +` with an ``unnamedOnly`` argument +set to ``true``. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..a72c42cf45 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,3 @@ +Within an update block, you can remove a specific subscription by name. Pass +the name to :flutter-sdk:`MutableSubscriptionSet.removeByName() +`. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst new file mode 100644 index 0000000000..14ca6d8c65 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst @@ -0,0 +1,4 @@ +You can remove a subscription if you have a reference to its :flutter-sdk:`Subscription +` object. +Within a subscription update block, pass the ``Subscription`` reference to +:flutter-sdk:`MutableSubscriptionSet.remove() `. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst new file mode 100644 index 0000000000..703a0bba83 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst @@ -0,0 +1,6 @@ +Within an update block, you can remove a specific subscription by query. +Open an update block with ``SubscriptionSet.update()``. Pass the +``Subscription`` to :flutter-sdk:`MutableSubscriptionSet.removeByQuery() +`. + +In the following example, the subscription for all ``Plane`` objects is removed. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-description.rst new file mode 100644 index 0000000000..e6faa6f4c6 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-description.rst @@ -0,0 +1,11 @@ +To subscribe to a query, pass the following arguments to ``subscribe()``: + +- ``RealmResults query``: Required. A ``RealmResults`` object that you can + create using the :ref:`Realm Query Language `. +- ``String name``: Optional. Name for the subscription that you can refer to. +- ``bool update``: Optional. When true, adding a subscription with an existing + name replaces the existing query with the new query. When false, the SDK + throws an exception for duplicate subscriptions. Only use with named + subscriptions. + +In the following example, we subscribe to two new named queries. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst new file mode 100644 index 0000000000..8af0b49ddc --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst @@ -0,0 +1,7 @@ +To subscribe to a query with a name, pass the following arguments to ``subscribe()``: + +- ``RealmResults query``: Required. A ``RealmResults`` object that you can create using the + :ref:`Realm Query Language `. +- ``String name``: Optional. Name for the subscription that you can refer to. + +In the following example, we subscribe to two new named queries. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscription-set-state-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscription-set-state-description.rst new file mode 100644 index 0000000000..6b9a6dcd3d --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-subscription-set-state-description.rst @@ -0,0 +1,8 @@ +Use the :flutter-sdk:`Realm.subscriptions.state ` +property to read the current state of the subscription set. + +The ``superseded`` state is a :flutter-sdk:`SubscriptionSetState +` that can occur when another thread updates a +subscription on a different instance of the subscription set. If the state +becomes ``superseded``, you must obtain a new instance of the subscription set +before you can update it. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst new file mode 100644 index 0000000000..2ff60fb92c --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst @@ -0,0 +1,2 @@ +You can unsubscribe from a query's results using :flutter-sdk:`unsubscribe() +`. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst new file mode 100644 index 0000000000..3836c62430 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst @@ -0,0 +1,21 @@ +When you do need specify the desired sync behavior, configure the +:flutter-sdk:`waitForSyncMode ` option. + +This example uses the ``firstTime`` option, which is the default behavior. +A subscription with ``firstTime`` behavior only waits for sync to finish when a +subscription is first created. + +.. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.wait-first-time-subscribe-api.dart + :language: dart + :emphasize-lines: 5 + +The other supported ``waitForSyncMode`` options are: + +- ``always``: Wait to download matching objects every time your app launches. + The app must have an internet connection at every launch. +- ``never``: Never wait to download matching objects. The app needs an internet + connection for the user to authenticate the first time the app launches, but + can open offline on subsequent launches using cached credentials. + +You can optionally specify a :flutter-sdk:`cancellationToken ` +to limit how long the sync download runs. diff --git a/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst b/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst new file mode 100644 index 0000000000..23967457f8 --- /dev/null +++ b/source/includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst @@ -0,0 +1,11 @@ +Use :flutter-sdk:`Realm.subscriptions.waitForSynchronization() ` +to wait for the server to acknowledge this set of subscriptions. +If the server rejects the change, and an exception is thrown. + +An exception may occur if: + +- You subscribe to an unsupported query. Subscribing to an unsupported query will pause synchronization. + To resume synchronization, :ref:`remove the unsupported query `. +- You are performing an invalid action, such as adding an object that does not match a subscription. + This triggers a :ref:`client reset `: data is erased from the device, + and a new copy of the data is created without any subscriptions in the set. diff --git a/source/includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst b/source/includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst new file mode 100644 index 0000000000..e1e62323ee --- /dev/null +++ b/source/includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst @@ -0,0 +1,3 @@ +The selected language does not provide a dedicated API to set initial +subscriptions. Instead, refer to the :ref:`sdks-sync-subscriptions-add-subscription` +section on this page. diff --git a/source/includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst b/source/includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst new file mode 100644 index 0000000000..e51a3ebe76 --- /dev/null +++ b/source/includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst @@ -0,0 +1,3 @@ +The selected language does not support the API that enables you to subscribe +to a query. Instead, refer to :ref:`manually manage queries +`. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-access-subscription-set-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-access-subscription-set-description.rst new file mode 100644 index 0000000000..82b79ba8f6 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-access-subscription-set-description.rst @@ -0,0 +1,4 @@ +You can access the :java-sdk:`SubscriptionSet ` +through the :java-sdk:`Realm.getSubscriptions() ` +method. You perform all operations to add, find, update, remove, or watch +subscriptions through this property. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-add-subscription-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-add-subscription-description.rst new file mode 100644 index 0000000000..b382351c85 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-add-subscription-description.rst @@ -0,0 +1,12 @@ +To add a subscription: + +1. Open the synced database. +#. Call the ``getSubscriptions()`` method to interact with the subscription set. +#. Open a subscription ``update`` block using + :java-sdk:`SubscriptionSet.update() + `. +#. Use the :java-sdk:`MutableSubscriptionSet.addOrUpdate() + ` + method to append the new subscription to the subscription set. +#. Call ``Subscription.create()`` with a query to a specific object type. + Optionally, add a name for the query. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-change-named-subscription-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-change-named-subscription-description.rst new file mode 100644 index 0000000000..7d5f2b3775 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-change-named-subscription-description.rst @@ -0,0 +1,5 @@ +You can update subscriptions using :java-sdk:`SubscriptionSet.update() +`. +In this example, we use :java-sdk:`MutableSubscriptionSet.addOrUpdate() +` +to update the query for the subscription named "my frog subscription". diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..71d788c522 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst @@ -0,0 +1,7 @@ +The Java SDK does not support updating subscriptions created without a name. +If you know in advance that your app may need to change subscriptions, +:ref:`create the subscription with a name `. + +Alternately, you can look up unnamed subscriptions by query, :ref:`remove them +from the subscription set `, and :ref:`create a new +subscription ` with the desired query. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-duplicate-subscription-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-duplicate-subscription-description.rst new file mode 100644 index 0000000000..37b53635a2 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-duplicate-subscription-description.rst @@ -0,0 +1,9 @@ +Subscription names must be unique. Adding a subscription +with the same name as an existing subscription throws an error. + +If you do not explicitly name a subscription, and instead subscribe +to the same unnamed query more than once, the SDD does not persist +duplicate queries to the subscription set. + +If you subscribe to the same query more than once under different names, +the SDK persists both subscriptions to the subscription set. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-find-subscription-description.rst new file mode 100644 index 0000000000..85746ac7ed --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -0,0 +1,8 @@ +To find a specific subscription by name, call the +:java-sdk:`find() ` +method with the name of a subscription. + +You can also find a subscription matching a specific query by calling the +:java-sdk:`find() +` method +with a :java-sdk:`RealmQuery ` argument. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst new file mode 100644 index 0000000000..a5d01f3365 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst @@ -0,0 +1,3 @@ +To remove all subscriptions from the subscription set, use +:java-sdk:`removeAll() ` +with no arguments. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst new file mode 100644 index 0000000000..f9cad38d10 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst @@ -0,0 +1,4 @@ +If you want to remove all subscriptions to a specific object type, pass +a class to the :java-sdk:`removeAll() +` +method. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst new file mode 100644 index 0000000000..8b4cf26586 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst @@ -0,0 +1,6 @@ +The Java SDK does not provide a method to remove all unnamed subscriptions. + +Instead, you can remove all subscriptions from the subscription set, with +:java-sdk:`removeAll() `. +Then, :ref:`create the new subscriptions +` that your app needs. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..b3bc09b867 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,5 @@ +You can remove a specific subscription query +using :java-sdk:`MutableSubscriptionSet.remove() +`. +The ``remove()`` method takes a subscription name, or a reference to the +subscription itself. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst new file mode 100644 index 0000000000..0c30406c98 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst @@ -0,0 +1,4 @@ +You can remove a subscription by reference when you pass the +subscription to the :java-sdk:`MutableSubscriptionSet.remove() +` +method. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..bb3ea0c8e7 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst @@ -0,0 +1,5 @@ +The Java SDK does not provide a method to remove an unnamed subscription +directly. However, you can look up a subscription by query, and pass the +subscription to the :java-sdk:`MutableSubscriptionSet.remove() +` +method to remove it from the subscription set. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-subscription-set-state-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-subscription-set-state-description.rst new file mode 100644 index 0000000000..92eca87599 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-subscription-set-state-description.rst @@ -0,0 +1,17 @@ +You can watch the state of the subscription set with the +:java-sdk:`SubscriptionSet.State ` enum. +You can use subscription state to: + +- Show a progress indicator while data is downloading +- Find out when a subscription set becomes superseded + +You can access the state of your application's subscription set using +:java-sdk:`SubscriptionSet.getState() `. + +Superseded +`````````` + +``SUPERSEDED`` is a ``SubscriptionSet.State`` that can occur when another +thread writes a subscription on a different instance of the +subscription set. If the state becomes ``SUPERSEDED``, you must obtain +a new instance of the subscription set before you can write to it. diff --git a/source/includes/api-details/java/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst b/source/includes/api-details/java/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst new file mode 100644 index 0000000000..2afb9f60e3 --- /dev/null +++ b/source/includes/api-details/java/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst @@ -0,0 +1,11 @@ +Use the :java-sdk:`waitForInitialRemoteData() +` +builder method to force your application to block until client subscription +data synchronizes to the backend before opening the database. + +Alternately, you could use :java-sdk:`SubscriptionSet.waitForSynchronization() +` +or :java-sdk:`SubscriptionSet.waitForSynchronizationAsync() +` +to delay execution until subscription sync completes after instantiating +a sync connection. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-set-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-set-js-ts-description.rst new file mode 100644 index 0000000000..d08316c6ae --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-set-js-ts-description.rst @@ -0,0 +1,4 @@ +When using a synced database, you can access a ``SubscriptionSet``, a +collection of subscriptions, through the :js-sdk:`realm.subscriptions +` property. You perform all operations to +add, find, update, remove, or watch subscriptions through this property. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-add-subscription-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-add-subscription-js-ts-description.rst new file mode 100644 index 0000000000..a839d6898a --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-add-subscription-js-ts-description.rst @@ -0,0 +1,11 @@ +To add a subscription: + +1. Open the synced database. +#. Access the database's :js-sdk:`realm.subscriptions + ` property. +#. Open a subscription ``update`` block. +#. Create a subscription to a specific object type. Optionally add a query to + subscribe to only a subset of the objects that match the query. +#. Call the ``add()`` method with the subscription you just created + to append the new subscription to the subscription set. Optionally, you can + name the subscription. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-named-subscription-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-named-subscription-js-ts-description.rst new file mode 100644 index 0000000000..03cb2426f4 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-named-subscription-js-ts-description.rst @@ -0,0 +1,11 @@ +You can update a named subscription with a new query. To update a subscription's +query, pass the new query and a subscription option with the name of the +subscription that you want to update to the ``MutableSubscriptionSet.add()`` +method. Like adding a new subscription, you must update a subscription within a +transaction by calling ``subscriptions.update()``. + +The ``SubscriptionOptions.throwOnUpdate`` field must be set to ``false``, or +else attempting to change the subscription throws an exception. + +In the following example, long-running tasks are re-defined to be any tasks that +have taken more than 180 minutes. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-unnamed-subscription-js-ts-not-supported.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-unnamed-subscription-js-ts-not-supported.rst new file mode 100644 index 0000000000..2a69c057c4 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-change-unnamed-subscription-js-ts-not-supported.rst @@ -0,0 +1,7 @@ +The JS SDK does not provide the ability to change an unnamed subscription. If +you know in advance that your app may need to change subscriptions, :ref:`create +the subscription with a name `. + +Alternately, you can :ref:`delete the unnamed subscription +`, and :ref:`create a new subscription +` with the desired query. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst new file mode 100644 index 0000000000..8492b6225e --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst @@ -0,0 +1,8 @@ +To find a specific subscription by name, call the +:js-sdk:`findByName() ` +method with the name of a subscription. + +You can also find a subscription matching a specific query by calling the +:js-sdk:`findByQuery() +` method with a +query to match against. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-js-ts-description.rst new file mode 100644 index 0000000000..75ec192a8f --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-js-ts-description.rst @@ -0,0 +1,4 @@ +To remove all subscriptions from the subscriptions set, execute a transaction on +the subscriptions set. Call :js-sdk:`removeAll() +` on the +``MutableSubscriptionSet`` within the transaction. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-js-ts-description.rst new file mode 100644 index 0000000000..4cad711bff --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-js-ts-description.rst @@ -0,0 +1,5 @@ +To remove all subscriptions on a specific object type, execute a transaction on +the subscriptions set. Within the transaction, pass the object type as a string +to the :js-sdk:`removeByObjectType +` method on the +``MutableSubscriptionSet``. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-js-ts-description.rst new file mode 100644 index 0000000000..62124d90df --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-js-ts-description.rst @@ -0,0 +1,3 @@ +You can remove all unnamed subscriptions from the subscription set by +calling ``.removeUnnamed()`` on ``mutableSubs``. ``.removeUnnamed()`` returns +the number of unnamed subscriptions removed. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..f97ec343a8 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,5 @@ +To remove a specific subscription by name, execute a transaction on the +subscriptions set. Within the transaction, pass the name to the +:js-sdk:`removeByName() +` method on the +``MutableSubscriptionSet``. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-subscription-by-reference-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-subscription-by-reference-js-ts-description.rst new file mode 100644 index 0000000000..c95b0be89f --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-subscription-by-reference-js-ts-description.rst @@ -0,0 +1,5 @@ +If you have a reference to a subscription, you can remove that subscription. To +do so, execute a transaction on the subscriptions set. Within the transaction, +pass the reference variable to the :js-sdk:`removeSubscription +` method on the +``MutableSubscriptionSet``. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst new file mode 100644 index 0000000000..656bdcbaab --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst @@ -0,0 +1,7 @@ +You can remove a specific subscription by query by executing a transaction on +the subscriptions set. Pass the query to the :js-sdk:`remove() +` method on the +``MutableSubscriptionSet`` within a transaction. + +In the following example, the subscription to tasks with an owner named 'Ben' is +removed from the subscriptions set. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-set-initial-subscriptions-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-set-initial-subscriptions-js-ts-description.rst new file mode 100644 index 0000000000..014f56125a --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-set-initial-subscriptions-js-ts-description.rst @@ -0,0 +1,10 @@ +To set initial subscriptions, include the ``initialSubscriptions`` field in +your realm's :js-sdk:`SyncConfiguration `. +Within the ``initialSubscriptions`` object, add an ``update`` +field set to a callback that subscribes to queries. + +By default, initial subscriptions are only created the first time the database +is opened. If your app needs to rerun this initial subscription every time the app +starts, you can set ``rerunOnOpen`` to ``true``. You might need to do this to +re-run dynamic time ranges or other queries that require a re-computation of +static variables for the subscription. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-js-ts-description.rst new file mode 100644 index 0000000000..fceca4706a --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-js-ts-description.rst @@ -0,0 +1,13 @@ +To subscribe to a query: + +#. Query for the objects that you want to read and write. +#. Call ``subscribe()`` on the query results to create a sync subscription for + objects matching the query. +#. Pass a ``SubscriptionOptions`` object. + +Most of the time, you should give your subscriptions a name. If you don't, the +name is set to :mdn:`null `. + +If you use ``filtered()`` on an unnamed query subscription, the subscription +identifier is based on the ``filtered`` query. This means that every time your +query string changes, ``subscribe()`` will create a new subscription. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst new file mode 100644 index 0000000000..055e5a5a88 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst @@ -0,0 +1,7 @@ +To subscribe to a query: + +#. Query for the objects that you want to read and write. +#. Call ``subscribe()`` on the query results to create a sync subscription for + objects matching the query. +#. Pass a ``SubscriptionOptions`` object that contains the ``name`` property to + ``subscribe()``. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscription-set-state-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscription-set-state-js-ts-description.rst new file mode 100644 index 0000000000..6803e3ba45 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-subscription-set-state-js-ts-description.rst @@ -0,0 +1,13 @@ +You can check the :js-sdk:`subscription state ` +to see if the server has acknowledged the subscription and the device has +downloaded the data locally. + +You can use subscription state to: + +- Trigger error handling +- Show if the transaction is pending or has completed +- Find out when a subscription set is superseded, and you should obtain a + new instance of the subscription set to write a subscription change + +The :js-sdk:`SubscriptionSetState enum ` +provides information about the status of a subscription. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-unsubscribe-from-query-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-unsubscribe-from-query-js-ts-description.rst new file mode 100644 index 0000000000..777a390204 --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-unsubscribe-from-query-js-ts-description.rst @@ -0,0 +1 @@ +To unsubscribe from a query's results, call the ``unsubscribe()`` method. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst new file mode 100644 index 0000000000..6f4f742c8c --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst @@ -0,0 +1,16 @@ +When you call the ``.subscribe()`` method on a query, you can optionally +specify the ``WaitForSync`` behavior, which is an enum of options describing +different sync behaviors. + +The supported ``WaitForSync`` options are: + +- ``FirstTime``: Wait for sync to finish when a subscription is first created. +- ``Always``: Wait to download matching objects every time your app launches. + The app must have an internet connection at every launch. +- ``Never``: Never wait to download matching objects. The app needs an internet + connection for the user to authenticate the first time the app launches, but + can :ref:`open offline ` on subsequent + launches using cached credentials. + +You can optionally specify a ``timeout`` value to limit how long the sync +download runs. diff --git a/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-js-ts-description.rst b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-js-ts-description.rst new file mode 100644 index 0000000000..b0efe1a73d --- /dev/null +++ b/source/includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-js-ts-description.rst @@ -0,0 +1,10 @@ +You can wait for subscription changes to sync in two ways: + +- ``await`` the call to :js-sdk:`SubscriptionSet.update() + `, which returns a promise + that resolves when the ``SubscriptionSet`` is synchronized, or is rejected if + there was an error during synchronization. +- Explicitly call :js-sdk:`SubscriptionSet.waitForSynchronization() + ` to + wait for the server to acknowledge this set of subscriptions and return the + matching objects, or throw an error. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-access-subscription-set-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-access-subscription-set-description.rst new file mode 100644 index 0000000000..0dc2e2e433 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-access-subscription-set-description.rst @@ -0,0 +1,4 @@ +You can access a :kotlin-sync-sdk:`SubscriptionSet +` through the +database ``subscriptions`` property. You perform all operations to add, find, +update, remove, or watch subscriptions through this property. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-add-subscription-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-add-subscription-description.rst new file mode 100644 index 0000000000..2a40bef164 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-add-subscription-description.rst @@ -0,0 +1,10 @@ +To add a subscription: + +1. Open the synced database. +#. Access the database's ``subscriptions`` property. +#. Open a subscription ``update`` block. +#. Call the ``add`` method to append the new subscription to the + subscription set. +#. Pass a query with the name of the object type. Optionally, use + :ref:`Realm Query Language ` to query only a subset of the objects. + You can also add an optional query name. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-named-subscription-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-named-subscription-description.rst new file mode 100644 index 0000000000..44328b0aa0 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-named-subscription-description.rst @@ -0,0 +1,10 @@ +You can update subscriptions using +:kotlin-sync-sdk:`SubscriptionSet.update() +`. + +In this example, we use :kotlin-sync-sdk:`MutableSubscriptionSet.add() +`. +to update the query for the subscription named ``"bob_smith_teams"``. + +You must set the ``updateExisting`` parameter to ``true`` to update +a subscription - otherwise the SDK throws an exception. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..41ff017cf1 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst @@ -0,0 +1,7 @@ +Kotlin does not provide the ability to change an unnamed subscription. If you +know in advance that your app may need to change subscriptions, :ref:`create the +subscription with a name `. + +Alternately, you can :ref:`delete the unnamed subscription +`, and :ref:`create a new subscription +` with the desired query. \ No newline at end of file diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-find-subscription-description.rst new file mode 100644 index 0000000000..1d706baa57 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -0,0 +1,10 @@ +To find a specific subscription by name, call the +:kotlin-sync-sdk:`findByName() +` +method with the name of a subscription. + +You can also find a subscription matching a specific query by calling the +:kotlin-sync-sdk:`findByQuery() +` +method with a :kotlin-sdk:`RealmQuery ` +argument. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst new file mode 100644 index 0000000000..792c44ad45 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst @@ -0,0 +1,4 @@ +To remove all subscriptions from the subscription set, use +:kotlin-sync-sdk:`MutableSubscriptionSet.removeAll() +` +with no arguments. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst new file mode 100644 index 0000000000..ceb4bb97ce --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst @@ -0,0 +1,4 @@ +If you want to remove all subscriptions to a specific object type, pass +a class to the :kotlin-sync-sdk:`MutableSubscriptionSet.removeAll() +` +method. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst new file mode 100644 index 0000000000..c28ae9c786 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst @@ -0,0 +1,2 @@ +You can remove all unnamed (anonymous) subscriptions from the subscription set by +setting ``anonymousOnly`` to ``true`` when you call the ``removeAll`` method. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..bd58a591ba --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,3 @@ +You can remove a named subscription query by passing the subscription +name to :kotlin-sync-sdk:`MutableSubscriptionSet.remove() +`. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst new file mode 100644 index 0000000000..897416d887 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst @@ -0,0 +1,3 @@ +You can remove a subscription by reference by passing the subscription +to :kotlin-sync-sdk:`MutableSubscriptionSet.remove() +`. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst new file mode 100644 index 0000000000..b6194b8f72 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst @@ -0,0 +1,4 @@ +Kotlin does not provide an API to directly remove an unnamed subscription. +However, you can you can look up the subscription by query and then pass +the reference to the subscription to :kotlin-sync-sdk:`MutableSubscriptionSet.remove() +`. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst new file mode 100644 index 0000000000..af1d87010f --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst @@ -0,0 +1,22 @@ +You can bootstrap the database with an initial subscription set when you open +it with the +:kotlin-sync-sdk:`SyncConfiguration() `. + +Pass the ``initialSubscriptions`` parameter with the +subscription queries you want to use to bootstrap the database: + +.. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.initialize-subscribe-query-realm-app.kt + :language: kotlin + +If your app needs to rerun this initial subscription every +time the app starts, you can pass an additional parameter: +``rerunOnOpen``. This is a boolean that denotes whether the +initial subscription should re-run every time the +app starts. You might need to do this to re-run dynamic time +ranges or other queries that require a re-computation of +static variables for the subscription. + +In this example, we only want incomplete tasks. With +``rerunOnOpen`` set to ``true``, the query dynamically +recalculates the relevant objects to sync based on the +desired query results every time the app starts. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst new file mode 100644 index 0000000000..143644eb5f --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst @@ -0,0 +1,15 @@ +To subscribe to a ``RealmQuery`` or ``RealmResults`` set, call the +:kotlin-sync-sdk:`.subscribe() ` method. + +.. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.subscribe-unnamed-query.kt + :language: kotlin + +Update a Query Subscription +``````````````````````````` + +You can update a named query subscription with a new query +by setting ``updateExisting`` to ``true``. + +This updates the subscription automatically, instead of requiring you to +:ref:`manually update the subscription ` +in the subscription set. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst new file mode 100644 index 0000000000..c09b1846de --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst @@ -0,0 +1 @@ +To add a name to the subscription, pass a string when you call ``.subscribe()``. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscription-set-state-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscription-set-state-description.rst new file mode 100644 index 0000000000..92a9b7dc97 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-subscription-set-state-description.rst @@ -0,0 +1,9 @@ +Use the :kotlin-sync-sdk:`SubscriptionSet.state +` +property to read the current state of the subscription set. + +``SUPERCEDED`` (sic -- note alternate spelling) is a :kotlin-sync-sdk:`SubscriptionSetState +` +that can occur when another thread writes a subscription on a different instance +of the subscription set. If the state becomes ``SUPERCEDED``, you must obtain a +new instance of the subscription set before you can write to it. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-unsubscribe-from-query-not-supported.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-unsubscribe-from-query-not-supported.rst new file mode 100644 index 0000000000..c68cb245d1 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-unsubscribe-from-query-not-supported.rst @@ -0,0 +1,3 @@ +Kotlin does not currently support the unsubscribe API. Instead, you can +:ref:`manually remove subscriptions ` from the +subscription set. diff --git a/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst new file mode 100644 index 0000000000..3ff1ce2bc3 --- /dev/null +++ b/source/includes/api-details/kotlin/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst @@ -0,0 +1,10 @@ +Use the :kotlin-sync-sdk:`SyncConfiguration.waitForInitialRemoteData() +` +builder method to force your application to block until client subscription +data synchronizes to the backend before opening the database. + +Alternately, you can use :kotlin-sync-sdk:`SubscriptionSet.waitForSynchronization() +` +to delay execution until subscription sync completes after instantiating +a sync connection. + diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-access-subscription-set-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-access-subscription-set-description.rst new file mode 100644 index 0000000000..520e9d25fb --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-access-subscription-set-description.rst @@ -0,0 +1,5 @@ +You can access a :swift-sdk:`SyncSubscriptionSet +` through the database :swift-sdk:`subscriptions +` +property. You perform all operations to add, find, update, remove, or watch +subscriptions through this property. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-add-subscription-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-add-subscription-description.rst new file mode 100644 index 0000000000..064327fcec --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-add-subscription-description.rst @@ -0,0 +1,10 @@ +To add a subscription: + +1. Open the synced database. +#. Access the database's ``subscriptions`` property. +#. Open a subscription ``update`` block. +#. Call the ``append`` method to append the new subscription to the + subscription set. +#. Pass a ``QuerySubscription`` with the name of the object + type. Optionally, use the ``.where`` or ``NSPredicate`` query API to + subscribe to only a subset of the objects of the type. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-change-named-subscription-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-change-named-subscription-description.rst new file mode 100644 index 0000000000..f6bb0a9aac --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-change-named-subscription-description.rst @@ -0,0 +1,6 @@ +You can :swift-sdk:`search for a subscription by name +`, +and then update the named subscription. + +To change a subscription query, call the ``updateQuery`` method on an existing +query inside a ``subscriptions.update`` block. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-change-unnamed-subscription-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-change-unnamed-subscription-description.rst new file mode 100644 index 0000000000..fcec0ae0b7 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-change-unnamed-subscription-description.rst @@ -0,0 +1,5 @@ +To change a subscription query, call the ``updateQuery`` method on an existing +query inside a ``subscriptions.update`` block. + +In this example, we search for a subscription matching our query and then +update it with a new query. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst new file mode 100644 index 0000000000..caffbff8ab --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst @@ -0,0 +1,16 @@ +Subscription names must be unique. Trying to append a subscription +with the same name as an existing subscription throws an error. + +If you do not explicitly name a subscription, and instead subscribe +to the same unnamed query more than once, the SDK does not persist +duplicate queries to the subscription set. + +If you subscribe to the same query more than once under different names, +the SDK persists both subscriptions to the subscription set. + +If your application flow appends the same named subscription to the subscription +set every time you run the application, add a check for an existing subscription +before appending it. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.check-before-adding-subscription.swift + :language: swift diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-find-subscription-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-find-subscription-description.rst new file mode 100644 index 0000000000..2f2a7f2391 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-find-subscription-description.rst @@ -0,0 +1,10 @@ +To find a specific subscription by name, call the +:swift-sdk:`subscriptions.first(named: ) +` +method with the name of a subscription. + +You can also find a subscription matching a specific query by calling one of +the variants of :swift-sdk:`subscriptions.first(ofType: where:) +` +method with the SDK object type and a query, query builder, or NSPredicate +argument. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst new file mode 100644 index 0000000000..eeba7ff845 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst @@ -0,0 +1,2 @@ +To remove all subscriptions from the subscription set, use the ``removeAll`` +method in a subscription update block. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst new file mode 100644 index 0000000000..085a21bf36 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst @@ -0,0 +1,4 @@ +You can remove all subscriptions to a specific object type by calling the +:swift-sdk:`removeAll +` +method with an ``ofType`` argument in a subscription update block. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst new file mode 100644 index 0000000000..09f0ebeb74 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst @@ -0,0 +1,2 @@ +You can remove all unnamed subscriptions from the subscription set by +setting ``unnamedOnly`` to ``true`` when you call the ``removeAll`` method. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..49f9f3b06c --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,4 @@ +You can remove a specific named subscription by passing the name to the +:swift-sdk:`remove() +` +method in a subscription update block. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst new file mode 100644 index 0000000000..2489e8372c --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst @@ -0,0 +1,3 @@ +You can remove a subscription by reference by passing the subscription to the +:swift-sdk:`remove() ` +method in a subscription update block. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst new file mode 100644 index 0000000000..f7e20a1eb2 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst @@ -0,0 +1,3 @@ +You can remove a specific subscription query in a subscription update block +by calling ``remove``. You can find a subscription matching the query to remove +the appropriate subscription. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst new file mode 100644 index 0000000000..71668ef9b7 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst @@ -0,0 +1,22 @@ +You can set initial subscriptions through the +:swift-sdk:`flexibleSyncConfiguration() +`. +Pass the ``initialSubscriptions`` parameter with the subscription queries +you want to use to bootstrap the database: + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-initial-subscriptions.swift + :language: swift + +If your app needs to rerun this initial subscription every time the app starts, +you can pass an additional parameter - ``rerunOnOpen``. This is a bool that +denotes whether the initial subscription should re-run every time the +app starts. You might need to do this to re-run dynamic time ranges +or other queries that require a re-computation of static variables for the +subscription. + +In this example, we don't want users to be overwhelmed by irrelevant tasks, +so we'll load only tasks due within the previous 7 days and the next 7 days. +Tasks that were due more than a week ago are no longer relevant, and tasks +that are due further out than the next week are also not relevant. With +``rerunOnOpen`` here, the query dynamically recalculates the relevant +objects to sync based on the desired date range every time the app starts. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-description.rst new file mode 100644 index 0000000000..344d761a4b --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-description.rst @@ -0,0 +1,20 @@ +Use the :swift-sdk:`.subscribe() +` +method to create a subscription for objects matching the query. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-unnamed.swift + :language: swift + +Subscribe to an Actor-Confined Query +```````````````````````````````````` + +You can subscribe to actor-confined queries. For more information about +working with actor-confined database instances, refer to +:ref:`swift-actor-isolated-realm`. + +You can subscribe to an actor-confined query on the MainActor. + +.. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-on-main-actor.swift + :language: swift + +Or subscribe to a query on a custom actor. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst new file mode 100644 index 0000000000..e267599a3e --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst @@ -0,0 +1,4 @@ +To give a query subscription a name, supply a string name argument for the +``name`` parameter when you call the :swift-sdk:`.subscribe() +` +method. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscription-set-state-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscription-set-state-description.rst new file mode 100644 index 0000000000..4a77164174 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-subscription-set-state-description.rst @@ -0,0 +1,9 @@ +Use the :swift-sdk:`SubscriptionSet.state +` +property to read the current state of the subscription set. + +The ``superseded`` state is a :swift-sdk:`SyncSubscriptionState +` +that can occur when another thread updates a subscription on a different +instance of the subscription set. If the state becomes ``superseded``, you must +obtain a new instance of the subscription set before you can update it. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst new file mode 100644 index 0000000000..5d1e903325 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst @@ -0,0 +1,4 @@ +You can unsubscribe from a query's ``Results`` set by calling +:swift-sdk:`.unsubscribe() +` on the query. +This removes the subscription from the ``MutableSubscriptionSet``. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst new file mode 100644 index 0000000000..344909a423 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst @@ -0,0 +1,17 @@ +To wait for a query subscription to sync, pass the ``waitForSync`` parameter +when you call the :swift-sdk:`.subscribe() +` +method. This takes a ``WaitForSyncMode`` enum argument, whose cases are: + +- **.onCreation**: Wait to download matching objects when your app creates the + subscription. Otherwise, return without waiting for new downloads. The + app must have an internet connection the first time you add the subscription. +- **.always**: Wait to download matching objects when ``.subscribe()`` is executed. + The app must have an internet connection when ``.subscribe()`` is executed. +- **.never**: Never wait to download matching objects. The app needs an internet + connection for the user to authenticate the first time the app launches, but + can :ref:`open offline ` on subsequent + launches using cached credentials. + +You can optionally specify a ``timeout`` value of type :apple:`TimeInterval +`. diff --git a/source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst b/source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst new file mode 100644 index 0000000000..6392d63492 --- /dev/null +++ b/source/includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst @@ -0,0 +1,32 @@ +Async/Await +``````````` + +If your application uses async/await, you don't need the ``onComplete`` +block. The update executes asynchronously and throws an +error if the update cannot complete successfully. + +.. code-block:: swift + + @MainActor + func changeSubscription() async throws { + let subscriptions = realm.subscriptions + try await subcriptions.update { + subscriptions.remove { + QuerySubscription { + $0.assignee == "Joe Doe" + } + } + } + } + +Completion +`````````` + +If your application does not use Swift's async/await feature, you can react +to subscription changes syncing with the server using the ``onComplete`` +block. This block is called after subscriptions are synchronized with the +server. If you want to react to subscription state changes by redrawing a +UI, for example, or taking another action based on changes to the data set, +take those actions in ``onComplete``. This is also where you can handle +optional errors that occur during synchronization. + diff --git a/source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst b/source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst new file mode 100644 index 0000000000..f97ec343a8 --- /dev/null +++ b/source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst @@ -0,0 +1,5 @@ +To remove a specific subscription by name, execute a transaction on the +subscriptions set. Within the transaction, pass the name to the +:js-sdk:`removeByName() +` method on the +``MutableSubscriptionSet``. diff --git a/source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst b/source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst new file mode 100644 index 0000000000..3c3b6ba3ee --- /dev/null +++ b/source/includes/api-details/typescript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst @@ -0,0 +1,4 @@ +You can remove a specific subscription by query by executing a transaction on +the subscriptions set. Pass the query to the :js-sdk:`remove() +` method on the +``MutableSubscriptionSet`` within a transaction. diff --git a/source/includes/api-details/typescript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst b/source/includes/api-details/typescript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst new file mode 100644 index 0000000000..4a96cf8a8e --- /dev/null +++ b/source/includes/api-details/typescript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst @@ -0,0 +1,22 @@ +When you call the ``.subscribe()`` method on a query, you can optionally +specify the ``WaitForSync`` behavior, which is an enum of options describing +different sync behaviors. + +This example uses the ``FirstTime`` option, which is the default behavior. +A subscription with ``FirstTime`` behavior only waits for sync to finish when a +subscription is first created. + +.. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-wait-first.ts + :language: typescript + +The other supported ``WaitForSync`` options are: + +- ``Always``: Wait to download matching objects every time your app launches. + The app must have an internet connection at every launch. +- ``Never``: Never wait to download matching objects. The app needs an internet + connection for the user to authenticate the first time the app launches, but + can :ref:`open offline ` on subsequent + launches using cached credentials. + +You can optionally specify a ``timeout`` value to limit how long the sync +download runs. diff --git a/source/includes/flex-sync-limitations.rst b/source/includes/flex-sync-limitations.rst index b862e019f2..5b6fe08ff1 100644 --- a/source/includes/flex-sync-limitations.rst +++ b/source/includes/flex-sync-limitations.rst @@ -8,7 +8,7 @@ store, or user, such as ``user_id == $0, “641374b03725038381d2e1fb”``, is a good candidate for an indexed queryable field. However, an indexed queryable field has specific requirements for use in a query subscription: -- The indexed queryable field must be used in every subscription query. It +- The indexed queryable field must be used in *every* subscription query. It cannot be missing from the query. - The indexed queryable field must use an ``==`` or ``IN`` comparison against a constant at least once in the subscription query. For example, @@ -20,7 +20,7 @@ queryable field is directly compared against a constant using ``==`` or ``IN`` at least once. For example, ``store_id IN {1,2,3} AND region=="Northeast"`` or ``store_id == 1 AND (active_promotions < 5 OR num_employees < 10)``. -*Invalid* Flexible Sync queries on an indexed queryable field include queries +*Invalid* Device Sync queries on an indexed queryable field include queries where: - The indexed queryable field does not use ``AND`` with the rest of the query. @@ -37,14 +37,14 @@ where: ``region=="Northeast`` or ``truepredicate`` are invalid because they do not contain the indexed queryable field. -Unsupported Query Operators in Flexible Sync -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Unsupported Sync Subscription Query Operators +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Flexible Sync has some limitations when using RQL operators. When you -write the :ref:`query subscription ` -that determines which data to sync, the server does not support these -query operators. However, you can still use the full range of RQL features -to query the synced data set in the client application. +Device Sync does not support all RQL operators when creating your subscription +queries. When you write the :ref:`query subscription ` +that determines which data to sync to the device, the server does not support +these query operators. However, you can use all RQL operators to query the +data set once it has synced to the client application. .. list-table:: :header-rows: 1 @@ -63,12 +63,12 @@ Case insensitive queries (``[c]``) cannot use indexes effectively. As a result, case insensitive queries are not recommended, since they could lead to performance problems. -Flexible Sync only supports ``@count`` for array fields. +Device Sync only supports ``@count`` for array fields. List Queries ~~~~~~~~~~~~ -Flexible Sync supports querying lists using the ``IN`` operator. +Device Sync supports querying lists using the ``IN`` operator. You can query a list of constants to see if it contains the value of a queryable field: @@ -88,8 +88,9 @@ contains a constant value: .. warning:: - You **cannot** compare two lists with each other in a Flexible Sync query. - Note that this is valid Realm Query Language syntax outside of Flexible Sync queries. + You **cannot** compare two lists with each other in a Device Sync query. + Note that this is valid Realm Query Language syntax outside of Device Sync + queries. .. code-block:: javascript :copyable: false @@ -103,5 +104,5 @@ contains a constant value: Embedded or Linked Objects ~~~~~~~~~~~~~~~~~~~~~~~~~~ -Flexible Sync does not support querying on properties in Embedded Objects +Device Sync does not support querying on properties in Embedded Objects or links. For example, ``obj1.field == "foo"``. diff --git a/source/includes/note-sync-state-complete.rst b/source/includes/note-sync-state-complete.rst deleted file mode 100644 index 61a660564f..0000000000 --- a/source/includes/note-sync-state-complete.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. note:: Subscription State "Complete" - - The subscription set state "complete" does not mean "sync is done" or "all - documents have been synced". "Complete" means the following two things have - happened: - - - The subscription has become the active subscription set that is currently - being synchronized with the server. - - The documents that matched the subscription *at the time the subscription - was sent to the server* are now on the local device. Note that this does - not necessarily include all documents that currently match the - subscription. - - The Realm SDK does not provide a way to check whether all documents that - match a subscription have synced to the device. diff --git a/source/includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst b/source/includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst index 861f97a29e..fd9465f894 100644 --- a/source/includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst +++ b/source/includes/pbs-to-fs-migration-remove-and-add-subscriptions.rst @@ -2,8 +2,8 @@ When you migrate from Partition-Based Sync to Flexible Sync, the SDK automatically creates hidden Sync subscriptions for your app. The next time you add or change subscriptions, we recommend that you: -1. :ref:`Remove the automatically-generated subscriptions `. -2. :ref:`Manually add the relevant subscriptions in your client codebase `. +1. :ref:`Remove the automatically-generated subscriptions `. +2. :ref:`Manually add the relevant subscriptions in your client codebase `. This enables you to see all of your subscription logic together in your codebase for future iteration and debugging. diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-access-subscription-set.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-access-subscription-set.rst new file mode 100644 index 0000000000..e563809665 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-access-subscription-set.rst @@ -0,0 +1,63 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.get-subscriptions.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.get-subscriptions.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + :copyable: false + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst new file mode 100644 index 0000000000..69964babed --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst @@ -0,0 +1,66 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + :copyable: false + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + + - id: csharp + content: | + + While you can add a single query using ``SubscribeAsync``, you can + only batch multiple queries within a ``SubscriptionSet.Update`` block. + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.update-multiple-subscriptions.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.add-subscription.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.subscribe-to-queryable-fields.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-multiple-subscriptions.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst new file mode 100644 index 0000000000..536afacbea --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst @@ -0,0 +1,63 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscribe-to-objects-matching-a-query.cpp + :language: cpp + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.subscribe-to-queryable-fields.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.add-a-named-subscription.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.query-subscription-by-name.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst new file mode 100644 index 0000000000..86bac7a5c0 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst @@ -0,0 +1,60 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscribe-to-all-objects-of-a-type.cpp + :language: cpp + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.subasync.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.update-subscriptions-by-name.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.update-subscriptions-by-name.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.subscribe-to-queryable-fields.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.add-a-subscription.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-single-subscription.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst new file mode 100644 index 0000000000..8d8b1c7a50 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst @@ -0,0 +1,65 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + :copyable: false + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.add-a-subscription.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.query-subscription-without-name.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst new file mode 100644 index 0000000000..814b9cc802 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst @@ -0,0 +1,60 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.change-subscription-query.cpp + :language: cpp + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.update-a-subscription.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.update-subscriptions-new-query.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.update-subscriptions-by-name.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.update-subscriptions-by-name.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.update-subscriptions.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.update-subscriptions-by-name.kt + :language: kotlin + :emphasize-lines: 14 + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.update-subscription-by-name.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst new file mode 100644 index 0000000000..2659e32773 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst @@ -0,0 +1,61 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.update-subscriptions-by-query.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.update-subscriptions-by-query.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.update-subscriptions-by-query.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.update-subscription.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-find-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-find-subscription.rst new file mode 100644 index 0000000000..2a329445aa --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-find-subscription.rst @@ -0,0 +1,64 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscription-count-and-find-subscription.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + :copyable: false + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst new file mode 100644 index 0000000000..f32b59e2d9 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst @@ -0,0 +1,61 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.remove-all-subscriptions-of-object-type.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.remove-subscriptions-by-object-type.dart + :language: dart + :emphasize-lines: 2 + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.remove-all-subscriptions-to-an-object-type.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.remove-all-subscriptions-to-an-object-type.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.remove-all-subscriptions-of-object-type.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.remove-all-subscriptions-to-an-object-type.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-subscriptions-to-object-type.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst new file mode 100644 index 0000000000..587776fc1c --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst @@ -0,0 +1,60 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.clear-all-subscriptions.cpp + :language: cpp + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.remove-all-subscriptions.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.remove-all-subscriptions.dart + :language: dart + :emphasize-lines: 2 + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.remove-all-subscriptions.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.remove-all-subscriptions.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.remove-all-subscriptions.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.remove-all-subscriptions.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-all-subscriptions.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions.rst new file mode 100644 index 0000000000..a90082d7ec --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-remove-unnamed.ts + :language: typescript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.remove-all-unnamed-subscriptions.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-all-unnamed-subscriptions.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst new file mode 100644 index 0000000000..eb836e54d4 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst @@ -0,0 +1,60 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.remove-subscription-by-name.cpp + :language: cpp + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.remove-subscription-by-name.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.remove-subscriptions-by-name.dart + :language: dart + :emphasize-lines: 2 + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.remove-single-subscription.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.remove-single-subscription.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.remove-subscription-by-name.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.remove-single-subscription.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.remove-single-subscription.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst new file mode 100644 index 0000000000..cefaf4d975 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst @@ -0,0 +1,64 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.remove-subscriptions-by-reference.dart + :language: dart + :emphasize-lines: 1, 3 + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.remove-subscription-by-reference.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + :copyable: false + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-unnamed-subscription.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-unnamed-subscription.rst new file mode 100644 index 0000000000..6d32a4174c --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-remove-unnamed-subscription.rst @@ -0,0 +1,63 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.remove-subscription-by-query.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.remove-subscriptions-by-query.dart + :language: dart + :emphasize-lines: 2 + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.remove-single-subscription.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.swift + :language: swift + :copyable: false + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-set-initial-subscriptions.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-set-initial-subscriptions.rst new file mode 100644 index 0000000000..f2e8fc3daa --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-set-initial-subscriptions.rst @@ -0,0 +1,60 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.bootstrap-a-subscription.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.set-initial-subscriptions.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.initialize-subscribe-query-realm-app-rerun.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-initial-subscriptions-rerun-on-open.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.set-initial-subscriptions.ts + :language: typescript diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst new file mode 100644 index 0000000000..7d351e99ee --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst @@ -0,0 +1,64 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/flexible-sync.snippet.subscribe-to-all-objects-of-a-type.cpp + :language: cpp + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-refresh-realm-description.rst + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.dart + :language: dart + :copyable: false + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/flexible-sync.snippet.subscribe-to-queryable-fields.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-all-objects-of-a-type.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst new file mode 100644 index 0000000000..c42bbd8aad --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst @@ -0,0 +1,61 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.add-subscription-subscribe-api.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-name.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.subscribe-named-query.kt + :language: kotlin + :emphasize-lines: 3 + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-with-name.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-name.ts + :language: typescript diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst new file mode 100644 index 0000000000..b67634726a --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst @@ -0,0 +1,61 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.add-subscription-subscribe-api.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-basic.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.update-query-by-name.kt + :language: kotlin + :emphasize-lines: 9 + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-to-results-on-custom-actor.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-basic.ts + :language: typescript diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-unsubscribe-from-query.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-unsubscribe-from-query.rst new file mode 100644 index 0000000000..a82dd6b396 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-unsubscribe-from-query.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.remove-subscription-unsubscribe-api.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.kt + :language: kotlin + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-api-unsubscribe.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-unsubscribe.ts + :language: typescript diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst new file mode 100644 index 0000000000..2237a88d00 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.wait-with-timeout-subscribe-api.dart + :language: dart + :emphasize-lines: 5-6 + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin + :copyable: false + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.subscribe-unnamed-query.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.subscribe-wait-for-sync.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/manage-subscriptions.test.snippet.sub-with-timeout.ts + :language: typescript diff --git a/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst.rst b/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst.rst new file mode 100644 index 0000000000..a52c990a52 --- /dev/null +++ b/source/includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst.rst @@ -0,0 +1,62 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/FlexibleSyncExamples.snippet.wait-for-synchronization.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/manage_sync_subscription_test.snippet.wait-for-subscription-change.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.wait-for-subscription-sync.java + :language: java + :emphasize-lines: 10 + :copyable: false + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/sync/FlexibleSyncTest.snippet.wait-for-subscription-sync.kt + :language: kotlin + :emphasize-lines: 11-14 + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/SyncTest.snippet.wait-for-subscription-changes.kt + :language: kotlin + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/FlexibleSync.snippet.add-subscription-with-oncomplete.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/sdk/sync/configure-and-open-synced-database.txt b/source/sdk/sync/configure-and-open-synced-database.txt index e67848c7dc..8b32dfec50 100644 --- a/source/sdk/sync/configure-and-open-synced-database.txt +++ b/source/sdk/sync/configure-and-open-synced-database.txt @@ -25,7 +25,14 @@ Placeholder page for configuring and opening a synced database. Download Changes Before Open ---------------------------- + +.. _sdks-open-synced-database-offline: + +Open a Synced Database Offline +------------------------------ + .. _sdks-synced-dbs-vs-non-synced-dbs: Synced Databases vs. Non-Synced Databases ----------------------------------------- + diff --git a/source/sdk/sync/manage-sync-subscriptions.txt b/source/sdk/sync/manage-sync-subscriptions.txt index 436c09a9a3..cca7dc8fc9 100644 --- a/source/sdk/sync/manage-sync-subscriptions.txt +++ b/source/sdk/sync/manage-sync-subscriptions.txt @@ -4,20 +4,1454 @@ Manage Sync Subscriptions ========================= +.. meta:: + :description: Create, update, and delete query subscriptions to sync data between client devices and Atlas Device Sync. + :keywords: Realm, C++ SDK, Flutter SDK, Kotlin SDK, Java SDK, .NET SDK, Node.js SDK, Swift SDK, code example + +.. facet:: + :name: genre + :values: reference + +.. facet:: + :name: programming_language + :values: cpp, csharp, dart, java, javascript/typescript, kotlin, swift + .. contents:: On this page :local: :backlinks: none :depth: 2 :class: singlecol -Placeholder page for information about managing Flexible Sync subscriptions. +.. tabs-selector:: drivers + +Atlas Device Sync uses subscriptions and permissions to determine what +data to sync with your client application. + +After you :ref:`open a synced database `, +you must add subscriptions before you can read to and write from the database. + +You can manually add, update, and remove subscriptions to determine which +data syncs to the client device. Or you can subscribe to queries instead of +or in addition to manually managing subscriptions. + +.. _sdks-query-subscription-concept: + +What are Subscriptions? +----------------------- + +When you configure Device Sync in Atlas, you specify which fields your +client application can query. The SDK tracks these queries through a +**subscription**. When you subscribe to a query, the SDK automatically tracks +changes to data matching that subscription, and uploads and downloads relevant +data. + +Each subscription corresponds to a query on **queryable fields** for a +specific object type. See :ref:`Queryable Fields ` +in the Device Sync documentation for more information. + +For each query subscription, the SDK looks for data matching the query. +Data matching the subscription, where the user has the appropriate +permissions, syncs between clients and the backend application. + +The SDK tracks these queries through a **subscription set**, which is a +collection of subscriptions. You can add, remove, and update subscriptions in +the subscription set. + +You can construct subscription queries with Realm Query Language (RQL), or one +of the SDK-idiomatic query engines. + +- :ref:`realm-query-language` +- :ref:`java-filter-data` +- :ref:`dotnet-linq` +- :ref:`sdks-filter-data-swift` + +.. important:: RQL Support in Sync Subscription Queries + + Device Sync does not support the full range of RQL operators when constructing + a subscription query. For details about these limitations, refer to + :ref:`sdks-sync-subscription-query-rql-limitations`. + +Subscribe to Object Types +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Subscription sets are based on your :ref:`data model object types `. +You might have multiple subscriptions if you have many types of SDK objects. +You can also have multiple subscriptions on the same object type. + +However, note the following if you use :ref:`relationships +` or :ref:`asymmetric objects +` in your app: + +Object Links +```````````` + +You must add both an object and its linked object to the subscription +set to see a linked object. + +If your subscription results contain an object with a property that links +to an object not contained in the results, the link appears to be nil. +The SDK does not provide a way to distinguish whether that property's value is +legitimately nil, or whether the object it links to exists but is out of +view of the query subscription. + +Asymmetric Objects +`````````````````` + +If your app uses :ref:`Data Ingest ` to +unidirectionally sync **asymmetric objects**, you *cannot* create subscriptions +for those objects. If your app contains asymmetric objects and non-asymmetric +objects in the same database, you can add subscription queries for the +non-asymmetric objects. + +Permissions +~~~~~~~~~~~ + +Subscriptions work hand-in-hand with permissions to determine what data to +Sync to your client application. The client application only sees the +subset of data that matches your subscriptions which *also* matches the +permissions of the logged-in user. For more information about the intersection +of subscriptions and user permissions, refer to :ref:`sdks-write-synced-database`. + +This page details how to manage client subscriptions for Device Sync. +For information about setting up permissions for Device Sync, see: +:ref:`Device Sync Rules & Permissions `. + +.. _sdks-manage-subscriptions-in-client: + +Manage Subscriptions in Your Client App +--------------------------------------- + +In the client application, you add, update, and remove subscriptions to specific +queries on the queryable fields. This determines which data syncs to the +client device. + +You can: + +- Add subscriptions with an optional subscription name: + + - You can subscribe to a database query. This automatically adds the + subscription to the subscription set. + - Manually add a subscription to the subscription set with the subscribe API. + Use this API if you need more control over subscriptions for performance + optimization or business-logic reasons. See :ref:`Performance Considerations + ` for more information. + +- React to subscription state changes. +- Update subscriptions with new queries. +- Remove individual subscriptions or all subscriptions for an object type. + +Subscriptions persist across user sessions unless you unsubscribe from them. + +Initial Subscriptions +~~~~~~~~~~~~~~~~~~~~~ + +Before you can read from or write to a synced database, you must provide at +least one subscription. Some of the SDK languages provide a dedicated API +to make it more convenient to set initial subscriptions. For details, refer +to :ref:`sdks-set-initial-subscriptions`. + +.. _sdks-sync-results-subscribe-api: + +Subscribe to Queries +-------------------- + +To simplify subscription management, the SDK offers APIs to subscribe to and +unsubscribe from a query directly. These APIs abstract away the details of +manually adding and removing subscriptions. This API is not available for all +languages. If your preferred language does not provide this API, refer to +:ref:`sdks-manually-manage-subscriptions`. + +.. important:: The Subscribe to Queries API is in Preview + + The APIs described here are currently in Preview. These APIs may be subject + to change in the future. + +.. _sdks-subscribe-to-query: + +Subscribe to a Query +~~~~~~~~~~~~~~~~~~~~ + +With an :ref:`authenticated user ` and a +:ref:`Sync configuration `, you can +open a synced database and query for the objects you want to read and write. +You can subscribe to the query to create a subscription for objects matching +the query. + +This creates an unnamed subscription and adds it to the subscription set, +similar to :ref:`manually creating a subscription +`. + +Subscriptions persist across user sessions unless you unsubscribe from them. + +.. tip:: + + If your app works with multiple subscriptions, or if you want to update + a subscription, you should add a name when you subscribe to a query. For + details, refer to the :ref:`sdks-subscribe-to-query-with-name` section on + this page. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query.rst + +.. _sdks-subscribe-to-query-with-name: + +Subscribe to a Query with a Subscription Name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your app works with multiple subscriptions, or if you want to update +a subscription, you should add a name when you subscribe to a query. + +You can later use this name to: + +- :ref:`Change a subscription's query ` +- :ref:`Remove the query by name ` + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscribe-to-query-with-name-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-query-with-name.rst + +.. _sdks-wait-for-query-subscription-to-sync: + +Wait for a Query Subscription to Sync +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When you subscribe to a query, that query's results do not contain objects +until the subscription syncs with Atlas. + +If your app creates objects, you may not need to download synced data before +the user works with it. However, if your app requires data from Atlas before +the user can work with your app, you can specify that the SDK should wait for +the subscription query data to sync before proceeding. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-subscribe-to-query-with-name-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/sync/manage-sync-subscriptions-wait-for-query-subscription-to-sync-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-query-subscriptions-to-sync.rst + +.. _sdks-unsubscribe-from-query: + +Unsubscribe from a Query +~~~~~~~~~~~~~~~~~~~~~~~~ + +You can unsubscribe from a query that you have previously subscribed to. +Unsubscribing removes the suscription from the subscription set, similar to +:ref:`manually removing a subscription `. + +A query results set may still contain objects after calling the unsubscribe +method if the subscription set contains another overlapping subscription. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-subscribe-to-query-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-unsubscribe-from-query-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-unsubscribe-from-query-not-supported.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-unsubscribe-from-query-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-unsubscribe-from-query-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-unsubscribe-from-query.rst + +The unsubscribe method returns before objects matching the removed subscription +are deleted from the database. Sync continues in the background based on the +new set of subscriptions. There is no API to wait for the unsubscribe method +to sync with the server. + +.. _sdks-manually-manage-subscriptions: + +Manually Manage Subscriptions +----------------------------- + +As an alternative to the subscribe to a query API, you can manually manage the +subscriptions in a subscription set. + +You can: + +- Add subscriptions +- React to subscription state change +- Update subscriptions with new queries +- Remove individual subscriptions or all subscriptions for an object type + +Data matching the subscription, where the user has the appropriate +permissions, syncs between devices and Atlas. + +You can specify an optional string name for your subscription. + +When you create a subscription, the SDK looks for data matching a query on a +specific object type. You can have multiple subscription sets on different +object types. You can also have multiple queries on the same object type. + +.. _sdks-get-sync-subscriptions: + +Access the Subscription Set +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can access the subscription set through the database ``subscriptions`` +property. You perform all operations to add, find, update, remove, or watch +subscriptions through this property. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-access-subscription-set-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-access-subscription-set-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-access-subscription-set-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-access-subscription-set-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-access-subscription-set-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-set-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-access-subscription-set-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-access-subscription-set-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-access-subscription-set-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-access-subscription-set.rst + +.. _sdks-find-sync-subscriptions: + +Find a Subscription +~~~~~~~~~~~~~~~~~~~ + +You can find a specific subscription in a subscription set. You might want to +find a specific subscription: + +- To avoid adding the same subscription again, which in some languages throws + an error. +- To update the subscription. +- To remove the subscription. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-find-subscription-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-find-subscription-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-find-subscription.rst + +.. _sdks-sync-subscriptions-add-subscription: + +Add a Subscription +~~~~~~~~~~~~~~~~~~ + +Add a subscription in a subscriptions update block. You append each +new subscription to the client's SDK subscriptions. + +Subscriptions persist across user sessions unless you remove them from the +subscription set. + +If your app is adding subscriptions for the first time, some SDK languages +provide a special parameter to set initial subscriptions or recalculate +initial subscriptions on app launch. For details, skip to the +:ref:`set initial subscriptions ` on this page. + +.. tip:: + + If your app works with multiple subscriptions, or if you want to update + a subscription, you should add a name when you subscribe to a query. For + details, refer to the :ref:`sdks-add-named-subscription` section on + this page. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-add-subscription-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-add-subscription-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-add-subscription-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-add-subscription.rst + +.. Some of the SDKs have special behavior around duplicate subs, but others don't. +.. Adding this tab set to show/hide relevant details. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-duplicate-subscription-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-duplicate-subscription-description.rst + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-duplicate-subscriptions-description.rst + + .. tab:: + :tabid: typescript + +.. _sdks-add-unnamed-subscription: + +Add Unnamed Subscription +```````````````````````` + +If your app doesn't need to update or remove subscriptions, you can add a +subscription without a name. + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-add-unnamed-subscription.rst + +.. _sdks-add-named-subscription: + +Add a Named Subscription +```````````````````````` + +If your app might need to update or remove subscriptions, you should add a +name when you create a subscription. You can use the name to find and update +or remove the appropriate subscription later. + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-add-named-subscription.rst + +.. _sdks-add-multiple-subscriptions: + +Add Multiple Subscriptions +`````````````````````````` + +You can add multiple subscriptions within a subscription update block, +including subscriptions of different object types. + +Performing query updates requires Atlas to recalculate which documents match the +query. We strongly advise designing your application to minimize updates. You +can do this by batching additions and changes to the subscription set. + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-add-multiple-subscriptions.rst + +.. _sdks-subscribe-to-all-objects-of-type: + +Subscribe to All Objects of a Specific Type +``````````````````````````````````````````` + +In addition to syncing all objects that match a given query, you can subscribe +to all objects of a specific type. You do this by appending a subscription +without providing a query. + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-subscribe-to-all-objects-of-type.rst + +.. _sdks-set-initial-subscriptions: + +Set Initial Subscriptions +````````````````````````` + +You must have at least one subscription before you can read from or write +to the database. You can bootstrap the database with an initial subscription +set when you open it. This ensures your app can start working with the database +successfully right away. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/sync/manage-sync-subscriptions-set-initial-subscriptions-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-set-initial-subscriptions-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-set-initial-subscriptions-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-set-initial-subscriptions-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-set-initial-subscriptions.rst + +At any point after setting initial subscriptions, you can: + +- :ref:`Add more subscriptions to the subscription set. ` +- :ref:`Change existing subscriptions in the subscription set. ` +- :ref:`Remove subscriptions from the subscription set. ` + +.. _sdks-wait-for-subscription-changes-to-sync: + +Wait for Subscription Changes to Sync +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Updating the subscription set on the device is only one component +of changing a subscription. After the client app subscription change, the SDK +synchronizes with the server to resolve any updates to the data due to +the subscription change. This could mean adding or removing data from the +synced database. + +**Adding New Subscriptions** + +If your app creates objects, you may not need to download synced data before +the user works with it. However, if your app requires data from Atlas before +the user can work with your app, you can specify that the SDK should wait for +the subscription changes to sync before proceeding. + +**Updating Existing Subscriptions** + +When you update an existing subscription, this could mean adding new data or +removing data from the synced database. If this involves things like changing +user permissions to add or remove data, or if your app otherwise makes these +changes visible to users in the UI, you may want to wait for subscription +changes to update before proceeding with app execution. Otherwise, the changes +may appear to the user as unexpected changes to the data set later during +"normal" app execution. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-wait-for-subscription-changes-to-sync.rst + +.. _sdks-subscription-set-state: + +Check Subscription Set State +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can check the state of the subscription set through to find out the current +status of the subscription set. This provides information about whether +Atlas has registered the subscription that is on the device. It does not +make any guarantees about the state of the documents matching the subscription. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-subscription-set-state-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-subscription-set-state-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-subscription-set-state-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-subscription-set-state-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-subscription-set-state-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscription-set-state-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-subscription-set-state-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-subscription-set-state-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-subscription-set-state-js-ts-description.rst + +.. note:: Subscription State "Complete" + + The subscription set state "complete" does not mean "sync is done" or "all + documents have been synced". "Complete" means the following two things have + happened: + + - The subscription has become the active subscription set that is currently + being synchronized with the server. + - The documents that matched the subscription *at the time the subscription + was sent to the server* are now on the device. Note that this does + not necessarily include all documents that currently match the + subscription. + + The SDK does not provide a way to check whether all documents that + match a subscription have synced to the device. + +.. _sdks-change-subscription-queries: + +Change Subscription Queries +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can change the queries in a subscription set. You might want to do this +when business logic dictates syncing a different subset of objects, such as +when a user unlocks new features in an app. + +- Change a named query +- Change an unnamed query + +When you change a query, consider how it interacts with any other queries that +may be in the subscription set. You may need to +:ref:`add ` or +:ref:`remove ` other subscriptions, such as: + +- Adding a new subscription when a change to a query introduces new linked objects +- Removing a subscription when an overlapping query inadvertently exposes + objects you don't want to sync + +.. _sdks-change-named-subscription: + +Change a Named Subscription +``````````````````````````` + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-change-named-subscription-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-change-named-subscription-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-change-named-subscription.rst + +.. _sdks-change-unnamed-subscription: + +Change an Unnamed Subscription +`````````````````````````````` + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-change-unnamed-subscription-js-ts-not-supported.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-change-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-change-unnamed-subscription-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-change-unnamed-subscription-js-ts-not-supported.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-change-unnamed-subscription.rst + +.. _sdks-remove-subscriptions: + +Remove Subscriptions +~~~~~~~~~~~~~~~~~~~~ + +To remove subscriptions, you can: + +- Remove a specific subscription + + - Remove a named subscription + - Remove an unnamed subscription + - Remove a subscription by reference + +- Remove all subscriptions for a specific object type +- Remove all unnamed subscriptions +- Remove all subscriptions + +When you remove a subscription query, the SDK asynchronously removes the +synced data that matched the query from the client device. + +.. _sdks-remove-query-by-name: + +Remove a Named Subscription +```````````````````````````` + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-change-named-subscription-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/sync/manage-sync-subscriptions-remove-named-subscription-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-named-subscription.rst + +.. _sdks-remove-unnamed-subscription: + +Remove an Unnamed Subscription +`````````````````````````````` + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-unnamed-subscription-not-supported.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/sync/manage-sync-subscriptions-remove-unnamed-subscription-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-unnamed-subscription.rst + +.. _sdks-remove-subscription-by-reference: + +Remove a Subscription by Reference +`````````````````````````````````` + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-subscription-by-reference-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-subscription-by-reference-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-subscription-by-reference-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-subscription-by-reference-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-subscription-by-reference.rst + +.. _sdks-remove-all-subscriptions-for-object-type: + +Remove All Subscriptions to an Object Type +`````````````````````````````````````````` + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions-to-object-type.rst + +.. _sdks-remove-all-unnamed-subscriptions: + +Remove All Unnamed Subscriptions +````````````````````````````````` + +You may want to remove unnamed subscriptions that are transient or dynamically +generated, but leave named subscriptions in place. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-unnamed-subscriptions.rst + +.. _sdks-remove-all-subscriptions: + +Remove All Subscriptions +```````````````````````` + +.. important:: + + If you remove all subscriptions and do not add a new one, you'll + get an error. A database opened with a flexible sync configuration needs + at least one subscription to sync with the server. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/sync/manage-sync-subscriptions-remove-all-subscriptions-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/sync/manage-sync-subscriptions-remove-all-subscriptions-js-ts-description.rst + +.. include:: /includes/sdk-examples/sync/manage-sync-subscriptions-remove-all-subscriptions.rst + +.. _sdks-sync-subscription-performance-considerations: + +Performance Considerations +-------------------------- + +API Efficiency +~~~~~~~~~~~~~~ + +Adding several subscriptions with the ``.subscribe()`` and ``.unsubscribe()`` +APIs described in the :ref:`sdks-sync-results-subscribe-api` section +is less efficient than performing batch updates when you manually +manage subscriptions. On every call to ``.subscribe()``, the SDK opens a new +update block. For better performance adding multiple +subscriptions, use the ``subscriptions.update`` API described in the +:ref:`sdks-manually-manage-subscriptions` section. + +Group Updates for Improved Performance +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _sdks-add-sync-subscriptions: +.. include:: /includes/sync-memory-performance.rst -Add Sync Subscriptions ----------------------- +.. _sdks-sync-subscription-query-rql-limitations: -.. _sdks-remove-sync-subscriptions: +Sync RQL Requirements and Limitations +------------------------------------- -Remove Sync Subscriptions -------------------------- +.. include:: /includes/flex-sync-limitations.rst