From 55414280247fe51fe800d73bd0886837b780144f Mon Sep 17 00:00:00 2001 From: cbullinger Date: Wed, 20 Mar 2024 17:10:38 -0400 Subject: [PATCH] Apply Lindsey feedback --- examples/dart/test/data_types_test.dart | 2 ++ examples/dart/test/read_write_data_test.dart | 12 +++---- ...a_types_test.snippet.realm-value-type.dart | 2 ++ ...est.snippet.filter-nested-collections.dart | 11 +++---- source/sdk/flutter/crud/read.txt | 19 +++++++++-- .../realm-database/model-data/data-types.txt | 32 ++++++++++++------- .../model-data/define-realm-object-schema.txt | 3 ++ 7 files changed, 53 insertions(+), 28 deletions(-) diff --git a/examples/dart/test/data_types_test.dart b/examples/dart/test/data_types_test.dart index 30099f36212..fa854a5009c 100644 --- a/examples/dart/test/data_types_test.dart +++ b/examples/dart/test/data_types_test.dart @@ -225,7 +225,9 @@ main() { final data = realm.all(); for (var obj in data) { final anyValue = obj.singleAnyValue; + // Access the RealmValue.type property switch (anyValue.type) { + // Work with the returned RealmValueType enums case RealmValueType.int: approximateAge = DateTime.now().year - anyValue.as(); break; diff --git a/examples/dart/test/read_write_data_test.dart b/examples/dart/test/read_write_data_test.dart index aa10330d960..4eba0584bf0 100644 --- a/examples/dart/test/read_write_data_test.dart +++ b/examples/dart/test/read_write_data_test.dart @@ -205,28 +205,24 @@ void main() { ]); final teams = realm.all(); - // Use [bracket notation] to query values at the specified path + // Use bracket notation to query values at the specified path final teamsWithHighPriorityEvents = + // Check any element at that path with [*] teams.query("eventLog[*].priority == 'high'"); print(teamsWithHighPriorityEvents.length); // prints `2` final teamsWithMaintenanceEvents = + // Check for the first element at that path with [FIRST] teams.query("eventLog[*].type[FIRST] == 'maintenance'"); print(teamsWithMaintenanceEvents.length); // prints `1` - // Use @keys to query map keys - final eventsWithComments = - teams.query("eventLog[*].@keys == 'comment'"); - print(eventsWithComments.length); // prints `1` - - // Use @type to query the collection type final teamsWithEventsAsLists = + // Check the collection type with @type teams.query("eventLog[*].type.@type == 'list'"); print(teamsWithEventsAsLists.length); // prints `2` // :remove-start: expect(teamsWithHighPriorityEvents.length, 2); expect(teamsWithMaintenanceEvents.length, 1); - expect(eventsWithComments.length, 1); expect(teamsWithEventsAsLists.length, 2); // :remove-end: }); diff --git a/source/examples/generated/flutter/data_types_test.snippet.realm-value-type.dart b/source/examples/generated/flutter/data_types_test.snippet.realm-value-type.dart index 4178077f271..90c402a68e1 100644 --- a/source/examples/generated/flutter/data_types_test.snippet.realm-value-type.dart +++ b/source/examples/generated/flutter/data_types_test.snippet.realm-value-type.dart @@ -1,7 +1,9 @@ final data = realm.all(); for (var obj in data) { final anyValue = obj.singleAnyValue; + // Access the RealmValue.type property switch (anyValue.type) { + // Work with the returned RealmValueType enums case RealmValueType.int: approximateAge = DateTime.now().year - anyValue.as(); break; diff --git a/source/examples/generated/flutter/read_write_data_test.snippet.filter-nested-collections.dart b/source/examples/generated/flutter/read_write_data_test.snippet.filter-nested-collections.dart index 6ae7aabbc1d..e559d1d468f 100644 --- a/source/examples/generated/flutter/read_write_data_test.snippet.filter-nested-collections.dart +++ b/source/examples/generated/flutter/read_write_data_test.snippet.filter-nested-collections.dart @@ -28,22 +28,19 @@ realm.write(() { ]); final teams = realm.all(); - // Use [bracket notation] to query values at the specified path + // Use bracket notation to query values at the specified path final teamsWithHighPriorityEvents = + // Check any element at that path with [*] teams.query("eventLog[*].priority == 'high'"); print(teamsWithHighPriorityEvents.length); // prints `2` final teamsWithMaintenanceEvents = + // Check for the first element at that path with [FIRST] teams.query("eventLog[*].type[FIRST] == 'maintenance'"); print(teamsWithMaintenanceEvents.length); // prints `1` - // Use @keys to query map keys - final eventsWithComments = - teams.query("eventLog[*].@keys == 'comment'"); - print(eventsWithComments.length); // prints `1` - - // Use @type to query the collection type final teamsWithEventsAsLists = + // Check the collection type with @type teams.query("eventLog[*].type.@type == 'list'"); print(teamsWithEventsAsLists.length); // prints `2` }); diff --git a/source/sdk/flutter/crud/read.txt b/source/sdk/flutter/crud/read.txt index 109307d6fe9..b5d8470bf68 100644 --- a/source/sdk/flutter/crud/read.txt +++ b/source/sdk/flutter/crud/read.txt @@ -214,8 +214,23 @@ Query Nested Collections of Mixed Data In Flutter SDK v2.0.0 and later, :ref:`RealmValue ` properties can contain collections (a list or map) of mixed data. These collections can be nested within collections and can contain other -collections of mixed data. You can query these with dot notation, the -same way you would a normal collection. You can also use bracket notation to query a specific element in the collection (for example, ``[FIRST]``, ``[1]``, ``[LAST]``, or ``[*]``). +collections of mixed data. + +You can query these using the same RQL operators and syntax as you would for a +normal list or dictionary. Refer to the :ref:`rql` documentation for more +information. + +For nested collections, you can also use: + +- Bracket notation, which provides additional collection query support: + - ``[FIRST]`` and [``LAST``] - match the first or last elements within the collection + - ``[]`` - match the element at the specific index + - ``[*]`` - match any elements within the collection + - ``[SIZE]`` - match the collection length +- The ``@type`` operator, which has the following possible values: + - ``array`` and ``list`` - match a list collection + - ``dictionary`` and ``object`` - match a map collection + - ``collection`` - matches a list or a map collection .. literalinclude:: /examples/generated/flutter/read_write_data_test.snippet.filter-nested-collections.dart :language: dart 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 3dfb67aac58..8a1a7c4db94 100644 --- a/source/sdk/flutter/realm-database/model-data/data-types.txt +++ b/source/sdk/flutter/realm-database/model-data/data-types.txt @@ -356,8 +356,9 @@ RealmValue - ``RealmValue.type`` is now an enum of ``RealmValueType`` instead of ``Type``. - ``RealmValue.uint8List`` is renamed to ``RealmValue.binary``. - For more information on how to update an existing app from an earlier - version to v2.0.0 or later, refer to :ref:`flutter-upgrade-v2`. +.. TODO: Add this back to above note once upgrade page is available +.. For more information on how to update an existing app from an earlier +.. version to v2.0.0 or later, refer to :ref:`flutter-upgrade-v2`. The `RealmValue `__ data type is a mixed data type that can represent any other valid @@ -367,28 +368,37 @@ can represent a ``List`` or ``Map``. ``RealmValue`` is indexable, but cannot be a primary key. You can also create collections of type ``RealmValue``. +Define a RealmValue Property +```````````````````````````` + +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 + .. 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 object model. - -.. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-model.dart - :language: dart +Create a RealmValue +``````````````````` To add a ``RealmValue`` to a Realm object, call ``RealmValue.from()`` on the data or ``RealmValue.nullValue()`` to set a null value. .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-from.dart :language: dart + + .. _flutter-access-realm-value-type: Access RealmValue Data Type ``````````````````````````` .. versionchanged:: 2.0.0 + ``RealmValueType`` enum replaces ``RealmValue.type``. ``RealmValue.binary`` replaces ``RealmValue.uint8List``. @@ -399,16 +409,16 @@ To access the data stored in a ``RealmValue``, you can use: .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-value.dart :language: dart - :emphasize-lines: 3, 11 + :emphasize-lines: 4, 13 You can check the type of data currently stored in a ``RealmValue`` property by -accessing the type property. Starting with Flutter SDK v2.0.0, this returns a +accessing the ``type`` property. Starting with Flutter SDK v2.0.0, this returns a ``RealmValueType`` enum. In earlier SDK versions, the SDK returned a ``RealmValue.value.runtimeType``. .. literalinclude:: /examples/generated/flutter/data_types_test.snippet.realm-value-type.dart :language: dart - :emphasize-lines: 4 + :emphasize-lines: 7, 10, 16 .. _flutter-nested-collections-realm-value: @@ -425,8 +435,8 @@ collections. They can also be :ref:`listened to for changes like a normal collection `. You can leverage these nested collections to define unstructured -or variable data in your data model (for more information, refer to -:ref:``). +or variable data in your data model. For more information, refer to +:ref:``. To create nested collections of mixed data in your app, define the mixed type property in your data model the same way you would any other ``RealmValue`` type. 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 a6b07975d10..6560dad7e3e 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 @@ -268,8 +268,11 @@ data when modeling a variable event log object: .. literalinclude:: /examples/generated/flutter/define_realm_model_test.snippet.unstructured-data-model.dart :language: dart + :emphasize-lines: 9 + :caption: EventLog data model .. io-code-block:: + :copyable: true .. input:: /examples/generated/flutter/define_realm_model_test.snippet.create-unstructured-data-example.dart :language: dart