diff --git a/source/examples/generated/flutter/schemas.snippet.part-directive.dart b/source/examples/generated/flutter/schemas.snippet.part-directive.dart index 730fd18b33..caf6dc542c 100644 --- a/source/examples/generated/flutter/schemas.snippet.part-directive.dart +++ b/source/examples/generated/flutter/schemas.snippet.part-directive.dart @@ -1 +1 @@ -part 'schemas.realm.dart'; +part 'modelFile.realm.dart'; diff --git a/source/frameworks/flutter/quick-start.txt b/source/frameworks/flutter/quick-start.txt index 5a4d70244d..c28d39641e 100644 --- a/source/frameworks/flutter/quick-start.txt +++ b/source/frameworks/flutter/quick-start.txt @@ -59,8 +59,8 @@ classes in your application code with an SDK object schema. You then have to generate the :flutter-sdk:`RealmObjectBase ` class that's used within your application. -For more information, refer to :ref:`Define an Object Schema -`. +For more information, refer to :ref:`Define an Object Model +`. .. procedure:: diff --git a/source/includes/api-details/cpp/model-data/object-models-database-schema-description.rst b/source/includes/api-details/cpp/model-data/object-models-database-schema-description.rst new file mode 100644 index 0000000000..50baf93245 --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-database-schema-description.rst @@ -0,0 +1,3 @@ +In C++, when opening a database, you must specify which models are available by +passing the models to the template you use to open the database. Those +models must have schemas, and this list of schemas becomes the database schema. diff --git a/source/includes/api-details/cpp/model-data/object-models-define-asymmetric-object-description.rst b/source/includes/api-details/cpp/model-data/object-models-define-asymmetric-object-description.rst new file mode 100644 index 0000000000..8bdb42a6da --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-define-asymmetric-object-description.rst @@ -0,0 +1,12 @@ +In C++, define an asymmetric object the same way you would +a regular C++ struct or class. Provide a ``REALM_ASYMMETRIC_SCHEMA`` with the +struct or class name as the first argument. Add the names of any properties +that you want the database to persist. + +An ``asymmetric_object`` broadly has the same :ref:`supported types +` as ``realm::object``, with a few exceptions: + +- Asymmetric objects can link to the following types: + - ``object`` + - ``embedded_object`` + - ``std::vector`` diff --git a/source/includes/api-details/cpp/model-data/object-models-define-embedded-object-description.rst b/source/includes/api-details/cpp/model-data/object-models-define-embedded-object-description.rst new file mode 100644 index 0000000000..18ff917b0b --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-define-embedded-object-description.rst @@ -0,0 +1,6 @@ +In C++, you define an embedded object by providing a ``REALM_EMBEDDED_SCHEMA`` +whose first argument is the struct or class name. Add the names of any +properties that you want the database to persist. + +Define a property as an embedded object on the parent object by setting +a pointer to the embedded object's type. diff --git a/source/includes/api-details/cpp/model-data/object-models-define-geospatial-object-not-supported.rst b/source/includes/api-details/cpp/model-data/object-models-define-geospatial-object-not-supported.rst new file mode 100644 index 0000000000..0fb2bb5e45 --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-define-geospatial-object-not-supported.rst @@ -0,0 +1 @@ +The C++ SDK does not currently support geospatial data. diff --git a/source/includes/api-details/cpp/model-data/object-models-define-optional-property-description.rst b/source/includes/api-details/cpp/model-data/object-models-define-optional-property-description.rst new file mode 100644 index 0000000000..01a68f1d88 --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-define-optional-property-description.rst @@ -0,0 +1,2 @@ +In C++, define an optional type using the class template +`std::optional `__. diff --git a/source/includes/api-details/cpp/model-data/object-models-define-realm-object-description.rst b/source/includes/api-details/cpp/model-data/object-models-define-realm-object-description.rst new file mode 100644 index 0000000000..ef4ddf57be --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-define-realm-object-description.rst @@ -0,0 +1,12 @@ +In C++, the base :cpp-sdk:`object ` +provides accessors and other methods to work with SDK objects, including +things like: + +- Checking whether an object is valid +- Getting its managing database instance +- Registering a notification token + +Define a C++ struct or class as you would normally. Add a ``REALM_SCHEMA`` +whose first value is the name of the struct or class. Add the names of the +properties that you want the database to manage. Omit any fields that you do +not want to persist. diff --git a/source/includes/api-details/cpp/model-data/object-models-define-sdk-object-model-description.rst b/source/includes/api-details/cpp/model-data/object-models-define-sdk-object-model-description.rst new file mode 100644 index 0000000000..53aed98776 --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-define-sdk-object-model-description.rst @@ -0,0 +1,9 @@ +In the C++ SDK, you can define your models as regular C++ structs or classes. +Provide an :ref:`sdks-object-schema` with the object type name and +the names of any properties that you want to persist to the database. When you +add the object to the database, the SDK ignores any properties that you omit +from the schema. + +You must declare your object and the schema within the ``realm`` namespace. +You must then use the ``realm`` namespace when you initialize and perform CRUD +operations with the object. diff --git a/source/includes/api-details/cpp/model-data/object-models-designate-primary-key-description.rst b/source/includes/api-details/cpp/model-data/object-models-designate-primary-key-description.rst new file mode 100644 index 0000000000..9cfbe7a1c4 --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-designate-primary-key-description.rst @@ -0,0 +1,11 @@ +C++ supports primary keys of the following types, and their optional variants: + +- ``int64_t`` +- ``realm::object_id`` +- ``realm::uuid`` +- ``std::string`` + +Additionally, a required ``realm::enum`` property can be a primary key, but +``realm::enum`` cannot be optional if it is used as a primary key. + +Set a property as a primary key with the ``primary_key`` template. diff --git a/source/includes/api-details/cpp/model-data/object-models-fts-index-property-not-supported.rst b/source/includes/api-details/cpp/model-data/object-models-fts-index-property-not-supported.rst new file mode 100644 index 0000000000..53a38fce2c --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-fts-index-property-not-supported.rst @@ -0,0 +1 @@ +The C++ SDK does not currently support Full-Text Search. diff --git a/source/includes/api-details/cpp/model-data/object-models-ignore-property-description.rst b/source/includes/api-details/cpp/model-data/object-models-ignore-property-description.rst new file mode 100644 index 0000000000..e05b7ce89f --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-ignore-property-description.rst @@ -0,0 +1 @@ +To ignore a property, omit it from the :ref:`object schema `. diff --git a/source/includes/api-details/cpp/model-data/object-models-index-property-not-supported.rst b/source/includes/api-details/cpp/model-data/object-models-index-property-not-supported.rst new file mode 100644 index 0000000000..519f3da06a --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-index-property-not-supported.rst @@ -0,0 +1 @@ +The C++ SDK does not currently support indexing a property. \ No newline at end of file diff --git a/source/includes/api-details/cpp/model-data/object-models-map-model-or-property-to-different-name-not-supported.rst b/source/includes/api-details/cpp/model-data/object-models-map-model-or-property-to-different-name-not-supported.rst new file mode 100644 index 0000000000..df47476348 --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-map-model-or-property-to-different-name-not-supported.rst @@ -0,0 +1,2 @@ +C++ does not currently provide an API to map a model or property name to a +different stored name. diff --git a/source/includes/api-details/cpp/model-data/object-models-object-model-description.rst b/source/includes/api-details/cpp/model-data/object-models-object-model-description.rst new file mode 100644 index 0000000000..067fa55318 --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-object-model-description.rst @@ -0,0 +1,7 @@ +The C++ SDK object model is a regular C++ class or struct that contains +a collection of properties. When you define your C++ class or struct, you +must also provide an object schema. The schema is a C++ macro that gives the +SDK information about which properties to persist, and what type of database +object it is. + +You must define your SDK object model within the ``realm`` namespace. diff --git a/source/includes/api-details/cpp/model-data/object-models-object-schema-description.rst b/source/includes/api-details/cpp/model-data/object-models-object-schema-description.rst new file mode 100644 index 0000000000..7bde1a40cc --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-object-schema-description.rst @@ -0,0 +1,13 @@ +In C++, schemas are managed through macros. The schema must list every +property type that you want to persist. The SDK inspects the object model to +determine the property types and other special information, such as whether +a property is the object's primary key. + +A schema must accompany every object model you want to persist, and it may be +one of: + +- ``REALM_SCHEMA`` +- ``REALM_EMBEDDED_SCHEMA`` +- ``REALM_ASYMMETRIC_SCHEMA`` + +You must define the schema and your object model within the ``realm`` namespace. diff --git a/source/includes/api-details/cpp/model-data/object-models-unstructured-data-not-supported.rst b/source/includes/api-details/cpp/model-data/object-models-unstructured-data-not-supported.rst new file mode 100644 index 0000000000..ddd41f7f12 --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-unstructured-data-not-supported.rst @@ -0,0 +1,2 @@ +C++ does not currently support modeling unstructured data as a collection +of the mixed property type. diff --git a/source/includes/api-details/csharp/model-data/object-models-database-schema-description.rst b/source/includes/api-details/csharp/model-data/object-models-database-schema-description.rst new file mode 100644 index 0000000000..f0527803a8 --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-database-schema-description.rst @@ -0,0 +1,16 @@ +In C#, you can define object schemas by using the C# class declarations. +When a database is initialized, it discovers the SDK objects defined in all +assemblies that have been loaded and generates schemas accordingly. If you +want to restrict a database to manage only a subset of the SDK models in the +loaded assemblies, you *can* explicitly pass the models when configuring a +database. + +For more information, refer to :ref:`sdks-provide-a-subset-of-models-to-a-database`. + +.. note:: + + .NET does not load an assembly until you reference a class in it. If you + define your object models in one assembly and instantiate a database + in another, be sure to call a method in the assembly that contains the object + models *before* initialization. Otherwise, the SDK does not discover + the objects when it first loads. diff --git a/source/includes/api-details/csharp/model-data/object-models-define-asymmetric-object-description.rst b/source/includes/api-details/csharp/model-data/object-models-define-asymmetric-object-description.rst new file mode 100644 index 0000000000..0428e4a92d --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-define-asymmetric-object-description.rst @@ -0,0 +1,3 @@ +In C#, to define a asymmetric object, inherit from the the +:dotnet-sdk:`IAsymmetricObject ` +interface and declare the class a ``partial`` class. diff --git a/source/includes/api-details/csharp/model-data/object-models-define-custom-setters-description.rst b/source/includes/api-details/csharp/model-data/object-models-define-custom-setters-description.rst new file mode 100644 index 0000000000..8ab3229f5b --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-define-custom-setters-description.rst @@ -0,0 +1,2 @@ +In the following code, the private ``email`` property is stored in the database, +but the public ``Email`` property, which provides validation, is not persisted. diff --git a/source/includes/api-details/csharp/model-data/object-models-define-embedded-object-description.rst b/source/includes/api-details/csharp/model-data/object-models-define-embedded-object-description.rst new file mode 100644 index 0000000000..60973a7c7d --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-define-embedded-object-description.rst @@ -0,0 +1,8 @@ +In C#, to define an embedded object, inherit from the the +:dotnet-sdk:`IEmbeddedObject ` interface +and declare the class a ``partial`` class. You can reference an embedded object +type from parent object types in the same way as you would define a relationship. + +Consider the following example where the ``Address`` is an Embedded Object. Both +the ``Contact`` and the ``Business`` classes reference the ``Address`` as an +embedded object. diff --git a/source/includes/api-details/csharp/model-data/object-models-define-geospatial-object-description.rst b/source/includes/api-details/csharp/model-data/object-models-define-geospatial-object-description.rst new file mode 100644 index 0000000000..1c6ebe3235 --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-define-geospatial-object-description.rst @@ -0,0 +1,24 @@ +In C#, to create a class that conforms to the GeoJSON spec: + +1. Create an embedded object (a class that inherits from + :dotnet-sdk:`IEmbeddedObject `). + +#. At a minimum, add the two fields required by the GeoJSON spec: + + - A field of type ``IList`` that maps to a "coordinates" (case sensitive) + property in the object schema. + + - A field of type ``string`` that maps to a "type" property. The value of this + field must be "Point". + +The following example shows an embedded class named "CustomGeoPoint" that is used +to persist GeoPoint data: + +.. literalinclude:: /examples/generated/dotnet/CustomGeoPoint.snippet.customgeopoint.cs + :language: csharp + +Use the Embedded Class +`````````````````````` + +You then use the custom GeoPoint class in your SDK object model, as shown in +the following example. diff --git a/source/includes/api-details/csharp/model-data/object-models-define-optional-property-description.rst b/source/includes/api-details/csharp/model-data/object-models-define-optional-property-description.rst new file mode 100644 index 0000000000..9934c386e7 --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-define-optional-property-description.rst @@ -0,0 +1,31 @@ +In C#, value types, such as ``int`` and ``bool``, are implicitly non-nullable. +However, they can be made optional by using the question mark (``?``) `notation +`__. + +Beginning with C# 8.0, nullable reference types were introduced. If your project +is using C# 8.0 or later, you can also declare reference types, such as ``string`` +and ``byte[]``, as nullable with ``?``. + +.. note:: + + Beginning with .NET 6.0, the nullable context is enabled by default for new + projects. For older projects, you can manually enable it. For more information, + refer to ``__. + +The SDK fully supports the nullable-aware context and uses nullability +to determine whether a property is required or optional. + +Alternatives to the Nullable-Aware Context +`````````````````````````````````````````` + +If you are using the older schema type definition (your classes derive from +the ``RealmObject`` base class), or you do not have nullability enabled, you +must use the :dotnet-sdk:`[Required] ` +attribute for any required ``string`` and ``byte[]`` property. + +You may prefer to have more flexibility in defining the nullability of properties +in your SDK objects. You can do so by setting ``realm.ignore_objects_nullability = true`` +in a `global configuration file `__. + +If you enable ``realm.ignore_objects_nullability``, the SDK ignores nullability +annotations on object properties, including collections of SDK objects. diff --git a/source/includes/api-details/csharp/model-data/object-models-define-realm-object-description.rst b/source/includes/api-details/csharp/model-data/object-models-define-realm-object-description.rst new file mode 100644 index 0000000000..a4544c80ee --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-define-realm-object-description.rst @@ -0,0 +1,8 @@ +In C#, to define a Realm object, inherit from the the +:dotnet-sdk:`IRealmObject ` interface and +declare the class a ``partial`` class. + +The following code block shows an object schema that describes a Dog. +Every Dog object must include a ``Name`` and may +optionally include the dog's ``Age``, ``Breed`` and a list of people that +represents the dog's ``Owners``. diff --git a/source/includes/api-details/csharp/model-data/object-models-define-sdk-object-model-description.rst b/source/includes/api-details/csharp/model-data/object-models-define-sdk-object-model-description.rst new file mode 100644 index 0000000000..115ac6901a --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-define-sdk-object-model-description.rst @@ -0,0 +1,32 @@ +All SDK objects inherit from the +:dotnet-sdk:`IRealmObject `, +:dotnet-sdk:`IEmbeddedObject `, or +:dotnet-sdk:`IAsymmetricObject ` +interface and must be declared ``partial`` classes. + +In versions of the .NET SDK v10.18.0 and earlier, objects derive from +:dotnet-sdk:`RealmObject `, +:dotnet-sdk:`EmbeddedObject `, or +:dotnet-sdk:`AsymmetricObject ` +base classes. This approach to SDK model definition is still supported, but +does not include new features such as the :ref:`nullability annotations +`. These base classes will be +deprecated in a future SDK release. You should use the interfaces for any +new classes that you write and should consider migrating your existing +classes. + +.. literalinclude:: /examples/generated/dotnet/ObjectModelsAndSchemas.snippet.dog_class.cs + :language: csharp + +**Customize the Object Schema (Optional)** + +You can use the +:dotnet-sdk:`Schema ` +property of the +:dotnet-sdk:`RealmConfigurationBase ` +object to customize how schemas are defined. The following code example shows +three ways to do this, from easiest to most complex: + +- Automatic configuration +- Manual configuration +- A mix of both methods diff --git a/source/includes/api-details/csharp/model-data/object-models-designate-primary-key-description.rst b/source/includes/api-details/csharp/model-data/object-models-designate-primary-key-description.rst new file mode 100644 index 0000000000..6172aecf7e --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-designate-primary-key-description.rst @@ -0,0 +1,13 @@ +You can create a primary key with any of the following types (or their nullable counterparts): + +- ``ObjectId`` +- ``UUID`` +- ``string`` +- ``char`` +- ``byte`` +- ``short`` +- ``int`` +- ``long`` + +To designate a property as the object's primary key, use the +:dotnet-sdk:`Primary Key ` attribute. diff --git a/source/includes/api-details/csharp/model-data/object-models-fts-index-property-description.rst b/source/includes/api-details/csharp/model-data/object-models-fts-index-property-description.rst new file mode 100644 index 0000000000..5c93c23304 --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-fts-index-property-description.rst @@ -0,0 +1,4 @@ +To index an FTS property, use the :dotnet-sdk:`Indexed ` +attribute with the :dotnet-sdk:`IndexType.FullText ` +enum. In the following example, we have a ``FullText`` index on the +``Biography`` property: diff --git a/source/includes/api-details/csharp/model-data/object-models-ignore-property-description.rst b/source/includes/api-details/csharp/model-data/object-models-ignore-property-description.rst new file mode 100644 index 0000000000..979b5577f7 --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-ignore-property-description.rst @@ -0,0 +1,5 @@ +A property is ignored by default if it is not autoimplemented or +does not have a setter. + +Ignore an object property with the +:dotnet-sdk:`Ignored ` attribute. diff --git a/source/includes/api-details/csharp/model-data/object-models-index-property-description.rst b/source/includes/api-details/csharp/model-data/object-models-index-property-description.rst new file mode 100644 index 0000000000..35caf099e5 --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-index-property-description.rst @@ -0,0 +1,20 @@ +You can index properties of these data types: + +- ``bool`` +- ``byte`` +- ``short`` +- ``int`` +- ``long`` +- ``DateTimeOffset`` +- ``char`` +- ``string`` +- ``ObjectId`` +- ``UUID`` + +To index a property, use the :dotnet-sdk:`Indexed ` +attribute. With the ``Indexed`` attribute, you can specify the type of index +on the property by using the :dotnet-sdk:`IndexType ` +enum. + +In the following example, we have a default ("General") index on the ``Name`` +property: diff --git a/source/includes/api-details/csharp/model-data/object-models-map-model-or-property-to-different-name-description.rst b/source/includes/api-details/csharp/model-data/object-models-map-model-or-property-to-different-name-description.rst new file mode 100644 index 0000000000..0d8f7cf7bc --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-map-model-or-property-to-different-name-description.rst @@ -0,0 +1,2 @@ +Use the :dotnet-sdk:`[MapTo] ` +attribute to rename a class or property. diff --git a/source/includes/api-details/csharp/model-data/object-models-model-unstructured-data-description.rst b/source/includes/api-details/csharp/model-data/object-models-model-unstructured-data-description.rst new file mode 100644 index 0000000000..67f244c2e2 --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-model-unstructured-data-description.rst @@ -0,0 +1,10 @@ +Starting in SDK version 12.22.0, you can store collections of mixed data +within a ``RealmValue`` property. + +To model unstructured data in your app, define the appropriate properties in +your schema as :ref:`RealmValue ` types. You can then +set these ``RealmValue`` properties as a :ref:`list ` +or a :ref:`dictionary ` of ``RealmValue`` +elements. + +Note that ``RealmValue`` *cannot* represent a set or an embedded object. diff --git a/source/includes/api-details/csharp/model-data/object-models-object-model-description.rst b/source/includes/api-details/csharp/model-data/object-models-object-model-description.rst new file mode 100644 index 0000000000..5ddd400424 --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-object-model-description.rst @@ -0,0 +1 @@ +In C#, SDK object models are regular C# classes that define the SDK data model. diff --git a/source/includes/api-details/csharp/model-data/object-models-object-schema-description.rst b/source/includes/api-details/csharp/model-data/object-models-object-schema-description.rst new file mode 100644 index 0000000000..a4d056e8c8 --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-object-schema-description.rst @@ -0,0 +1,4 @@ +In C#, when the SDK processes SDK object types, it generates a schema for each +class based on the class properties. However, there may be times that you want +to manually define the schema, and the .NET SDK provides a mechanism for doing +so. diff --git a/source/includes/api-details/csharp/model-data/object-models-set-default-value-for-property-description.rst b/source/includes/api-details/csharp/model-data/object-models-set-default-value-for-property-description.rst new file mode 100644 index 0000000000..7a2a1e5a90 --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-set-default-value-for-property-description.rst @@ -0,0 +1,9 @@ +You can use the built-in language features to assign a default value to a property. +In C#, you can assign a default value on primitives in the property declaration. + +.. note:: Default Values and Nullability + + While default values ensure that a newly created object cannot contain + a value of ``null`` (unless you specify a default value of ``null``), + they do not impact the nullability of a property. For details about + nullability, refer to :ref:`sdks-optional-property-types`. diff --git a/source/includes/api-details/dart/model-data/object-models-database-schema-description.rst b/source/includes/api-details/dart/model-data/object-models-database-schema-description.rst new file mode 100644 index 0000000000..6c91eea29b --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-database-schema-description.rst @@ -0,0 +1,5 @@ +In Dart, the database configuration takes a :flutter-sdk:`RealmSchema +` that has an iterable collection of +:flutter-sdk:`SchemaObjects `. These +``SchemaObjects`` represent the SDK object types that the database file can +manage. diff --git a/source/includes/api-details/dart/model-data/object-models-define-asymmetric-object-description.rst b/source/includes/api-details/dart/model-data/object-models-define-asymmetric-object-description.rst new file mode 100644 index 0000000000..808942a2c0 --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-define-asymmetric-object-description.rst @@ -0,0 +1,10 @@ +In Dart, to define an asymmetric object, create a class model and add the +`RealmModel `__ +annotation. Pass `ObjectType.asymmetricObject +`__ +to the ``@RealmModel()`` annotation. + +Follow the :ref:`sdks-define-objects` procedure detailed on this +page to generate the ``RealmObject`` model and schema definitions. + +Then, use the generated ``RealmObject`` model in your application code. diff --git a/source/includes/api-details/dart/model-data/object-models-define-embedded-object-description.rst b/source/includes/api-details/dart/model-data/object-models-define-embedded-object-description.rst new file mode 100644 index 0000000000..4264428a9d --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-define-embedded-object-description.rst @@ -0,0 +1,18 @@ +In Dart, to define an embedded object, create a class model and add the +`RealmModel `__ +annotation. Pass `ObjectType.embeddedObject +`__ +to the ``@RealmModel()`` annotation. + +Embedded objects must be nullable when defining them in the parent object's +``RealmModel``. You can use the :flutter-sdk:`parent +` property to access the parent of +the embedded object. + +Follow the :ref:`sdks-define-objects` procedure detailed on this +page to generate the ``RealmObject`` model and schema definitions. + +Then, use the generated ``RealmObject`` model in your application code. + +The following example shows how to model an embedded object in a Realm object +schema. The ``_Address`` model is embedded within the ``_Person`` model. diff --git a/source/includes/api-details/dart/model-data/object-models-define-geospatial-object-description.rst b/source/includes/api-details/dart/model-data/object-models-define-geospatial-object-description.rst new file mode 100644 index 0000000000..55f23480ea --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-define-geospatial-object-description.rst @@ -0,0 +1,24 @@ +In Dart, to create a class that conforms to the GeoJSON spec, you: + +1. Create an embedded object. For more information about embedded + objects, refer to :ref:`sdks-object-models`. + +#. At a minimum, add the two fields required by the GeoJSON spec: + + - A field of type ``double[]`` that maps to a "coordinates" (case sensitive) + property in the schema. + + - A field of type ``string`` that maps to a "type" property. The value of this + field must be "Point". + +The following example shows an embedded class named ``MyGeoPoint`` that is +used to persist geospatial data: + +.. literalinclude:: /examples/generated/flutter/geospatial_data_test.snippet.define-geopoint-class.dart + :language: dart + +Use the Embedded Class +``````````````````````` + +You then use the custom ``MyGeoPoint`` class in your data model, as shown +in the following example: diff --git a/source/includes/api-details/dart/model-data/object-models-define-optional-property-description.rst b/source/includes/api-details/dart/model-data/object-models-define-optional-property-description.rst new file mode 100644 index 0000000000..b6238f6620 --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-define-optional-property-description.rst @@ -0,0 +1,3 @@ +In Dart, value types are implicitly non-nullable, but can be made optional +(nullable) by appending `? `__. Include ``?`` +to make properties optional. diff --git a/source/includes/api-details/dart/model-data/object-models-define-realm-object-description.rst b/source/includes/api-details/dart/model-data/object-models-define-realm-object-description.rst new file mode 100644 index 0000000000..f7732b0a22 --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-define-realm-object-description.rst @@ -0,0 +1,6 @@ +In Dart, to define a Realm object, create a class model and add the +`RealmModel `__ +annotation. Follow the :ref:`sdks-define-objects` procedure detailed on this +page to generate the ``RealmObject`` model and schema definitions. + +Then, use the generated ``RealmObject`` model in your application code. diff --git a/source/includes/api-details/dart/model-data/object-models-define-sdk-object-model-description.rst b/source/includes/api-details/dart/model-data/object-models-define-sdk-object-model-description.rst new file mode 100644 index 0000000000..bd379a827a --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-define-sdk-object-model-description.rst @@ -0,0 +1,85 @@ +1. Create Generated File Part Directive + + .. versionchanged:: v2.0.0 + Generated files are named ``.realm.dart`` instead of ``.g.dart`` + + Add a part directive to include the ``RealmObject`` file that you generate in step 4 + in the same package as the file you're currently working on. + + .. literalinclude:: /examples/generated/flutter/schemas.snippet.part-directive.dart + :language: dart + :caption: modelFile.dart + +2. Create a ``RealmModel``. + + Create the model for your SDK object type. + You must include the annotation `RealmModel `__ + at the top of the class definition. + + You'll use the ``RealmModel`` to generate the public ``RealmObject`` + used throughout the application in step 4. + + You can make the model private or public. We recommend making + all models private and defining them in a single file. + Prepend the class name with an underscore (``_``) to make it private. + + If you need to define your schema across multiple files, + you can make the ``RealmModel`` public. Prepend the name with a dollar + sign (``$``) to make the model public. You must do this to generate the + ``RealmObject`` from the ``RealmModel``, as described in step 4. + + Add fields to the ``RealmModel``. + You can add fields of any :ref:`supported data types `. + Include additional behavior using :ref:`special object types + `. + + .. literalinclude:: /examples/generated/flutter/schemas.snippet.create-realm-model.dart + :language: dart + :caption: modelFile.dart + +3. Generate a ``RealmObject``. + + .. versionchanged:: v2.0.0 + Generated files are named ``.realm.dart`` instead of ``.g.dart`` + + Generate the ``RealmObject``, which you'll use in your application: + + .. tabs:: + + .. tab:: Flutter + :tabid: flutter + + .. code-block:: + + dart run realm generate + + .. tab:: Dart + :tabid: dart + + .. code-block:: + + dart run realm_dart generate + + This command generates the file in the same directory as your model file. + It has the name you specified in the part directive of step 2. + + .. tip:: Track the generated file + + Track the generated file in your version control system, such as git. + + .. example:: File structure after generating model + + .. code-block:: + + . + ├── modelFile.dart + ├── modelFile.realm.dart // newly generated file + ├── myapp.dart + └── ...rest of application + +4. Use the ``RealmObject`` in your application code. + + Use the ``RealmObject`` that you generated in the previous step in your + application code. Since you included the generated file as part of the same + package where you defined the ``RealmModel`` in step 2, access the + ``RealmObject`` by importing the file with the ``RealmModel``. diff --git a/source/includes/api-details/dart/model-data/object-models-designate-primary-key-description.rst b/source/includes/api-details/dart/model-data/object-models-designate-primary-key-description.rst new file mode 100644 index 0000000000..2b3786d240 --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-designate-primary-key-description.rst @@ -0,0 +1,10 @@ +You can create a primary key with any of the following types (or their nullable counterparts): + +- ``String`` +- ``int`` +- ``ObjectId`` +- ``Uuid`` + +To designate a property as the object's primary key, use the `PrimaryKey +`__ +annotation. diff --git a/source/includes/api-details/dart/model-data/object-models-fts-index-property-description.rst b/source/includes/api-details/dart/model-data/object-models-fts-index-property-description.rst new file mode 100644 index 0000000000..874c3e88ea --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-fts-index-property-description.rst @@ -0,0 +1,5 @@ +To create an FTS index on a property, use the `@Indexed +`__ +annotation and specify the `RealmIndexType `__ +as ``fullText``. This enables full-text queries on the property. In the +following example, we mark the pattern and material properties with the FTS annotation: diff --git a/source/includes/api-details/dart/model-data/object-models-ignore-property-description.rst b/source/includes/api-details/dart/model-data/object-models-ignore-property-description.rst new file mode 100644 index 0000000000..8d7aa606d1 --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-ignore-property-description.rst @@ -0,0 +1,5 @@ +To ignore a property, add the `Ignored `__ +annotation to the property in your ``RealmModel``. When you +:ref:`generate the model `, the object generator doesn't +include the property in the ``RealmObject`` schema or persist it to the +database. diff --git a/source/includes/api-details/dart/model-data/object-models-index-property-description.rst b/source/includes/api-details/dart/model-data/object-models-index-property-description.rst new file mode 100644 index 0000000000..42eacaeeef --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-index-property-description.rst @@ -0,0 +1,13 @@ +You can index properties of these data types: + +- ``bool`` +- ``int`` +- ``String`` +- ``ObjectId`` +- ``Uuid`` +- ``DateTime`` +- ``RealmValue`` + +To create an index on the field, add the `Indexed +`__ +annotation to the property. diff --git a/source/includes/api-details/dart/model-data/object-models-map-model-or-property-to-different-name-description.rst b/source/includes/api-details/dart/model-data/object-models-map-model-or-property-to-different-name-description.rst new file mode 100644 index 0000000000..6d403827fa --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-map-model-or-property-to-different-name-description.rst @@ -0,0 +1,3 @@ +Use the `MapTo `__ +annotation to map an SDK object model or property to a different stored +name. diff --git a/source/includes/api-details/dart/model-data/object-models-model-unstructured-data-description.rst b/source/includes/api-details/dart/model-data/object-models-model-unstructured-data-description.rst new file mode 100644 index 0000000000..8d8b7b67ec --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-model-unstructured-data-description.rst @@ -0,0 +1,15 @@ +.. versionadded:: 2.0.0 + +Starting in Flutter SDK version 2.0.0, you can store +collections of mixed data within a ``RealmValue`` property. + +To model unstructured data in your app, define the appropriate properties in +your schema as :ref:`RealmValue ` types. You can then set +these ``RealmValue`` properties as a :ref:`RealmList ` +or a :ref:`RealmMap ` collection of +``RealmValue`` elements. + +Note that ``RealmValue`` *cannot* represent a ``RealmSet`` or an embedded object. + +For example, you might use a ``RealmValue`` that contains a map of mixed +data when modeling a variable event log object. diff --git a/source/includes/api-details/dart/model-data/object-models-model-unstructured-data-example.rst b/source/includes/api-details/dart/model-data/object-models-model-unstructured-data-example.rst new file mode 100644 index 0000000000..d594d65cce --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-model-unstructured-data-example.rst @@ -0,0 +1,23 @@ +.. literalinclude:: /examples/generated/flutter/define_realm_model_test.snippet.unstructured-data-model.dart + :language: dart + :emphasize-lines: 10 + :caption: Data model + +.. io-code-block:: + :copyable: true + :caption: Create unstructured data + + .. input:: /examples/generated/flutter/define_realm_model_test.snippet.create-unstructured-data-example.dart + :language: dart + + .. output:: + :language: shell + + Event Type: purchase + Timestamp: 2024-03-18 13:50:58.402979Z + User ID: user123 + Details: + Item: + ipAddress: RealmValue(192.168.1.1) + items: RealmValue([RealmValue({id: RealmValue(1), name: RealmValue(Laptop), price: RealmValue(1200.0)}), RealmValue({id: RealmValue(2), name: RealmValue(Mouse), price: RealmValue(49.99)})]) + total: RealmValue(1249.99) diff --git a/source/includes/api-details/dart/model-data/object-models-object-model-description.rst b/source/includes/api-details/dart/model-data/object-models-object-model-description.rst new file mode 100644 index 0000000000..810dcf3ecd --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-object-model-description.rst @@ -0,0 +1,5 @@ +In Dart, you can define the object model using the native class implementation. +You must annotate the class model with the SDK object type definition. As a +separate step, you must generate SDK object classes that contain additional +methods and meta-information that makes it possible to store, retrieve, and +work with the object. diff --git a/source/includes/api-details/dart/model-data/object-models-object-schema-description.rst b/source/includes/api-details/dart/model-data/object-models-object-schema-description.rst new file mode 100644 index 0000000000..66a7ca35e6 --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-object-schema-description.rst @@ -0,0 +1,3 @@ +In Dart, the object schema is automatically generated as part of the SDK object +model code generation step. You can view the schema as a ``static final schema`` +property in the generated ``.realm.dart`` file. diff --git a/source/includes/api-details/dart/model-data/object-models-set-default-value-for-property-description.rst b/source/includes/api-details/dart/model-data/object-models-set-default-value-for-property-description.rst new file mode 100644 index 0000000000..3063be0ae7 --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-set-default-value-for-property-description.rst @@ -0,0 +1,2 @@ +You can use the built-in language features to assign a default value to a property. +Assign a default value in the property declaration. diff --git a/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst b/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst index 64812df3dc..58c2064164 100644 --- a/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst +++ b/source/includes/api-details/dart/quick-start/quick-start-define-your-object-model-procedure.rst @@ -4,8 +4,8 @@ classes in your application code with an SDK object schema. You then have to generate the :flutter-sdk:`RealmObjectBase ` class that's used within your application. -For more information, refer to :ref:`Define an Object Schema -`. +For more information, refer to :ref:`Define an Object Model +`. **Create a Model Class** diff --git a/source/includes/api-details/generic/model-data/object-models-define-projection-not-supported.rst b/source/includes/api-details/generic/model-data/object-models-define-projection-not-supported.rst new file mode 100644 index 0000000000..a1db911e94 --- /dev/null +++ b/source/includes/api-details/generic/model-data/object-models-define-projection-not-supported.rst @@ -0,0 +1,3 @@ +Projection is not currently supported for this programming language. If you'd +like to file a feature request for this functionality, refer to +:ref:`getting-help`. diff --git a/source/includes/api-details/java/model-data/object-models-database-schema-description.rst b/source/includes/api-details/java/model-data/object-models-database-schema-description.rst new file mode 100644 index 0000000000..2350949522 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-database-schema-description.rst @@ -0,0 +1,2 @@ +In Java, the SDK automatically adds all classes in your project +that derive from an SDK object type to the database schema. diff --git a/source/includes/api-details/java/model-data/object-models-define-asymmetric-object-not-supported.rst b/source/includes/api-details/java/model-data/object-models-define-asymmetric-object-not-supported.rst new file mode 100644 index 0000000000..8f5ad82b4e --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-define-asymmetric-object-not-supported.rst @@ -0,0 +1,2 @@ +The Java SDK does not support Data Ingest or asymmetric objects. Use the +Kotlin SDK for heavy insert-only workloads. diff --git a/source/includes/api-details/java/model-data/object-models-define-embedded-object-java-description.rst b/source/includes/api-details/java/model-data/object-models-define-embedded-object-java-description.rst new file mode 100644 index 0000000000..e661f06c87 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-define-embedded-object-java-description.rst @@ -0,0 +1,10 @@ +To embed an object, set the ``embedded`` property of the +:java-sdk:`@RealmClass ` +annotation to ``true`` on the class that you'd like to nest within +another class: + +.. include:: /examples/generated/java/local/FlyEmbeddedExample.snippet.complete.java.rst + +Then, any time you reference that class from another class, +the SDK embeds the referenced class within the enclosing +class, as in the following example: diff --git a/source/includes/api-details/java/model-data/object-models-define-embedded-object-kotlin-description.rst b/source/includes/api-details/java/model-data/object-models-define-embedded-object-kotlin-description.rst new file mode 100644 index 0000000000..8041391625 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-define-embedded-object-kotlin-description.rst @@ -0,0 +1,10 @@ +To embed an object, set the ``embedded`` property of the +:java-sdk:`@RealmClass ` +annotation to ``true`` on the class that you'd like to nest within +another class: + +.. include:: /examples/generated/java/local/FlyEmbeddedExampleKt.snippet.complete.kt.rst + +Then, any time you reference that class from another class, +the SDK embeds the referenced class within the enclosing +class, as in the following example: diff --git a/source/includes/api-details/java/model-data/object-models-define-geospatial-object-not-supported.rst b/source/includes/api-details/java/model-data/object-models-define-geospatial-object-not-supported.rst new file mode 100644 index 0000000000..6f7bc6f1c1 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-define-geospatial-object-not-supported.rst @@ -0,0 +1,2 @@ +The Java SDK does not support geospatial data. Use the Kotlin SDK to work with +GeoJSON and location data. diff --git a/source/includes/api-details/java/model-data/object-models-define-optional-property-java-description.rst b/source/includes/api-details/java/model-data/object-models-define-optional-property-java-description.rst new file mode 100644 index 0000000000..10afdabf48 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-define-optional-property-java-description.rst @@ -0,0 +1,22 @@ +Fields marked with Java object types are nullable by default. All other types +(primitives) are required by default. You can mark a nullable field with the +:java-sdk:`@Required ` +annotation to prevent that field from holding a null value. + +The following types are nullable: + +- ``String`` +- ``Date`` +- ``UUID`` +- ``ObjectId`` +- ``Integer`` +- ``Long`` +- ``Short`` +- ``Byte`` or ``byte[]`` +- ``Boolean`` +- ``Float`` +- ``Double`` + +Primitive types like ``int`` and ``long`` are non-nullable by +default and cannot be made nullable, as they cannot be set to a +null value. diff --git a/source/includes/api-details/java/model-data/object-models-define-optional-property-kotlin-description.rst b/source/includes/api-details/java/model-data/object-models-define-optional-property-kotlin-description.rst new file mode 100644 index 0000000000..c2331095d1 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-define-optional-property-kotlin-description.rst @@ -0,0 +1,17 @@ +In Kotlin, fields are considered nullable only if a field is +marked nullable with the Kotlin `? operator +`__ except +for the following types: + +- ``String`` +- ``Date`` +- ``UUID`` +- ``ObjectId`` +- ``Decimal128`` +- ``RealmAny`` + +You can require any type that ends with the Kotlin ``?`` +operator, such as ``Int?``. + +The ``RealmList`` type is non-nullable by default and cannot be +made nullable. diff --git a/source/includes/api-details/java/model-data/object-models-define-realm-object-description.rst b/source/includes/api-details/java/model-data/object-models-define-realm-object-description.rst new file mode 100644 index 0000000000..dc8ee7c10d --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-define-realm-object-description.rst @@ -0,0 +1,3 @@ +In the Java SDK, to define a Realm object in your application, +subclass :java-sdk:`RealmObject ` +or implement :java-sdk:`RealmModel `. diff --git a/source/includes/api-details/java/model-data/object-models-define-sdk-object-model-java-description.rst b/source/includes/api-details/java/model-data/object-models-define-sdk-object-model-java-description.rst new file mode 100644 index 0000000000..09a988c615 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-define-sdk-object-model-java-description.rst @@ -0,0 +1,38 @@ +In Java, to define an SDK object in your application, +create a subclass of :java-sdk:`RealmObject ` +or implement :java-sdk:`RealmModel `. + +.. important:: + + - All SDK objects must provide an empty constructor. + - All SDK objects must use the ``public`` visibility modifier + +**Extend RealmObject** + +The following code block shows a Realm object that +describes a Frog. This Frog class can be stored in the database because it +``extends`` the ``RealmObject`` class. + +.. include:: /examples/generated/java/local/FrogObjectExample.snippet.complete.java.rst + +**Implement RealmModel** + +The following code block shows a Realm object that +describes a Frog. This Frog class can +be stored in the database because it ``implements`` the +``RealmModel`` class and uses the ``@RealmClass`` annotation: + +.. include:: /examples/generated/java/local/FrogRealmModelExample.snippet.complete.java.rst + +.. important:: + + All Realm objects must use the ``public`` + visibility modifier. + +.. tip:: Using ``RealmObject`` Methods + + When you create a Realm object by extending the ``RealmObject`` + class, you can access ``RealmObject`` class methods dynamically on + instances of your Realm object. Realm objects + created by implementing ``RealmModel`` can access those same methods + statically through the ``RealmObject`` class. diff --git a/source/includes/api-details/java/model-data/object-models-define-sdk-object-model-kotlin-description.rst b/source/includes/api-details/java/model-data/object-models-define-sdk-object-model-kotlin-description.rst new file mode 100644 index 0000000000..45132774f8 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-define-sdk-object-model-kotlin-description.rst @@ -0,0 +1,39 @@ +Using Kotlin in the Java SDK, to define an SDK object in your application, +create a subclass of :java-sdk:`RealmObject ` +or implement :java-sdk:`RealmModel `. + +.. important:: + + - All SDK objects must provide an empty constructor. + - All SDK objects must use the ``open`` visibility modifier. + +**Extend RealmObject** + +The following code block shows an SDK object that +describes a Frog. This Frog class can be stored in +the database because it ``extends`` the ``RealmObject`` class. + +.. include:: /examples/generated/java/local/FrogObjectExampleKt.snippet.complete.kt.rst + +**Implement RealmModel** + +The following code block shows an SDK object that +describes a Frog. This Frog class can +be stored in the database because it ``implements`` the +``RealmModel`` class and uses the ``@RealmClass`` annotation: + +.. include:: /examples/generated/java/local/FrogRealmModelExampleKt.snippet.complete.kt.rst + + .. important:: + + All Realm objects must use the ``open`` + visibility modifier. + + +.. tip:: Using ``RealmObject`` Methods + + When you create a Realm object by extending the ``RealmObject`` + class, you can access ``RealmObject`` class methods dynamically on + instances of your Realm object. Realm objects + created by implementing ``RealmModel`` can access those same methods + statically through the ``RealmObject`` class. diff --git a/source/includes/api-details/java/model-data/object-models-designate-primary-key-description.rst b/source/includes/api-details/java/model-data/object-models-designate-primary-key-description.rst new file mode 100644 index 0000000000..42d7f507b0 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-designate-primary-key-description.rst @@ -0,0 +1,13 @@ +You can create a primary key with any of the following types: + +- ``String`` +- ``UUID`` +- ``ObjectId`` +- ``Integer`` or ``int`` +- ``Long`` or ``long`` +- ``Short`` or ``short`` +- ``Byte`` or ``byte[]`` + +To designate a property as the primary key for the object, annotate the +property with the :java-sdk:`@PrimaryKey ` +annotation. diff --git a/source/includes/api-details/java/model-data/object-models-fts-index-property-not-supported.rst b/source/includes/api-details/java/model-data/object-models-fts-index-property-not-supported.rst new file mode 100644 index 0000000000..92e786e8d8 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-fts-index-property-not-supported.rst @@ -0,0 +1,2 @@ +The Java SDK does not support Full-Text Search. If you would like to use FTS, +use the Kotlin SDK, instead. diff --git a/source/includes/api-details/java/model-data/object-models-ignore-property-description.rst b/source/includes/api-details/java/model-data/object-models-ignore-property-description.rst new file mode 100644 index 0000000000..ca852d50fd --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-ignore-property-description.rst @@ -0,0 +1,7 @@ +Ignore a field from an SDK object model with the +:java-sdk:`@Ignore ` annotation. + +.. note:: The SDK ignores ``static`` and ``transient`` Fields + + Fields marked ``static`` or ``transient`` are always ignored, and do + not need the ``@Ignore`` annotation. diff --git a/source/includes/api-details/java/model-data/object-models-index-property-description.rst b/source/includes/api-details/java/model-data/object-models-index-property-description.rst new file mode 100644 index 0000000000..362db4110e --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-index-property-description.rst @@ -0,0 +1,15 @@ +You can index properties of these data types: + +- ``String`` +- ``UUID`` +- ``ObjectId`` +- ``Integer`` or ``int`` +- ``Long`` or ``long`` +- ``Short`` or ``short`` +- ``Byte`` or ``byte[]`` +- ``Boolean`` or ``bool`` +- ``Date`` +- ``RealmAny`` + +To index a field, use the :java-sdk:`@Index ` +annotation. diff --git a/source/includes/api-details/java/model-data/object-models-map-model-or-property-to-different-name-java-description.rst b/source/includes/api-details/java/model-data/object-models-map-model-or-property-to-different-name-java-description.rst new file mode 100644 index 0000000000..88cdc82ca6 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-map-model-or-property-to-different-name-java-description.rst @@ -0,0 +1,23 @@ +**Map a Model Name** + +Use the :java-sdk:`@RealmClass ` +annotation to rename a class. + +.. include:: /examples/generated/java/local/FrogClassRenamePolicyExample.snippet.complete.java.rst + +**Map a Property Name** + +Use the :java-sdk:`@RealmField ` +annotation to rename a field: + +.. include:: /examples/generated/java/local/FrogRenameAFieldExample.snippet.complete.java.rst + +**Assign a Naming Policy at the Module or Class Level** + +Alternatively, you can also assign a naming policy at the module or +class levels to change the way that the SDK interprets field names. + +You can define a +:java-sdk:`naming policy ` +at the :ref:`module level `, +which affects all classes included in the module. diff --git a/source/includes/api-details/java/model-data/object-models-map-model-or-property-to-different-name-kotlin-description.rst b/source/includes/api-details/java/model-data/object-models-map-model-or-property-to-different-name-kotlin-description.rst new file mode 100644 index 0000000000..6821c78078 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-map-model-or-property-to-different-name-kotlin-description.rst @@ -0,0 +1,23 @@ +**Map a Model Name** + +Use the :java-sdk:`@RealmClass ` +annotation to rename a class. + +.. include:: /examples/generated/java/local/FrogClassRenamePolicyExampleKt.snippet.complete.kt.rst + +**Map a Property Name** + +Use the :java-sdk:`@RealmField ` +annotation to rename a field. + +.. include:: /examples/generated/java/local/FrogRenameAFieldExampleKt.snippet.complete.kt.rst + +**Assign a Naming Policy at the Module or Class Level** + +Alternatively, you can also assign a naming policy at the module or +class levels to change the way that the SDK interprets field names. + +You can define a +:java-sdk:`naming policy ` +at the :ref:`module level `, +which affects all classes included in the module. diff --git a/source/includes/api-details/java/model-data/object-models-object-model-description.rst b/source/includes/api-details/java/model-data/object-models-object-model-description.rst new file mode 100644 index 0000000000..c15adb30c8 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-object-model-description.rst @@ -0,0 +1,45 @@ +In the Java SDK, unlike normal Java objects, which contain their own data, an +SDK object doesn't contain data. Instead, SDK objects read and write properties +directly to the database. + +The Java SDK uses ``RealmProxy`` classes to ensure that database objects +don't contain any data themselves. Instead, each class's ``RealmProxy`` +accesses data directly in the database. + +For every model class in your project, the SDK annotation processor generates +a corresponding ``RealmProxy`` class. This class extends your model class and +is returned when you call ``Realm.createObject()``. In your code, this object +works just like your model class. + +**Java SDK Object Limitations** + +SDK objects: + +- cannot contain fields that use the ``final`` or ``volatile`` modifiers + (except for :ref:`inverse relationship ` fields). + +- cannot extend any object other than ``RealmObject``. + +- must contain an empty constructor (if your class does not include any + constructor, the automatically generated empty constructor will suffice) + +Usage limitations: + +- Because SDK objects are live and can change at any time, + their ``hashCode()`` value can change over time. As a result, you + should not use ``RealmObject`` instances as a key in any map or set. + +**Java SDK Incremental Builds** + +The bytecode transformer used by the Java SDK supports incremental +builds, but your application requires a full rebuild when adding or +removing the following from an SDK object field: + +- an ``@Ignore`` annotation + +- the ``static`` keyword + +- the ``transient`` keyword + +You can perform a full rebuild with :guilabel:`Build > Clean Project` +and :guilabel:`Build > Rebuild Project` in these cases. diff --git a/source/includes/api-details/java/model-data/object-models-object-schema-description.rst b/source/includes/api-details/java/model-data/object-models-object-schema-description.rst new file mode 100644 index 0000000000..36e8ee661b --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-object-schema-description.rst @@ -0,0 +1,2 @@ +In the Java SDK, the SDK automatically creates object schemas based on your +SDK model classes. diff --git a/source/includes/api-details/java/model-data/object-models-set-default-value-for-property-java-description.rst b/source/includes/api-details/java/model-data/object-models-set-default-value-for-property-java-description.rst new file mode 100644 index 0000000000..e54ea6773e --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-set-default-value-for-property-java-description.rst @@ -0,0 +1,9 @@ +To assign a default value to a field, use the built-in language features. Use +the class constructor(s) to assign default values. + +.. note:: Default Values and Nullability + + While default values ensure that a newly created object cannot contain + a value of ``null`` (unless you specify a default value of ``null``), + they do not impact the nullability of a field. For details about + nullability, refer to :ref:`sdks-optional-property-types`. diff --git a/source/includes/api-details/java/model-data/object-models-set-default-value-for-property-kotlin-description.rst b/source/includes/api-details/java/model-data/object-models-set-default-value-for-property-kotlin-description.rst new file mode 100644 index 0000000000..fbd9c00942 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-set-default-value-for-property-kotlin-description.rst @@ -0,0 +1,9 @@ +To assign a default value to a field, use the built-in language features. +Assign default values in the field declaration. + +.. note:: Default Values and Nullability + + While default values ensure that a newly created object cannot contain + a value of ``null`` (unless you specify a default value of ``null``), + they do not impact the nullability of a field. For details about + nullability, refer to :ref:`sdks-optional-property-types`. diff --git a/source/includes/api-details/java/model-data/object-models-unstructured-data-not-supported.rst b/source/includes/api-details/java/model-data/object-models-unstructured-data-not-supported.rst new file mode 100644 index 0000000000..6081e8e1a8 --- /dev/null +++ b/source/includes/api-details/java/model-data/object-models-unstructured-data-not-supported.rst @@ -0,0 +1,3 @@ +The Java SDK does not support modeling unstructured data as a collection +of the mixed property type. If you would like to take advantage of more +flexible data models, use the Kotlin SDK. diff --git a/source/includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst b/source/includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst new file mode 100644 index 0000000000..ff353dd86e --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst @@ -0,0 +1,3 @@ +The JS SDK's :js-sdk:`database configuration ` +has a ``schema`` property that takes an array of object schemas that the +database instance can manage. diff --git a/source/includes/api-details/javascript/model-data/object-models-define-asymmetric-object-description.rst b/source/includes/api-details/javascript/model-data/object-models-define-asymmetric-object-description.rst new file mode 100644 index 0000000000..ac6fb9e0bb --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-define-asymmetric-object-description.rst @@ -0,0 +1,2 @@ +In JavaScript, to define an asymmetric object, set the ``asymmetric`` property +on your object schema. diff --git a/source/includes/api-details/javascript/model-data/object-models-define-embedded-object-js-ts-description.rst b/source/includes/api-details/javascript/model-data/object-models-define-embedded-object-js-ts-description.rst new file mode 100644 index 0000000000..c3584f4b91 --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-define-embedded-object-js-ts-description.rst @@ -0,0 +1,3 @@ +In the JavaScript SDK, to define an embedded object, set ``embedded`` +to ``true``. You can reference an embedded object type from parent object types +in the same way as you would define a relationship. diff --git a/source/includes/api-details/javascript/model-data/object-models-define-geospatial-object-description.rst b/source/includes/api-details/javascript/model-data/object-models-define-geospatial-object-description.rst new file mode 100644 index 0000000000..2749ea4e31 --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-define-geospatial-object-description.rst @@ -0,0 +1,34 @@ +In JavaScript, to create a class that conforms to the GeoJSON spec, you: + +1. Create an embedded SDK object. For more information about embedded + objects, refer to :ref:`sdks-embedded-objects`. + +#. At a minimum, add the two fields required by the GeoJSON spec: + + - A field of type ``double[]`` that maps to a "coordinates" (case sensitive) + property in the object schema. + + - A field of type ``string`` that maps to a "type" property. The value of this + field must be "Point". + +To simplify geodata persistance, you can define a model that implements +``CanonicalGeoPoint``, which already has the correct shape. The following +example shows an embedded class named ``MyGeoPoint`` that is used +to persist geospatial data: + +.. literalinclude:: /examples/generated/node/v12/geospatial.test.snippet.define-geopoint-class.js + :language: javascript + +Use the Embedded Class +`````````````````````` + +You then use the custom ``MyGeoPoint`` class in your SDK model, as shown in the +following example: + +.. literalinclude:: /examples/generated/node/v12/geospatial.test.snippet.use-geopoint-class.js + :language: javascript + +You add instances of your class to the database just like any other SDK +model. However, in this example, because the ``MyGeoPoint`` class does not +extend ``Realm.Object``, we must specify ``MyGeoPoint.schema`` when opening +the database: diff --git a/source/includes/api-details/javascript/model-data/object-models-define-optional-property-description.rst b/source/includes/api-details/javascript/model-data/object-models-define-optional-property-description.rst new file mode 100644 index 0000000000..0ffb7b9735 --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-define-optional-property-description.rst @@ -0,0 +1,3 @@ +To mark a property as optional, append a question mark ``?`` to its type. + +The following ``Car`` schema defines an optional ``miles`` property of type ``int``. diff --git a/source/includes/api-details/javascript/model-data/object-models-define-realm-object-description.rst b/source/includes/api-details/javascript/model-data/object-models-define-realm-object-description.rst new file mode 100644 index 0000000000..f604fb4dd4 --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-define-realm-object-description.rst @@ -0,0 +1,12 @@ +Create a JavaScript class that extends :js-sdk:`Realm.Object +`. + +Define a static ``schema`` object of type :js-sdk:`ObjectSchema +`. This schema includes a ``name`` property, +which becomes the table name in the database. The schema should include a +``properties`` array, which is an array of objects of type +:js-sdk:`PropertiesTypes `. Each object in +this array contains a string key that becomes the name of the property, and +a :js-sdk:`PropertySchema ` that provides +additional details about the property, such as its type and any special +behaviors it should have. diff --git a/source/includes/api-details/javascript/model-data/object-models-define-sdk-object-model-description.rst b/source/includes/api-details/javascript/model-data/object-models-define-sdk-object-model-description.rst new file mode 100644 index 0000000000..458b26a6cc --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-define-sdk-object-model-description.rst @@ -0,0 +1,12 @@ +In JavaScript, to define an SDK object, create a JavaScript class that extends +:js-sdk:`Realm.Object `. + +Define a static ``schema`` object that includes a ``name`` property and +a ``properties`` array. The ``name`` becomes the table name in the database. +The ``properties`` array describes the property names, types, and any additional +details about special property behaviors, such as whether the property should +be indexed. + +For object types with special behaviors, such as embedded objects and +asymmetric objects, set the optional ``embedded`` or ``asymmetric`` property +to ``true``. diff --git a/source/includes/api-details/javascript/model-data/object-models-designate-primary-key-js-ts-description.rst b/source/includes/api-details/javascript/model-data/object-models-designate-primary-key-js-ts-description.rst new file mode 100644 index 0000000000..0129865c3d --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-designate-primary-key-js-ts-description.rst @@ -0,0 +1,5 @@ +To specify a property as an object type's primary key, set the schema's +``primaryKey`` field to the property name. + +The following ``Car`` object schema specifies the ``_id`` property as its +primary key. diff --git a/source/includes/api-details/javascript/model-data/object-models-fts-index-property-js-ts-description.rst b/source/includes/api-details/javascript/model-data/object-models-fts-index-property-js-ts-description.rst new file mode 100644 index 0000000000..22cfdae1cf --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-fts-index-property-js-ts-description.rst @@ -0,0 +1,3 @@ +To create an FTS index, set the `indexed `__ +type to ``'full-text'``. This enables full-text queries on the property. In the +following example, we set the indexed type for the ``name`` property to ``'full-text'``. diff --git a/source/includes/api-details/javascript/model-data/object-models-ignore-property-js-ts-description.rst b/source/includes/api-details/javascript/model-data/object-models-ignore-property-js-ts-description.rst new file mode 100644 index 0000000000..9a1c7596c0 --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-ignore-property-js-ts-description.rst @@ -0,0 +1 @@ +To ignore a property, omit it from the object schema. diff --git a/source/includes/api-details/javascript/model-data/object-models-index-property-js-ts-description.rst b/source/includes/api-details/javascript/model-data/object-models-index-property-js-ts-description.rst new file mode 100644 index 0000000000..7bf911d797 --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-index-property-js-ts-description.rst @@ -0,0 +1,13 @@ +You can index properties of these data types: + +- string +- integer +- boolean +- ``Date`` +- ``UUID`` +- ``ObjectId`` + +To define an index for a given property, set ``indexed`` to ``true``. + +The following ``Car`` object schema defines an index on the ``_id`` +property. diff --git a/source/includes/api-details/javascript/model-data/object-models-map-model-or-property-to-different-name-description.rst b/source/includes/api-details/javascript/model-data/object-models-map-model-or-property-to-different-name-description.rst new file mode 100644 index 0000000000..1cfb326f80 --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-map-model-or-property-to-different-name-description.rst @@ -0,0 +1,28 @@ +**Map a Model Name** + +To use a different class name in your code than is stored in the database: + +1. Set the ``name`` property of your SDK object's **schema** to the name + that you want to use to store the object. + +#. Use the **class** name in the database configuration's ``schema`` property + when you :ref:`open the database `. + +#. Use the mapped name for performing CRUD operations or when defining + Sync Subscriptions. + +In the following example, the SDK stores objects created with the +``Task`` class as ``Todo_Item``. + +.. literalinclude:: /examples/generated/node/v12/define-a-realm-object-schema.test.snippet.remap-class-name.js + :language: javascript + :emphasize-lines: 5, 18, 27, 39, 47 + +**Map a Property Name** + +To use a different property name in your code than is stored in the database, +set ``mapTo`` to the name of the property as it appears in your code. + +In the following ``Car`` object schema, the database stores the car's +model name with the snake case ``model_name`` property. The schema maps the property +to ``modelName`` for objects used in client code. diff --git a/source/includes/api-details/javascript/model-data/object-models-model-unstructured-data-js-ts-description.rst b/source/includes/api-details/javascript/model-data/object-models-model-unstructured-data-js-ts-description.rst new file mode 100644 index 0000000000..6674d81e29 --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-model-unstructured-data-js-ts-description.rst @@ -0,0 +1,11 @@ +.. versionadded:: 12.9.0 + +Starting in Node.js SDK version 12.9.0, you can store +collections of mixed data within a ``mixed`` property. + +To model unstructured data in your app, define the appropriate properties in +your schema as :ref:`mixed ` types. You can then set these +``mixed`` properties as a :ref:`list ` or a +:ref:`dictionary ` collection of mixed elements. + +Note that ``mixed`` *cannot* represent a set or an embedded object. diff --git a/source/includes/api-details/javascript/model-data/object-models-object-model-description.rst b/source/includes/api-details/javascript/model-data/object-models-object-model-description.rst new file mode 100644 index 0000000000..2f8edbdac5 --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-object-model-description.rst @@ -0,0 +1,16 @@ +You can define SDK models as JavaScript classes that extend ``Realm.Object``. + +When you create objects, use an object literal. This lets you create an +**unmanaged** object, and pass it to the database when it makes sense to do so. + +Do not use ``new`` to construct a new object instance. If you use ``new`` with +class-based models, this creates a new **managed** object, which has the +following side effects: + +- Constructing a ``new`` object calls the ``realm.create()`` method, which can + only be used in a write transcation. +- Constructing a ``new`` object has complications when the object contains or + is itself an embedded object. + +For more information about object creation and managed objects, refer to +:ref:`sdks-crud-create` and :ref:`sdks-create-specific-object-types`. diff --git a/source/includes/api-details/javascript/model-data/object-models-object-schema-js-ts-description.rst b/source/includes/api-details/javascript/model-data/object-models-object-schema-js-ts-description.rst new file mode 100644 index 0000000000..f5ccf7caaa --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-object-schema-js-ts-description.rst @@ -0,0 +1,12 @@ +When you create an SDK object model class, you define the type's ``name`` and +``properties`` in a static property called ``schema``. + +When the SDK model extends ``Realm.Object``, you pass the model class directly +to the database ``schema`` list, and it uses the ``schema`` property in your +model class as a part of the database schema. + +When the SDK model does *not* extend ``Realm.Object``, as when it is an +embedded object, you pass only the object's schema to the database ``schema`` +list. You cannot pass the object itself directly to the database. + +.. TODO: Verify that this is accurate diff --git a/source/includes/api-details/javascript/model-data/object-models-set-default-value-for-property-description.rst b/source/includes/api-details/javascript/model-data/object-models-set-default-value-for-property-description.rst new file mode 100644 index 0000000000..06abe27ff0 --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-set-default-value-for-property-description.rst @@ -0,0 +1,5 @@ +To define a default value, set the value of the property to an object with a +``type`` field and a ``default`` field. + +The following ``Car`` object schema specifies a default value of ``0`` for +the ``miles`` property. diff --git a/source/includes/api-details/kotlin/model-data/object-models-database-schema-description.rst b/source/includes/api-details/kotlin/model-data/object-models-database-schema-description.rst new file mode 100644 index 0000000000..ea0ccb91c2 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-database-schema-description.rst @@ -0,0 +1,3 @@ +In Kotlin, the database :kotlin-sdk:`configuration ` +has a :kotlin-sdk:`schema ` +property that takes a set of classes that the database can manage. diff --git a/source/includes/api-details/kotlin/model-data/object-models-define-asymmetric-object-description.rst b/source/includes/api-details/kotlin/model-data/object-models-define-asymmetric-object-description.rst new file mode 100644 index 0000000000..b6bf6079f8 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-define-asymmetric-object-description.rst @@ -0,0 +1,3 @@ +In the Kotlin SDK, to define an asymmetric object type, create a Kotlin class +that implements the :kotlin-sync-sdk:`AsymmetricRealmObject +` interface: diff --git a/source/includes/api-details/kotlin/model-data/object-models-define-embedded-object-description.rst b/source/includes/api-details/kotlin/model-data/object-models-define-embedded-object-description.rst new file mode 100644 index 0000000000..9e6b950825 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-define-embedded-object-description.rst @@ -0,0 +1,4 @@ +In the Kotlin SDK, to define an embedded object type, create a Kotlin class +that implements the :kotlin-sdk:`EmbeddedRealmObject +` +interface. diff --git a/source/includes/api-details/kotlin/model-data/object-models-define-geospatial-object-description.rst b/source/includes/api-details/kotlin/model-data/object-models-define-geospatial-object-description.rst new file mode 100644 index 0000000000..c48b1cd2b3 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-define-geospatial-object-description.rst @@ -0,0 +1,26 @@ +In the Kotlin SDK, to create a class that conforms to the GeoJSON spec, you: + +1. Create an :ref:`embedded object ` + (a class that inherits from :kotlin-sdk:`EmbeddedRealmObject + `). + +#. At a minimum, add the two fields required by the GeoJSON spec: + + - A field of type ``String`` property that maps to a ``type`` property + with the value of ``"Point"``: ``var type: String = "Point"`` + + - A field of type ``RealmList`` that maps to a ``coordinates`` + property in the object schema containing a latitude/longitude + pair: ``var coordinates: RealmList = realmListOf()`` + +The following example shows an embedded class named ``CustomGeoPoint`` that is used +to persist geospatial data: + +.. literalinclude:: /examples/generated/kotlin/Geospatial.snippet.custom-geopoint.kt + :language: kotlin + +Use the Embedded Class +`````````````````````` + +Use the ``customGeoPoint`` class in your SDK model, as shown in the +following example: diff --git a/source/includes/api-details/kotlin/model-data/object-models-define-optional-property-description.rst b/source/includes/api-details/kotlin/model-data/object-models-define-optional-property-description.rst new file mode 100644 index 0000000000..1687d2075f --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-define-optional-property-description.rst @@ -0,0 +1,5 @@ +SDK object properties *must* be mutable and initialized when declared. +The Kotlin SDK does not currently support abstract properties. You +can declare properties optional (nullable) using the built-in +``?`` Kotlin operator, or you can assign a default value to a property +when you declare it. diff --git a/source/includes/api-details/kotlin/model-data/object-models-define-realm-object-description.rst b/source/includes/api-details/kotlin/model-data/object-models-define-realm-object-description.rst new file mode 100644 index 0000000000..384a84f174 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-define-realm-object-description.rst @@ -0,0 +1,3 @@ +In the Kotlin SDK, to define a Realm object type, create a Kotlin class that +implements the :kotlin-sdk:`RealmObject +` interface. diff --git a/source/includes/api-details/kotlin/model-data/object-models-define-sdk-object-model-description.rst b/source/includes/api-details/kotlin/model-data/object-models-define-sdk-object-model-description.rst new file mode 100644 index 0000000000..67baca51f4 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-define-sdk-object-model-description.rst @@ -0,0 +1,25 @@ +In the Kotlin SDK, define an SDK object as a Kotlin class. Each object class +represents an **object type**. + +SDK objects *must* inherit from the ``RealmObject`` class or its +subclasses: ``EmbeddedRealmObject`` or ``AsymmetricRealmObject``. +The Kotlin SDK does *not* support inheritance from custom base classes. + +Additionally, the Kotlin SDK does *not* support using Kotlin +`data classes `__ to model +data. This is because data classes are typically used for immutable data, +which goes against how the Kotlin SDK models data. + +**Kotlin SDK Requires an Empty Constructor** + +The Kotlin SDK requires that SDK objects have an empty constructor. + +If you cannot provide an empty constructor, as a workaround, you can do +something similar to the following: + +.. code-block:: kotlin + :copyable: false + + class Person(var name: String, var age: Int): RealmObject { + constructor(): this("", 0) // Empty constructor required by the SDK + } diff --git a/source/includes/api-details/kotlin/model-data/object-models-designate-primary-key-description.rst b/source/includes/api-details/kotlin/model-data/object-models-designate-primary-key-description.rst new file mode 100644 index 0000000000..95199c8131 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-designate-primary-key-description.rst @@ -0,0 +1,14 @@ +You can create a primary key with any of the following types: + +- ``String`` +- ``Byte`` +- ``Char`` +- ``Short`` +- ``Int`` +- ``Long`` +- ``ObjectId`` +- ``RealmUUID`` + +To specify a property as the object type's primary key, use the +:kotlin-sdk:`@PrimaryKey ` +annotation. diff --git a/source/includes/api-details/kotlin/model-data/object-models-fts-index-property-description.rst b/source/includes/api-details/kotlin/model-data/object-models-fts-index-property-description.rst new file mode 100644 index 0000000000..c79ec4f106 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-fts-index-property-description.rst @@ -0,0 +1,2 @@ +To create an FTS index on a property, use the :kotlin-sdk:`@FullText +` annotation. diff --git a/source/includes/api-details/kotlin/model-data/object-models-ignore-property-description.rst b/source/includes/api-details/kotlin/model-data/object-models-ignore-property-description.rst new file mode 100644 index 0000000000..d2fae88811 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-ignore-property-description.rst @@ -0,0 +1,3 @@ +To ignore a property and prevent it from persisting to the database, use the +:kotlin-sdk:`@Ignore ` +annotation. diff --git a/source/includes/api-details/kotlin/model-data/object-models-index-property-description.rst b/source/includes/api-details/kotlin/model-data/object-models-index-property-description.rst new file mode 100644 index 0000000000..94b79b5153 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-index-property-description.rst @@ -0,0 +1,15 @@ +You can index properties of these data types: + +- ``String`` +- ``Byte`` +- ``Short`` +- ``Int`` +- ``Long`` +- ``Boolean`` +- ``RealmInstant`` +- ``ObjectId`` +- ``RealmUUID`` + +To create an index on a property, use the :kotlin-sdk:`@Index +` annotation on the +property. diff --git a/source/includes/api-details/kotlin/model-data/object-models-map-model-or-property-to-different-name-description.rst b/source/includes/api-details/kotlin/model-data/object-models-map-model-or-property-to-different-name-description.rst new file mode 100644 index 0000000000..f00104b3b8 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-map-model-or-property-to-different-name-description.rst @@ -0,0 +1,37 @@ +To map a Kotlin class or property name in your code to a different in the +database: + +#. Use the + :kotlin-sdk:`@PersistedName ` + annotation on the Kotlin class or property. +#. Specify a class or property ``name`` that you want persisted to + the database. + +**Map a Model Name** + +In this example, ``Frog`` is the Kotlin class name used in the code +throughout the project to perform CRUD operations, and ``Frog_Entity`` is the +persisted name to used to store objects in the database: + +.. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-persisted-class.kt + :language: kotlin + +.. important:: Querying by Remapped Class Names + + When querying an inverse relationship on an object with a + remapped class name, you must use the persisted class name. + In the example above, you must query ``Frog_Entity`` instead of + ``Frog``. + For more information, refer to :ref:`Query Inverse Relationships + `. + +**Map a Property Name** + +In this example, ``species`` is the Kotlin property name used in the code +throughout the project to perform CRUD operations and ``latin_name`` is the +persisted name used to store values in the database: + +.. tip:: Querying by Remapped Property Names + + You can query by either the Kotlin name used in the code *or* by the + persisted name stored in the database. diff --git a/source/includes/api-details/kotlin/model-data/object-models-model-unstructured-data-description.rst b/source/includes/api-details/kotlin/model-data/object-models-model-unstructured-data-description.rst new file mode 100644 index 0000000000..0dc6fe8c4c --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-model-unstructured-data-description.rst @@ -0,0 +1,12 @@ +.. versionadded:: 2.0.0 + +Starting in Kotlin SDK version 2.0.0, you can store +collections of mixed data within a ``RealmAny`` property. + +To model unstructured data in your app, define the appropriate properties in +your schema as :ref:`RealmAny ` types. You can then set +these ``RealmAny`` properties as a :ref:`list ` or a +:ref:`dictionary ` collection of ``RealmAny`` +elements. + +Note that ``RealmAny`` *cannot* represent a ``RealmSet`` or an embedded object. diff --git a/source/includes/api-details/kotlin/model-data/object-models-object-model-description.rst b/source/includes/api-details/kotlin/model-data/object-models-object-model-description.rst new file mode 100644 index 0000000000..095018a499 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-object-model-description.rst @@ -0,0 +1,2 @@ +In the Kotlin SDK, you define your application's data model with regular Kotlin +classes declared in your application code. diff --git a/source/includes/api-details/kotlin/model-data/object-models-object-schema-description.rst b/source/includes/api-details/kotlin/model-data/object-models-object-schema-description.rst new file mode 100644 index 0000000000..6a67547e46 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-object-schema-description.rst @@ -0,0 +1,4 @@ +In the Kotlin SDK, you do not need to manually specify an object schema. The +SDK automatically creates an object schema for every object type that inherits +from the ``RealmObject`` class or its subclasses: ``EmbeddedRealmObject`` or +``AsymmetricRealmObject``. diff --git a/source/includes/api-details/objectivec/model-data/object-models-database-schema-description.rst b/source/includes/api-details/objectivec/model-data/object-models-database-schema-description.rst new file mode 100644 index 0000000000..0a200a337e --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-database-schema-description.rst @@ -0,0 +1,7 @@ +In Objective-C, you don't have to explicitly specify the database schema when +you configure the database. Swift SDK executables can automatically read and +write any valid SDK object whose model is included in the executable. If you +want to restrict a database to manage only a subset of the SDK models in the +executable, you *can* explicitly pass the models when configuring a database. + +For more information, refer to :ref:`sdks-provide-a-subset-of-models-to-a-database`. diff --git a/source/includes/api-details/objectivec/model-data/object-models-define-asymmetric-object-description.rst b/source/includes/api-details/objectivec/model-data/object-models-define-asymmetric-object-description.rst new file mode 100644 index 0000000000..f7e9104725 --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-define-asymmetric-object-description.rst @@ -0,0 +1,14 @@ +In Objective-C, to define an embedded object, create a class that inherits from +:objc-sdk:`RLMAsymmetricObject `. + +``RLMAsymmetricObject`` broadly supports the same property types as +``RLMObject``, with a few exceptions: + +- Asymmetric objects can only link to embedded objects + - ``RLMObject`` and ``RLMArray`` properties are not supported in Swift SDK + versions 10.42.3 and earlier. In Swift SDK versions 10.42.4 and later, + asymmetric objects can link to non-embedded objects. + - ``RLMEmbeddedObject`` and ``RLMArray`` are supported. + +You cannot link to an ``RLMAsymmetricObject`` from within an ``RLMObject``. +Doing so throws an error. diff --git a/source/includes/api-details/objectivec/model-data/object-models-define-embedded-object-description.rst b/source/includes/api-details/objectivec/model-data/object-models-define-embedded-object-description.rst new file mode 100644 index 0000000000..96bc070c6f --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-define-embedded-object-description.rst @@ -0,0 +1,3 @@ +In Objective-C, to define an embedded object, create a class that inherits from +:objc-sdk:`RLMEmbeddedObject `. You can use +your embedded object in another model as you would any other type. diff --git a/source/includes/api-details/objectivec/model-data/object-models-define-geospatial-object-description.rst b/source/includes/api-details/objectivec/model-data/object-models-define-geospatial-object-description.rst new file mode 100644 index 0000000000..2850761d80 --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-define-geospatial-object-description.rst @@ -0,0 +1,3 @@ +The SDK does not have an example of persisting GeoJSON data with Objective-C. +Refer to the Swift language for details about persisting geospatial data +with the Swift SDK. diff --git a/source/includes/api-details/objectivec/model-data/object-models-define-optional-property-description.rst b/source/includes/api-details/objectivec/model-data/object-models-define-optional-property-description.rst new file mode 100644 index 0000000000..36f727c5a1 --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-define-optional-property-description.rst @@ -0,0 +1,9 @@ +In Objective-C, pointer-type properties are considered optional in the +data model unless you specifically declare a property as required. +To declare a given property as required, implement the +:objc-sdk:`requiredProperties +` +method and return an array of required property names. + +Implicitly required properties, such as properties of primitive types, do +not need to be manually included in the ``requiredProperties`` array. diff --git a/source/includes/api-details/objectivec/model-data/object-models-define-projection-missing-description.rst b/source/includes/api-details/objectivec/model-data/object-models-define-projection-missing-description.rst new file mode 100644 index 0000000000..34eee13df2 --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-define-projection-missing-description.rst @@ -0,0 +1,2 @@ +The documentation is currently missing an example of how to define a projection +in Objective-C. diff --git a/source/includes/api-details/objectivec/model-data/object-models-define-realm-object-description.rst b/source/includes/api-details/objectivec/model-data/object-models-define-realm-object-description.rst new file mode 100644 index 0000000000..31fdb0d9fe --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-define-realm-object-description.rst @@ -0,0 +1,2 @@ +In Objective-C, to define a Realm object, create a class that inherits from +:objc-sdk:`RLMObject `. diff --git a/source/includes/api-details/objectivec/model-data/object-models-define-sdk-object-model-description.rst b/source/includes/api-details/objectivec/model-data/object-models-define-sdk-object-model-description.rst new file mode 100644 index 0000000000..e21148cfa1 --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-define-sdk-object-model-description.rst @@ -0,0 +1,10 @@ +In Objective-C, to define an SDK object, create a class that inherits from one +of the SDK object types: + +- :objc-sdk:`RLMObject ` +- :objc-sdk:`RLMEmbeddedObject ` +- :objc-sdk:`RLMAsymmetricObject ` + +The name of the class becomes the table name in the database. Properties of the +class persist in the database. This makes it as easy to work with persisted +objects as it is to work with regular Objective-C objects. diff --git a/source/includes/api-details/objectivec/model-data/object-models-designate-primary-key-description.rst b/source/includes/api-details/objectivec/model-data/object-models-designate-primary-key-description.rst new file mode 100644 index 0000000000..3066e50a3f --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-designate-primary-key-description.rst @@ -0,0 +1,8 @@ +You can create a primary key with any of the following types: + +- ``RLMPropertyTypeString`` +- ``RLMPropertyTypeInt`` + +To designate a property as an object's primary key, override +:objc-sdk:`+[RLMObject primaryKey] +`. diff --git a/source/includes/api-details/objectivec/model-data/object-models-ignore-property-description.rst b/source/includes/api-details/objectivec/model-data/object-models-ignore-property-description.rst new file mode 100644 index 0000000000..66740a0e6b --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-ignore-property-description.rst @@ -0,0 +1,3 @@ +To ignore a property, override :objc-sdk:`+[RLMObject ignoredProperties] +` +and return a list of ignored property names. diff --git a/source/includes/api-details/objectivec/model-data/object-models-index-property-description.rst b/source/includes/api-details/objectivec/model-data/object-models-index-property-description.rst new file mode 100644 index 0000000000..c3da06b10e --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-index-property-description.rst @@ -0,0 +1,11 @@ +You can index proeprties of these data types: + +- string +- integer +- boolean +- NSDate + +To index a property, override :objc-sdk:`+[RLMObject +indexedProperties] +` +and return a list of indexed property names. diff --git a/source/includes/api-details/objectivec/model-data/object-models-map-model-or-property-to-different-name-description.rst b/source/includes/api-details/objectivec/model-data/object-models-map-model-or-property-to-different-name-description.rst new file mode 100644 index 0000000000..75978c7a6c --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-map-model-or-property-to-different-name-description.rst @@ -0,0 +1,8 @@ +**Map a Model Name** + +The Swift SDK does not support mapping a model name to a different name. + +**Map a Property Name** + +The documentation does not currently have an example of how to map a property +name to a different persisted name with Objective-C. diff --git a/source/includes/api-details/objectivec/model-data/object-models-model-unstructured-data-description.rst b/source/includes/api-details/objectivec/model-data/object-models-model-unstructured-data-description.rst new file mode 100644 index 0000000000..6904b9f585 --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-model-unstructured-data-description.rst @@ -0,0 +1,13 @@ +.. versionadded:: 10.51.0 + +Starting in SDK version 10.51.0, you can store collections of mixed data +within an ``RLMValue`` property. + +To model unstructured data in your app, define the appropriate properties in +your schema as :ref:`RLMValue ` types. You can then +set these ``RLMValue`` properties as a :ref:`list ` +or a :ref:`dictionary ` collection of +``RLMValue`` elements. + +Note that ``RLMValue`` *cannot* represent a ``RLMSet`` or an embedded +object. diff --git a/source/includes/api-details/objectivec/model-data/object-models-object-model-description.rst b/source/includes/api-details/objectivec/model-data/object-models-object-model-description.rst new file mode 100644 index 0000000000..ff6858dff9 --- /dev/null +++ b/source/includes/api-details/objectivec/model-data/object-models-object-model-description.rst @@ -0,0 +1,21 @@ +In Objective-C, SDK object models are regular Objective-C classes that define +the SDK data model. + +Objective-C SDK objects must derive from one of the SDK object types. + +Model Inheritance +````````````````` + +You can subclass SDK models to share behavior between +classes, but there are limitations. In particular, the SDK +does not allow you to: + +- Cast between polymorphic classes: subclass to subclass, subclass to parent, parent to subclass +- Query on multiple classes simultaneously: for example, "get all instances of parent class and subclass" +- Multi-class containers: ``List`` and ``Results`` with a mixture of parent and subclass + +.. tip:: + + Check out the :github:`code samples + ` for working + around these limitations. diff --git a/source/includes/api-details/swift/model-data/object-models-database-schema-description.rst b/source/includes/api-details/swift/model-data/object-models-database-schema-description.rst new file mode 100644 index 0000000000..65e2d70146 --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-database-schema-description.rst @@ -0,0 +1,7 @@ +In Swift, you don't have to explicitly specify the database schema when you +configure the database. Swift SDK executables can automatically read and write +any valid SDK object whose model is included in the executable. If you want to +restrict a database to manage only a subset of the SDK models in the executable, +you *can* explicitly pass the models when configuring a database. + +For more information, refer to :ref:`sdks-provide-a-subset-of-models-to-a-database`. diff --git a/source/includes/api-details/swift/model-data/object-models-define-asymmetric-object-description.rst b/source/includes/api-details/swift/model-data/object-models-define-asymmetric-object-description.rst new file mode 100644 index 0000000000..6fe1eaec85 --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-define-asymmetric-object-description.rst @@ -0,0 +1,14 @@ +In Swift, to define an asymmetric object, create a class that inherits from +:swift-sdk:`AsymmetricObject `. + +``AsymmetricObject`` broadly supports the same property types as ``Object``, +with a few exceptions: + +- Asymmetric objects can only link to embedded objects + - ``Object`` and ``List`` properties are not supported in Swift SDK + versions 10.42.3 and earlier. In Swift SDK versions 10.42.4 and later, + asymmetric objects can link to non-embedded objects. + - ``EmbeddedObject`` and ``List`` are supported. + +You cannot link to an ``AsymmetricObject`` from within an ``Object``. Doing so +throws an error. diff --git a/source/includes/api-details/swift/model-data/object-models-define-embedded-object-description.rst b/source/includes/api-details/swift/model-data/object-models-define-embedded-object-description.rst new file mode 100644 index 0000000000..614e77dd69 --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-define-embedded-object-description.rst @@ -0,0 +1,3 @@ +In Swift, to define an embedded object, create a class that inherits from +:swift-sdk:`EmbeddedObject `. You can use your +embedded object in another model as you would any other type. diff --git a/source/includes/api-details/swift/model-data/object-models-define-geospatial-object-description.rst b/source/includes/api-details/swift/model-data/object-models-define-geospatial-object-description.rst new file mode 100644 index 0000000000..be2d651aed --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-define-geospatial-object-description.rst @@ -0,0 +1,12 @@ +To persist geospatial data with the Swift SDK, create a GeoJSON-compatible +embedded class that you can use in your data model. + +Your custom embedded object must contain the two fields required by the +GeoJSON spec: + +- A field of type ``String`` property that maps to a ``type`` property with + the value of ``"Point"``: ``@Persisted var type: String = "Point"`` + +- A field of type ``List`` that maps to a ``coordinates`` + property containing a latitude/longitude pair: + ``@Persisted private var coordinates: List`` diff --git a/source/includes/api-details/swift/model-data/object-models-define-optional-property-description.rst b/source/includes/api-details/swift/model-data/object-models-define-optional-property-description.rst new file mode 100644 index 0000000000..d739db3657 --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-define-optional-property-description.rst @@ -0,0 +1,2 @@ +You can declare properties as optional or required (non-optional) using +standard Swift syntax. diff --git a/source/includes/api-details/swift/model-data/object-models-define-projection-description.rst b/source/includes/api-details/swift/model-data/object-models-define-projection-description.rst new file mode 100644 index 0000000000..863261f1de --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-define-projection-description.rst @@ -0,0 +1,23 @@ +Define a class projection by creating a class of type :swift-sdk:`Projection +`. Specify the :swift-sdk:`Object ` +or :swift-sdk:`EmbeddedObject ` base whose +properties you want to use in the class projection. Use the ``@Projected`` +property wrapper to declare a property that you want to project from a +``@Persisted`` property on the base object. + +.. note:: + + When you use a :ref:`List ` or a :ref:`Set + ` in a class projection, the type in the + projection should be :swift-sdk:`ProjectedCollection + `. + +The examples in this section use a simple data set. The two SDK object +types are ``Person`` and an embedded object ``Address``. A ``Person`` has +a first and last name, an optional ``Address``, and a list of friends +consisting of other ``Person`` objects. An ``Address`` has a city and country. + +See the model for these two classes, ``Person`` and ``Address``, below: + +.. literalinclude:: /examples/generated/code/start/ClassProjection.snippet.models.swift + :language: swift diff --git a/source/includes/api-details/swift/model-data/object-models-define-realm-object-description.rst b/source/includes/api-details/swift/model-data/object-models-define-realm-object-description.rst new file mode 100644 index 0000000000..e1b82a493e --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-define-realm-object-description.rst @@ -0,0 +1,2 @@ +In Swift, to define a Realm object, create a class that inherits from +:swift-sdk:`Object `. diff --git a/source/includes/api-details/swift/model-data/object-models-define-sdk-object-model-description.rst b/source/includes/api-details/swift/model-data/object-models-define-sdk-object-model-description.rst new file mode 100644 index 0000000000..b49975fa56 --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-define-sdk-object-model-description.rst @@ -0,0 +1,10 @@ +In Swift, to define an SDK object, create a class that inherits from one +of the SDK object types: + +- :swift-sdk:`Object ` +- :swift-sdk:`EmbeddedObject ` +- :swift-sdk:`AsymmetricObject ` + +The name of the class becomes the table name in the database. Properties of the +class persist in the database. This makes it as easy to work with persisted +objects as it is to work with regular Swift objects. diff --git a/source/includes/api-details/swift/model-data/object-models-designate-primary-key-description.rst b/source/includes/api-details/swift/model-data/object-models-designate-primary-key-description.rst new file mode 100644 index 0000000000..1231c2d3c2 --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-designate-primary-key-description.rst @@ -0,0 +1,11 @@ +You can create a primary key with any of the following types: + +- String +- Int +- ObjectId +- UUID + +To designate a property as an object's primary key, declare the property with +:swift-sdk:`primaryKey: true +` +on the ``@Persisted`` notation. diff --git a/source/includes/api-details/swift/model-data/object-models-fts-index-property-swift-objc-not-supported.rst b/source/includes/api-details/swift/model-data/object-models-fts-index-property-swift-objc-not-supported.rst new file mode 100644 index 0000000000..809aaa29d7 --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-fts-index-property-swift-objc-not-supported.rst @@ -0,0 +1 @@ +The Swift SDK does not currently support Full-Text Search. diff --git a/source/includes/api-details/swift/model-data/object-models-ignore-property-description.rst b/source/includes/api-details/swift/model-data/object-models-ignore-property-description.rst new file mode 100644 index 0000000000..b66bf988bd --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-ignore-property-description.rst @@ -0,0 +1,2 @@ +To ignore a property, omit the ``@Persisted`` notation from the property +attribute. diff --git a/source/includes/api-details/swift/model-data/object-models-index-property-description.rst b/source/includes/api-details/swift/model-data/object-models-index-property-description.rst new file mode 100644 index 0000000000..32ccf8b8ed --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-index-property-description.rst @@ -0,0 +1,14 @@ +You can index properties of these data types: + +- string +- integer +- boolean +- ``Date`` +- ``UUID`` +- ``ObjectId`` +- ``AnyRealmValue`` + +To index a property, declare the property with +:swift-sdk:`indexed:true +` +on the ``@Persisted`` notation. diff --git a/source/includes/api-details/swift/model-data/object-models-map-model-or-property-to-different-name-description.rst b/source/includes/api-details/swift/model-data/object-models-map-model-or-property-to-different-name-description.rst new file mode 100644 index 0000000000..f16b8bb2c6 --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-map-model-or-property-to-different-name-description.rst @@ -0,0 +1,16 @@ +**Map a Model Name** + +The Swift SDK does not support mapping a model name to a different name. + +**Map a Property Name** + +Declare the name you want to use in your project as the ``@Persisted`` +property on the object model. Then, pass a dictionary containing the +public and private values for the property names via the +``propertiesMapping()`` function. + +In this example, ``firstName`` is the public property name we use in the code +throughout the project to perform CRUD operations. Using the ``propertiesMapping()`` +function, we map that to store values using the private property name +``first_name`` in the database. If we write to a synced database, the Sync +schema sees the values stored using the private property name ``first_name``. diff --git a/source/includes/api-details/swift/model-data/object-models-model-unstructured-data-description.rst b/source/includes/api-details/swift/model-data/object-models-model-unstructured-data-description.rst new file mode 100644 index 0000000000..b4a9d422ce --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-model-unstructured-data-description.rst @@ -0,0 +1,13 @@ +.. versionadded:: 10.51.0 + +Starting in SDK version 10.51.0, you can store collections of mixed data +within a ``AnyRealmValue`` property. + +To model unstructured data in your app, define the appropriate properties in +your schema as :ref:`AnyRealmValue ` types. You can then +set these ``AnyRealmValue`` properties as a :ref:`list ` +or a :ref:`dictionary ` collection of +``AnyRealmValue`` elements. + +Note that ``AnyRealmValue`` *cannot* represent a ``MutableSet`` or an embedded +object. diff --git a/source/includes/api-details/swift/model-data/object-models-object-model-description.rst b/source/includes/api-details/swift/model-data/object-models-object-model-description.rst new file mode 100644 index 0000000000..40da5ff400 --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-object-model-description.rst @@ -0,0 +1,51 @@ +In Swift, SDK object models are regular Swift classes that define the SDK data +model. + +Swift SDK objects must derive from one of the SDK object types. + +Model Inheritance +````````````````` + +You can subclass SDK models to share behavior between +classes, but there are limitations. In particular, the SDK +does not allow you to: + +- Cast between polymorphic classes: subclass to subclass, subclass to parent, parent to subclass +- Query on multiple classes simultaneously: for example, "get all instances of parent class and subclass" +- Multi-class containers: ``List`` and ``Results`` with a mixture of parent and subclass + +.. tip:: + + Check out the :github:`code samples + ` for working + around these limitations. + +Swift Structs +````````````` + +The SDK does not support Swift structs as models for a variety of +reasons. The SDK's design focuses on "live" objects. +This concept is not compatible with value-type structs. By design, +the SDK provides features that are incompatible with these +semantics, such as: + +- :ref:`Live data ` +- :ref:`Reactive APIs ` +- Low memory footprint of data +- Good operation performance +- :ref:`Lazy and cheap access to partial data ` +- Lack of data serialization/deserialization +- :ref:`Keeping potentially complex object graphs synchronized ` + +That said, it is sometimes useful to detach objects from their backing +database. This typically isn't an ideal design decision. Instead, +developers use this as a workaround for temporary limitations in our +library. + +You can use key-value coding to initialize an unmanaged object as a copy of +a managed object. Then, you can work with that unmanaged object +like any other :apple:`NSObject `. + +.. code-block:: swift + + let standaloneModelObject = MyModel(value: persistedModelObject) diff --git a/source/includes/api-details/swift/model-data/object-models-object-schema-description.rst b/source/includes/api-details/swift/model-data/object-models-object-schema-description.rst new file mode 100644 index 0000000000..ef6988cba2 --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-object-schema-description.rst @@ -0,0 +1,7 @@ +The Swift SDK does not require you to manually create object schemas. Instead, +it uses reflection to automatically create schemas for your SDK object types. + +Your project must not set +``SWIFT_REFLECTION_METADATA_LEVEL = none``, or the SDK cannot discover +properties in your models. Reflection is enabled by default if your project +does not specifically set a level for this setting. diff --git a/source/includes/api-details/swift/sync/stream-data-open-synced-database-description.rst b/source/includes/api-details/swift/sync/stream-data-open-synced-database-description.rst index 82a38be092..424d8c78fc 100644 --- a/source/includes/api-details/swift/sync/stream-data-open-synced-database-description.rst +++ b/source/includes/api-details/swift/sync/stream-data-open-synced-database-description.rst @@ -5,7 +5,7 @@ Specify the ``AsymmetricObject`` types you want to sync. The ``AsymmetricObject`` type is incompatible with non-synced databases. If your project uses both a synced and non-synced database, you must explicitly :ref:`pass a subset of classes in your database configuration - ` to exclude the + ` to exclude the ``AsymmetricObject`` from your non-synced database. Automatic schema discovery means that opening a non-synced database diff --git a/source/includes/api-details/typescript/model-data/object-models-define-asymmetric-object-description.rst b/source/includes/api-details/typescript/model-data/object-models-define-asymmetric-object-description.rst new file mode 100644 index 0000000000..242b984e2f --- /dev/null +++ b/source/includes/api-details/typescript/model-data/object-models-define-asymmetric-object-description.rst @@ -0,0 +1,2 @@ +In TypeScript, to define an asymmetric object, set the ``asymmetric`` property +on your object schema. diff --git a/source/includes/api-details/typescript/model-data/object-models-define-geospatial-object-description.rst b/source/includes/api-details/typescript/model-data/object-models-define-geospatial-object-description.rst new file mode 100644 index 0000000000..896d7d0db5 --- /dev/null +++ b/source/includes/api-details/typescript/model-data/object-models-define-geospatial-object-description.rst @@ -0,0 +1,34 @@ +In TypeScript, to create a class that conforms to the GeoJSON spec, you: + +1. Create an embedded SDK object. For more information about embedded + objects, refer to :ref:`sdks-embedded-objects`. + +#. At a minimum, add the two fields required by the GeoJSON spec: + + - A field of type ``double[]`` that maps to a "coordinates" (case sensitive) + property in the object schema. + + - A field of type ``string`` that maps to a "type" property. The value of this + field must be "Point". + +To simplify geodata persistance, you can define a model that implements +``CanonicalGeoPoint``, which already has the correct shape. The following +example shows an embedded class named ``MyGeoPoint`` that is used +to persist geospatial data: + +.. literalinclude:: /examples/generated/node/v12/geospatial.test.snippet.define-geopoint-class.ts + :language: typescript + +Use the Embedded Class +`````````````````````` + +You then use the custom ``MyGeoPoint`` class in your SDK model, as shown in the +following example: + +.. literalinclude:: /examples/generated/node/v12/geospatial.test.snippet.use-geopoint-class.ts + :language: typescript + +You add instances of your class to the database just like any other SDK +model. However, in this example, because the ``MyGeoPoint`` class does not +extend ``Realm.Object``, we must specify ``MyGeoPoint.schema`` when opening +the database: diff --git a/source/includes/api-details/typescript/model-data/object-models-define-optional-property-description.rst b/source/includes/api-details/typescript/model-data/object-models-define-optional-property-description.rst new file mode 100644 index 0000000000..2dbe939d1a --- /dev/null +++ b/source/includes/api-details/typescript/model-data/object-models-define-optional-property-description.rst @@ -0,0 +1 @@ +To mark a property as optional, append a question mark ``?`` to its type. diff --git a/source/includes/api-details/typescript/model-data/object-models-define-realm-object-description.rst b/source/includes/api-details/typescript/model-data/object-models-define-realm-object-description.rst new file mode 100644 index 0000000000..1544c31dc0 --- /dev/null +++ b/source/includes/api-details/typescript/model-data/object-models-define-realm-object-description.rst @@ -0,0 +1,12 @@ +Create a TypeScript class that extends :js-sdk:`Realm.Object +`. + +Define a static ``schema`` object of type :js-sdk:`ObjectSchema +`. This schema includes a ``name`` property, +which becomes the table name in the database. The schema should include a +``properties`` array, which is an array of objects of type +:js-sdk:`PropertiesTypes `. Each object in +this array contains a string key that becomes the name of the property, and +a :js-sdk:`PropertySchema ` that provides +additional details about the property, such as its type and any special +behaviors it should have. diff --git a/source/includes/api-details/typescript/model-data/object-models-define-sdk-object-model-description.rst b/source/includes/api-details/typescript/model-data/object-models-define-sdk-object-model-description.rst new file mode 100644 index 0000000000..f390a28203 --- /dev/null +++ b/source/includes/api-details/typescript/model-data/object-models-define-sdk-object-model-description.rst @@ -0,0 +1,12 @@ +In TypeScript, to define an SDK object, create a TypeScript class that extends +:js-sdk:`Realm.Object `. + +Define a static ``schema`` object that includes a ``name`` property and +a ``properties`` array. The ``name`` becomes the table name in the database. +The ``properties`` array describes the property names, types, and any additional +details about special property behaviors, such as whether the property should +be indexed. + +For object types with special behaviors, such as embedded objects and +asymmetric objects, set the optional ``embedded`` or ``asymmetric`` property +to ``true``. diff --git a/source/includes/api-details/typescript/model-data/object-models-map-model-or-property-to-different-name-description.rst b/source/includes/api-details/typescript/model-data/object-models-map-model-or-property-to-different-name-description.rst new file mode 100644 index 0000000000..5a471fc204 --- /dev/null +++ b/source/includes/api-details/typescript/model-data/object-models-map-model-or-property-to-different-name-description.rst @@ -0,0 +1,24 @@ +**Map a Model Name** + +To use a different class name in your code than is stored in the database: + +1. Set the ``name`` property of your SDK object's **schema** to the name + that you want to use to store the object. + +#. Use the **class** name in the database configuration's ``schema`` property + when you :ref:`open the database `. + +#. Use the mapped name for performing CRUD operations or when defining + Sync Subscriptions. + +In the following example, the SDK stores objects created with the +``Task`` class as ``Todo_Item``. + +.. literalinclude:: /examples/generated/node/v12/define-a-realm-object-schema.test.snippet.remap-class-name.ts + :language: typescript + :emphasize-lines: 9, 22, 31, 43, 51 + +**Map a Property Name** + +To use a different property name in your code than is stored in the database, +set ``mapTo`` to the name of the property as it appears in your code. diff --git a/source/includes/api-details/typescript/model-data/object-models-object-model-description.rst b/source/includes/api-details/typescript/model-data/object-models-object-model-description.rst new file mode 100644 index 0000000000..3bdea0b235 --- /dev/null +++ b/source/includes/api-details/typescript/model-data/object-models-object-model-description.rst @@ -0,0 +1,16 @@ +You can define SDK models as TypeScript classes that extend ``Realm.Object``. + +When you create objects, use an object literal. This lets you create an +**unmanaged** object, and pass it to the database when it makes sense to do so. + +Do not use ``new`` to construct a new object instance. If you use ``new`` with +class-based models, this creates a new **managed** object, which has the +following side effects: + +- Constructing a ``new`` object calls the ``realm.create()`` method, which can + only be used in a write transcation. +- Constructing a ``new`` object has complications when the object contains or + is itself an embedded object. + +For more information about object creation and managed objects, refer to +:ref:`sdks-crud-create` and :ref:`sdks-create-specific-object-types`. diff --git a/source/includes/api-details/typescript/model-data/object-models-set-default-value-for-property-description.rst b/source/includes/api-details/typescript/model-data/object-models-set-default-value-for-property-description.rst new file mode 100644 index 0000000000..b38e740e2e --- /dev/null +++ b/source/includes/api-details/typescript/model-data/object-models-set-default-value-for-property-description.rst @@ -0,0 +1,2 @@ +To define a default value, set the value of the property to an object with a +``type`` field and a ``default`` field. \ No newline at end of file diff --git a/source/includes/dotnet-implement-interface.rst b/source/includes/dotnet-implement-interface.rst index e036cdc995..f3326ccd26 100644 --- a/source/includes/dotnet-implement-interface.rst +++ b/source/includes/dotnet-implement-interface.rst @@ -12,7 +12,7 @@ :dotnet-sdk:`AsymmetricObject ` base classes. This approach to SDK model definition is still supported, but does not include new features such as the :ref:`nullability annotations - `. These base classes will be + `. These base classes will be deprecated in a future SDK release. You should use the interfaces for any new classes that you write and should consider migrating your existing classes. \ No newline at end of file diff --git a/source/includes/important-cant-persist-geospatial.rst b/source/includes/important-cant-persist-geospatial.rst deleted file mode 100644 index 077f8003b8..0000000000 --- a/source/includes/important-cant-persist-geospatial.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. important:: Cannot Persist Geospatial Data Types - - Currently, you can only persist geospatial data. Geospatial data types *cannot* be persisted directly. For example, you - can't declare a property that is of type ``GeoBox``. - - These types can only be used as arguments for geospatial queries. diff --git a/source/includes/sdk-examples/model-data/object-models-define-asymmetric-object.rst b/source/includes/sdk-examples/model-data/object-models-define-asymmetric-object.rst new file mode 100644 index 0000000000..e5f6a64530 --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-define-asymmetric-object.rst @@ -0,0 +1,69 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/asymmetric-sync.snippet.asymmetric-object.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cs + :language: csharp + :copyable: false + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.asymmetric-sync-object.dart + :language: dart + :emphasize-lines: 1 + + - 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/react-native/js/data-ingest.test.snippet.data-ingest-object.jsx + :language: javascript + :emphasize-lines: 6 + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-asymmetric-model.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.asymmetric-model.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/react-native/ts/data-ingest.test.snippet.data-ingest-object.tsx + :language: typescript + :emphasize-lines: 12 diff --git a/source/includes/sdk-examples/model-data/object-models-define-custom-setters.rst b/source/includes/sdk-examples/model-data/object-models-define-custom-setters.rst new file mode 100644 index 0000000000..7818169cc5 --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-define-custom-setters.rst @@ -0,0 +1,71 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Objects.snippet.custom-setter.cs + :language: csharp + + - 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: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + :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/model-data/object-models-define-embedded-object.rst b/source/includes/sdk-examples/model-data/object-models-define-embedded-object.rst new file mode 100644 index 0000000000..d75300b8d3 --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-define-embedded-object.rst @@ -0,0 +1,61 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/crud.snippet.model-with-embedded-object.cpp + :language: cpp + :emphasize-lines: 8, 13 + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/EmbeddedExamples.snippet.embedded-classes.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.embedded-object-model.dart + :language: dart + + - id: java + content: | + + .. include:: /examples/generated/java/local/FrogEmbeddedExample.snippet.complete.java.rst + + - id: java-kotlin + content: | + + .. include:: /examples/generated/java/local/FrogEmbeddedExampleKt.snippet.complete.kt.rst + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/data-types.snippet.define-embedded-objects.js + :language: javascript + :emphasize-lines: 3, 18, 28 + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-embedded-object.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/EmbeddedObjects.snippet.models.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/ReadRealmObjects.snippet.embedded-object-models.swift + :language: swift + + - id: typescript + content: | + + .. include:: /examples/generated/react-native/v12/models.snippet.define-embedded-property.ts.rst diff --git a/source/includes/sdk-examples/model-data/object-models-define-geospatial-object.rst b/source/includes/sdk-examples/model-data/object-models-define-geospatial-object.rst new file mode 100644 index 0000000000..7061972c58 --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-define-geospatial-object.rst @@ -0,0 +1,69 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Geospatial.snippet.usingcustomgeopoint.cs + :language: csharp + :emphasize-lines: 7 + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/geospatial_data_test.snippet.use-geopoint-class.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/geospatial.test.snippet.write-geospatial-object.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/Geospatial.snippet.geopoint-model.kt + :language: kotlin + :emphasize-lines: 4 + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/Geospatial.snippet.custom-geopoint.swift + :language: swift + :emphasize-lines: 2-3 + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/geospatial.test.snippet.write-geospatial-object.ts + :language: typescript diff --git a/source/includes/sdk-examples/model-data/object-models-define-optional-property.rst b/source/includes/sdk-examples/model-data/object-models-define-optional-property.rst new file mode 100644 index 0000000000..b7998ce7e5 --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-define-optional-property.rst @@ -0,0 +1,67 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/supported-types.snippet.optional-string.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/NullabilityTest.snippet.nullability.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/schemas.snippet.property-annotations.dart + :language: dart + :emphasize-lines: 5 + + - 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/define-a-realm-object-schema.snippet.define-object-properties.js + :language: javascript + :emphasize-lines: 8 + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/DataTypes.snippet.string-optional.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.optional-required-properties.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.optional-required-properties.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/model-data/object-models-define-projection.rst b/source/includes/sdk-examples/model-data/object-models-define-projection.rst new file mode 100644 index 0000000000..32ebf06e57 --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-define-projection.rst @@ -0,0 +1,71 @@ +.. 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/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/api.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.kt + :language: kotlin + :copyable: false + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/ClassProjection.snippet.declare-class-projection.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/model-data/object-models-define-realm-object.rst b/source/includes/sdk-examples/model-data/object-models-define-realm-object.rst new file mode 100644 index 0000000000..72618af10b --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-define-realm-object.rst @@ -0,0 +1,67 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/crud.snippet.define-model.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/ObjectModelsAndSchemas.snippet.dog_class.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/schemas.snippet.create-realm-model.dart + :language: dart + + .. literalinclude:: /examples/generated/flutter/define_realm_object_schema_usage_test.snippet.use-realm-object.dart + :language: dart + + - id: java + content: | + + .. include:: /examples/generated/java/local/FrogObjectExample.snippet.complete.java.rst + + .. include:: /examples/generated/java/local/FrogRealmModelExample.snippet.complete.java.rst + + - id: java-kotlin + content: | + + .. include:: /examples/generated/java/local/FrogObjectExampleKt.snippet.complete.kt.rst + + .. include:: /examples/generated/java/local/FrogRealmModelExampleKt.snippet.complete.kt.rst + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/react-native/js/Book.snippet.js-book-schema.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-realm-object.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.define-a-model.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.define-a-model.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/react-native/ts/Book.snippet.ts-book-schema.ts + :language: typescript diff --git a/source/includes/sdk-examples/model-data/object-models-define-sdk-object-model.rst b/source/includes/sdk-examples/model-data/object-models-define-sdk-object-model.rst new file mode 100644 index 0000000000..103e122266 --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-define-sdk-object-model.rst @@ -0,0 +1,63 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/crud.snippet.define-model.cpp + :language: cpp + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Schemas.snippet.schema_property.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/define_realm_object_schema_usage_test.snippet.use-realm-object.dart + :language: dart + :caption: myapp.dart + + - id: java + content: | + + .. literalinclude:: /examples/generated/java/local/RealmObjectVsRealmModelTest.snippet.realm-object-vs-realm-model.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/generated/java/local/RealmObjectVsRealmModelTest.snippet.realm-object-vs-realm-model.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/react-native/js/Book.snippet.js-book-schema.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-realm-object.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.define-a-model.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.define-a-model.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/react-native/ts/Book.snippet.ts-book-schema.ts + :language: typescript diff --git a/source/includes/sdk-examples/model-data/object-models-designate-primary-key.rst b/source/includes/sdk-examples/model-data/object-models-designate-primary-key.rst new file mode 100644 index 0000000000..4dbb93a139 --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-designate-primary-key.rst @@ -0,0 +1,64 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/crud.snippet.person-model.cpp + :language: cpp + :emphasize-lines: 2 + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Objects.snippet.primary-key.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/schemas.snippet.property-annotations.dart + :language: dart + :emphasize-lines: 2-3 + + - id: java + content: | + + .. include:: /examples/generated/java/local/FrogPrimaryKeyExample.snippet.complete.java.rst + + - id: java-kotlin + content: | + + .. include:: /examples/generated/java/local/FrogPrimaryKeyExampleKt.snippet.complete.kt.rst + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/define-a-realm-object-schema.snippet.define-object-properties.js + :language: javascript + :emphasize-lines: 10 + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-primary-key.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.specify-a-primary-key.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.specify-a-primary-key.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/model-data/object-models-enable-full-text-search-on-property.rst b/source/includes/sdk-examples/model-data/object-models-enable-full-text-search-on-property.rst new file mode 100644 index 0000000000..1a73d59e2e --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-enable-full-text-search-on-property.rst @@ -0,0 +1,71 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Objects.snippet.index.cs + :language: csharp + :emphasize-lines: 6-7 + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/full_text_search_test.snippet.flutter-fts-annotation.dart + :language: dart + :emphasize-lines: 6-10 + + - 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/Schema.snippet.define-fts.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.m + :language: objectivec + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.swift + :language: swift + :copyable: false + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/v12/full-text-search.test.snippet.node-fts-annotation.ts + :language: typescript + :emphasize-lines: 8 diff --git a/source/includes/sdk-examples/model-data/object-models-ignore-property.rst b/source/includes/sdk-examples/model-data/object-models-ignore-property.rst new file mode 100644 index 0000000000..1c0ec0a5ad --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-ignore-property.rst @@ -0,0 +1,64 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/crud.snippet.employee-model.cpp + :language: cpp + :emphasize-lines: 8 + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Objects.snippet.ignore.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/schemas.snippet.property-annotations.dart + :language: dart + :emphasize-lines: 9-10 + + - id: java + content: | + + .. include:: /examples/generated/java/local/FrogIgnoreExample.snippet.complete.java.rst + + - id: java-kotlin + content: | + + .. include:: /examples/generated/java/local/FrogIgnoreExampleKt.snippet.complete.kt.rst + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + :copyable: false + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-ignored.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.ignore-a-property.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.ignore-a-property.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/model-data/object-models-index-property.rst b/source/includes/sdk-examples/model-data/object-models-index-property.rst new file mode 100644 index 0000000000..60f9943b76 --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-index-property.rst @@ -0,0 +1,65 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Objects.snippet.index.cs + :language: csharp + :emphasize-lines: 3-4 + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/schemas.snippet.property-annotations.dart + :language: dart + :emphasize-lines: 12-13 + + - id: java + content: | + + .. include:: /examples/generated/java/local/FrogIndexExample.snippet.complete.java.rst + + - id: java-kotlin + content: | + + .. include:: /examples/generated/java/local/FrogIndexExampleKt.snippet.complete.kt.rst + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/define-a-realm-object-schema.snippet.define-advanced-properties.js + :language: javascript + :emphasize-lines: 5 + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-index.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.index-a-property.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.index-a-property.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/model-data/object-models-map-model-or-property-to-different-name.rst b/source/includes/sdk-examples/model-data/object-models-map-model-or-property-to-different-name.rst new file mode 100644 index 0000000000..6fdbf57e59 --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-map-model-or-property-to-different-name.rst @@ -0,0 +1,76 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Objects.snippet.rename-class.cs + :language: csharp + :caption: Map a model name + + .. literalinclude:: /examples/generated/dotnet/Objects.snippet.rename.cs + :language: csharp + :caption: Map a property name + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/define_realm_model_test.snippet.map-to.dart + :language: dart + :emphasize-lines: 2 + :caption: Map a model name + + .. literalinclude:: /examples/generated/flutter/schemas.snippet.property-annotations.dart + :language: dart + :emphasize-lines: 15-16 + :caption: Map a property name + + - id: java + content: | + + .. include:: /examples/generated/java/local/RenameModuleExample.snippet.complete.java.rst + + - id: java-kotlin + content: | + + .. include:: /examples/generated/java/local/RenameModuleExampleKt.snippet.complete.kt.rst + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/define-a-realm-object-schema.snippet.define-advanced-properties.js + :language: javascript + :emphasize-lines: 7 + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-persisted-name.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + :copyable: false + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.rename-a-property.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.ts + :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/model-data/object-models-model-unstructured-data.rst b/source/includes/sdk-examples/model-data/object-models-model-unstructured-data.rst new file mode 100644 index 0000000000..2676768ad6 --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-model-unstructured-data.rst @@ -0,0 +1,70 @@ +.. 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: | + + .. include:: /includes/api-details/dart/model-data/object-models-model-unstructured-data-example.rst + + - 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/example.kt + :language: kotlin + :copyable: false + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + :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/model-data/object-models-set-default-value-for-property.rst b/source/includes/sdk-examples/model-data/object-models-set-default-value-for-property.rst new file mode 100644 index 0000000000..37c978bb8d --- /dev/null +++ b/source/includes/sdk-examples/model-data/object-models-set-default-value-for-property.rst @@ -0,0 +1,67 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.cpp + :language: cpp + :copyable: false + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/Objects.snippet.default.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/schemas.snippet.property-annotations.dart + :language: dart + :emphasize-lines: 7 + + - id: java + content: | + + .. include:: /examples/generated/java/local/FrogDefaultValueExample.snippet.complete.java.rst + + - id: java-kotlin + content: | + + .. include:: /examples/generated/java/local/FrogDefaultValueExampleKt.snippet.complete.kt.rst + + - id: javascript + content: | + + .. literalinclude:: /examples/generated/node/define-a-realm-object-schema.snippet.define-advanced-properties.js + :language: javascript + :emphasize-lines: 8 + + - id: kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.kt + :language: kotlin + :copyable: false + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + :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/platforms/apple/swift-concurrency.txt b/source/platforms/apple/swift-concurrency.txt index bb64760b16..ba2cc0f255 100644 --- a/source/platforms/apple/swift-concurrency.txt +++ b/source/platforms/apple/swift-concurrency.txt @@ -230,6 +230,6 @@ To avoid threading-related issues in code that uses Swift concurrency features: .. _concurrency-page-sendable-thread-confined-reference: Sendable, Non-Sendable, and Thread-Confined Types ------------------------------------------------- +------------------------------------------------- .. include:: /includes/swift-api-sendable-thread-confined-reference.rst diff --git a/source/platforms/unity.txt b/source/platforms/unity.txt index 8caa8f1e94..bdc51d845f 100644 --- a/source/platforms/unity.txt +++ b/source/platforms/unity.txt @@ -243,7 +243,7 @@ away. For examples of when you may perform BSON deserialization, check out the ` documentation. Using the SDK While the Application is Quitting -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The .NET SDK cannot be accessed within the `AppDomain.DomainUnload Event `_ or diff --git a/source/sdk/crud/read.txt b/source/sdk/crud/read.txt index cdc99da7c4..fbc5798a14 100644 --- a/source/sdk/crud/read.txt +++ b/source/sdk/crud/read.txt @@ -46,3 +46,11 @@ and the one you use varying depending on the SDK you're using. i.e.: - LINQ (C#) - Swift SDK (Swift & Objective-C Type-Safe queries and NS Predicate queries) - Java (Java & Kotlin, Fluent Interface) + +Read Relationship Properties +---------------------------- + +.. _sdks-query-inverse-relationships: + +Query Inverse Relationships +~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/sdk/files/configure-and-open.txt b/source/sdk/files/configure-and-open.txt index c4b912df59..3d5c090a30 100644 --- a/source/sdk/files/configure-and-open.txt +++ b/source/sdk/files/configure-and-open.txt @@ -37,8 +37,8 @@ specify a subset of schemas (objects) when opening a realm. Open a Database Asynchronously ------------------------------ -.. _sdks-provide-a-subset-of-classes-to-a-database: +.. _sdks-provide-a-subset-of-models-to-a-database: -Provide a Subset of Classes to a Database ------------------------------------------ +Provide a Subset of Models to a Database +---------------------------------------- diff --git a/source/sdk/model-data.txt b/source/sdk/model-data.txt index 11296dd223..66fdddd50c 100644 --- a/source/sdk/model-data.txt +++ b/source/sdk/model-data.txt @@ -6,8 +6,8 @@ Model Data :titlesonly: Define an Object Model + Define Property Types Relationships - Supported Types Change an Object Model Model Data with Device Sync @@ -15,7 +15,7 @@ The following pages contain information about how to model data in Atlas Device SDK code: - :ref:`sdks-object-models` +- :ref:`sdks-define-property-types` - :ref:`sdks-relationships` -- :ref:`sdks-supported-data-types` - :ref:`sdks-change-object-model` - :ref:`sdks-model-data-device-sync` diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 9cb67efbdc..ac8057081b 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -4,70 +4,1403 @@ Define an SDK Object Model ========================== +.. meta:: + :description: Define an object and schema to persist data with Atlas Device SDK. Data models may include properties with special behaviors, such as indexes or default values. + :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, objective-c, swift + .. contents:: On this page :local: :backlinks: none - :depth: 3 + :depth: 2 :class: singlecol -.. _sdks-define-object-schema: +.. tabs-selector:: drivers + +Atlas Device SDK applications model data as objects composed of +field-value pairs that each contain one or more :ref:`supported +` data types. You can annotate a property to +provide additional meta-information that gives the property special behaviors, +such as: + +- Designate a property as the object's primary key +- Ignore a property when reading and writing data +- Index a property to improve performance for queries on that property +- Index a property for use with Full-Text Search +- Map a property or class to a different stored name + +.. _sdks-object-types-schemas: + +Object Types and Schemas +------------------------ + +Every database object has an *object type* that refers to the object's +class or struct. Objects of the same type share an :ref:`object schema +` that defines the properties and relationships of those +objects. + +.. _sdks-database-schema: + +Database Schema +~~~~~~~~~~~~~~~ + +A **database schema** is a list of valid object schemas that the database may +contain. Every database object must conform to an object type that's included +in its database's schema. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-database-schema-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-database-schema-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-database-schema-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-database-schema-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-database-schema-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-database-schema-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-database-schema-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-database-schema-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst + +If the database already contains data when you open it, the SDK +validates each object to ensure that an object schema was provided for +its type and that it meets all of the constraints specified in the schema. + +For more information about how to open the database, refer to +:ref:`sdks-configure-and-open-database`. + +.. _sdks-object-model: + +Object Model +~~~~~~~~~~~~ + +Your **object model** is the core structure that gives the database +information about how to interpret and store the objects in your app. +The properties that you want to persist must use the :ref:`supported data types +`. Properties are also the mechanism for +establishing :ref:`relationships ` between object types, +or establishing other special behaviors for specific fields in your object. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-object-model-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-object-model-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-object-model-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-object-model-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-object-model-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-object-model-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-object-model-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-object-model-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-object-model-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/model-data/object-models-object-model-description.rst + +.. _sdks-object-schema: + +Object Schema +~~~~~~~~~~~~~ + +An **object schema** maps properties for a specific object type. The SDK +schemas give the SDK the information it needs to validate, store, and retrieve +the objects. A schema must accompany every object model you want to persist. +When possible, Device SDK uses language-specific features to simplify or +abstract away the process of creating a schema. + +.. tabs-drivers:: -Define an SDK Object Schema ---------------------------- + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-object-schema-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-object-schema-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-object-schema-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-object-schema-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-object-schema-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-object-schema-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-object-schema-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/swift/model-data/object-models-object-schema-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-object-schema-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/model-data/object-models-object-schema-js-ts-description.rst .. _sdks-define-objects: Define an SDK Object Model -------------------------- -Placeholder page for defining an object model. +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-define-sdk-object-model-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-define-sdk-object-model-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-define-sdk-object-model-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-define-sdk-object-model-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-define-sdk-object-model-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-define-sdk-object-model-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-define-sdk-object-model-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-define-sdk-object-model-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-define-sdk-object-model-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/model-data/object-models-define-sdk-object-model-description.rst + +.. include:: /includes/sdk-examples/model-data/object-models-define-sdk-object-model.rst + +.. include:: /includes/note-class-char-limit.rst + +.. _sdks-define-models-object-types: + +Define Models for Specific Object Types +--------------------------------------- + +The SDK provides three specific object types, plus support for using an object +with geospatial data: + +- **Realm object**: the base object type used by the SDK. +- **Embedded object**: a special object type that cannot exist outside the + lifecycle of its parent Realm object. +- **Asymmetric object**: a special object type used in heavy insert-only + workloads using the Data Ingest feature. +- **Geospatial object**: an object that uses duck-typing to provide a + consistent interface and special methods for working with geospatial data. + +Throughout the documentation, when we refer to "SDK objects" or "SDK object +types," we refer to one of these object types. + +.. _sdks-realm-objects: + +Define a Realm Object +~~~~~~~~~~~~~~~~~~~~~ + +A Realm object is the base object type stored by the SDK's device persistence +layer, Realm. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-define-realm-object-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-define-realm-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-define-realm-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-define-realm-object-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-define-realm-object-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-define-realm-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-define-realm-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-define-realm-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-define-realm-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/model-data/object-models-define-realm-object-description.rst + +.. include:: /includes/sdk-examples/model-data/object-models-define-realm-object.rst .. _sdks-embedded-objects: Define an Embedded Object ~~~~~~~~~~~~~~~~~~~~~~~~~ -Placeholder for defining an embedded object, so we have a ref target to link to. +An **embedded object** is a special type of object that models complex +data about a specific object. Embedded objects are similar to +relationships, but they provide additional constraints and +map more naturally to the denormalized :manual:`MongoDB document model +`. + +The SDK enforces unique ownership constraints that treat each embedded +object as nested data inside of a single, specific parent object. An +embedded object inherits the lifecycle of its parent object and cannot +exist as an independent database object. The SDK automatically deletes +embedded objects if their parent object is deleted or when overwritten +by a new embedded object instance. This differs from a :ref:`to-one +` or :ref:`to-many ` +relationship, in which the related objects have independent lifecycles. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-define-embedded-object-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-define-embedded-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-define-embedded-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-define-embedded-object-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-define-embedded-object-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-define-embedded-object-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-define-embedded-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-define-embedded-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-define-embedded-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/model-data/object-models-define-embedded-object-js-ts-description.rst + +.. include:: /includes/sdk-examples/model-data/object-models-define-embedded-object.rst + +.. important:: Lifecycle considerations + + Because embedded objects cannot exist as objects independent of their parent + object, when you delete a Realm object, the SDK automatically deletes any + embedded objects referenced by that object. Any objects that your + application must persist after the deletion of their parent object + should use :ref:`relationships ` instead. + + Additionally, embedded objects cannot have a primary key. .. _sdks-asymmetric-objects: Define an Asymmetric Object ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Placeholder for defining an asymmetric object, so we have a ref target to link to. +You can use :ref:`Data Ingest ` to sync an +object unidirectionally from your device to the database linked to your +Atlas App Services App. + +Asymmetric objects do not function in the same way as other database objects. +You cannot: + +- Remove an asymmetric object from the device database +- Query an asymmetric object from the device database + +You can only create an asymmetric object, which then syncs unidirectionally +to the Atlas database linked to your App with Device Sync. + +For more information, see: :ref:`Create an Asymmetric Object +`. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-define-asymmetric-object-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-define-asymmetric-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-define-asymmetric-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-define-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-define-asymmetric-object-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-define-asymmetric-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-define-asymmetric-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-define-asymmetric-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-define-asymmetric-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/model-data/object-models-define-asymmetric-object-description.rst + +.. include:: /includes/sdk-examples/model-data/object-models-define-asymmetric-object.rst .. _sdks-define-geospatial-object: Define a Geospatial Object ~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. _sdks-define-special-property-types: +To persist ``GeoPoint`` data, it must conform to the +`GeoJSON spec `_. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk -Define Special Property Types ------------------------------ + .. include:: /includes/api-details/cpp/model-data/object-models-define-geospatial-object-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-define-geospatial-object-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-define-geospatial-object-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-define-geospatial-object-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-define-geospatial-object-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-define-geospatial-object-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-define-geospatial-object-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-define-geospatial-object-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-define-geospatial-object-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/model-data/object-models-define-geospatial-object-description.rst + +.. include:: /includes/sdk-examples/model-data/object-models-define-geospatial-object.rst + +.. important:: Cannot Persist Geospatial Data Types + + Currently, you can only persist geospatial data. Geospatial data types + *cannot* be persisted directly. For example, you can't declare a property + that is of type ``GeoBox``. + + These types can only be used as arguments for geospatial queries. + +.. _sdks-define-property-behaviors: + +Define Property Behaviors +------------------------- + +You can define property types that have special behavior. These property types +provide additional functionality or constraints to these fields in your data +model. + +.. _sdks-index-property: + +Index a Property +~~~~~~~~~~~~~~~~ + +When you add an index to a property, the SDK can perform equality matches and +range-based query operations on the property much more efficiently. Without +indexes, the SDK scans every object of its type to select the objects that +match the given query. However, if an applicable index exists for a query, the +SDK uses the index to limit the number of objects it must inspect. + +Indexes are special data structures that store a small portion of a +database's data in an easy-to-traverse form. The index stores the value +of a specific field ordered by the value of the field. + +When indexing a property, keep in mind: + +- Indexes can be nullable. +- :ref:`Primary keys ` are indexed by default. +- You *cannot* combine standard indexes with full-text search (FTS) + indexes on the same property. To create an FTS index on a property, refer to + the :ref:`sdks-fts-property` section on this page. + +Indexing a property makes some types of queries more efficient, but can slow +down writes and increase the size of the database file: + +- Indexes support more efficient match and range-based query operations. +- Indexes make insert and update operation speed slightly slower. +- Adding an index to a property increases disk space consumed by your database + file. Each index entry is a minimum of 12 bytes. +- Indexes on the client and on the server are entirely separate. The only + effect that adding indexes has on initial Sync performance is to make it + slightly slower as the index has to be populated. + +Generally, you should only add an index when you need to improve the performance +of a specific equality-based query, and the minor slowdown in writes is +acceptable with your app's write patterns. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-index-property-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-index-property-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-index-property-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-index-property-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-index-property-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-index-property-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-index-property-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-index-property-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-index-property-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/model-data/object-models-index-property-js-ts-description.rst + +.. include:: /includes/sdk-examples/model-data/object-models-index-property.rst + +.. note:: + + When you create an index with the SDK, you are creating it in the device + persistence layer and not on an Atlas collection. If you need to query an + Atlas collection directly and want to improve performance, refer to + `Create, View, Drop, and Hide Indexes `__. .. _sdks-fts-property: -Define a Full-Text Search Property -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Enable Full-Text Search on a Property +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The SDK supports Full-Text Search (FTS) on string properties. You do this by +adding a FTS index on the property. When you query a FTS property, the FTS +index enables searching for multiple words and phrases and excluding others. -.. _sdks-optional-property-types: +Similar to a regular index, FTS indexes have performance benefits and +implications. Adding a FTS index to a property makes some types of queries more +efficient, but can slow down writes and increase the size of the database file: -Define Optional Property Types -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- FTS indexes support more efficient match and range-based query operations + when seraching for multiple words or phrases and excluding others. +- FTS indexes make insert and update operation speed slightly slower. +- Adding a FTS index to a property increases disk space consumed by your + database file. Each index entry is a minimum of 12 bytes. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-fts-index-property-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-fts-index-property-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-fts-index-property-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-fts-index-property-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-fts-index-property-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-fts-index-property-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-fts-index-property-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/swift/model-data/object-models-fts-index-property-swift-objc-not-supported.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-fts-index-property-swift-objc-not-supported.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/model-data/object-models-fts-index-property-js-ts-description.rst + +.. include:: /includes/sdk-examples/model-data/object-models-enable-full-text-search-on-property.rst + +You *cannot* combine standard indexes with full-text search (FTS) +indexes on the same property. To create a standard index on a property, refer +to the :ref:`sdks-index-property` section on this page. + +.. note:: Character Limitations for Full-Text Search Indexes + + For Full-Text Search (FTS) indexes, only ASCII and Latin-1 alphanumerical + chars (most western languages) are included in the index. + + Indexes are diacritics- and case-insensitive. .. _sdks-primary-key: -Define a Primary Key -~~~~~~~~~~~~~~~~~~~~ +Designate a Primary Key +~~~~~~~~~~~~~~~~~~~~~~~ + +A **primary key** is a property that uniquely identifies an object. + +Primary keys allow you to efficiently find, update, and upsert objects. + +Primary keys are subject to the following limitations: + +- You can define only one primary key per object model. +- Primary key values must be unique across all instances of an object + in the database. The SDK throws an error if you try to + insert a duplicate primary key value. +- Primary key values are immutable. To change the primary key value of + an object, you must delete the original object and insert a new object + with a different primary key value. +- Embedded objects cannot define a primary key. + +If you are using :ref:`Device Sync `, your models must +have a primary key named ``_id``. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-designate-primary-key-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-designate-primary-key-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-designate-primary-key-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-designate-primary-key-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-designate-primary-key-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-designate-primary-key-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-designate-primary-key-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-designate-primary-key-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-designate-primary-key-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/model-data/object-models-designate-primary-key-js-ts-description.rst + +.. include:: /includes/sdk-examples/model-data/object-models-designate-primary-key.rst + +.. _sdks-optional-property-types: + +Define an Optional Property +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The SDK supports defining optional properties. The SDK uses language-specific +idioms for handling optional model properties. The SDK considers all model +properties required unless you designate them as optional, or ignore them. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-define-optional-property-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-define-optional-property-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-define-optional-property-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-define-optional-property-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-define-optional-property-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-define-optional-property-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-define-optional-property-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-define-optional-property-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-define-optional-property-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/model-data/object-models-define-optional-property-description.rst + +.. include:: /includes/sdk-examples/model-data/object-models-define-optional-property.rst + +Special Rules +````````````` + +The SDK has some special rules about when things *must* be nullable, and when +they *cannot* be nullable: + +- You must declare properties that are SDK object types as nullable. + +- You cannot declare collections (list, sets, backlinks, and dictionaries) as + nullable, but their parameters may be nullable according to the following rules: + + - For all types of collections, if the parameters are primitives + (value- or reference-types), they can be required or nullable. + + - For lists, sets, and backlinks, if the parameters are SDK objects, they + **cannot** be nullable. + + - For dictionaries with a value type of an SDK object, you **must** declare + the value type parameter as nullable. + +.. _sdks-ignore-property: + +Ignore a Property +~~~~~~~~~~~~~~~~~ + +You can ignore a property to avoid persisting that property's value. + +An ignored property behaves exactly like a managed property, except: + +- They aren't stored to the database +- They can't be used in queries +- They don't trigger notifications + +You can mix managed and ignored properties within a model. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-ignore-property-description.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-ignore-property-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-ignore-property-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-ignore-property-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-ignore-property-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-ignore-property-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-ignore-property-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-ignore-property-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-ignore-property-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/model-data/object-models-ignore-property-js-ts-description.rst + +.. include:: /includes/sdk-examples/model-data/object-models-ignore-property.rst + +.. _sdks-set-default-property-value: + +Set a Default Value for a Property +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can specify a default value for a property in your data model. + +You cannot set a default value on a collection, except to set it to null or nil. +Even if you set a collection to nil, collections are always initialized on +first access, so will never be nil. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp -.. _sdks-required-optional-property: + .. include:: /includes/api-details/csharp/model-data/object-models-set-default-value-for-property-description.rst + + .. tab:: + :tabid: dart -Placeholder for .NET nullability info, and any other SDKs with similar -APIs/requirements + .. include:: /includes/api-details/dart/model-data/object-models-set-default-value-for-property-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-set-default-value-for-property-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-set-default-value-for-property-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-set-default-value-for-property-description.rst + + .. tab:: + :tabid: kotlin + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/model-data/object-models-set-default-value-for-property-description.rst + +.. include:: /includes/sdk-examples/model-data/object-models-set-default-value-for-property.rst + +.. _sdks-custom-setters: + +Define Custom Setters +~~~~~~~~~~~~~~~~~~~~~ + +For some platforms and languages, the idiomatic developer experience involves +defining custom setters. The SDK does not directly persist properties using +custom setters. Instead, you can store the property value in a private property, +and then map that value to a public property that uses the custom setter. + +The SDK stores the private property, while you modify its value through the +public property. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-define-custom-setters-description.rst + + .. tab:: + :tabid: dart + + .. tab:: + :tabid: java + + .. tab:: + :tabid: java-kotlin + + .. tab:: + :tabid: javascript + + .. tab:: + :tabid: kotlin + + .. tab:: + :tabid: objectivec + + .. tab:: + :tabid: swift + + .. tab:: + :tabid: typescript + +.. include:: /includes/sdk-examples/model-data/object-models-define-custom-setters.rst .. _sdks-model-unstructured-data: Model Unstructured Data -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- + +**Unstructured data** is data that doesn't easily conform to an expected +schema, making it difficult or impractical to model to individual +data classes. For example, your app might have highly variable data or dynamic +data whose structure is unknown at runtime. + +The SDK provides the ability to store :ref:`collections of mixed data +` within a mixed property. You can use this +feature to model complex data structures, such as JSON or MongoDB documents, +without having to define a strict data model. + +You can work with these collections the same way you would a non-mixed +collection: + +- You can nest mixed collections up to 100 levels. +- You can query on and :ref:`react to changes + ` on mixed collections. +- You can find and update individual mixed collection elements. + +However, storing data in mixed collections is less performant than using a +structured schema or serializing JSON blobs into a single string property. + +.. tip:: + + - Use a map of mixed data types when the type is unknown but each value will have a unique identifier. + - Use a list of mixed data types when the type is unknown but the order of objects is meaningful. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-unstructured-data-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-model-unstructured-data-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-model-unstructured-data-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-unstructured-data-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-unstructured-data-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-model-unstructured-data-js-ts-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-model-unstructured-data-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-model-unstructured-data-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-model-unstructured-data-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/javascript/model-data/object-models-model-unstructured-data-js-ts-description.rst + +.. include:: /includes/sdk-examples/model-data/object-models-model-unstructured-data.rst + +.. _sdks-map-db-name: + +Map a Model or Property to a Different Name +------------------------------------------- + +Some of the SDK implementations provide the ability to map an SDK object model +or property to a different stored name in the database. This can be useful when: + +- You work across platforms where naming conventions differ. For example, if + your Device Sync schema property names use snake case, while your project + uses camel case. +- You want to change a class or field name without forcing a migration. +- You need to support multiple model classes with the same name in different + packages. +- You want to use a class name that is longer than the 57-character limit + enforced by the SDK. + +If you're using Atlas Device Sync, the name that you specify when you map the +model or property to a new name is the name used in the persisted +:ref:`App Services Schema `. + +.. note:: + + Migrations must use the persisted class or property name. Any schema errors + reported also use the persisted name. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/cpp/model-data/object-models-map-model-or-property-to-different-name-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/csharp/model-data/object-models-map-model-or-property-to-different-name-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-map-model-or-property-to-different-name-description.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/java/model-data/object-models-map-model-or-property-to-different-name-java-description.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/java/model-data/object-models-map-model-or-property-to-different-name-kotlin-description.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/javascript/model-data/object-models-map-model-or-property-to-different-name-description.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/kotlin/model-data/object-models-map-model-or-property-to-different-name-description.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-map-model-or-property-to-different-name-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-map-model-or-property-to-different-name-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/typescript/model-data/object-models-map-model-or-property-to-different-name-description.rst + +.. include:: /includes/sdk-examples/model-data/object-models-map-model-or-property-to-different-name.rst + +.. _sdks-define-model-projection: + +Transform Model Data for View Models +------------------------------------ + +You can define a **projection** of your model objects and properties to +transform the data into different shapes and structures. You might want to use +a projection to make data available in a specific form, but persist it in a +different form. + +For example, you might want to work with persisted data in a different way in +a view model or based on certain business logic. This simplifies using and +testing SDK objects in your application. + +With projection, you can use a subset of your object's properties directly in +the UI, or transform them. When you use a projection for this, you get all the +benefits of the SDK's live objects: + +- The class-projected object live updates +- You can observe it for changes +- You can apply changes directly to the properties in write transactions + +Projection is currently only available in the Swift SDK. + +Transform Persisted Properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When you define a projection, you can transform the original persisted +property in several ways: + +- Passthrough: the property is the same name and type as the original object +- Rename: the property has the same type as the original object, but a + different name +- Keypath resolution: use keypath resolution to access properties of the + original object, including embedded object properties +- Collection mapping: Project :ref:`lists ` or + :ref:`sets ` of ``Object`` s or + ``EmbeddedObject`` s as a collection of primitive values +- Exclusion: when you use a model projection, the underlying object's + properties that are not projected through the model projection are + excluded. This enables you to watch for changes to a model projection + and not see changes for properties that are not part of the model + projection. + +Define a Projection +~~~~~~~~~~~~~~~~~~~ + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. include:: /includes/api-details/generic/model-data/object-models-define-projection-not-supported.rst + + .. tab:: + :tabid: csharp + + .. include:: /includes/api-details/generic/model-data/object-models-define-projection-not-supported.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/generic/model-data/object-models-define-projection-not-supported.rst + + .. tab:: + :tabid: java + + .. include:: /includes/api-details/generic/model-data/object-models-define-projection-not-supported.rst + + .. tab:: + :tabid: java-kotlin + + .. include:: /includes/api-details/generic/model-data/object-models-define-projection-not-supported.rst + + .. tab:: + :tabid: javascript + + .. include:: /includes/api-details/generic/model-data/object-models-define-projection-not-supported.rst + + .. tab:: + :tabid: kotlin + + .. include:: /includes/api-details/generic/model-data/object-models-define-projection-not-supported.rst + + .. tab:: + :tabid: objectivec + + .. include:: /includes/api-details/objectivec/model-data/object-models-define-projection-missing-description.rst + + .. tab:: + :tabid: swift + + .. include:: /includes/api-details/swift/model-data/object-models-define-projection-description.rst + + .. tab:: + :tabid: typescript + + .. include:: /includes/api-details/generic/model-data/object-models-define-projection-not-supported.rst + +.. include:: /includes/sdk-examples/model-data/object-models-define-projection.rst diff --git a/source/sdk/model-data/supported-types.txt b/source/sdk/model-data/property-types.txt similarity index 65% rename from source/sdk/model-data/supported-types.txt rename to source/sdk/model-data/property-types.txt index 0d67e2f1ae..50b82a1107 100644 --- a/source/sdk/model-data/supported-types.txt +++ b/source/sdk/model-data/property-types.txt @@ -1,8 +1,8 @@ -.. _sdks-supported-data-types: +.. _sdks-define-property-types: -=============== -Supported Types -=============== +===================== +Define Property Types +===================== .. meta:: :description: Atlas Device SDK supports a range of primitive data types, as well as collections and geospatial data. @@ -20,12 +20,21 @@ Supported Types Placeholder page for supported data types. +.. _sdks-data-property-types: + +Data Property Types +------------------- .. _sdks-mixed-data-type: Generic (Mixed) Data Type ~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _sdks-nested-collections-in-mixed: + +Nested Collections in Mixed +``````````````````````````` + .. _sdks-counter-data-type: Counter Data Type @@ -36,10 +45,15 @@ Counter Data Type Timestamp Data Type ~~~~~~~~~~~~~~~~~~~ +.. _sdks-collection-property-types: + +Collection Property Types +------------------------- + .. _sdks-list-property-types: -Supported List Property Types -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Define a List Property +~~~~~~~~~~~~~~~~~~~~~~ .. _dart-define-uint8list-property-type: @@ -59,12 +73,25 @@ Then, set the object's type as ``Uint8List`` in your object model. .. _sdks-set-property-types: -Supported Set Property Types -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Define a Set Property +~~~~~~~~~~~~~~~~~~~~~ .. _sdks-dictionary-property-types: -Supported Dictionary Property Types -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Define a Dictionary Property +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. _sdks-relationship-property-types: + +Relationship Property Types +--------------------------- + +.. _sdks-other-property-types: + +Other Property Types +-------------------- +.. _sdks-enum-property: +Define an Enum Property +~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/sdk/sync/event-library.txt b/source/sdk/sync/event-library.txt index d6658e1bb0..35c4489b8d 100644 --- a/source/sdk/sync/event-library.txt +++ b/source/sdk/sync/event-library.txt @@ -213,7 +213,7 @@ JSON Object Serialization ~~~~~~~~~~~~~~~~~~~~~~~~~ The Event Library converts each event object to a JSON object. Most -:ref:`Realm types ` have an +:ref:`SDK types ` have an analogous JSON representation. For example, a Realm String property becomes a JSON String.