From 633153b9303df9d6e47443efebdfa41dbdabc8a6 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 27 Jun 2024 14:51:03 -0400 Subject: [PATCH 01/36] Draft concept content and stage for discussion --- source/frameworks/flutter/quick-start.txt | 4 +- ...ect-models-database-schema-description.rst | 3 + ...models-define-realm-object-description.rst | 12 + ...ls-define-sdk-object-model-description.rst | 9 + ...object-models-object-model-description.rst | 7 + ...bject-models-object-schema-description.rst | 13 + .../object-models-database-schema.rst | 16 + ...ect-models-database-schema-description.rst | 5 + ...art-define-your-object-model-procedure.rst | 4 +- ...ect-models-database-schema-description.rst | 2 + ...dels-database-schema-js-ts-description.rst | 3 + ...ect-models-database-schema-description.rst | 3 + ...ect-models-database-schema-description.rst | 7 + ...ect-models-database-schema-description.rst | 7 + .../model-data/define-object-model.rst | 63 +++ .../model-data/define-realm-object.rst | 63 +++ source/sdk/model-data/object-models.txt | 369 +++++++++++++++++- 17 files changed, 582 insertions(+), 8 deletions(-) create mode 100644 source/includes/api-details/cpp/model-data/object-models-database-schema-description.rst create mode 100644 source/includes/api-details/cpp/model-data/object-models-define-realm-object-description.rst create mode 100644 source/includes/api-details/cpp/model-data/object-models-define-sdk-object-model-description.rst create mode 100644 source/includes/api-details/cpp/model-data/object-models-object-model-description.rst create mode 100644 source/includes/api-details/cpp/model-data/object-models-object-schema-description.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-database-schema.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-database-schema-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-database-schema-description.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-database-schema-description.rst create mode 100644 source/includes/api-details/objectivec/model-data/object-models-database-schema-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-database-schema-description.rst create mode 100644 source/includes/sdk-examples/model-data/define-object-model.rst create mode 100644 source/includes/sdk-examples/model-data/define-realm-object.rst 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-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-object-model-description.rst b/source/includes/api-details/cpp/model-data/object-models-object-model-description.rst new file mode 100644 index 0000000000..c471f0f3e6 --- /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 a 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/csharp/model-data/object-models-database-schema.rst b/source/includes/api-details/csharp/model-data/object-models-database-schema.rst new file mode 100644 index 0000000000..94c04aa526 --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-database-schema.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-classes-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/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/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/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/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/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/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..385c422da1 --- /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-classes-to-a-database`. 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..a746f8166a --- /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-classes-to-a-database`. diff --git a/source/includes/sdk-examples/model-data/define-object-model.rst b/source/includes/sdk-examples/model-data/define-object-model.rst new file mode 100644 index 0000000000..dc10c0d558 --- /dev/null +++ b/source/includes/sdk-examples/model-data/define-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/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt + :language: kotlin + :emphasize-lines: 10, 11 + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts + :language: typescript diff --git a/source/includes/sdk-examples/model-data/define-realm-object.rst b/source/includes/sdk-examples/model-data/define-realm-object.rst new file mode 100644 index 0000000000..dc10c0d558 --- /dev/null +++ b/source/includes/sdk-examples/model-data/define-realm-object.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/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt + :language: kotlin + :emphasize-lines: 10, 11 + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts + :language: typescript diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 9cb67efbdc..7b3f9b0072 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -4,23 +4,384 @@ Define an SDK Object Model ========================== +.. meta:: + :description: Learn about object models and schemas, including how to define an object. + :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 :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. 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-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 + +.. _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:: + + .. 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-database-schema-description.rst + + .. tab:: + :tabid: dart + + .. include:: /includes/api-details/dart/model-data/object-models-database-schema-description.rst -Define an SDK Object Schema ---------------------------- + .. 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 .. _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-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 + +.. include:: /includes/sdk-examples/model-data/define-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-embedded-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-sdk-object-model-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 + +.. include:: /includes/sdk-examples/model-data/define-object-model.rst .. _sdks-embedded-objects: From ea2523fc88c264ad0e66eb670dacd106dec48bba Mon Sep 17 00:00:00 2001 From: dacharyc Date: Thu, 27 Jun 2024 15:05:12 -0400 Subject: [PATCH 02/36] Tweak wording and fix wrong include path --- source/sdk/model-data/object-models.txt | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 7b3f9b0072..7d230e47d0 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -310,13 +310,13 @@ 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 +- **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. +- **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. @@ -334,7 +334,7 @@ layer, Realm. .. tab:: :tabid: cpp-sdk - .. include:: /includes/api-details/cpp/model-data/object-models-define-sdk-object-model-description.rst + .. include:: /includes/api-details/cpp/model-data/object-models-define-realm-object-description.rst .. tab:: :tabid: csharp From e4c6a7261c4e4596aaa2d706b5cd3c14a15a3d15 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 28 Jun 2024 11:17:32 -0400 Subject: [PATCH 03/36] Add CSharp object model and schema information --- ...s-define-asymmetric-object-description.rst | 12 + ...els-define-embedded-object-description.rst | 6 + ...-define-geospatial-model-not-supported.rst | 1 + ...object-models-object-model-description.rst | 2 +- ...ct-models-database-schema-description.rst} | 0 ...s-define-asymmetric-object-description.rst | 3 + ...els-define-embedded-object-description.rst | 8 + ...s-define-geospatial-object-description.rst | 24 ++ ...models-define-realm-object-description.rst | 8 + ...ls-define-sdk-object-model-description.rst | 33 +++ ...object-models-object-model-description.rst | 1 + ...bject-models-object-schema-description.rst | 4 + .../important-cant-persist-geospatial.rst | 6 - .../model-data/define-asymmetric-object.rst | 63 +++++ .../model-data/define-embedded-object.rst | 64 +++++ .../model-data/define-geospatial-object.rst | 65 +++++ .../model-data/define-object-model.rst | 2 +- .../model-data/define-realm-object.rst | 2 +- source/sdk/model-data/object-models.txt | 228 +++++++++++++++++- 19 files changed, 514 insertions(+), 18 deletions(-) create mode 100644 source/includes/api-details/cpp/model-data/object-models-define-asymmetric-object-description.rst create mode 100644 source/includes/api-details/cpp/model-data/object-models-define-embedded-object-description.rst create mode 100644 source/includes/api-details/cpp/model-data/object-models-define-geospatial-model-not-supported.rst rename source/includes/api-details/csharp/model-data/{object-models-database-schema.rst => object-models-database-schema-description.rst} (100%) create mode 100644 source/includes/api-details/csharp/model-data/object-models-define-asymmetric-object-description.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-define-embedded-object-description.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-define-geospatial-object-description.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-define-realm-object-description.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-define-sdk-object-model-description.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-object-model-description.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-object-schema-description.rst delete mode 100644 source/includes/important-cant-persist-geospatial.rst create mode 100644 source/includes/sdk-examples/model-data/define-asymmetric-object.rst create mode 100644 source/includes/sdk-examples/model-data/define-embedded-object.rst create mode 100644 source/includes/sdk-examples/model-data/define-geospatial-object.rst 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..89de21a7f8 --- /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-model-not-supported.rst b/source/includes/api-details/cpp/model-data/object-models-define-geospatial-model-not-supported.rst new file mode 100644 index 0000000000..0fb2bb5e45 --- /dev/null +++ b/source/includes/api-details/cpp/model-data/object-models-define-geospatial-model-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-object-model-description.rst b/source/includes/api-details/cpp/model-data/object-models-object-model-description.rst index c471f0f3e6..067fa55318 100644 --- 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 @@ -1,4 +1,4 @@ -The C++ SDK object model is a regular C++ class or a struct that contains +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 diff --git a/source/includes/api-details/csharp/model-data/object-models-database-schema.rst b/source/includes/api-details/csharp/model-data/object-models-database-schema-description.rst similarity index 100% rename from source/includes/api-details/csharp/model-data/object-models-database-schema.rst rename to source/includes/api-details/csharp/model-data/object-models-database-schema-description.rst 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-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..b094ef25d5 --- /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 realm 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 Realm object model, as shown in +the following example. 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..3e12fb3c29 --- /dev/null +++ b/source/includes/api-details/csharp/model-data/object-models-define-sdk-object-model-description.rst @@ -0,0 +1,33 @@ +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-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/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/define-asymmetric-object.rst b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst new file mode 100644 index 0000000000..13cbd7892b --- /dev/null +++ b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst @@ -0,0 +1,63 @@ +.. 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 + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt + :language: kotlin + :emphasize-lines: 10, 11 + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts + :language: typescript diff --git a/source/includes/sdk-examples/model-data/define-embedded-object.rst b/source/includes/sdk-examples/model-data/define-embedded-object.rst new file mode 100644 index 0000000000..a8a9d7ec89 --- /dev/null +++ b/source/includes/sdk-examples/model-data/define-embedded-object.rst @@ -0,0 +1,64 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/generated/cpp/crud.snippet.model-with-embedded-object.cpp + :language: cpp + :emphasize-lines: 7, 12 + + - id: csharp + content: | + + .. literalinclude:: /examples/generated/dotnet/EmbeddedExamples.snippet.embedded-classes.cs + :language: csharp + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt + :language: kotlin + :emphasize-lines: 10, 11 + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts + :language: typescript diff --git a/source/includes/sdk-examples/model-data/define-geospatial-object.rst b/source/includes/sdk-examples/model-data/define-geospatial-object.rst new file mode 100644 index 0000000000..a1204ad8e1 --- /dev/null +++ b/source/includes/sdk-examples/model-data/define-geospatial-object.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/Geospatial.snippet.usingcustomgeopoint.cs + :language: csharp + :emphasize-lines: 7 + + - id: dart + content: | + + .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart + :language: dart + + - id: java + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + + - id: java-kotlin + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + :language: kotlin + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt + :language: kotlin + :emphasize-lines: 10, 11 + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + :language: swift + + - id: typescript + content: | + + .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts + :language: typescript diff --git a/source/includes/sdk-examples/model-data/define-object-model.rst b/source/includes/sdk-examples/model-data/define-object-model.rst index dc10c0d558..2223abd998 100644 --- a/source/includes/sdk-examples/model-data/define-object-model.rst +++ b/source/includes/sdk-examples/model-data/define-object-model.rst @@ -10,7 +10,7 @@ - id: csharp content: | - .. literalinclude:: /examples/MissingPlaceholders/example.cs + .. literalinclude:: /examples/generated/dotnet/Schemas.snippet.schema_property.cs :language: csharp - id: dart diff --git a/source/includes/sdk-examples/model-data/define-realm-object.rst b/source/includes/sdk-examples/model-data/define-realm-object.rst index dc10c0d558..491031318d 100644 --- a/source/includes/sdk-examples/model-data/define-realm-object.rst +++ b/source/includes/sdk-examples/model-data/define-realm-object.rst @@ -10,7 +10,7 @@ - id: csharp content: | - .. literalinclude:: /examples/MissingPlaceholders/example.cs + .. literalinclude:: /examples/generated/dotnet/ObjectModelsAndSchemas.snippet.dog_class.cs :language: csharp - id: dart diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 7d230e47d0..9ea98f27dd 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -42,7 +42,7 @@ Object Types and Schemas ------------------------ Every database object has an *object type* that refers to the object's -class. Objects of the same type share an :ref:`object schema +class or struct. Objects of the same type share an :ref:`object schema ` that defines the properties and relationships of those objects. @@ -136,7 +136,7 @@ or establishing other special behaviors for specific fields in your object. .. tab:: :tabid: csharp - .. include:: /includes/api-details/csharp/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/csharp/model-data/object-models-object-model-description.rst .. tab:: :tabid: dart @@ -199,7 +199,7 @@ abstract away the process of creating a schema. .. tab:: :tabid: csharp - .. include:: /includes/api-details/csharp/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/csharp/model-data/object-models-object-schema-description.rst .. tab:: :tabid: dart @@ -256,7 +256,7 @@ Define an SDK Object Model .. tab:: :tabid: csharp - .. include:: /includes/api-details/csharp/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/csharp/model-data/object-models-define-sdk-object-model-description.rst .. tab:: :tabid: dart @@ -321,7 +321,7 @@ 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-embedded-objects: +.. _sdks-realm-objects: Define a Realm Object ~~~~~~~~~~~~~~~~~~~~~ @@ -339,7 +339,7 @@ layer, Realm. .. tab:: :tabid: csharp - .. include:: /includes/api-details/csharp/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/csharp/model-data/object-models-define-realm-object-description.rst .. tab:: :tabid: dart @@ -381,27 +381,237 @@ layer, Realm. .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst -.. include:: /includes/sdk-examples/model-data/define-object-model.rst +.. include:: /includes/sdk-examples/model-data/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-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 + +.. include:: /includes/sdk-examples/model-data/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-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 + +.. include:: /includes/sdk-examples/model-data/define-asymmetric-object.rst .. _sdks-define-geospatial-object: Define a Geospatial Object ~~~~~~~~~~~~~~~~~~~~~~~~~~ +To persist ``GeoPoint`` data, it must conform to the +`GeoJSON spec `_. + +.. tabs-drivers:: + + .. tab:: + :tabid: cpp-sdk + + .. 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-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 + +.. include:: /includes/sdk-examples/model-data/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-special-property-types: Define Special Property Types From cd4176352f72a9e62129ad9deca27bb5b0c875fa Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 28 Jun 2024 13:59:56 -0400 Subject: [PATCH 04/36] Add Dart object model and schema information --- .../schemas.snippet.part-directive.dart | 2 +- ...efine-geospatial-object-not-supported.rst} | 0 ...s-define-asymmetric-object-description.rst | 10 ++ ...els-define-embedded-object-description.rst | 18 +++ ...s-define-geospatial-object-description.rst | 24 ++++ ...models-define-realm-object-description.rst | 6 + .../object-models-define-sdk-object-model.rst | 109 ++++++++++++++++++ ...object-models-object-model-description.rst | 5 + ...bject-models-object-schema-description.rst | 3 + .../model-data/define-asymmetric-object.rst | 3 +- .../model-data/define-embedded-object.rst | 4 +- .../model-data/define-geospatial-object.rst | 2 +- .../model-data/define-object-model.rst | 3 +- .../model-data/define-realm-object.rst | 5 +- source/sdk/model-data/object-models.txt | 6 +- 15 files changed, 190 insertions(+), 10 deletions(-) rename source/includes/api-details/cpp/model-data/{object-models-define-geospatial-model-not-supported.rst => object-models-define-geospatial-object-not-supported.rst} (100%) create mode 100644 source/includes/api-details/dart/model-data/object-models-define-asymmetric-object-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-define-embedded-object-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-define-geospatial-object-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-define-realm-object-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-define-sdk-object-model.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-object-model-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-object-schema-description.rst 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/includes/api-details/cpp/model-data/object-models-define-geospatial-model-not-supported.rst b/source/includes/api-details/cpp/model-data/object-models-define-geospatial-object-not-supported.rst similarity index 100% rename from source/includes/api-details/cpp/model-data/object-models-define-geospatial-model-not-supported.rst rename to source/includes/api-details/cpp/model-data/object-models-define-geospatial-object-not-supported.rst 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..4a590f5b7b --- /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 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-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.rst b/source/includes/api-details/dart/model-data/object-models-define-sdk-object-model.rst new file mode 100644 index 0000000000..e8bdf4340a --- /dev/null +++ b/source/includes/api-details/dart/model-data/object-models-define-sdk-object-model.rst @@ -0,0 +1,109 @@ +.. procedure:: + + .. step:: Import the SDK + + Import the Realm SDK package at the top of your file. + + .. tabs:: + + .. tab:: Flutter + :tabid: flutter + + .. code-block:: dart + :caption: modelFile.dart + + import 'package:realm/realm.dart'; + + .. tab:: Dart + :tabid: dart + + .. code-block:: dart + :caption: modelFile.dart + + import 'package:realm_dart/realm.dart'; + + .. step:: 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 + + .. step:: Create 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 + + .. step:: Generate 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 + + .. step:: Use RealmObject in Application + + Use the ``RealmObject`` that you generated in the previous step in your application. + 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-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/sdk-examples/model-data/define-asymmetric-object.rst b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst index 13cbd7892b..f4d34a3efc 100644 --- a/source/includes/sdk-examples/model-data/define-asymmetric-object.rst +++ b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst @@ -16,8 +16,9 @@ - id: dart content: | - .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart + .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.asymmetric-sync-object.dart :language: dart + :emphasize-lines: 1 - id: java content: | diff --git a/source/includes/sdk-examples/model-data/define-embedded-object.rst b/source/includes/sdk-examples/model-data/define-embedded-object.rst index a8a9d7ec89..009ef56294 100644 --- a/source/includes/sdk-examples/model-data/define-embedded-object.rst +++ b/source/includes/sdk-examples/model-data/define-embedded-object.rst @@ -6,7 +6,7 @@ .. literalinclude:: /examples/generated/cpp/crud.snippet.model-with-embedded-object.cpp :language: cpp - :emphasize-lines: 7, 12 + :emphasize-lines: 8, 13 - id: csharp content: | @@ -17,7 +17,7 @@ - id: dart content: | - .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart + .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.embedded-object-model.dart :language: dart - id: java diff --git a/source/includes/sdk-examples/model-data/define-geospatial-object.rst b/source/includes/sdk-examples/model-data/define-geospatial-object.rst index a1204ad8e1..48157b1f01 100644 --- a/source/includes/sdk-examples/model-data/define-geospatial-object.rst +++ b/source/includes/sdk-examples/model-data/define-geospatial-object.rst @@ -18,7 +18,7 @@ - id: dart content: | - .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart + .. literalinclude:: /examples/generated/flutter/geospatial_data_test.snippet.use-geopoint-class.dart :language: dart - id: java diff --git a/source/includes/sdk-examples/model-data/define-object-model.rst b/source/includes/sdk-examples/model-data/define-object-model.rst index 2223abd998..14bf5e03a5 100644 --- a/source/includes/sdk-examples/model-data/define-object-model.rst +++ b/source/includes/sdk-examples/model-data/define-object-model.rst @@ -16,8 +16,9 @@ - id: dart content: | - .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart + .. literalinclude:: /examples/generated/flutter/define_realm_object_schema_usage_test.snippet.use-realm-object.dart :language: dart + :caption: myapp.dart - id: java content: | diff --git a/source/includes/sdk-examples/model-data/define-realm-object.rst b/source/includes/sdk-examples/model-data/define-realm-object.rst index 491031318d..76b3ddc0e2 100644 --- a/source/includes/sdk-examples/model-data/define-realm-object.rst +++ b/source/includes/sdk-examples/model-data/define-realm-object.rst @@ -16,7 +16,10 @@ - id: dart content: | - .. literalinclude:: /examples/generated/flutter/data_ingest.test.snippet.write-asymmetric-object.dart + .. 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 diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 9ea98f27dd..bd78cf6c98 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -19,7 +19,7 @@ Define an SDK Object Model .. contents:: On this page :local: :backlinks: none - :depth: 3 + :depth: 2 :class: singlecol .. tabs-selector:: drivers @@ -141,7 +141,7 @@ or establishing other special behaviors for specific fields in your object. .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/dart/model-data/object-models-object-model-description.rst .. tab:: :tabid: java @@ -204,7 +204,7 @@ abstract away the process of creating a schema. .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/dart/model-data/object-models-object-schema-description.rst .. tab:: :tabid: java From 43e9170e1e33fda82ab335f3de565b53964e43de Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 28 Jun 2024 14:29:18 -0400 Subject: [PATCH 05/36] Update Dart include paths --- source/sdk/model-data/object-models.txt | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index bd78cf6c98..1b1283989a 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -261,7 +261,7 @@ Define an SDK Object Model .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/dart/model-data/object-models-define-sdk-object-model-description.rst .. tab:: :tabid: java @@ -344,7 +344,7 @@ layer, Realm. .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/dart/model-data/object-models-define-realm-object-description.rst .. tab:: :tabid: java @@ -418,7 +418,7 @@ relationship, in which the related objects have independent lifecycles. .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/dart/model-data/object-models-define-embedded-object-description.rst .. tab:: :tabid: java @@ -503,7 +503,7 @@ For more information, see: :ref:`Create an Asymmetric Object .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/dart/model-data/object-models-define-asymmetric-object-description.rst .. tab:: :tabid: java @@ -565,7 +565,7 @@ To persist ``GeoPoint`` data, it must conform to the .. tab:: :tabid: dart - .. include:: /includes/api-details/dart/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/dart/model-data/object-models-define-geospatial-object-description.rst .. tab:: :tabid: java From 3ef2481933c9a68dcc7e47a97d4c43d579478a39 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 28 Jun 2024 16:38:46 -0400 Subject: [PATCH 06/36] Add Java SDK object model and schema information --- ...s-define-sdk-object-model-description.rst} | 0 ...define-asymmetric-object-not-supported.rst | 2 + ...efine-embedded-object-java-description.rst | 10 +++++ ...ine-embedded-object-kotlin-description.rst | 10 +++++ ...define-geospatial-object-not-supported.rst | 2 + ...models-define-realm-object-description.rst | 3 ++ ...fine-sdk-object-model-java-description.rst | 38 ++++++++++++++++ ...ne-sdk-object-model-kotlin-description.rst | 39 ++++++++++++++++ ...object-models-object-model-description.rst | 45 +++++++++++++++++++ ...bject-models-object-schema-description.rst | 2 + .../model-data/define-asymmetric-object.rst | 2 +- .../model-data/define-embedded-object.rst | 6 +-- .../model-data/define-geospatial-object.rst | 2 +- .../model-data/define-object-model.rst | 4 +- .../model-data/define-realm-object.rst | 10 +++-- source/sdk/model-data/object-models.txt | 28 ++++++------ 16 files changed, 177 insertions(+), 26 deletions(-) rename source/includes/api-details/dart/model-data/{object-models-define-sdk-object-model.rst => object-models-define-sdk-object-model-description.rst} (100%) create mode 100644 source/includes/api-details/java/model-data/object-models-define-asymmetric-object-not-supported.rst create mode 100644 source/includes/api-details/java/model-data/object-models-define-embedded-object-java-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-define-embedded-object-kotlin-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-define-geospatial-object-not-supported.rst create mode 100644 source/includes/api-details/java/model-data/object-models-define-realm-object-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-define-sdk-object-model-java-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-define-sdk-object-model-kotlin-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-object-model-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-object-schema-description.rst diff --git a/source/includes/api-details/dart/model-data/object-models-define-sdk-object-model.rst b/source/includes/api-details/dart/model-data/object-models-define-sdk-object-model-description.rst similarity index 100% rename from source/includes/api-details/dart/model-data/object-models-define-sdk-object-model.rst rename to source/includes/api-details/dart/model-data/object-models-define-sdk-object-model-description.rst 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-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..e8f21a896c --- /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 +Realm 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 Realm 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-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/sdk-examples/model-data/define-asymmetric-object.rst b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst index f4d34a3efc..91acc62b1f 100644 --- a/source/includes/sdk-examples/model-data/define-asymmetric-object.rst +++ b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst @@ -29,7 +29,7 @@ - id: java-kotlin content: | - .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt :language: kotlin - id: javascript diff --git a/source/includes/sdk-examples/model-data/define-embedded-object.rst b/source/includes/sdk-examples/model-data/define-embedded-object.rst index 009ef56294..e6e28c027f 100644 --- a/source/includes/sdk-examples/model-data/define-embedded-object.rst +++ b/source/includes/sdk-examples/model-data/define-embedded-object.rst @@ -23,14 +23,12 @@ - id: java content: | - .. literalinclude:: /examples/MissingPlaceholders/api.java - :language: java + .. include:: /examples/generated/java/local/FrogEmbeddedExample.snippet.complete.java.rst - id: java-kotlin content: | - .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt - :language: kotlin + .. include:: /examples/generated/java/local/FrogEmbeddedExampleKt.snippet.complete.kt.rst - id: javascript content: | diff --git a/source/includes/sdk-examples/model-data/define-geospatial-object.rst b/source/includes/sdk-examples/model-data/define-geospatial-object.rst index 48157b1f01..c8009b286c 100644 --- a/source/includes/sdk-examples/model-data/define-geospatial-object.rst +++ b/source/includes/sdk-examples/model-data/define-geospatial-object.rst @@ -30,7 +30,7 @@ - id: java-kotlin content: | - .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt :language: kotlin - id: javascript diff --git a/source/includes/sdk-examples/model-data/define-object-model.rst b/source/includes/sdk-examples/model-data/define-object-model.rst index 14bf5e03a5..af9ce339b5 100644 --- a/source/includes/sdk-examples/model-data/define-object-model.rst +++ b/source/includes/sdk-examples/model-data/define-object-model.rst @@ -23,13 +23,13 @@ - id: java content: | - .. literalinclude:: /examples/MissingPlaceholders/api.java + .. literalinclude:: /examples/generated/java/local/RealmObjectVsRealmModelTest.snippet.realm-object-vs-realm-model.java :language: java - id: java-kotlin content: | - .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt + .. literalinclude:: /examples/generated/java/local/RealmObjectVsRealmModelTest.snippet.realm-object-vs-realm-model.kt :language: kotlin - id: javascript diff --git a/source/includes/sdk-examples/model-data/define-realm-object.rst b/source/includes/sdk-examples/model-data/define-realm-object.rst index 76b3ddc0e2..51f9a3b794 100644 --- a/source/includes/sdk-examples/model-data/define-realm-object.rst +++ b/source/includes/sdk-examples/model-data/define-realm-object.rst @@ -25,14 +25,16 @@ - id: java content: | - .. literalinclude:: /examples/MissingPlaceholders/api.java - :language: java + .. include:: /examples/generated/java/local/FrogObjectExample.snippet.complete.java.rst + + .. include:: /examples/generated/java/local/FrogRealmModelExample.snippet.complete.java.rst - id: java-kotlin content: | - .. literalinclude:: /examples/MissingPlaceholders/example-java-kotlin.kt - :language: kotlin + .. include:: /examples/generated/java/local/FrogObjectExampleKt.snippet.complete.kt.rst + + .. include:: /examples/generated/java/local/FrogRealmModelExampleKt.snippet.complete.kt.rst - id: javascript content: | diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 1b1283989a..a3a6fed28f 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -146,12 +146,12 @@ or establishing other special behaviors for specific fields in your object. .. tab:: :tabid: java - .. include:: /includes/api-details/java/model-data/object-models-database-schema-description.rst + .. 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-database-schema-description.rst + .. include:: /includes/api-details/java/model-data/object-models-object-model-description.rst .. tab:: :tabid: javascript @@ -209,12 +209,12 @@ abstract away the process of creating a schema. .. tab:: :tabid: java - .. include:: /includes/api-details/java/model-data/object-models-database-schema-description.rst + .. 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-database-schema-description.rst + .. include:: /includes/api-details/java/model-data/object-models-object-schema-description.rst .. tab:: :tabid: javascript @@ -266,12 +266,12 @@ Define an SDK Object Model .. tab:: :tabid: java - .. include:: /includes/api-details/java/model-data/object-models-database-schema-description.rst + .. 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-database-schema-description.rst + .. include:: /includes/api-details/java/model-data/object-models-define-sdk-object-model-kotlin-description.rst .. tab:: :tabid: javascript @@ -349,12 +349,12 @@ layer, Realm. .. tab:: :tabid: java - .. include:: /includes/api-details/java/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/java/model-data/object-models-define-realm-object-java-description.rst .. tab:: :tabid: java-kotlin - .. include:: /includes/api-details/java/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/java/model-data/object-models-define-realm-object-kotlin-description.rst .. tab:: :tabid: javascript @@ -423,12 +423,12 @@ relationship, in which the related objects have independent lifecycles. .. tab:: :tabid: java - .. include:: /includes/api-details/java/model-data/object-models-database-schema-description.rst + .. 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-database-schema-description.rst + .. include:: /includes/api-details/java/model-data/object-models-define-embedded-object-kotlin-description.rst .. tab:: :tabid: javascript @@ -508,12 +508,12 @@ For more information, see: :ref:`Create an Asymmetric Object .. tab:: :tabid: java - .. include:: /includes/api-details/java/model-data/object-models-database-schema-description.rst + .. 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-database-schema-description.rst + .. include:: /includes/api-details/java/model-data/object-models-define-asymmetric-object-not-supported.rst .. tab:: :tabid: javascript @@ -570,12 +570,12 @@ To persist ``GeoPoint`` data, it must conform to the .. tab:: :tabid: java - .. include:: /includes/api-details/java/model-data/object-models-database-schema-description.rst + .. 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-database-schema-description.rst + .. include:: /includes/api-details/java/model-data/object-models-define-geospatial-object-not-supported.rst .. tab:: :tabid: javascript From 84466005565d767cb704fe030e349bdde746cd32 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 28 Jun 2024 17:49:31 -0400 Subject: [PATCH 07/36] Add (incomplete) JS and TS object model and schema information --- ...s-define-asymmetric-object-description.rst | 2 ++ ...fine-embedded-object-js-ts-description.rst | 3 ++ ...s-define-geospatial-object-description.rst | 34 +++++++++++++++++++ ...object-models-object-model-description.rst | 13 +++++++ ...models-object-schema-js-ts-description.rst | 12 +++++++ ...s-define-asymmetric-object-description.rst | 2 ++ ...s-define-geospatial-object-description.rst | 34 +++++++++++++++++++ ...object-models-object-model-description.rst | 13 +++++++ .../model-data/define-asymmetric-object.rst | 6 ++-- .../model-data/define-embedded-object.rst | 6 ++-- .../model-data/define-geospatial-object.rst | 4 +-- .../model-data/define-object-model.rst | 6 ++-- .../model-data/define-realm-object.rst | 6 ++-- source/sdk/model-data/object-models.txt | 31 +++++++---------- 14 files changed, 140 insertions(+), 32 deletions(-) create mode 100644 source/includes/api-details/javascript/model-data/object-models-define-asymmetric-object-description.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-define-embedded-object-js-ts-description.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-define-geospatial-object-description.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-object-model-description.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-object-schema-js-ts-description.rst create mode 100644 source/includes/api-details/typescript/model-data/object-models-define-asymmetric-object-description.rst create mode 100644 source/includes/api-details/typescript/model-data/object-models-define-geospatial-object-description.rst create mode 100644 source/includes/api-details/typescript/model-data/object-models-object-model-description.rst 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..f814fb35e7 --- /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 Node.js 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..6f59ed38b4 --- /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 realm 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-object-model-description.rst b/source/includes/api-details/javascript/model-data/object-models-object-model-description.rst new file mode 100644 index 0000000000..ee1aae23c4 --- /dev/null +++ b/source/includes/api-details/javascript/model-data/object-models-object-model-description.rst @@ -0,0 +1,13 @@ +You can define SDK models as JavaScript classes that extend ``Realm.Object`` +(like most of the examples on this page). Or you can define models as +JavaScript objects. + +When you define models as JavaScript classes that extend ``Realm.Object``, +you can pass those model objects directly to the database. Prefer this approach +when possible. + +If you do define a model that does not extend ``Realm.Object``, you cannot pass +the model directly to the database. Instead, you pass only the schema to the +database that manages the object. + +.. TODO: Provide more info about why you would choose one of these approaches over the other 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/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..a5d6e9def0 --- /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 realm 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-object-model-description.rst b/source/includes/api-details/typescript/model-data/object-models-object-model-description.rst new file mode 100644 index 0000000000..f7f981d261 --- /dev/null +++ b/source/includes/api-details/typescript/model-data/object-models-object-model-description.rst @@ -0,0 +1,13 @@ +You can define SDK models as TypeScript classes that extend ``Realm.Object`` +(like most of the examples on this page). Or you can define models as +TypeScript objects. + +When you define models as TypeScript classes that extend ``Realm.Object``, +you can pass those model objects directly to the database. Prefer this approach +when possible. + +If you do define a model that does not extend ``Realm.Object``, you cannot pass +the model directly to the database. Instead, you pass only the schema to the +database that manages the object. + +.. TODO: Provide more info about why you would choose one of these approaches over the other diff --git a/source/includes/sdk-examples/model-data/define-asymmetric-object.rst b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst index 91acc62b1f..2d83a2fc6c 100644 --- a/source/includes/sdk-examples/model-data/define-asymmetric-object.rst +++ b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst @@ -35,8 +35,9 @@ - id: javascript content: | - .. literalinclude:: /examples/MissingPlaceholders/example.js + .. literalinclude:: /examples/generated/react-native/js/data-ingest.test.snippet.data-ingest-object.jsx :language: javascript + :emphasize-lines: 6 - id: kotlin content: | @@ -60,5 +61,6 @@ - id: typescript content: | - .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts + .. 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/define-embedded-object.rst b/source/includes/sdk-examples/model-data/define-embedded-object.rst index e6e28c027f..cd143ea2d2 100644 --- a/source/includes/sdk-examples/model-data/define-embedded-object.rst +++ b/source/includes/sdk-examples/model-data/define-embedded-object.rst @@ -33,8 +33,9 @@ - id: javascript content: | - .. literalinclude:: /examples/MissingPlaceholders/example.js + .. literalinclude:: /examples/generated/node/data-types.snippet.define-embedded-objects.js :language: javascript + :emphasize-lines: 3, 18, 28 - id: kotlin content: | @@ -58,5 +59,4 @@ - id: typescript content: | - .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts - :language: typescript + .. include:: /examples/generated/react-native/v12/models.snippet.define-embedded-property.ts.rst diff --git a/source/includes/sdk-examples/model-data/define-geospatial-object.rst b/source/includes/sdk-examples/model-data/define-geospatial-object.rst index c8009b286c..1b0abdfc22 100644 --- a/source/includes/sdk-examples/model-data/define-geospatial-object.rst +++ b/source/includes/sdk-examples/model-data/define-geospatial-object.rst @@ -36,7 +36,7 @@ - id: javascript content: | - .. literalinclude:: /examples/MissingPlaceholders/example.js + .. literalinclude:: /examples/generated/node/v12/geospatial.test.snippet.write-geospatial-object.js :language: javascript - id: kotlin @@ -61,5 +61,5 @@ - id: typescript content: | - .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts + .. literalinclude:: /examples/generated/node/v12/geospatial.test.snippet.write-geospatial-object.ts :language: typescript diff --git a/source/includes/sdk-examples/model-data/define-object-model.rst b/source/includes/sdk-examples/model-data/define-object-model.rst index af9ce339b5..b5a1495b38 100644 --- a/source/includes/sdk-examples/model-data/define-object-model.rst +++ b/source/includes/sdk-examples/model-data/define-object-model.rst @@ -35,7 +35,7 @@ - id: javascript content: | - .. literalinclude:: /examples/MissingPlaceholders/example.js + .. literalinclude:: /examples/generated/react-native/js/Book.snippet.js-book-schema.js :language: javascript - id: kotlin @@ -60,5 +60,5 @@ - id: typescript content: | - .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts - :language: typescript + .. literalinclude:: /examples/generated/react-native/ts/Book.snippet.ts-book-schema.ts + :language: javascript diff --git a/source/includes/sdk-examples/model-data/define-realm-object.rst b/source/includes/sdk-examples/model-data/define-realm-object.rst index 51f9a3b794..73f5e238e3 100644 --- a/source/includes/sdk-examples/model-data/define-realm-object.rst +++ b/source/includes/sdk-examples/model-data/define-realm-object.rst @@ -39,7 +39,7 @@ - id: javascript content: | - .. literalinclude:: /examples/MissingPlaceholders/example.js + .. literalinclude:: /examples/generated/react-native/js/Book.snippet.js-book-schema.js :language: javascript - id: kotlin @@ -64,5 +64,5 @@ - id: typescript content: | - .. literalinclude:: /examples/generated/node/asymmetric-sync.snippet.write-asymmetric-object.ts - :language: typescript + .. literalinclude:: /examples/generated/react-native/ts/Book.snippet.ts-book-schema.ts + :language: javascript diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index a3a6fed28f..e68d0ec3ae 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -156,7 +156,7 @@ or establishing other special behaviors for specific fields in your object. .. tab:: :tabid: javascript - .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst + .. include:: /includes/api-details/javascript/model-data/object-models-object-model-description.rst .. tab:: :tabid: kotlin @@ -176,7 +176,7 @@ or establishing other special behaviors for specific fields in your object. .. tab:: :tabid: typescript - .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst + .. include:: /includes/api-details/typescript/model-data/object-models-object-model-description.rst .. _sdks-object-schema: @@ -219,7 +219,7 @@ abstract away the process of creating a schema. .. tab:: :tabid: javascript - .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst + .. include:: /includes/api-details/javascript/model-data/object-models-object-schema-js-ts-description.rst .. tab:: :tabid: kotlin @@ -239,7 +239,7 @@ abstract away the process of creating a schema. .. tab:: :tabid: typescript - .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst + .. include:: /includes/api-details/javascript/model-data/object-models-object-schema-js-ts-description.rst .. _sdks-define-objects: @@ -276,8 +276,6 @@ Define an SDK Object Model .. tab:: :tabid: javascript - .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst - .. tab:: :tabid: kotlin @@ -296,7 +294,6 @@ Define an SDK Object Model .. tab:: :tabid: typescript - .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst .. include:: /includes/sdk-examples/model-data/define-object-model.rst @@ -349,18 +346,16 @@ layer, Realm. .. tab:: :tabid: java - .. include:: /includes/api-details/java/model-data/object-models-define-realm-object-java-description.rst + .. 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-kotlin-description.rst + .. 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-database-schema-js-ts-description.rst - .. tab:: :tabid: kotlin @@ -379,8 +374,6 @@ layer, Realm. .. tab:: :tabid: typescript - .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst - .. include:: /includes/sdk-examples/model-data/define-realm-object.rst .. _sdks-embedded-objects: @@ -433,7 +426,7 @@ relationship, in which the related objects have independent lifecycles. .. tab:: :tabid: javascript - .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst + .. include:: /includes/api-details/javascript/model-data/object-models-define-embedded-object-js-ts-description.rst .. tab:: :tabid: kotlin @@ -453,7 +446,7 @@ relationship, in which the related objects have independent lifecycles. .. tab:: :tabid: typescript - .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst + .. include:: /includes/api-details/javascript/model-data/object-models-define-embedded-object-js-ts-description.rst .. include:: /includes/sdk-examples/model-data/define-embedded-object.rst @@ -518,7 +511,7 @@ For more information, see: :ref:`Create an Asymmetric Object .. tab:: :tabid: javascript - .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst + .. include:: /includes/api-details/javascript/model-data/object-models-define-asymmetric-object-description.rst .. tab:: :tabid: kotlin @@ -538,7 +531,7 @@ For more information, see: :ref:`Create an Asymmetric Object .. tab:: :tabid: typescript - .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst + .. include:: /includes/api-details/typescript/model-data/object-models-define-asymmetric-object-description.rst .. include:: /includes/sdk-examples/model-data/define-asymmetric-object.rst @@ -580,7 +573,7 @@ To persist ``GeoPoint`` data, it must conform to the .. tab:: :tabid: javascript - .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst + .. include:: /includes/api-details/javascript/model-data/object-models-define-geospatial-object-description.rst .. tab:: :tabid: kotlin @@ -600,7 +593,7 @@ To persist ``GeoPoint`` data, it must conform to the .. tab:: :tabid: typescript - .. include:: /includes/api-details/javascript/model-data/object-models-database-schema-js-ts-description.rst + .. include:: /includes/api-details/typescript/model-data/object-models-define-geospatial-object-description.rst .. include:: /includes/sdk-examples/model-data/define-geospatial-object.rst From 2eefb50ad790747c786d6f2fd7e7d865929c3c61 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 28 Jun 2024 18:13:28 -0400 Subject: [PATCH 08/36] Add Kotlin object model and schema information --- ...s-define-asymmetric-object-description.rst | 3 +++ ...els-define-embedded-object-description.rst | 4 +++ ...s-define-geospatial-object-description.rst | 26 +++++++++++++++++++ ...models-define-realm-object-description.rst | 3 +++ ...ct-models-define-sdk-model-description.rst | 25 ++++++++++++++++++ ...object-models-object-model-description.rst | 2 ++ ...bject-models-object-schema-description.rst | 4 +++ .../model-data/define-asymmetric-object.rst | 3 +-- .../model-data/define-embedded-object.rst | 3 +-- .../model-data/define-geospatial-object.rst | 4 +-- .../model-data/define-object-model.rst | 3 +-- .../model-data/define-realm-object.rst | 3 +-- source/sdk/model-data/object-models.txt | 14 +++++----- 13 files changed, 80 insertions(+), 17 deletions(-) create mode 100644 source/includes/api-details/kotlin/model-data/object-models-define-asymmetric-object-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-define-embedded-object-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-define-geospatial-object-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-define-realm-object-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-define-sdk-model-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-object-model-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-object-schema-description.rst 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..947671fbd7 --- /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-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..025872afe0 --- /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 realm 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-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-model-description.rst b/source/includes/api-details/kotlin/model-data/object-models-define-sdk-model-description.rst new file mode 100644 index 0000000000..67baca51f4 --- /dev/null +++ b/source/includes/api-details/kotlin/model-data/object-models-define-sdk-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-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/sdk-examples/model-data/define-asymmetric-object.rst b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst index 2d83a2fc6c..dee0ca73a4 100644 --- a/source/includes/sdk-examples/model-data/define-asymmetric-object.rst +++ b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst @@ -42,9 +42,8 @@ - id: kotlin content: | - .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt + .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-asymmetric-model.kt :language: kotlin - :emphasize-lines: 10, 11 - id: objectivec content: | diff --git a/source/includes/sdk-examples/model-data/define-embedded-object.rst b/source/includes/sdk-examples/model-data/define-embedded-object.rst index cd143ea2d2..abc1ddfd60 100644 --- a/source/includes/sdk-examples/model-data/define-embedded-object.rst +++ b/source/includes/sdk-examples/model-data/define-embedded-object.rst @@ -40,9 +40,8 @@ - id: kotlin content: | - .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt + .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-embedded-object.kt :language: kotlin - :emphasize-lines: 10, 11 - id: objectivec content: | diff --git a/source/includes/sdk-examples/model-data/define-geospatial-object.rst b/source/includes/sdk-examples/model-data/define-geospatial-object.rst index 1b0abdfc22..1de3ca1adf 100644 --- a/source/includes/sdk-examples/model-data/define-geospatial-object.rst +++ b/source/includes/sdk-examples/model-data/define-geospatial-object.rst @@ -42,9 +42,9 @@ - id: kotlin content: | - .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt + .. literalinclude:: /examples/generated/kotlin/Geospatial.snippet.geopoint-model.kt :language: kotlin - :emphasize-lines: 10, 11 + :emphasize-lines: 4 - id: objectivec content: | diff --git a/source/includes/sdk-examples/model-data/define-object-model.rst b/source/includes/sdk-examples/model-data/define-object-model.rst index b5a1495b38..3099589673 100644 --- a/source/includes/sdk-examples/model-data/define-object-model.rst +++ b/source/includes/sdk-examples/model-data/define-object-model.rst @@ -41,9 +41,8 @@ - id: kotlin content: | - .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt + .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-realm-object.kt :language: kotlin - :emphasize-lines: 10, 11 - id: objectivec content: | diff --git a/source/includes/sdk-examples/model-data/define-realm-object.rst b/source/includes/sdk-examples/model-data/define-realm-object.rst index 73f5e238e3..86dc13dfa0 100644 --- a/source/includes/sdk-examples/model-data/define-realm-object.rst +++ b/source/includes/sdk-examples/model-data/define-realm-object.rst @@ -45,9 +45,8 @@ - id: kotlin content: | - .. literalinclude:: /examples/generated/kotlin/AsymmetricSyncTest.snippet.create-asymmetric-object.kt + .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-realm-object.kt :language: kotlin - :emphasize-lines: 10, 11 - id: objectivec content: | diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index e68d0ec3ae..84b4b5d58a 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -161,7 +161,7 @@ or establishing other special behaviors for specific fields in your object. .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/kotlin/model-data/object-models-object-model-description.rst .. tab:: :tabid: objectivec @@ -224,7 +224,7 @@ abstract away the process of creating a schema. .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/kotlin/model-data/object-models-object-schema-description.rst .. tab:: :tabid: objectivec @@ -279,7 +279,7 @@ Define an SDK Object Model .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/kotlin/model-data/object-models-define-sdk-object-model-description.rst .. tab:: :tabid: objectivec @@ -359,7 +359,7 @@ layer, Realm. .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/kotlin/model-data/object-models-define-realm-object-description.rst .. tab:: :tabid: objectivec @@ -431,7 +431,7 @@ relationship, in which the related objects have independent lifecycles. .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/kotlin/model-data/object-models-define-embedded-object-description.rst .. tab:: :tabid: objectivec @@ -516,7 +516,7 @@ For more information, see: :ref:`Create an Asymmetric Object .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/kotlin/model-data/object-models-define-asymmetric-object-description.rst .. tab:: :tabid: objectivec @@ -578,7 +578,7 @@ To persist ``GeoPoint`` data, it must conform to the .. tab:: :tabid: kotlin - .. include:: /includes/api-details/kotlin/model-data/object-models-database-schema-description.rst + .. include:: /includes/api-details/kotlin/model-data/object-models-define-geospatial-object-description.rst .. tab:: :tabid: objectivec From 7102a45a4e5b0e61f157eb70262a171303b16757 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 28 Jun 2024 20:22:52 -0400 Subject: [PATCH 09/36] Add Swift and Objective-C object model and schema information --- ...s-define-sdk-object-model-description.rst} | 0 ...s-define-asymmetric-object-description.rst | 14 +++++ ...els-define-embedded-object-description.rst | 3 ++ ...s-define-geospatial-object-description.rst | 3 ++ ...models-define-realm-object-description.rst | 2 + ...ls-define-sdk-object-model-description.rst | 10 ++++ ...object-models-object-model-description.rst | 21 ++++++++ ...s-define-asymmetric-object-description.rst | 14 +++++ ...els-define-embedded-object-description.rst | 3 ++ ...s-define-geospatial-object-description.rst | 12 +++++ ...models-define-realm-object-description.rst | 2 + ...ls-define-sdk-object-model-description.rst | 10 ++++ ...object-models-object-model-description.rst | 51 +++++++++++++++++++ ...bject-models-object-schema-description.rst | 7 +++ .../model-data/define-asymmetric-object.rst | 2 +- .../model-data/define-embedded-object.rst | 4 +- .../model-data/define-geospatial-object.rst | 3 +- .../model-data/define-object-model.rst | 4 +- .../model-data/define-realm-object.rst | 4 +- source/sdk/model-data/object-models.txt | 28 +++++----- 20 files changed, 175 insertions(+), 22 deletions(-) rename source/includes/api-details/kotlin/model-data/{object-models-define-sdk-model-description.rst => object-models-define-sdk-object-model-description.rst} (100%) create mode 100644 source/includes/api-details/objectivec/model-data/object-models-define-asymmetric-object-description.rst create mode 100644 source/includes/api-details/objectivec/model-data/object-models-define-embedded-object-description.rst create mode 100644 source/includes/api-details/objectivec/model-data/object-models-define-geospatial-object-description.rst create mode 100644 source/includes/api-details/objectivec/model-data/object-models-define-realm-object-description.rst create mode 100644 source/includes/api-details/objectivec/model-data/object-models-define-sdk-object-model-description.rst create mode 100644 source/includes/api-details/objectivec/model-data/object-models-object-model-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-define-asymmetric-object-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-define-embedded-object-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-define-geospatial-object-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-define-realm-object-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-define-sdk-object-model-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-object-model-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-object-schema-description.rst diff --git a/source/includes/api-details/kotlin/model-data/object-models-define-sdk-model-description.rst b/source/includes/api-details/kotlin/model-data/object-models-define-sdk-object-model-description.rst similarity index 100% rename from source/includes/api-details/kotlin/model-data/object-models-define-sdk-model-description.rst rename to source/includes/api-details/kotlin/model-data/object-models-define-sdk-object-model-description.rst 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-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-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-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-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-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/sdk-examples/model-data/define-asymmetric-object.rst b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst index dee0ca73a4..f8380cabe2 100644 --- a/source/includes/sdk-examples/model-data/define-asymmetric-object.rst +++ b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst @@ -54,7 +54,7 @@ - id: swift content: | - .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.asymmetric-model.swift :language: swift - id: typescript diff --git a/source/includes/sdk-examples/model-data/define-embedded-object.rst b/source/includes/sdk-examples/model-data/define-embedded-object.rst index abc1ddfd60..d75300b8d3 100644 --- a/source/includes/sdk-examples/model-data/define-embedded-object.rst +++ b/source/includes/sdk-examples/model-data/define-embedded-object.rst @@ -46,13 +46,13 @@ - id: objectivec content: | - .. literalinclude:: /examples/MissingPlaceholders/example.m + .. literalinclude:: /examples/generated/code/start/EmbeddedObjects.snippet.models.m :language: objectivec - id: swift content: | - .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + .. literalinclude:: /examples/generated/code/start/ReadRealmObjects.snippet.embedded-object-models.swift :language: swift - id: typescript diff --git a/source/includes/sdk-examples/model-data/define-geospatial-object.rst b/source/includes/sdk-examples/model-data/define-geospatial-object.rst index 1de3ca1adf..be1892155f 100644 --- a/source/includes/sdk-examples/model-data/define-geospatial-object.rst +++ b/source/includes/sdk-examples/model-data/define-geospatial-object.rst @@ -55,8 +55,9 @@ - id: swift content: | - .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + .. literalinclude:: /examples/generated/code/start/Geospatial.snippet.custom-geopoint.swift :language: swift + :emphasize-lines: 2-3 - id: typescript content: | diff --git a/source/includes/sdk-examples/model-data/define-object-model.rst b/source/includes/sdk-examples/model-data/define-object-model.rst index 3099589673..d83376ef0d 100644 --- a/source/includes/sdk-examples/model-data/define-object-model.rst +++ b/source/includes/sdk-examples/model-data/define-object-model.rst @@ -47,13 +47,13 @@ - id: objectivec content: | - .. literalinclude:: /examples/MissingPlaceholders/example.m + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.define-a-model.m :language: objectivec - id: swift content: | - .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.define-a-model.swift :language: swift - id: typescript diff --git a/source/includes/sdk-examples/model-data/define-realm-object.rst b/source/includes/sdk-examples/model-data/define-realm-object.rst index 86dc13dfa0..2ccce35f58 100644 --- a/source/includes/sdk-examples/model-data/define-realm-object.rst +++ b/source/includes/sdk-examples/model-data/define-realm-object.rst @@ -51,13 +51,13 @@ - id: objectivec content: | - .. literalinclude:: /examples/MissingPlaceholders/example.m + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.define-a-model.m :language: objectivec - id: swift content: | - .. literalinclude:: /examples/generated/code/start/AsymmetricSync.snippet.create-asymmetric-object.swift + .. literalinclude:: /examples/generated/code/start/ObjectModels.snippet.define-a-model.swift :language: swift - id: typescript diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 84b4b5d58a..b91cb7c475 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -166,12 +166,12 @@ or establishing other special behaviors for specific fields in your object. .. tab:: :tabid: objectivec - .. include:: /includes/api-details/objectivec/model-data/object-models-database-schema-description.rst + .. 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-database-schema-description.rst + .. include:: /includes/api-details/swift/model-data/object-models-object-model-description.rst .. tab:: :tabid: typescript @@ -229,12 +229,12 @@ abstract away the process of creating a schema. .. tab:: :tabid: objectivec - .. include:: /includes/api-details/objectivec/model-data/object-models-database-schema-description.rst + .. 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-database-schema-description.rst + .. include:: /includes/api-details/swift/model-data/object-models-object-schema-description.rst .. tab:: :tabid: typescript @@ -284,12 +284,12 @@ Define an SDK Object Model .. tab:: :tabid: objectivec - .. include:: /includes/api-details/objectivec/model-data/object-models-database-schema-description.rst + .. 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-database-schema-description.rst + .. include:: /includes/api-details/swift/model-data/object-models-define-sdk-object-model-description.rst .. tab:: :tabid: typescript @@ -364,12 +364,12 @@ layer, Realm. .. tab:: :tabid: objectivec - .. include:: /includes/api-details/objectivec/model-data/object-models-database-schema-description.rst + .. 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-database-schema-description.rst + .. include:: /includes/api-details/swift/model-data/object-models-define-realm-object-description.rst .. tab:: :tabid: typescript @@ -436,12 +436,12 @@ relationship, in which the related objects have independent lifecycles. .. tab:: :tabid: objectivec - .. include:: /includes/api-details/objectivec/model-data/object-models-database-schema-description.rst + .. 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-database-schema-description.rst + .. include:: /includes/api-details/swift/model-data/object-models-define-embedded-object-description.rst .. tab:: :tabid: typescript @@ -521,12 +521,12 @@ For more information, see: :ref:`Create an Asymmetric Object .. tab:: :tabid: objectivec - .. include:: /includes/api-details/objectivec/model-data/object-models-database-schema-description.rst + .. 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-database-schema-description.rst + .. include:: /includes/api-details/swift/model-data/object-models-define-asymmetric-object-description.rst .. tab:: :tabid: typescript @@ -583,12 +583,12 @@ To persist ``GeoPoint`` data, it must conform to the .. tab:: :tabid: objectivec - .. include:: /includes/api-details/objectivec/model-data/object-models-database-schema-description.rst + .. 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-database-schema-description.rst + .. include:: /includes/api-details/swift/model-data/object-models-define-geospatial-object-description.rst .. tab:: :tabid: typescript From 507f0794c9109e6169c62e45f4e204ca1a97618d Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 28 Jun 2024 20:35:22 -0400 Subject: [PATCH 10/36] Remove headings from includes to avoid headings in OTP --- ...ls-define-sdk-object-model-description.rst | 3 +- ...ls-define-sdk-object-model-description.rst | 138 ++++++++---------- 2 files changed, 58 insertions(+), 83 deletions(-) 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 index 3e12fb3c29..e4a69f42ae 100644 --- 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 @@ -18,8 +18,7 @@ classes. .. literalinclude:: /examples/generated/dotnet/ObjectModelsAndSchemas.snippet.dog_class.cs :language: csharp -Customize the Object Schema (Optional) -`````````````````````````````````````` +**Customize the Object Schema (Optional)** You can use the :dotnet-sdk:`Schema ` 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 index e8bdf4340a..b7d6609c78 100644 --- 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 @@ -1,109 +1,85 @@ -.. procedure:: +1. Create Generated File Part Directive - .. step:: Import the SDK + .. versionchanged:: v2.0.0 + Generated files are named ``.realm.dart`` instead of ``.g.dart`` - Import the Realm SDK package at the top of your file. + 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. - .. tabs:: + .. literalinclude:: /examples/generated/flutter/schemas.snippet.part-directive.dart + :language: dart + :caption: modelFile.dart - .. tab:: Flutter - :tabid: flutter +2. Create a ``RealmModel``. - .. code-block:: dart - :caption: modelFile.dart + Create the model for your SDK object type. + You must include the annotation `RealmModel `__ + at the top of the class definition. - import 'package:realm/realm.dart'; + You'll use the ``RealmModel`` to generate the public ``RealmObject`` + used throughout the application in step 4. - .. tab:: Dart - :tabid: dart + 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. - .. code-block:: dart - :caption: modelFile.dart + 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. - import 'package:realm_dart/realm.dart'; + Add fields to the ``RealmModel``. + You can add fields of any :ref:`supported data types `. + Include additional behavior using :ref:`special object types + `. - .. step:: Create Generated File Part Directive + .. literalinclude:: /examples/generated/flutter/schemas.snippet.create-realm-model.dart + :language: dart + :caption: modelFile.dart - .. versionchanged:: v2.0.0 - Generated files are named ``.realm.dart`` instead of ``.g.dart`` +3. Generate a ``RealmObject``. - 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. + .. versionchanged:: v2.0.0 + Generated files are named ``.realm.dart`` instead of ``.g.dart`` - .. literalinclude:: /examples/generated/flutter/schemas.snippet.part-directive.dart - :language: dart - :caption: modelFile.dart + Generate the ``RealmObject``, which you'll use in your application: - .. step:: Create RealmModel + .. tabs:: - Create the model for your SDK object type. - You must include the annotation `RealmModel `__ - at the top of the class definition. + .. tab:: Flutter + :tabid: flutter - 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 - - .. step:: Generate 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:: + .. code-block:: - dart run realm generate + dart run realm generate - .. tab:: Dart - :tabid: dart + .. tab:: Dart + :tabid: dart - .. code-block:: + .. code-block:: - dart run realm_dart generate + 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. + 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 + .. tip:: Track the generated file - Track the generated file in your version control system, such as git. + Track the generated file in your version control system, such as git. - .. example:: File structure after generating model + .. example:: File structure after generating model - .. code-block:: + .. code-block:: - . - ├── modelFile.dart - ├── modelFile.realm.dart // newly generated file - ├── myapp.dart - └── ...rest of application + . + ├── modelFile.dart + ├── modelFile.realm.dart // newly generated file + ├── myapp.dart + └── ...rest of application - .. step:: Use RealmObject in Application +4. Use the ``RealmObject`` in your application code. - Use the ``RealmObject`` that you generated in the previous step in your application. - 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``. + 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``. From 5c5fe676569278b1fb51f24f00695d80bb7604a3 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Fri, 28 Jun 2024 20:41:11 -0400 Subject: [PATCH 11/36] Bold the object model for consistency in intro content --- source/sdk/model-data/object-models.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index b91cb7c475..bd1a680ade 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -119,7 +119,7 @@ For more information about how to open the database, refer to Object Model ~~~~~~~~~~~~ -Your object model is the core structure that gives the database +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 From 937dd9a1f745d0da45f2d1390865048e6ca1bee3 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 09:59:18 -0400 Subject: [PATCH 12/36] Add indexed property --- ...ct-models-index-property-not-supported.rst | 1 + ...ject-models-index-property-description.rst | 20 ++++ ...ject-models-index-property-description.rst | 13 +++ ...ject-models-index-property-description.rst | 15 +++ ...odels-index-property-js-ts-description.rst | 13 +++ ...ject-models-index-property-description.rst | 15 +++ ...ject-models-index-property-description.rst | 11 ++ ...ject-models-index-property-description.rst | 14 +++ .../model-data/define-index-property.rst | 63 +++++++++++ .../model-data/define-object-model.rst | 2 +- .../model-data/define-realm-object.rst | 2 +- source/sdk/model-data/object-models.txt | 102 ++++++++++++++++++ 12 files changed, 269 insertions(+), 2 deletions(-) create mode 100644 source/includes/api-details/cpp/model-data/object-models-index-property-not-supported.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-index-property-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-index-property-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-index-property-description.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-index-property-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-index-property-description.rst create mode 100644 source/includes/api-details/objectivec/model-data/object-models-index-property-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-index-property-description.rst create mode 100644 source/includes/sdk-examples/model-data/define-index-property.rst 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/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/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/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/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/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/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/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/sdk-examples/model-data/define-index-property.rst b/source/includes/sdk-examples/model-data/define-index-property.rst new file mode 100644 index 0000000000..8b79b5e941 --- /dev/null +++ b/source/includes/sdk-examples/model-data/define-index-property.rst @@ -0,0 +1,63 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + + - 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 diff --git a/source/includes/sdk-examples/model-data/define-object-model.rst b/source/includes/sdk-examples/model-data/define-object-model.rst index d83376ef0d..103e122266 100644 --- a/source/includes/sdk-examples/model-data/define-object-model.rst +++ b/source/includes/sdk-examples/model-data/define-object-model.rst @@ -60,4 +60,4 @@ content: | .. literalinclude:: /examples/generated/react-native/ts/Book.snippet.ts-book-schema.ts - :language: javascript + :language: typescript diff --git a/source/includes/sdk-examples/model-data/define-realm-object.rst b/source/includes/sdk-examples/model-data/define-realm-object.rst index 2ccce35f58..72618af10b 100644 --- a/source/includes/sdk-examples/model-data/define-realm-object.rst +++ b/source/includes/sdk-examples/model-data/define-realm-object.rst @@ -64,4 +64,4 @@ content: | .. literalinclude:: /examples/generated/react-native/ts/Book.snippet.ts-book-schema.ts - :language: javascript + :language: typescript diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index bd1a680ade..58555336e7 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -610,11 +610,113 @@ To persist ``GeoPoint`` data, it must conform to the Define Special Property Types ----------------------------- +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:`` section on this page. +- Indexes support more efficient match and range-based query operations. +- Indexes make insert and update operation speed slightly slower. + +.. note:: + + Adding an index speeds up queries at the cost of slightly slower write + times and additional storage and memory overhead. Indexes require space in + your database file. Adding an 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-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/define-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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +The SDK supports Full-Text Search (FTS) on string properties. You do this by + +When you query +a FTS property, an FTS index enables searching for multiple words and phrases and +excluding others. .. _sdks-optional-property-types: From 927b3c5a75a8c4f759fabd3ff359652ce003da2e Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 11:15:53 -0400 Subject: [PATCH 13/36] Add FTS details --- ...odels-fts-index-property-not-supported.rst | 1 + ...ls-define-sdk-object-model-description.rst | 2 +- ...-models-fts-index-property-description.rst | 4 + ...-models-fts-index-property-description.rst | 5 + ...odels-fts-index-property-not-supported.rst | 2 + ...s-fts-index-property-js-ts-description.rst | 3 + ...-models-fts-index-property-description.rst | 2 + ...ndex-property-swift-objc-not-supported.rst | 1 + .../includes/dotnet-implement-interface.rst | 2 +- .../model-data/define-fts-index-property.rst | 63 +++++++++ source/sdk/model-data/object-models.txt | 123 +++++++++++++++--- 11 files changed, 187 insertions(+), 21 deletions(-) create mode 100644 source/includes/api-details/cpp/model-data/object-models-fts-index-property-not-supported.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-fts-index-property-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-fts-index-property-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-fts-index-property-not-supported.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-fts-index-property-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-fts-index-property-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-fts-index-property-swift-objc-not-supported.rst create mode 100644 source/includes/sdk-examples/model-data/define-fts-index-property.rst 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/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 index e4a69f42ae..115ac6901a 100644 --- 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 @@ -10,7 +10,7 @@ In versions of the .NET SDK v10.18.0 and earlier, objects derive from :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. 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/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/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/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/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/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/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/sdk-examples/model-data/define-fts-index-property.rst b/source/includes/sdk-examples/model-data/define-fts-index-property.rst new file mode 100644 index 0000000000..d1f0cd2387 --- /dev/null +++ b/source/includes/sdk-examples/model-data/define-fts-index-property.rst @@ -0,0 +1,63 @@ +.. tabs-drivers:: + + tabs: + - id: cpp-sdk + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.cpp + :language: cpp + + - 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: | + + .. include:: /examples/MissingPlaceholders/api.java + + - id: java-kotlin + content: | + + .. include:: /examples/MissingPlaceholders/api-java-kotlin.kt + + - id: javascript + content: | + + .. literalinclude:: /examples/MissingPlaceholders/example.js + :language: javascript + + - id: kotlin + content: | + + .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-fts.kt + :language: kotlin + + - id: objectivec + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.m + :language: objectivec + + - id: swift + content: | + + .. literalinclude:: /examples/MissingPlaceholders/api.swift + :language: swift + + - 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/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 58555336e7..68e83d1f57 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -635,16 +635,15 @@ When indexing a property, keep in mind: - :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:`` section on this page. -- Indexes support more efficient match and range-based query operations. -- Indexes make insert and update operation speed slightly slower. + the :ref:`sdks-fts-property` section on this page. -.. note:: +Indexing a property makes some types of queries more efficient, but can slow +down writes and increase the size of the database file: - Adding an index speeds up queries at the cost of slightly slower write - times and additional storage and memory overhead. Indexes require space in - your database file. Adding an index to a property increases disk space - consumed by your database file. Each index entry is a minimum of 12 bytes. +- 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. .. tabs-drivers:: @@ -709,26 +708,112 @@ When indexing a property, keep in mind: .. _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. -When you query -a FTS property, an FTS index enables searching for multiple words and phrases and -excluding others. +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: -.. _sdks-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. -Define Optional Property Types -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. 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/define-fts-index-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. + +You may define a primary key on a **single property** for an object type. +The SDK automatically indexes primary key properties, which allows you to +efficiently read and modify objects based on their primary key. + +If an object type has a primary key, then all objects of that type must +include the primary key property with a value that is unique among +objects of the same type in the database. -.. _sdks-required-optional-property: +.. note:: + + Once you assign a property as a primary key, you cannot change it. + + +.. _sdks-optional-property-types: + +Define Optional Property Types +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Placeholder for .NET nullability info, and any other SDKs with similar APIs/requirements From 36dac9c360b4e8929149eee6145ffaf17b2dcdc3 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 12:26:48 -0400 Subject: [PATCH 14/36] Add info about primary keys --- ...dels-designate-primary-key-description.rst | 11 +++ ...dels-designate-primary-key-description.rst | 13 ++++ ...dels-designate-primary-key-description.rst | 10 +++ ...dels-designate-primary-key-description.rst | 13 ++++ ...esignate-primary-key-js-ts-description.rst | 5 ++ ...dels-designate-primary-key-description.rst | 14 ++++ ...dels-designate-primary-key-description.rst | 8 ++ ...dels-designate-primary-key-description.rst | 11 +++ .../define-primary-key-property.rst | 63 ++++++++++++++++ source/sdk/model-data/object-models.txt | 73 +++++++++++++++++-- 10 files changed, 213 insertions(+), 8 deletions(-) create mode 100644 source/includes/api-details/cpp/model-data/object-models-designate-primary-key-description.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-designate-primary-key-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-designate-primary-key-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-designate-primary-key-description.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-designate-primary-key-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-designate-primary-key-description.rst create mode 100644 source/includes/api-details/objectivec/model-data/object-models-designate-primary-key-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-designate-primary-key-description.rst create mode 100644 source/includes/sdk-examples/model-data/define-primary-key-property.rst 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/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/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/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/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/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/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/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/sdk-examples/model-data/define-primary-key-property.rst b/source/includes/sdk-examples/model-data/define-primary-key-property.rst new file mode 100644 index 0000000000..a03b7d5823 --- /dev/null +++ b/source/includes/sdk-examples/model-data/define-primary-key-property.rst @@ -0,0 +1,63 @@ +.. 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 diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 68e83d1f57..ca52721d40 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -797,18 +797,75 @@ Designate a Primary Key A **primary key** is a property that uniquely identifies an object. -You may define a primary key on a **single property** for an object type. -The SDK automatically indexes primary key properties, which allows you to -efficiently read and modify objects based on their primary key. +Primary keys allow you to efficiently find, update, and upsert objects. -If an object type has a primary key, then all objects of that type must -include the primary key property with a value that is unique among -objects of the same type in the database. +Primary keys are subject to the following limitations: -.. note:: +- 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 - Once you assign a property as a primary key, you cannot change it. + .. include:: /includes/api-details/javascript/model-data/object-models-designate-primary-key-js-ts-description.rst +.. include:: /includes/sdk-examples/model-data/define-primary-key-property.rst .. _sdks-optional-property-types: From 3ade84cc04daef952feefeaa327313b31f0ba3a9 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 12:30:20 -0400 Subject: [PATCH 15/36] Update the MissingPlaceholders to literalincludes you can't copy --- .../sdk-examples/model-data/define-fts-index-property.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/source/includes/sdk-examples/model-data/define-fts-index-property.rst b/source/includes/sdk-examples/model-data/define-fts-index-property.rst index d1f0cd2387..be5c622a5c 100644 --- a/source/includes/sdk-examples/model-data/define-fts-index-property.rst +++ b/source/includes/sdk-examples/model-data/define-fts-index-property.rst @@ -24,12 +24,16 @@ - id: java content: | - .. include:: /examples/MissingPlaceholders/api.java + .. literalinclude:: /examples/MissingPlaceholders/api.java + :language: java + :copyable: false - id: java-kotlin content: | - .. include:: /examples/MissingPlaceholders/api-java-kotlin.kt + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.java + :language: java + :copyable: false - id: javascript content: | From 3d493ad793f2b55f379e5e8393bd2522b0dfecea Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 13:39:10 -0400 Subject: [PATCH 16/36] Try to fix snooty build error --- .../sdk-examples/model-data/define-fts-index-property.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/source/includes/sdk-examples/model-data/define-fts-index-property.rst b/source/includes/sdk-examples/model-data/define-fts-index-property.rst index be5c622a5c..1a73d59e2e 100644 --- a/source/includes/sdk-examples/model-data/define-fts-index-property.rst +++ b/source/includes/sdk-examples/model-data/define-fts-index-property.rst @@ -6,6 +6,7 @@ .. literalinclude:: /examples/MissingPlaceholders/api.cpp :language: cpp + :copyable: false - id: csharp content: | @@ -31,8 +32,8 @@ - id: java-kotlin content: | - .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.java - :language: java + .. literalinclude:: /examples/MissingPlaceholders/api-java-kotlin.kt + :language: kotlin :copyable: false - id: javascript @@ -40,6 +41,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.js :language: javascript + :copyable: false - id: kotlin content: | @@ -52,12 +54,14 @@ .. literalinclude:: /examples/MissingPlaceholders/api.m :language: objectivec + :copyable: false - id: swift content: | .. literalinclude:: /examples/MissingPlaceholders/api.swift :language: swift + :copyable: false - id: typescript content: | From f3090eb8e9a94786f20f00bdcfc39fd80eaa4488 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 13:45:39 -0400 Subject: [PATCH 17/36] Make missing placeholders not copyable --- .../sdk-examples/model-data/define-asymmetric-object.rst | 4 ++++ .../sdk-examples/model-data/define-geospatial-object.rst | 3 +++ .../sdk-examples/model-data/define-index-property.rst | 2 ++ .../sdk-examples/model-data/define-primary-key-property.rst | 1 + 4 files changed, 10 insertions(+) diff --git a/source/includes/sdk-examples/model-data/define-asymmetric-object.rst b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst index f8380cabe2..e5f6a64530 100644 --- a/source/includes/sdk-examples/model-data/define-asymmetric-object.rst +++ b/source/includes/sdk-examples/model-data/define-asymmetric-object.rst @@ -12,6 +12,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | @@ -25,12 +26,14 @@ .. 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: | @@ -50,6 +53,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | diff --git a/source/includes/sdk-examples/model-data/define-geospatial-object.rst b/source/includes/sdk-examples/model-data/define-geospatial-object.rst index be1892155f..7061972c58 100644 --- a/source/includes/sdk-examples/model-data/define-geospatial-object.rst +++ b/source/includes/sdk-examples/model-data/define-geospatial-object.rst @@ -26,12 +26,14 @@ .. 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: | @@ -51,6 +53,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.m :language: objectivec + :copyable: false - id: swift content: | diff --git a/source/includes/sdk-examples/model-data/define-index-property.rst b/source/includes/sdk-examples/model-data/define-index-property.rst index 8b79b5e941..60f9943b76 100644 --- a/source/includes/sdk-examples/model-data/define-index-property.rst +++ b/source/includes/sdk-examples/model-data/define-index-property.rst @@ -6,6 +6,7 @@ .. literalinclude:: /examples/MissingPlaceholders/api.cpp :language: cpp + :copyable: false - id: csharp content: | @@ -61,3 +62,4 @@ .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false diff --git a/source/includes/sdk-examples/model-data/define-primary-key-property.rst b/source/includes/sdk-examples/model-data/define-primary-key-property.rst index a03b7d5823..4dbb93a139 100644 --- a/source/includes/sdk-examples/model-data/define-primary-key-property.rst +++ b/source/includes/sdk-examples/model-data/define-primary-key-property.rst @@ -61,3 +61,4 @@ .. literalinclude:: /examples/MissingPlaceholders/example.ts :language: typescript + :copyable: false From e37070f795d22e7f70e0ee11e23e2b9613addf74 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 15:02:56 -0400 Subject: [PATCH 18/36] Add optional property details --- ...s-define-optional-property-description.rst | 2 + ...s-define-optional-property-description.rst | 31 +++++++ ...s-define-optional-property-description.rst | 3 + ...ine-optional-property-java-description.rst | 22 +++++ ...e-optional-property-kotlin-description.rst | 17 ++++ ...s-define-optional-property-description.rst | 3 + ...s-define-optional-property-description.rst | 5 ++ ...s-define-optional-property-description.rst | 9 ++ ...s-define-optional-property-description.rst | 2 + ...s-define-optional-property-description.rst | 1 + .../model-data/define-optional-property.rst | 67 +++++++++++++++ source/sdk/model-data/object-models.txt | 85 +++++++++++++++++-- 12 files changed, 242 insertions(+), 5 deletions(-) create mode 100644 source/includes/api-details/cpp/model-data/object-models-define-optional-property-description.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-define-optional-property-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-define-optional-property-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-define-optional-property-java-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-define-optional-property-kotlin-description.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-define-optional-property-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-define-optional-property-description.rst create mode 100644 source/includes/api-details/objectivec/model-data/object-models-define-optional-property-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-define-optional-property-description.rst create mode 100644 source/includes/api-details/typescript/model-data/object-models-define-optional-property-description.rst create mode 100644 source/includes/sdk-examples/model-data/define-optional-property.rst 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/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/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/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/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/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/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/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/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/sdk-examples/model-data/define-optional-property.rst b/source/includes/sdk-examples/model-data/define-optional-property.rst new file mode 100644 index 0000000000..b7998ce7e5 --- /dev/null +++ b/source/includes/sdk-examples/model-data/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/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index ca52721d40..8d97be811b 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -869,13 +869,88 @@ have a primary key named ``_id``. .. _sdks-optional-property-types: -Define 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 -Placeholder for .NET nullability info, and any other SDKs with similar -APIs/requirements + .. 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/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-model-unstructured-data: Model Unstructured Data -~~~~~~~~~~~~~~~~~~~~~~~ +----------------------- From aa13a8a7e4bc0bf3070a981f5df75e8c3f8fbe03 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 16:19:47 -0400 Subject: [PATCH 19/36] Add ignored property details --- ...ect-models-ignore-property-description.rst | 1 + ...ect-models-ignore-property-description.rst | 5 ++ ...ect-models-ignore-property-description.rst | 5 ++ ...ect-models-ignore-property-description.rst | 7 ++ ...dels-ignore-property-js-ts-description.rst | 1 + ...ect-models-ignore-property-description.rst | 3 + ...ect-models-ignore-property-description.rst | 3 + ...ect-models-ignore-property-description.rst | 2 + .../model-data/define-ignored-property.rst | 64 +++++++++++++++++ source/sdk/model-data/object-models.txt | 69 +++++++++++++++++++ 10 files changed, 160 insertions(+) create mode 100644 source/includes/api-details/cpp/model-data/object-models-ignore-property-description.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-ignore-property-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-ignore-property-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-ignore-property-description.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-ignore-property-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-ignore-property-description.rst create mode 100644 source/includes/api-details/objectivec/model-data/object-models-ignore-property-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-ignore-property-description.rst create mode 100644 source/includes/sdk-examples/model-data/define-ignored-property.rst 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/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/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/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/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/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/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/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/sdk-examples/model-data/define-ignored-property.rst b/source/includes/sdk-examples/model-data/define-ignored-property.rst new file mode 100644 index 0000000000..1c0ec0a5ad --- /dev/null +++ b/source/includes/sdk-examples/model-data/define-ignored-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/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 8d97be811b..fd909088e1 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -950,6 +950,75 @@ 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/typescript/model-data/object-models-ignore-property-js-ts-description.rst + +.. include:: /includes/sdk-examples/model-data/define-ignored-property.rst + .. _sdks-model-unstructured-data: Model Unstructured Data From 7b8c8c1d0939cd6638399ac6cc6556a8874b32c7 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 16:26:55 -0400 Subject: [PATCH 20/36] Fix snooty build error --- source/sdk/model-data/object-models.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index fd909088e1..479b83a9cd 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -1015,7 +1015,7 @@ You can mix managed and ignored properties within a model. .. tab:: :tabid: typescript - .. include:: /includes/api-details/typescript/model-data/object-models-ignore-property-js-ts-description.rst + .. include:: /includes/api-details/javascript/model-data/object-models-ignore-property-js-ts-description.rst .. include:: /includes/sdk-examples/model-data/define-ignored-property.rst From a2f7ed2c05fa72bc52c21958aa2116aeb9fb6edc Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 16:51:26 -0400 Subject: [PATCH 21/36] Add details about default values --- ...default-value-for-property-description.rst | 9 +++ ...default-value-for-property-description.rst | 2 + ...lt-value-for-property-java-description.rst | 9 +++ ...-value-for-property-kotlin-description.rst | 9 +++ ...default-value-for-property-description.rst | 5 ++ ...default-value-for-property-description.rst | 2 + .../define-default-value-for-property.rst | 67 +++++++++++++++++++ source/sdk/model-data/object-models.txt | 57 ++++++++++++++++ 8 files changed, 160 insertions(+) create mode 100644 source/includes/api-details/csharp/model-data/object-models-set-default-value-for-property-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-set-default-value-for-property-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-set-default-value-for-property-java-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-set-default-value-for-property-kotlin-description.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-set-default-value-for-property-description.rst create mode 100644 source/includes/api-details/typescript/model-data/object-models-set-default-value-for-property-description.rst create mode 100644 source/includes/sdk-examples/model-data/define-default-value-for-property.rst 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-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/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/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/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/sdk-examples/model-data/define-default-value-for-property.rst b/source/includes/sdk-examples/model-data/define-default-value-for-property.rst new file mode 100644 index 0000000000..37c978bb8d --- /dev/null +++ b/source/includes/sdk-examples/model-data/define-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/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 479b83a9cd..e309b6c035 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -1019,6 +1019,63 @@ You can mix managed and ignored properties within a model. .. include:: /includes/sdk-examples/model-data/define-ignored-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 + + .. include:: /includes/api-details/csharp/model-data/object-models-set-default-value-for-property-description.rst + + .. tab:: + :tabid: dart + + .. 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/define-default-value-for-property.rst + .. _sdks-model-unstructured-data: Model Unstructured Data From d33584d7d09fec3152c4fb4c6cdc3864b3906b80 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 18:16:54 -0400 Subject: [PATCH 22/36] Add info about unstructured data --- ...models-unstructured-data-not-supported.rst | 2 + ...ls-model-unstructured-data-description.rst | 10 +++ ...ls-model-unstructured-data-description.rst | 15 ++++ ...models-model-unstructured-data-example.rst | 23 +++++ ...models-unstructured-data-not-supported.rst | 3 + ...el-unstructured-data-js-ts-description.rst | 11 +++ ...ls-model-unstructured-data-description.rst | 12 +++ ...ls-model-unstructured-data-description.rst | 13 +++ ...ls-model-unstructured-data-description.rst | 13 +++ .../model-data/model-unstructured-data.rst | 69 +++++++++++++++ source/sdk/model-data/object-models.txt | 84 ++++++++++++++++++- source/sdk/model-data/supported-types.txt | 5 ++ 12 files changed, 258 insertions(+), 2 deletions(-) create mode 100644 source/includes/api-details/cpp/model-data/object-models-unstructured-data-not-supported.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-model-unstructured-data-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-model-unstructured-data-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-model-unstructured-data-example.rst create mode 100644 source/includes/api-details/java/model-data/object-models-unstructured-data-not-supported.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-model-unstructured-data-js-ts-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-model-unstructured-data-description.rst create mode 100644 source/includes/api-details/objectivec/model-data/object-models-model-unstructured-data-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-model-unstructured-data-description.rst create mode 100644 source/includes/sdk-examples/model-data/model-unstructured-data.rst 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-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/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/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-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/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/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/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/sdk-examples/model-data/model-unstructured-data.rst b/source/includes/sdk-examples/model-data/model-unstructured-data.rst new file mode 100644 index 0000000000..760df3c15a --- /dev/null +++ b/source/includes/sdk-examples/model-data/model-unstructured-data.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/MissingPlaceholders/example.cs + :language: csharp + + - id: dart + content: | + + .. include:: /examples/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/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index e309b6c035..733f3941d9 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -607,8 +607,8 @@ To persist ``GeoPoint`` data, it must conform to the .. _sdks-define-special-property-types: -Define Special Property Types ------------------------------ +Define Special 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 @@ -1080,3 +1080,83 @@ first access, so will never be nil. 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/model-unstructured-data.rst diff --git a/source/sdk/model-data/supported-types.txt b/source/sdk/model-data/supported-types.txt index 0d67e2f1ae..f50e17456f 100644 --- a/source/sdk/model-data/supported-types.txt +++ b/source/sdk/model-data/supported-types.txt @@ -26,6 +26,11 @@ Placeholder page for supported data types. Generic (Mixed) Data Type ~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _sdks-nested-collections-in-mixed: + +Nested Collections in Mixed +``````````````````````````` + .. _sdks-counter-data-type: Counter Data Type From 6610a2d3a63b35d9be9c3d0ab9643ac225ea7fd5 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 18:19:54 -0400 Subject: [PATCH 23/36] Fix dart include file path --- .../sdk-examples/model-data/model-unstructured-data.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/sdk-examples/model-data/model-unstructured-data.rst b/source/includes/sdk-examples/model-data/model-unstructured-data.rst index 760df3c15a..c7c03f7009 100644 --- a/source/includes/sdk-examples/model-data/model-unstructured-data.rst +++ b/source/includes/sdk-examples/model-data/model-unstructured-data.rst @@ -17,7 +17,7 @@ - id: dart content: | - .. include:: /examples/api-details/dart/model-data/object-models-model-unstructured-data-example.rst + .. include:: /includes/api-details/dart/model-data/object-models-model-unstructured-data-example.rst - id: java content: | From cb69ad8885423174aba00a9aad12487e5e6d91c6 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 18:26:56 -0400 Subject: [PATCH 24/36] Rename supported property types to define property types to mirror Create content --- ...object-models-define-asymmetric-object-description.rst | 2 +- .../object-models-define-sdk-object-model-description.rst | 2 +- source/sdk/model-data.txt | 4 ++-- source/sdk/model-data/object-models.txt | 4 ++-- .../{supported-types.txt => property-types.txt} | 8 ++++---- source/sdk/sync/event-library.txt | 2 +- 6 files changed, 11 insertions(+), 11 deletions(-) rename source/sdk/model-data/{supported-types.txt => property-types.txt} (94%) 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 index 89de21a7f8..8bdb42a6da 100644 --- 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 @@ -4,7 +4,7 @@ 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: +` as ``realm::object``, with a few exceptions: - Asymmetric objects can link to the following types: - ``object`` 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 index b7d6609c78..bd379a827a 100644 --- 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 @@ -29,7 +29,7 @@ ``RealmObject`` from the ``RealmModel``, as described in step 4. Add fields to the ``RealmModel``. - You can add fields of any :ref:`supported data types `. + You can add fields of any :ref:`supported data types `. Include additional behavior using :ref:`special object types `. 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 733f3941d9..073af1fe42 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -26,7 +26,7 @@ Define an SDK Object Model 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 +` data types. You can annotate a property to provide additional meta-information that gives the property special behaviors, such as: @@ -122,7 +122,7 @@ 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 +`. Properties are also the mechanism for establishing :ref:`relationships ` between object types, or establishing other special behaviors for specific fields in your object. diff --git a/source/sdk/model-data/supported-types.txt b/source/sdk/model-data/property-types.txt similarity index 94% rename from source/sdk/model-data/supported-types.txt rename to source/sdk/model-data/property-types.txt index f50e17456f..4d0c2b87d4 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. 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. From 838e855a4ce3d158329851b9c4fd6de0af2c653c Mon Sep 17 00:00:00 2001 From: dacharyc Date: Tue, 9 Jul 2024 18:30:33 -0400 Subject: [PATCH 25/36] Fix title underline too short warnings --- source/platforms/apple/swift-concurrency.txt | 2 +- source/platforms/unity.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) 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 From 3474c26c6017f59c76b4d21f1b1769dae010f515 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 10 Jul 2024 10:10:30 -0400 Subject: [PATCH 26/36] Add details about mapping a model or property name to different stored name --- ...operty-to-different-name-not-supported.rst | 2 + ...ect-models-database-schema-description.rst | 2 +- ...property-to-different-name-description.rst | 2 + ...property-to-different-name-description.rst | 3 + ...rty-to-different-name-java-description.rst | 17 ++++ ...y-to-different-name-kotlin-description.rst | 17 ++++ ...property-to-different-name-description.rst | 28 +++++++ ...property-to-different-name-description.rst | 37 +++++++++ ...ect-models-database-schema-description.rst | 2 +- ...property-to-different-name-description.rst | 8 ++ ...ect-models-database-schema-description.rst | 2 +- ...property-to-different-name-description.rst | 16 ++++ ...-data-open-synced-database-description.rst | 2 +- ...property-to-different-name-description.rst | 24 ++++++ ...ap-model-or-property-to-different-name.rst | 76 ++++++++++++++++++ source/sdk/crud/read.txt | 8 ++ source/sdk/files/configure-and-open.txt | 6 +- source/sdk/model-data/object-models.txt | 80 +++++++++++++++++++ 18 files changed, 325 insertions(+), 7 deletions(-) create mode 100644 source/includes/api-details/cpp/model-data/object-models-map-model-or-property-to-different-name-not-supported.rst create mode 100644 source/includes/api-details/csharp/model-data/object-models-map-model-or-property-to-different-name-description.rst create mode 100644 source/includes/api-details/dart/model-data/object-models-map-model-or-property-to-different-name-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-map-model-or-property-to-different-name-java-description.rst create mode 100644 source/includes/api-details/java/model-data/object-models-map-model-or-property-to-different-name-kotlin-description.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-map-model-or-property-to-different-name-description.rst create mode 100644 source/includes/api-details/kotlin/model-data/object-models-map-model-or-property-to-different-name-description.rst create mode 100644 source/includes/api-details/objectivec/model-data/object-models-map-model-or-property-to-different-name-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-map-model-or-property-to-different-name-description.rst create mode 100644 source/includes/api-details/typescript/model-data/object-models-map-model-or-property-to-different-name-description.rst create mode 100644 source/includes/sdk-examples/model-data/map-model-or-property-to-different-name.rst 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/csharp/model-data/object-models-database-schema-description.rst b/source/includes/api-details/csharp/model-data/object-models-database-schema-description.rst index 94c04aa526..f0527803a8 100644 --- 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 @@ -5,7 +5,7 @@ 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-classes-to-a-database`. +For more information, refer to :ref:`sdks-provide-a-subset-of-models-to-a-database`. .. note:: 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/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/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..d02a70f8d5 --- /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,17 @@ +Use the :java-sdk:`@RealmClass ` +annotation to rename a class. + +.. include:: /examples/generated/java/local/FrogClassRenamePolicyExample.snippet.complete.java.rst + +Use the :java-sdk:`@RealmField ` +annotation to rename a field: + +.. include:: /examples/generated/java/local/FrogRenameAFieldExample.snippet.complete.java.rst + +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..4a62533dbb --- /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,17 @@ +Use the :java-sdk:`@RealmClass ` +annotation to rename a class. + +.. include:: /examples/generated/java/local/FrogClassRenamePolicyExampleKt.snippet.complete.kt.rst + +Use the :java-sdk:`@RealmField ` +annotation to rename a field. + +.. include:: /examples/generated/java/local/FrogRenameAFieldExampleKt.snippet.complete.kt.rst + +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/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..a35a9916d0 --- /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/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..34bb37f0eb --- /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 a realm: + +.. 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/objectivec/model-data/object-models-database-schema-description.rst b/source/includes/api-details/objectivec/model-data/object-models-database-schema-description.rst index 385c422da1..0a200a337e 100644 --- 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 @@ -4,4 +4,4 @@ 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-classes-to-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-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/swift/model-data/object-models-database-schema-description.rst b/source/includes/api-details/swift/model-data/object-models-database-schema-description.rst index a746f8166a..65e2d70146 100644 --- 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 @@ -4,4 +4,4 @@ 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-classes-to-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-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/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-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..1ecd8c31db --- /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/sdk-examples/model-data/map-model-or-property-to-different-name.rst b/source/includes/sdk-examples/model-data/map-model-or-property-to-different-name.rst new file mode 100644 index 0000000000..6fdbf57e59 --- /dev/null +++ b/source/includes/sdk-examples/model-data/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/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/object-models.txt b/source/sdk/model-data/object-models.txt index 073af1fe42..e38947a18f 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -1160,3 +1160,83 @@ structured schema or serializing JSON blobs into a single string property. .. include:: /includes/api-details/javascript/model-data/object-models-model-unstructured-data-js-ts-description.rst .. include:: /includes/sdk-examples/model-data/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 `. + +.. 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/javascript/model-data/object-models-map-model-or-property-to-different-name-description.rst + +.. include:: /includes/sdk-examples/model-data/map-model-or-property-to-different-name.rst + +.. note:: + + Migrations must use the persisted class or property name. Any schema errors + reported also use the persisted name. From 2c931970e8ad876b5bf70c3d696c12cbf094553a Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 10 Jul 2024 10:26:00 -0400 Subject: [PATCH 27/36] Minor cleanup --- ...r-property-to-different-name-java-description.rst | 6 ++++++ ...property-to-different-name-kotlin-description.rst | 6 ++++++ ...del-or-property-to-different-name-description.rst | 2 +- ...del-or-property-to-different-name-description.rst | 2 +- source/sdk/model-data/object-models.txt | 12 ++++++------ 5 files changed, 20 insertions(+), 8 deletions(-) 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 index d02a70f8d5..88cdc82ca6 100644 --- 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 @@ -1,13 +1,19 @@ +**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. 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 index 4a62533dbb..6821c78078 100644 --- 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 @@ -1,13 +1,19 @@ +**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. 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 index a35a9916d0..1cfb326f80 100644 --- 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 @@ -3,7 +3,7 @@ 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. + 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 `. 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 index 1ecd8c31db..5a471fc204 100644 --- 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 @@ -3,7 +3,7 @@ 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. + 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 `. diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index e38947a18f..08c189069e 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -1182,6 +1182,11 @@ 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:: @@ -1232,11 +1237,6 @@ model or property to a new name is the name used in the persisted .. tab:: :tabid: typescript - .. include:: /includes/api-details/javascript/model-data/object-models-map-model-or-property-to-different-name-description.rst + .. include:: /includes/api-details/typescript/model-data/object-models-map-model-or-property-to-different-name-description.rst .. include:: /includes/sdk-examples/model-data/map-model-or-property-to-different-name.rst - -.. note:: - - Migrations must use the persisted class or property name. Any schema errors - reported also use the persisted name. From ac55416a45b92b5eecb8f41340221e2245b07337 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 10 Jul 2024 11:02:21 -0400 Subject: [PATCH 28/36] Add information about projection --- ...models-define-projection-not-supported.rst | 3 + ...-define-projection-missing-description.rst | 2 + ...t-models-define-projection-description.rst | 13 +++ .../model-data/define-projection.rst | 71 ++++++++++++++ .../model-data/model-unstructured-data.rst | 1 + source/sdk/model-data/object-models.txt | 92 +++++++++++++++++++ source/sdk/model-data/property-types.txt | 23 +++-- 7 files changed, 197 insertions(+), 8 deletions(-) create mode 100644 source/includes/api-details/generic/model-data/object-models-define-projection-not-supported.rst create mode 100644 source/includes/api-details/objectivec/model-data/object-models-define-projection-missing-description.rst create mode 100644 source/includes/api-details/swift/model-data/object-models-define-projection-description.rst create mode 100644 source/includes/sdk-examples/model-data/define-projection.rst 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/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/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..10ae662564 --- /dev/null +++ b/source/includes/api-details/swift/model-data/object-models-define-projection-description.rst @@ -0,0 +1,13 @@ +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 + `. diff --git a/source/includes/sdk-examples/model-data/define-projection.rst b/source/includes/sdk-examples/model-data/define-projection.rst new file mode 100644 index 0000000000..32ebf06e57 --- /dev/null +++ b/source/includes/sdk-examples/model-data/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/model-unstructured-data.rst b/source/includes/sdk-examples/model-data/model-unstructured-data.rst index c7c03f7009..2676768ad6 100644 --- a/source/includes/sdk-examples/model-data/model-unstructured-data.rst +++ b/source/includes/sdk-examples/model-data/model-unstructured-data.rst @@ -13,6 +13,7 @@ .. literalinclude:: /examples/MissingPlaceholders/example.cs :language: csharp + :copyable: false - id: dart content: | diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 08c189069e..590fd3fa09 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -1240,3 +1240,95 @@ model or property to a new name is the name used in the persisted .. include:: /includes/api-details/typescript/model-data/object-models-map-model-or-property-to-different-name-description.rst .. include:: /includes/sdk-examples/model-data/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. + +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/define-projection.rst diff --git a/source/sdk/model-data/property-types.txt b/source/sdk/model-data/property-types.txt index 4d0c2b87d4..1f14dbaded 100644 --- a/source/sdk/model-data/property-types.txt +++ b/source/sdk/model-data/property-types.txt @@ -20,6 +20,10 @@ Define Property Types Placeholder page for supported data types. +.. _sdks-data-property-types: + +Data Property Types +------------------- .. _sdks-mixed-data-type: @@ -41,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: @@ -64,12 +73,10 @@ 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From e7cf6f8c39f379b16336de09dc787736cc5127f2 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 10 Jul 2024 11:22:03 -0400 Subject: [PATCH 29/36] Add info about custom setters --- ...dels-define-custom-setters-description.rst | 2 + .../model-data/define-custom-setters.rst | 71 +++++++++++++++++++ source/sdk/model-data/object-models.txt | 60 +++++++++++++++- source/sdk/model-data/property-types.txt | 15 ++++ 4 files changed, 147 insertions(+), 1 deletion(-) create mode 100644 source/includes/api-details/csharp/model-data/object-models-define-custom-setters-description.rst create mode 100644 source/includes/sdk-examples/model-data/define-custom-setters.rst 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/sdk-examples/model-data/define-custom-setters.rst b/source/includes/sdk-examples/model-data/define-custom-setters.rst new file mode 100644 index 0000000000..7818169cc5 --- /dev/null +++ b/source/includes/sdk-examples/model-data/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/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index 590fd3fa09..f0cb82ca06 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -1076,6 +1076,55 @@ first access, so will never be nil. .. include:: /includes/sdk-examples/model-data/define-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/define-custom-setters.rst + .. _sdks-model-unstructured-data: Model Unstructured Data @@ -1252,7 +1301,16 @@ 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. +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. diff --git a/source/sdk/model-data/property-types.txt b/source/sdk/model-data/property-types.txt index 1f14dbaded..50b82a1107 100644 --- a/source/sdk/model-data/property-types.txt +++ b/source/sdk/model-data/property-types.txt @@ -80,3 +80,18 @@ Define a Set Property 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 +~~~~~~~~~~~~~~~~~~~~~~~ From 6fee88caeeabd88b963dfcc7c01c5e15d897e4b2 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 10 Jul 2024 11:59:36 -0400 Subject: [PATCH 30/36] Incorporate feedback about creating objects for JS/TS --- ...fine-embedded-object-js-ts-description.rst | 2 +- ...object-models-object-model-description.rst | 23 +++++++++++-------- ...object-models-object-model-description.rst | 23 +++++++++++-------- 3 files changed, 27 insertions(+), 21 deletions(-) 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 index f814fb35e7..c3584f4b91 100644 --- 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 @@ -1,3 +1,3 @@ -In the Node.js SDK, to define an embedded object, set ``embedded`` +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-object-model-description.rst b/source/includes/api-details/javascript/model-data/object-models-object-model-description.rst index ee1aae23c4..2f8edbdac5 100644 --- 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 @@ -1,13 +1,16 @@ -You can define SDK models as JavaScript classes that extend ``Realm.Object`` -(like most of the examples on this page). Or you can define models as -JavaScript objects. +You can define SDK models as JavaScript classes that extend ``Realm.Object``. -When you define models as JavaScript classes that extend ``Realm.Object``, -you can pass those model objects directly to the database. Prefer this approach -when possible. +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. -If you do define a model that does not extend ``Realm.Object``, you cannot pass -the model directly to the database. Instead, you pass only the schema to the -database that manages the object. +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: -.. TODO: Provide more info about why you would choose one of these approaches over the other +- 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-object-model-description.rst b/source/includes/api-details/typescript/model-data/object-models-object-model-description.rst index f7f981d261..3bdea0b235 100644 --- 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 @@ -1,13 +1,16 @@ -You can define SDK models as TypeScript classes that extend ``Realm.Object`` -(like most of the examples on this page). Or you can define models as -TypeScript objects. +You can define SDK models as TypeScript classes that extend ``Realm.Object``. -When you define models as TypeScript classes that extend ``Realm.Object``, -you can pass those model objects directly to the database. Prefer this approach -when possible. +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. -If you do define a model that does not extend ``Realm.Object``, you cannot pass -the model directly to the database. Instead, you pass only the schema to the -database that manages the object. +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: -.. TODO: Provide more info about why you would choose one of these approaches over the other +- 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`. From 2eb6793c144ea4022fce170d046c80ba3ce5e74b Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 10 Jul 2024 12:11:34 -0400 Subject: [PATCH 31/36] Rename includes to comply with naming conventions --- ...bject-models-define-asymmetric-object.rst} | 0 ...> object-models-define-custom-setters.rst} | 0 ... object-models-define-embedded-object.rst} | 0 ...bject-models-define-geospatial-object.rst} | 0 ...bject-models-define-optional-property.rst} | 0 ...st => object-models-define-projection.rst} | 0 ... => object-models-define-realm-object.rst} | 0 ...object-models-define-sdk-object-model.rst} | 0 ...> object-models-designate-primary-key.rst} | 0 ...s-enable-full-text-search-on-property.rst} | 0 ....rst => object-models-ignore-property.rst} | 0 ...y.rst => object-models-index-property.rst} | 0 ...p-model-or-property-to-different-name.rst} | 0 ...object-models-model-unstructured-data.rst} | 0 ...models-set-default-value-for-property.rst} | 0 source/sdk/model-data/object-models.txt | 30 +++++++++---------- 16 files changed, 15 insertions(+), 15 deletions(-) rename source/includes/sdk-examples/model-data/{define-asymmetric-object.rst => object-models-define-asymmetric-object.rst} (100%) rename source/includes/sdk-examples/model-data/{define-custom-setters.rst => object-models-define-custom-setters.rst} (100%) rename source/includes/sdk-examples/model-data/{define-embedded-object.rst => object-models-define-embedded-object.rst} (100%) rename source/includes/sdk-examples/model-data/{define-geospatial-object.rst => object-models-define-geospatial-object.rst} (100%) rename source/includes/sdk-examples/model-data/{define-optional-property.rst => object-models-define-optional-property.rst} (100%) rename source/includes/sdk-examples/model-data/{define-projection.rst => object-models-define-projection.rst} (100%) rename source/includes/sdk-examples/model-data/{define-realm-object.rst => object-models-define-realm-object.rst} (100%) rename source/includes/sdk-examples/model-data/{define-object-model.rst => object-models-define-sdk-object-model.rst} (100%) rename source/includes/sdk-examples/model-data/{define-primary-key-property.rst => object-models-designate-primary-key.rst} (100%) rename source/includes/sdk-examples/model-data/{define-fts-index-property.rst => object-models-enable-full-text-search-on-property.rst} (100%) rename source/includes/sdk-examples/model-data/{define-ignored-property.rst => object-models-ignore-property.rst} (100%) rename source/includes/sdk-examples/model-data/{define-index-property.rst => object-models-index-property.rst} (100%) rename source/includes/sdk-examples/model-data/{map-model-or-property-to-different-name.rst => object-models-map-model-or-property-to-different-name.rst} (100%) rename source/includes/sdk-examples/model-data/{model-unstructured-data.rst => object-models-model-unstructured-data.rst} (100%) rename source/includes/sdk-examples/model-data/{define-default-value-for-property.rst => object-models-set-default-value-for-property.rst} (100%) diff --git a/source/includes/sdk-examples/model-data/define-asymmetric-object.rst b/source/includes/sdk-examples/model-data/object-models-define-asymmetric-object.rst similarity index 100% rename from source/includes/sdk-examples/model-data/define-asymmetric-object.rst rename to source/includes/sdk-examples/model-data/object-models-define-asymmetric-object.rst diff --git a/source/includes/sdk-examples/model-data/define-custom-setters.rst b/source/includes/sdk-examples/model-data/object-models-define-custom-setters.rst similarity index 100% rename from source/includes/sdk-examples/model-data/define-custom-setters.rst rename to source/includes/sdk-examples/model-data/object-models-define-custom-setters.rst diff --git a/source/includes/sdk-examples/model-data/define-embedded-object.rst b/source/includes/sdk-examples/model-data/object-models-define-embedded-object.rst similarity index 100% rename from source/includes/sdk-examples/model-data/define-embedded-object.rst rename to source/includes/sdk-examples/model-data/object-models-define-embedded-object.rst diff --git a/source/includes/sdk-examples/model-data/define-geospatial-object.rst b/source/includes/sdk-examples/model-data/object-models-define-geospatial-object.rst similarity index 100% rename from source/includes/sdk-examples/model-data/define-geospatial-object.rst rename to source/includes/sdk-examples/model-data/object-models-define-geospatial-object.rst diff --git a/source/includes/sdk-examples/model-data/define-optional-property.rst b/source/includes/sdk-examples/model-data/object-models-define-optional-property.rst similarity index 100% rename from source/includes/sdk-examples/model-data/define-optional-property.rst rename to source/includes/sdk-examples/model-data/object-models-define-optional-property.rst diff --git a/source/includes/sdk-examples/model-data/define-projection.rst b/source/includes/sdk-examples/model-data/object-models-define-projection.rst similarity index 100% rename from source/includes/sdk-examples/model-data/define-projection.rst rename to source/includes/sdk-examples/model-data/object-models-define-projection.rst diff --git a/source/includes/sdk-examples/model-data/define-realm-object.rst b/source/includes/sdk-examples/model-data/object-models-define-realm-object.rst similarity index 100% rename from source/includes/sdk-examples/model-data/define-realm-object.rst rename to source/includes/sdk-examples/model-data/object-models-define-realm-object.rst diff --git a/source/includes/sdk-examples/model-data/define-object-model.rst b/source/includes/sdk-examples/model-data/object-models-define-sdk-object-model.rst similarity index 100% rename from source/includes/sdk-examples/model-data/define-object-model.rst rename to source/includes/sdk-examples/model-data/object-models-define-sdk-object-model.rst diff --git a/source/includes/sdk-examples/model-data/define-primary-key-property.rst b/source/includes/sdk-examples/model-data/object-models-designate-primary-key.rst similarity index 100% rename from source/includes/sdk-examples/model-data/define-primary-key-property.rst rename to source/includes/sdk-examples/model-data/object-models-designate-primary-key.rst diff --git a/source/includes/sdk-examples/model-data/define-fts-index-property.rst b/source/includes/sdk-examples/model-data/object-models-enable-full-text-search-on-property.rst similarity index 100% rename from source/includes/sdk-examples/model-data/define-fts-index-property.rst rename to source/includes/sdk-examples/model-data/object-models-enable-full-text-search-on-property.rst diff --git a/source/includes/sdk-examples/model-data/define-ignored-property.rst b/source/includes/sdk-examples/model-data/object-models-ignore-property.rst similarity index 100% rename from source/includes/sdk-examples/model-data/define-ignored-property.rst rename to source/includes/sdk-examples/model-data/object-models-ignore-property.rst diff --git a/source/includes/sdk-examples/model-data/define-index-property.rst b/source/includes/sdk-examples/model-data/object-models-index-property.rst similarity index 100% rename from source/includes/sdk-examples/model-data/define-index-property.rst rename to source/includes/sdk-examples/model-data/object-models-index-property.rst diff --git a/source/includes/sdk-examples/model-data/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 similarity index 100% rename from source/includes/sdk-examples/model-data/map-model-or-property-to-different-name.rst rename to source/includes/sdk-examples/model-data/object-models-map-model-or-property-to-different-name.rst diff --git a/source/includes/sdk-examples/model-data/model-unstructured-data.rst b/source/includes/sdk-examples/model-data/object-models-model-unstructured-data.rst similarity index 100% rename from source/includes/sdk-examples/model-data/model-unstructured-data.rst rename to source/includes/sdk-examples/model-data/object-models-model-unstructured-data.rst diff --git a/source/includes/sdk-examples/model-data/define-default-value-for-property.rst b/source/includes/sdk-examples/model-data/object-models-set-default-value-for-property.rst similarity index 100% rename from source/includes/sdk-examples/model-data/define-default-value-for-property.rst rename to source/includes/sdk-examples/model-data/object-models-set-default-value-for-property.rst diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index f0cb82ca06..b064d790cd 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -295,7 +295,7 @@ Define an SDK Object Model :tabid: typescript -.. include:: /includes/sdk-examples/model-data/define-object-model.rst +.. include:: /includes/sdk-examples/model-data/object-models-define-sdk-object-model.rst .. include:: /includes/note-class-char-limit.rst @@ -374,7 +374,7 @@ layer, Realm. .. tab:: :tabid: typescript -.. include:: /includes/sdk-examples/model-data/define-realm-object.rst +.. include:: /includes/sdk-examples/model-data/object-models-define-realm-object.rst .. _sdks-embedded-objects: @@ -448,7 +448,7 @@ relationship, in which the related objects have independent lifecycles. .. include:: /includes/api-details/javascript/model-data/object-models-define-embedded-object-js-ts-description.rst -.. include:: /includes/sdk-examples/model-data/define-embedded-object.rst +.. include:: /includes/sdk-examples/model-data/object-models-define-embedded-object.rst .. important:: Lifecycle considerations @@ -533,7 +533,7 @@ For more information, see: :ref:`Create an Asymmetric Object .. include:: /includes/api-details/typescript/model-data/object-models-define-asymmetric-object-description.rst -.. include:: /includes/sdk-examples/model-data/define-asymmetric-object.rst +.. include:: /includes/sdk-examples/model-data/object-models-define-asymmetric-object.rst .. _sdks-define-geospatial-object: @@ -595,7 +595,7 @@ To persist ``GeoPoint`` data, it must conform to the .. include:: /includes/api-details/typescript/model-data/object-models-define-geospatial-object-description.rst -.. include:: /includes/sdk-examples/model-data/define-geospatial-object.rst +.. include:: /includes/sdk-examples/model-data/object-models-define-geospatial-object.rst .. important:: Cannot Persist Geospatial Data Types @@ -697,7 +697,7 @@ down writes and increase the size of the database file: .. include:: /includes/api-details/javascript/model-data/object-models-index-property-js-ts-description.rst -.. include:: /includes/sdk-examples/model-data/define-index-property.rst +.. include:: /includes/sdk-examples/model-data/object-models-index-property.rst .. note:: @@ -777,7 +777,7 @@ efficient, but can slow down writes and increase the size of the database file: .. include:: /includes/api-details/javascript/model-data/object-models-fts-index-property-js-ts-description.rst -.. include:: /includes/sdk-examples/model-data/define-fts-index-property.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 @@ -865,7 +865,7 @@ have a primary key named ``_id``. .. include:: /includes/api-details/javascript/model-data/object-models-designate-primary-key-js-ts-description.rst -.. include:: /includes/sdk-examples/model-data/define-primary-key-property.rst +.. include:: /includes/sdk-examples/model-data/object-models-designate-primary-key.rst .. _sdks-optional-property-types: @@ -928,7 +928,7 @@ properties required unless you designate them as optional, or ignore them. .. include:: /includes/api-details/typescript/model-data/object-models-define-optional-property-description.rst -.. include:: /includes/sdk-examples/model-data/define-optional-property.rst +.. include:: /includes/sdk-examples/model-data/object-models-define-optional-property.rst Special Rules ````````````` @@ -1017,7 +1017,7 @@ You can mix managed and ignored properties within a model. .. include:: /includes/api-details/javascript/model-data/object-models-ignore-property-js-ts-description.rst -.. include:: /includes/sdk-examples/model-data/define-ignored-property.rst +.. include:: /includes/sdk-examples/model-data/object-models-ignore-property.rst .. _sdks-set-default-property-value: @@ -1074,7 +1074,7 @@ first access, so will never be nil. .. include:: /includes/api-details/typescript/model-data/object-models-set-default-value-for-property-description.rst -.. include:: /includes/sdk-examples/model-data/define-default-value-for-property.rst +.. include:: /includes/sdk-examples/model-data/object-models-set-default-value-for-property.rst .. _sdks-custom-setters: @@ -1123,7 +1123,7 @@ public property. .. tab:: :tabid: typescript -.. include:: /includes/sdk-examples/model-data/define-custom-setters.rst +.. include:: /includes/sdk-examples/model-data/object-models-define-custom-setters.rst .. _sdks-model-unstructured-data: @@ -1208,7 +1208,7 @@ structured schema or serializing JSON blobs into a single string property. .. include:: /includes/api-details/javascript/model-data/object-models-model-unstructured-data-js-ts-description.rst -.. include:: /includes/sdk-examples/model-data/model-unstructured-data.rst +.. include:: /includes/sdk-examples/model-data/object-models-model-unstructured-data.rst .. _sdks-map-db-name: @@ -1288,7 +1288,7 @@ model or property to a new name is the name used in the persisted .. include:: /includes/api-details/typescript/model-data/object-models-map-model-or-property-to-different-name-description.rst -.. include:: /includes/sdk-examples/model-data/map-model-or-property-to-different-name.rst +.. include:: /includes/sdk-examples/model-data/object-models-map-model-or-property-to-different-name.rst .. _sdks-define-model-projection: @@ -1389,4 +1389,4 @@ Define a Projection .. include:: /includes/api-details/generic/model-data/object-models-define-projection-not-supported.rst -.. include:: /includes/sdk-examples/model-data/define-projection.rst +.. include:: /includes/sdk-examples/model-data/object-models-define-projection.rst From eb979a7f85c4cccde1cb7a366f40e5475877bc67 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 10 Jul 2024 12:13:30 -0400 Subject: [PATCH 32/36] Add missing Swift model to the projection description --- .../object-models-define-projection-description.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) 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 index 10ae662564..863261f1de 100644 --- 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 @@ -11,3 +11,13 @@ property wrapper to declare a property that you want to project from a ` 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 From ddf4b992175f70efa66b9e072923b68002fe245a Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 10 Jul 2024 12:17:41 -0400 Subject: [PATCH 33/36] Update the metadata information --- source/sdk/model-data/object-models.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index b064d790cd..ec055ad31d 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -5,7 +5,7 @@ Define an SDK Object Model ========================== .. meta:: - :description: Learn about object models and schemas, including how to define an object. + :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:: From 1742ab196d56d2415ed3741b5ba0faba436598d3 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 10 Jul 2024 12:49:42 -0400 Subject: [PATCH 34/36] Incorporate additional info about indexes from related Jira ticket --- source/sdk/model-data/object-models.txt | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index ec055ad31d..d1d799e377 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -644,6 +644,13 @@ down writes and increase the size of the database file: - 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:: From 9a1956fe1d716e4ce02aaa83e7783f1280c65702 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 17 Jul 2024 17:49:44 -0400 Subject: [PATCH 35/36] Add JS and TS descriptions for defining SDK and Realm models --- ...object-models-define-realm-object-description.rst | 12 ++++++++++++ ...ct-models-define-sdk-object-model-description.rst | 12 ++++++++++++ ...object-models-define-realm-object-description.rst | 12 ++++++++++++ ...ct-models-define-sdk-object-model-description.rst | 12 ++++++++++++ source/sdk/model-data/object-models.txt | 7 +++++++ 5 files changed, 55 insertions(+) create mode 100644 source/includes/api-details/javascript/model-data/object-models-define-realm-object-description.rst create mode 100644 source/includes/api-details/javascript/model-data/object-models-define-sdk-object-model-description.rst create mode 100644 source/includes/api-details/typescript/model-data/object-models-define-realm-object-description.rst create mode 100644 source/includes/api-details/typescript/model-data/object-models-define-sdk-object-model-description.rst 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/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/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index d1d799e377..db5e764721 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -276,6 +276,8 @@ Define an SDK Object Model .. tab:: :tabid: javascript + .. include:: /includes/api-details/javascript/model-data/object-models-define-sdk-object-model-description.rst + .. tab:: :tabid: kotlin @@ -294,6 +296,7 @@ Define an SDK Object Model .. 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 @@ -356,6 +359,8 @@ layer, Realm. .. tab:: :tabid: javascript + .. include:: /includes/api-details/javascript/model-data/object-models-define-realm-object-description.rst + .. tab:: :tabid: kotlin @@ -374,6 +379,8 @@ layer, Realm. .. 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: From 1e30fb0f64357b9bc572e60e296988bc6cef3d09 Mon Sep 17 00:00:00 2001 From: dacharyc Date: Wed, 17 Jul 2024 18:15:17 -0400 Subject: [PATCH 36/36] Incorporate review feedback --- .../object-models-define-geospatial-object-description.rst | 4 ++-- .../object-models-define-embedded-object-description.rst | 4 ++-- ...ject-models-define-sdk-object-model-java-description.rst | 6 +++--- .../object-models-define-geospatial-object-description.rst | 2 +- .../object-models-define-asymmetric-object-description.rst | 2 +- .../object-models-define-geospatial-object-description.rst | 2 +- ...-map-model-or-property-to-different-name-description.rst | 2 +- .../object-models-define-geospatial-object-description.rst | 2 +- source/sdk/model-data/object-models.txt | 6 +++--- 9 files changed, 15 insertions(+), 15 deletions(-) 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 index b094ef25d5..1c6ebe3235 100644 --- 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 @@ -6,7 +6,7 @@ In C#, to create a class that conforms to the GeoJSON spec: #. 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 realm schema. + property in the object schema. - A field of type ``string`` that maps to a "type" property. The value of this field must be "Point". @@ -20,5 +20,5 @@ to persist GeoPoint data: Use the Embedded Class `````````````````````` -You then use the custom GeoPoint class in your Realm object model, as shown in +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/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 index 4a590f5b7b..4264428a9d 100644 --- 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 @@ -14,5 +14,5 @@ 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 schema. -The ``_Address`` model is embedded within the ``_Person`` model. +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/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 index e8f21a896c..09a988c615 100644 --- 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 @@ -10,8 +10,8 @@ or implement :java-sdk:`RealmModel `. **Extend RealmObject** The following code block shows a Realm object that -describes a Frog. This Frog class can be stored in -Realm because it ``extends`` the ``RealmObject`` class. +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 @@ -19,7 +19,7 @@ Realm because it ``extends`` the ``RealmObject`` class. The following code block shows a Realm object that describes a Frog. This Frog class can -be stored in Realm because it ``implements`` the +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 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 index 6f59ed38b4..2749ea4e31 100644 --- 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 @@ -6,7 +6,7 @@ In JavaScript, to create a class that conforms to the GeoJSON spec, you: #. 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 realm schema. + property in the object schema. - A field of type ``string`` that maps to a "type" property. The value of this field must be "Point". 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 index 947671fbd7..b6bf6079f8 100644 --- 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 @@ -1,3 +1,3 @@ In the Kotlin SDK, to define an asymmetric object type, create a Kotlin class -that implements the :kotlin-sdk:`AsymmetricRealmObject +that implements the :kotlin-sync-sdk:`AsymmetricRealmObject ` 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 index 025872afe0..c48b1cd2b3 100644 --- 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 @@ -10,7 +10,7 @@ In the Kotlin SDK, to create a class that conforms to the GeoJSON spec, you: with the value of ``"Point"``: ``var type: String = "Point"`` - A field of type ``RealmList`` that maps to a ``coordinates`` - property in the realm schema containing a latitude/longitude + 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 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 index 34bb37f0eb..f00104b3b8 100644 --- 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 @@ -11,7 +11,7 @@ database: 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 a realm: +persisted name to used to store objects in the database: .. literalinclude:: /examples/generated/kotlin/Schema.snippet.define-persisted-class.kt :language: kotlin 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 index a5d6e9def0..896d7d0db5 100644 --- 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 @@ -6,7 +6,7 @@ In TypeScript, to create a class that conforms to the GeoJSON spec, you: #. 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 realm schema. + property in the object schema. - A field of type ``string`` that maps to a "type" property. The value of this field must be "Point". diff --git a/source/sdk/model-data/object-models.txt b/source/sdk/model-data/object-models.txt index db5e764721..ac8057081b 100644 --- a/source/sdk/model-data/object-models.txt +++ b/source/sdk/model-data/object-models.txt @@ -612,10 +612,10 @@ To persist ``GeoPoint`` data, it must conform to the These types can only be used as arguments for geospatial queries. -.. _sdks-define-special-property-types: +.. _sdks-define-property-behaviors: -Define Special 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