From 7c6523fc68b56456a16d60326cce6862f380ac17 Mon Sep 17 00:00:00 2001 From: cbullinger Date: Thu, 29 Feb 2024 18:53:08 -0500 Subject: [PATCH] Update Flutter SDK docs with nested collections --- source/sdk/flutter/crud/read.txt | 35 +++++++++-- .../realm-database/model-data/data-types.txt | 61 ++++++++++++++----- .../model-data/define-realm-object-schema.txt | 22 +++++++ 3 files changed, 100 insertions(+), 18 deletions(-) diff --git a/source/sdk/flutter/crud/read.txt b/source/sdk/flutter/crud/read.txt index 7ac0f1bd551..0ca83cbe1da 100644 --- a/source/sdk/flutter/crud/read.txt +++ b/source/sdk/flutter/crud/read.txt @@ -195,15 +195,37 @@ relationship. The following examples use the models defined on the .. _flutter-query-list-realm-objects: -Query Lists -~~~~~~~~~~~ +Query Collections +~~~~~~~~~~~~~~~~~ + +.. versionchanged:: v2.0.0 + Query nested collections (``RealmList`` or ``RealmMap``) of mixed data + +You can query collections of :flutter-sdk:`RealmObjects ` +or primitives. This includes: + +- ``RealmList`` +- ``RealmMap`` +- ``RealmSet`` + +In Flutter SDK v2.0.0 and later, you can also query nested collections of mixed ``RealmValue`` data + +Query RealmLists +```````````````` -You can query any list of :flutter-sdk:`RealmObjects ` -or primitives. +You can query any list of .. literalinclude:: /examples/generated/flutter/read_write_data_test.snippet.query-realm-list.dart :language: dart +Query RealmMaps +```````````````` + +.. _flutter-query-set-realm-objects: + +Query RealmSets +```````````````` + .. _flutter-as-results: Convert Lists or Sets to Results @@ -241,6 +263,11 @@ You can use iterable arguments in your filter. For example: .. literalinclude:: /examples/generated/flutter/read_write_data_test.snippet.filter-iterable.dart :language: dart +Filter Nested Collections + +Filter Inverse Relationships +```````````````````````````` + You can also filter by inverse relationships using the ``@links..`` syntax. For example, a filter can match a ``Task`` object based on properties of the ``User`` diff --git a/source/sdk/flutter/realm-database/model-data/data-types.txt b/source/sdk/flutter/realm-database/model-data/data-types.txt index 56a0c7b55c8..1ec0862be4b 100644 --- a/source/sdk/flutter/realm-database/model-data/data-types.txt +++ b/source/sdk/flutter/realm-database/model-data/data-types.txt @@ -5,9 +5,13 @@ Data Types - Flutter SDK ======================== .. meta:: - :keywords: code example, flutter + :keywords: code example :description: Learn about the data types Atlas Device SDK for Flutter supports and how to use them. +.. facet:: + :name: genre + :values: tutorial + .. contents:: On this page :local: :backlinks: none @@ -151,9 +155,9 @@ When defining a RealmSet in a schema: - A set of primitive types can be defined as either nullable or non-nullable. For example, both ``Set`` and ``Set`` are valid in a Realm schema. - A set of ``RealmObject`` and ``RealmValue`` types can only be non-nullable. - For example ``Set`` **is valid** and ``Set`` **is not valid**. -- You **cannot** define default values when defining a set in a schema. - For example, ``Set mySet = {0,1,2}`` **is not valid**. + For example ``Set`` is valid, but ``Set`` *is not* valid. +- You *cannot* define default values when defining a set in a schema. + For example, ``Set mySet = {0,1,2}`` *is not* valid. .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-set-model.dart :language: dart @@ -238,10 +242,10 @@ Collections are Live Like :ref:`live objects `, Realm collections are *usually* live: -- Live **results collections** always reflect the current results of the associated query. -- Live **lists** of ``RealmObjects`` always reflect the current state of the relationship on the realm instance. +- **Live results collections** always reflect the current results of the associated query. +- **Live lists** of ``RealmObjects`` always reflect the current state of the relationship on the realm instance. -There are two cases, however, when a collection is **not** live: +There are two cases, however, when a collection is *not* live: - The collection is unmanaged: a ``RealmList`` property of a Realm object that has not been added to a realm yet or that has been copied from a @@ -339,18 +343,24 @@ following things are true when using ``compareTo()``: RealmValue ~~~~~~~~~~ +.. versionchanged:: 2.0.0 + ``RealmValue`` can be a ``List`` or ``Map`` of ``RealmValue`` type. + ``RealmValueType`` enum and ``RealmValue.value.runtimeType`` added. + ``RealmValue.binary`` replaces ``RealmValue.uint8List``. + The `RealmValue `__ -data type is a mixed data type that can represent any other valid Realm data type except a collection. -You can create collections of type ``RealmValue``, but a ``RealmValue`` itself -cannot be a collection. ``RealmValue`` is indexable, but cannot be a primary key. +data type is a mixed data type that can represent any other valid Realm +data type. In Flutter SDK v2.0.0 and later, ``RealmValue`` can represent a List or Map collection (but *not* a Set) of mixed type. -.. note:: +``RealmValue`` is indexable, but cannot be a primary key. You can also create collections of type ``RealmValue``. + +.. note:: ``RealmValue`` Not Nullable But Can Contain Null Values When defining your Realm object schema, you cannot create a nullable ``RealmValue``. However, if you want a ``RealmValue`` property to contain a null value, you can use the special ``RealmValue.nullValue()`` property. -To define a property as ``RealmValue``, set its type in your Realm object model. +To define a property as ``RealmValue``, set its type in your object model. .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-model.dart :language: dart @@ -360,7 +370,30 @@ To add a ``RealmValue`` to a Realm object, call ``RealmValue.from()`` on the dat .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-from.dart :language: dart -Access the type of data with ``RealmValue.type`` and the value with ``RealmValue.value``. +In Flutter SDK v2.0.0 and later, you access the type of data with the ``RealmValueType`` enum and the value with ``RealmValue.value``. You can also access the runtime type of the value with ``RealmValue.value.runtimeType``. + +In earlier SDK versions, you access the type of data with ``RealmValue.type``. + +.. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-type-value.dart + :language: dart + +.. _flutter-nested-collections-realm-value: + +Nested Collections of RealmValue +```````````````````````````````` + +.. versionadded:: v2.0.0 + +Starting in Flutter SDK version 2.0.0, a ``RealmValue`` data type can contain nested collections (a list or map) of ``RealmValue`` type: + +- ``RealmValue>`` +- ``RealmValue>`` + +It *cannot* contain a set of mixed type. + +You can use nested collections of mixed type to define unstructured or variable data. For more information, refer to :ref:``. + +You can work with nested collections like a normal collection of mixed type. .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-type-value.dart :language: dart @@ -371,7 +404,7 @@ Uint8List `Uint8List `__ is a binary data type from `dart:typed_data `__. -You can use this binary data type in object models and property values. +You can use this data type in object models and property values. To define a property as ``Uint8List``, you must first import ``dart:typed_data``. Then, set the object's type as ``Uint8List`` in your :ref:`object model diff --git a/source/sdk/flutter/realm-database/model-data/define-realm-object-schema.txt b/source/sdk/flutter/realm-database/model-data/define-realm-object-schema.txt index fdb94d03223..c24cddde61b 100644 --- a/source/sdk/flutter/realm-database/model-data/define-realm-object-schema.txt +++ b/source/sdk/flutter/realm-database/model-data/define-realm-object-schema.txt @@ -6,6 +6,7 @@ Define a Realm Object Schema - Flutter SDK .. meta:: :keywords: code example, android, ios, data modeling + :description: Define the properties and relationships of database objects within your data model. .. facet:: :name: genre @@ -233,6 +234,27 @@ If you're using Atlas Device Sync, the name that you specify in the :language: dart :emphasize-lines: 15-16 +.. _flutter-model-unstructured-data: + +Model Unstructured Data +----------------------- + +.. versionadded:: 2.0.0 + +Starting in Flutter SDK version 2.0.0, you can leverage nested collections within a :ref:`RealmValue (Mixed) ` type to define data that doesn't otherwise conform to an expected schema. +This could include data with variable structures or data whose shape or type is not known at runtime. For example, user-created objects, event logs, or survey response data that are collected and stored in a variety of JSON formats. Collections of mixed data could also be a good temporary option when you're in the early development stages and still determining the structure of your app's data. + +To model unstructured data in your schema, define the appropriate properties as ``RealmValue`` types that contain either a List or Map of ``RealmValue`` type: +``RealmValue>`` or ``RealmValue>``. +The SDK does *not* support a Mixed data type containing a Set collection. + +.. 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. + +.. define a generic JSON structure to use across all SDK examples and add to doc plan/tickets + .. _flutter-generate-realm-object: Generate the RealmObject