(DOCSP-39513): Consolidate Create page

snooty.toml

@@ -9,6 +9,9 @@ intersphinx = [
 
 # These are the pages that open when you click on them (instead of just being containers)
 toc_landing_pages = [
+  # New IA
+  "/sdk/crud/create",
+
   # Tutorial
   "/tutorial",
   # SDKs

source/includes/api-details/cpp/api-not-supported-description.rst

@@ -0,0 +1 @@
+This API is not currently supported in C++.

source/includes/api-details/cpp/crud/create-counter-property-type-not-supported.rst

@@ -0,0 +1 @@
+The C++ SDK does not currently provide a dedicated counter property type.

source/includes/api-details/cpp/crud/create-dictionary-property-description.rst

@@ -0,0 +1,11 @@
+When you create an object that has a 
+:cpp-sdk:`map property <structrealm_1_1managed_3_01std_1_1map_3_01std_1_1string_00_01T_01_4_00_01void_01_4.html>`, 
+you can set the values for keys in a few ways: 
+
+- Set keys and values on the object and then add the object to the database
+- Set the object's keys and values directly inside a write transaction
+
+.. include:: /includes/map-key-string-limitations.rst
+
+.. literalinclude:: /examples/generated/cpp/crud.snippet.percent-encode-disallowed-characters.cpp
+   :language: cpp

source/includes/api-details/cpp/crud/create-embedded-object-description.rst

@@ -1,14 +1,14 @@
 To create an embedded object, assign the raw pointer of the embedded 
 object to a parent object's property. Move the parent object into 
-the realm using the :cpp-sdk:`Realm.add() function <structrealm_1_1db.html>` 
+the database using the :cpp-sdk:`Realm.add() function <structrealm_1_1db.html>` 
 inside of a write transaction.
 
 In this example, we assign the raw pointer of the embedded object - 
 ``ContactDetails *`` - to the embedded object property of the parent 
 object - ``Business.contactDetails``.
 
-Then, we add the ``business`` object to the realm. This copies the 
-``business`` and ``contactDetails`` objects to the realm. 
+Then, we add the ``business`` object to the database. This copies the 
+``business`` and ``contactDetails`` objects to the database. 
 
 Because ``ContactDetails`` is an embedded object, it does not have
 its own lifecycle independent of the main ``Business`` object. 

source/includes/api-details/cpp/crud/create-geospatial-object-not-supported.rst

@@ -0,0 +1 @@
+The C++ SDK does not currently support geospatial data.

source/includes/api-details/cpp/crud/create-inverse-relationship-description.rst

@@ -0,0 +1,11 @@
+To create an object with a inverse relationship to another object, 
+assign the raw pointer of the related object to the relationship 
+property of the main object. Move the object into the realm using the 
+:cpp-sdk:`Realm.add() function <structrealm_1_1db.html>` 
+inside of a write transaction.
+
+In this example, we create two ``Person`` objects that each have a to-one 
+relationship to the same ``Dog`` object. The ``Dog`` has an inverse 
+relationship to each ``Person`` object. The inverse relationship backlink 
+is automatically updated when a linked ``Person`` object updates its 
+``Dog`` relationship.

source/includes/api-details/cpp/crud/create-list-property-description.rst

@@ -0,0 +1,28 @@
+To create an object with a list property (to-many relationship) to one or
+more objects:
+
+- Initialize the main object and the related objects
+- Use the :cpp-sdk:`push_back 
+  <structrealm_1_1managed_3_01std_1_1vector_3_01T_01_5_01_4_01_4.html>`
+  member function available to the SDK object lists
+  to append the raw pointers of the related objects to the main object's 
+  list property
+- Move the object into the realm using the 
+  :cpp-sdk:`Realm.add() function <structrealm_1_1db.html>` 
+  inside of a write transaction.
+
+In this example, we append the raw pointers of the related objects - 
+``Employee *`` - to the relationship property of the main object
+- ``Company.employees``. This creates a one-way connection from the 
+``Company`` object to the ``Employee`` objects.
+
+Then, we add the ``Company`` to the database. This copies the 
+``Company`` and ``Employee`` objects to the database. 
+
+The related ``Employee`` objects have their own lifecycle independent 
+of the main ``Company`` object. If you delete the main object, the 
+related objects remain.
+
+You can optionally create an inverse relationship to refer to the main object
+from the related object. For more information, refer to: 
+:ref:`sdks-create-object-with-inverse-relationship`.

source/includes/api-details/cpp/crud/create-mixed-property-type-description.rst

@@ -0,0 +1,3 @@
+When you create an object with a ``realm::mixed`` value, you must specify the
+type of the value you store in the property. The SDK provides a ``type()``
+function you can call to determine what type of data the property has stored.

source/includes/api-details/cpp/crud/create-object-id-property-type-description.rst

@@ -0,0 +1 @@
+Create a unique Object ID with ``realm::object_id::generate()``.

source/includes/api-details/cpp/crud/create-procedure.rst

@@ -6,7 +6,7 @@
 #. Move the unmanaged object instance into the database using the 
    :cpp-sdk:`Realm.add() function <structrealm_1_1db.html>`.
 
-   When you move an object into a realm, this consumes the object as an rvalue.
+   When you move an object into a database, this consumes the object as an rvalue.
    You must use the managed object for any data access or observation. If
    you would like to immediately work with the object, return a managed
    version of the object.

source/includes/api-details/cpp/crud/create-realm-object-description.rst

@@ -1,10 +1,10 @@
 To create an object, you must instantiate it using the ``realm`` namespace. 
-Move the object into the realm using the
+Move the object into the database using the
 :cpp-sdk:`Realm.add() function <structrealm_1_1db.html>` 
 inside of a write transaction.
 
-When you move an object into a realm, this consumes the object as an 
+When you move an object into a database, this consumes the object as an 
 rvalue. You must use the managed object for any data access or observation.
-In this example, copying the ``dog`` object into the realm consumes 
+In this example, copying the ``dog`` object into the database consumes 
 it as an rvalue. You can return the managed object to continue to work 
 with it.

source/includes/api-details/cpp/crud/create-set-property-description.rst

@@ -0,0 +1,5 @@
+You can create objects that contain 
+:cpp-sdk:`set <structrealm_1_1managed_3_01std_1_1set_3_01T_01_5_01_4_01_4.html>` 
+properties as you would any SDK object, but you can only mutate a set 
+property within a write transaction. This means you can only set the value(s) 
+of a set property within a write transaction.

source/includes/api-details/cpp/crud/create-timestamp-property-type-description.rst

@@ -0,0 +1,4 @@
+Use the `chrono library 
+<https://en.cppreference.com/w/cpp/chrono>`__
+to store a ``time_point`` relative to the ``system_clock``: 
+``<std::chrono::time_point<std::chrono::system_clock>>``

source/includes/api-details/cpp/crud/create-to-many-relationship-description.rst

@@ -0,0 +1,23 @@
+To create an object with a to-many relationship to one or more objects:
+
+- Initialize the main object and the related objects
+- Use the :cpp-sdk:`push_back 
+  <structrealm_1_1managed_3_01std_1_1vector_3_01T_01_5_01_4_01_4.html>`
+  member function available to the Realm object lists
+  to append the raw pointers of the related objects to the main object's 
+  list property
+- Move the object into the realm using the 
+  :cpp-sdk:`Realm.add() function <structrealm_1_1db.html>` 
+  inside of a write transaction.
+
+In this example, we append the raw pointers of the related objects - 
+``Employee *`` - to the relationship property of the main object
+- ``Company.employees``. This creates a one-way connection from the 
+``Company`` object to the ``Employee`` objects.
+
+Then, we add the ``Company`` to the realm. This copies the 
+``Company`` and ``Employee`` objects to the realm. 
+
+The related ``Employee`` objects have their own lifecycle independent 
+of the main ``Company`` object. If you delete the main object, the 
+related objects remain.

source/includes/api-details/cpp/crud/create-to-one-relationship-description.rst

@@ -0,0 +1,14 @@
+To create an object with a to-one relationship to another object, 
+assign the raw pointer of the related object to the relationship 
+property of the main object. Move the object into the database using 
+the :cpp-sdk:`Realm.add() function <structrealm_1_1db.html>` 
+inside of a write transaction.
+
+In this example, we assign the raw pointer of the related object - 
+``FavoriteToy *`` - to the relationship property of the main object
+- ``Dog.favoriteToy``. Then, when we add the ``dog`` object to the 
+database, this copies both the ``dog`` and ``favoriteToy`` to the database.
+
+The related ``favoriteToy`` object has its own lifecycle independent 
+of the main ``dog`` object. If you delete the main object, the related 
+object remains.

source/includes/api-details/cpp/crud/create-unmanaged-copy-description.rst

@@ -0,0 +1,4 @@
+Create an unmanaged version of a managed object by calling the ``detach()``
+function. This returns a value of the managed type. For example, calling
+the ``detach()`` function on a managed string property of a managed object
+returns a ``std::string`` copy of that property.

source/includes/api-details/cpp/crud/create-uuid-property-type-description.rst

@@ -0,0 +1,2 @@
+You can create a UUID with ``realm::uuid()``. Or you can initialize a UUID
+with a specific value, similar to ``realm::uuid("18de7916-7f84-11ec-a8a3-0242ac120002")``.

source/includes/api-details/csharp/crud/create-counter-property-type-description.rst

@@ -0,0 +1,23 @@
+Traditionally, you would implement a counter by reading a value, incrementing 
+it, and then setting it (``myObject.Counter += 1``). This does not work well in 
+an asynchronous situation like when two clients are offline. Consider 
+the following scenario:
+
+- The SDK object has a ``counter`` property of type ``int``. It is currently 
+  set to a value of ``10``.
+
+- Clients 1 and 2 both read the ``counter`` property (``10``) and each increments 
+  the value by ``1``.
+
+- When each client regains connectivity and merges their changes, they expect a 
+  value of 11, and there is no conflict. However, the counter value should be 
+  ``12``!
+
+When using a ``RealmInteger``, however, you can call the ``Increment()`` and 
+``Decrement()`` methods, and to reset the counter, you set it to ``0``, just as 
+you would an ``int``.
+
+.. important::
+
+   When you reset a ``RealmInteger``, you may run into the offline merge issue 
+   described above.

source/includes/api-details/csharp/crud/create-list-property-description.rst

@@ -0,0 +1,3 @@
+You create a list collection property by defining a getter-only property of type
+`IList<T> <https://docs.microsoft.com/en-us/dotnet/api/system.collections.generic.ilist-1?view=net-5.0>`_,
+where ``T`` can be any data type (except other collections).

source/includes/api-details/csharp/crud/create-mixed-property-type-description.rst

@@ -0,0 +1,9 @@
+.. note:: 
+
+   You cannot create a nullable ``RealmValue``. However, if you want a
+   ``RealmValue`` property to contain a null value, you can 
+   use the special ``RealmValue.Null`` property.
+
+The following code demonstrates creating a ``RealmValue`` property in a class 
+that inherits from ``IRealmObject`` and then setting and getting the value of 
+that property:

source/includes/api-details/csharp/crud/create-multiple-objects-description.rst

@@ -0,0 +1,4 @@
+You can create multiple items in the database using the
+:dotnet-sdk:`Add<T>(IEnumerable<T>, bool) <Realms.Realm.html#Realms_Realm_Add__1_System_Collections_Generic_IEnumerable___0__System_Boolean_>`
+method. It takes a collection of standalone ``IRealmObject`` instances to
+add to the database.

source/includes/api-details/csharp/crud/create-object-id-property-type-description.rst

@@ -0,0 +1 @@
+Create a unique Object ID with ``ObjectId.GenerateNewId()``.

source/includes/api-details/csharp/crud/create-objects-in-background-description.rst

@@ -0,0 +1,3 @@
+Open a write transaction with the
+or :dotnet-sdk:`Realm.WriteAsync() <reference/Realms.Realm.html#Realms_Realm_WriteAsync_System_Action_System_Threading_CancellationToken_>`
+method to avoid blocking the UI thread.

source/includes/api-details/csharp/crud/create-or-update-object-description.rst

@@ -0,0 +1,5 @@
+Upserting a document is the same as creating a new one, except you set the 
+optional ``update`` parameter to ``true``. In this example, we create a new 
+``Item`` object with a unique ``Id``. We then insert an item with the 
+same id but a different ``Name`` value. Because we have set the ``update`` 
+parameter to ``true``, the existing record is updated with the new name.

source/includes/api-details/csharp/crud/create-timestamp-property-type-description.rst

@@ -0,0 +1,6 @@
+Use ``DateTimeOffset`` to store timestamp data. The SDK converts
+``DateTimeOffset`` values to UTC before storing in the database, and does not
+store the timezone information. 
+
+See :github:`Issue #1835 </realm/realm-dotnet/issues/1835>` for more
+information.

source/includes/api-details/dart/crud/create-asymmetric-object-description.rst

@@ -1,2 +1,2 @@
-Once you have an open Realm, you can create an asymmetric object inside
+Once you have an open database, you can create an asymmetric object inside
 a write transaction. Pass your object data to ``realm.ingest``.

source/includes/api-details/dart/crud/create-counter-property-type-not-supported.rst

@@ -0,0 +1 @@
+The Flutter SDK does not currently provide a dedicated counter property type.

source/includes/api-details/dart/crud/create-list-property-description.rst

@@ -0,0 +1,3 @@
+You can create a relationship between one object and any number of objects
+using a property of type ``List<T>`` in your application, where T is an SDK
+model class.

source/includes/api-details/dart/crud/create-mixed-property-type-description.rst

@@ -0,0 +1,2 @@
+To add a ``RealmValue`` to an object, call ``RealmValue.from()`` on the data
+or ``RealmValue.nullValue()`` to set a null value.

source/includes/api-details/dart/crud/create-multiple-objects-description.rst

@@ -0,0 +1,3 @@
+To add multiple objects to a database, pass a list of multiple objects
+to :flutter-sdk:`Realm.addAll() <realm/Realm/addAll.html>` inside a write
+transaction block.

source/includes/api-details/dart/crud/create-object-id-property-type-description.rst

@@ -0,0 +1,3 @@
+Call ``ObjectId()`` to set any unique identifier properties of
+your object. Alternatively, pass a string
+to ``ObjectId()`` to set the unique identifier property to a specific value.

source/includes/api-details/dart/crud/create-objects-in-background-description.rst

@@ -0,0 +1,6 @@
+You can add, modify, or delete objects asynchronously using
+:flutter-sdk:`Realm.writeAsync() <realm/Realm/writeAsync.html>`. 
+
+When you use ``Realm.writeAsync()`` to perform write operations, waiting 
+to obtain the write lock and committing a transaction occur in the background. 
+Only the write itself occurs on the main process. 

source/includes/api-details/dart/crud/create-or-update-object-description.rst

@@ -0,0 +1,2 @@
+To upsert an object, call :flutter-sdk:`Realm.add() <realm/Realm/add.html>`
+with the optional ``update`` flag set to ``true`` inside a transaction block.

source/includes/api-details/dart/crud/create-realm-object-description.rst

@@ -8,9 +8,3 @@ Once you've opened a database, you can create objects within it using a
    });
 
 You can also return values from the write transaction callback function.
-
-.. warning:: Write RealmObjects to One Realm File
-
-   You can only write ``RealmObjects`` to a single realm file.
-   If you already wrote a ``RealmObject`` to one realm file,
-   the SDK throws a ``RealmException`` if you try to write it to another database.

source/includes/api-details/dart/crud/create-timestamp-property-type-description.rst

@@ -0,0 +1,7 @@
+Use ``DateTime`` to store timestamp data.
+
+However, it is important to note that the SDK stores ``DateTime`` in UTC.
+When you use ``DateTime``, you must create it in UTC or convert it 
+with ``.toUtc()`` before you store it. If your application requires it, 
+you can convert it back to local or the desired time zone when reading 
+from the database.

source/includes/api-details/dart/crud/create-uuid-property-type-description.rst

@@ -0,0 +1,3 @@
+To set any unique identifier properties of
+your object to a random value, call one of the ``Uuid`` methods to create a UUID,
+such as ``Uuid.v4()``.

source/includes/api-details/generic/crud/create-copy-object-to-another-database-js-ts-description.rst

@@ -0,0 +1,6 @@
+To copy a managed object to another database instance, call the
+:js-sdk:`Realm.create() <classes/Realm-1.html#create>` method in a write
+transaction with the object to copy. You can optionally specify the
+:js-sdk:`UpdateMode <enums/Realm.UpdateMode.html>` to determine how to handle
+copying objects where the target database instance already contains an object
+with a matching primary key.

source/includes/api-details/generic/crud/create-copy-object-to-another-database-no-example.rst

@@ -0,0 +1,2 @@
+The selected language does not currently have an example of how to copy an
+object to another database instance.

source/includes/api-details/generic/crud/create-geospatial-object-js-ts-description.rst

@@ -0,0 +1,3 @@
+However, in this example, because the ``MyGeoPoint`` class does not 
+extend ``Realm.Object``, we must specify ``MyGeoPoint.schema`` when opening 
+the database:

source/includes/api-details/generic/crud/create-initialize-objects-with-value-no-dedicated-api.rst

@@ -0,0 +1,3 @@
+This SDK does not provide specialized methods to initialize objects with
+a value. Instead, use standard language features to create objects with
+initial values, or set the values after creating an object.

source/includes/api-details/generic/crud/create-multiple-objects-no-dedicated-api.rst

@@ -0,0 +1 @@
+The SDK does not have a dedicated API to create multiple objects.

source/includes/api-details/generic/crud/create-objects-from-json-missing-example.rst

@@ -0,0 +1,2 @@
+This language is currently missing an example of how to create objects from
+JSON.

source/includes/api-details/generic/crud/create-timestamp-property-type-js-ts-description.rst

@@ -0,0 +1,2 @@
+Use the ``date`` property type to store timestamp data. This maps to the
+JavaScript :mdn:`Date <Web/JavaScript/Reference/Global_Objects/Date>` type.

source/includes/api-details/generic/crud/create-unmanaged-copy-not-supported.rst

@@ -0,0 +1,2 @@
+The API to create an unmanaged copy of an object is either not needed or
+not currently supported in this SDK.

source/includes/api-details/generic/crud/create-uuid-property-type-js-ts-description.rst

@@ -0,0 +1,3 @@
+To set any unique identifier properties of
+your object to a random value, call ``new UUID()``. Alternatively, pass a string
+to ``new UUID()`` to set the unique identifier property to a specific value.

source/includes/api-details/java/crud/create-copy-object-to-another-database-description.rst

@@ -0,0 +1,9 @@
+Use :java-sdk:`realm.copyToRealm() <io/realm/Realm.html#copyToRealm(E,io.realm.ImportFlag...)>`
+in a write transaction to copy a managed object to another database instance.
+
+Alternately, to copy an object that does not exist, or update an object that
+does exist, use :java-sdk:`realm.copyToRealmOrUpdate()
+<io/realm/Realm.html#copyToRealmOrUpdate(E,io.realm.ImportFlag...)>`. This
+copies an object where the target database instance does not contain an
+object with the same primary key. If the target database instance already
+contains an object with a matching primary key, it updates the object.

source/includes/api-details/java/crud/create-counter-property-type-java-description.rst

@@ -0,0 +1,44 @@
+Typically, incrementing or decrementing a
+``byte``, ``short``, ``int``, or ``long`` field of a Realm
+object looks something like this:
+
+1. Read the current value of the field.
+#. Update that value in memory to a new value based on the increment or
+   decrement.
+#. Write a new value back to the field.
+
+When multiple distributed clients attempt this at the same time,
+updates reaching clients in different orders can
+result in different values on different clients. ``MutableRealmInteger``
+improves on this by translating numeric updates into sync operations
+that can be executed in any order to converge to the same value.
+
+The :java-sdk:`counter.increment() <io/realm/MutableRealmInteger.html#increment-long->`
+and :java-sdk:`counter.decrement() <io/realm/MutableRealmInteger.html#decrement-long->`
+operators ensure that increments and decrements from multiple distributed
+clients are aggregated correctly.
+
+To change a :java-sdk:`MutableRealmInteger
+<io/realm/MutableRealmInteger.html>` value, call ``increment()`` or
+``decrement()`` within a write transaction.
+
+You can assign a ``MutableRealmInteger`` a new value with a call to
+:java-sdk:`counter.set() <io/realm/MutableRealmInteger.html#set-long->`
+within a write transaction.
+
+.. warning:: Counter Resets
+
+   Use the ``set()`` operator with extreme care. ``set()`` ignores
+   the effects of any prior calls to ``increment()`` or ``decrement()``.
+   Although the value of a ``MutableRealmInteger`` always converges
+   across devices, the specific value on which it converges depends on
+   the actual order in which operations took place.
+   Mixing ``set()`` with ``increment()`` and ``decrement()`` is
+   not advised unless fuzzy counting is acceptable. 
+
+.. literalinclude:: /examples/generated/java/local/WritesTest.snippet.counter-set.java
+   :language: java
+
+Since ``MutableRealmInteger`` instances retain a reference to their
+parent object, neither object can be garbage collected while you still
+retain a reference to the ``MutableRealmInteger``.