(DOCSP-39514): Consolidate Read page

snooty.toml

@@ -11,6 +11,7 @@ intersphinx = [
 toc_landing_pages = [
  # New IA
  "/sdk/crud/create",
+ "/sdk/crud/read",
  "/sdk/platforms/android",
  "/sdk/platforms/apple",
  "/sdk/platforms/unity",

source/includes/api-details/cpp/crud/read-access-results-description.rst

@@ -0,0 +1,7 @@
+In C++, the :cpp-sdk:`Results <structrealm_1_1results.html>` type exposes member 
+functions to work with results. You may want to check the ``.size()`` of a
+results set, or access the object at a specific index.
+
+Additionally, you can iterate through the results, or observe a results
+set for changes. For more details about observing the results for changes,
+refer to :ref:`sdks-react-to-changes`.

source/includes/api-details/cpp/crud/read-aggregate-not-supported.rst

@@ -0,0 +1 @@
+C++ does not currently support aggregate operators.

source/includes/api-details/cpp/crud/read-all-objects-of-type-description.rst

@@ -0,0 +1,6 @@
+To query for objects of a given type in the database, pass the object type 
+``YourClassName`` to the :cpp-sdk:`db::objects\<T\> <structrealm_1_1db.html>`
+member function.
+
+This returns a :cpp-sdk:`Results <structrealm_1_1results.html>` object
+representing all objects of the given type in the database.

source/includes/api-details/cpp/crud/read-database-objects-procedure.rst

@@ -0,0 +1,25 @@
+To find objects stored within a database:
+
+1. Query for objects of a given type in the database, pass the object type 
+ ``YourClassName`` to the :cpp-sdk:`db::objects <structrealm_1_1db.html>`
+ member function.
+
+#. Optionally, pass any query conditions to further refine the results: 
+
+ - Specify a filter to only return objects that meet the condition. If 
+ you don't specify a filter, the SDK returns all objects of the specified 
+ type.
+
+ - Specify the sort order for the results. 
+ Because the database is unordered, if you don't include a sort order, 
+ the SDK cannot guarantee the query returns objects in any specific order.
+
+#. Work with the results. Objects may be frozen or live, depending on whether
+ you queried a frozen or live database, collection, or object.
+
+Note that any retrieved results don't actually hold matching database objects 
+in memory. Instead, the database uses **direct references**, or pointers. 
+Database objects in a results collection reference the matched objects, which
+map directly to data in the database file. This also means that you can
+traverse your graph of an object's :ref:`relationships <sdks-relationships>`
+directly through the results of a query.

source/includes/api-details/cpp/crud/read-filter-or-query-objects-description.rst

@@ -0,0 +1,11 @@
+To filter data, call the ``.where()`` function on a collection with a valid
+query. Currently, C++ supports only a subset of RQL operators.
+
+Supported Query Operators
+`````````````````````````
+
+C++ supports the following query operators:
+
+- Equality (``==``, ``!=``)
+- Greater than/less than (``>``, ``>=``, ``<``, ``<=``)
+- Compound queries (``||``, ``&&``)

source/includes/api-details/cpp/crud/read-find-object-by-primary-key-not-supported.rst

@@ -0,0 +1,3 @@
+C++ does not provide a dedicated API to find an object by its primary
+key. Instead, you can perform a regular query for objects where the primary
+key property matches the desired primary key value.

source/includes/api-details/cpp/crud/read-intro-description.rst

@@ -0,0 +1,7 @@
+Query operationsn return a :cpp-sdk:`results collection
+<structrealm_1_1results.html>`. Results collections may be either live or
+frozen.
+
+- **Live results** always contain the latest results of the associated query.
+- **Frozen results** represent a snapshot that cannot be modified and doesn't
+ reflect the latest changes to the database.

source/includes/api-details/cpp/crud/read-limit-not-supported.rst

@@ -0,0 +1,3 @@
+C++ does not provide an API to limit query results. Instead, rely on the
+SDK's lazy loading characteristics to implicitly limit the objects in
+memory by only accessing the objects you need for an operation.

source/includes/api-details/cpp/crud/read-query-dictionary-properties-description.rst

@@ -0,0 +1,3 @@
+You can iterate and check the values of a realm :cpp-sdk:`map property
+<structrealm_1_1managed_3_01std_1_1map_3_01std_1_1string_00_01T_01_4_00_01void_01_4.html>` 
+as you would a standard C++ `map <https://en.cppreference.com/w/cpp/container/map>`__.

source/includes/api-details/cpp/crud/read-query-list-properties-description.rst

@@ -0,0 +1,6 @@
+You can read, query, and sort a :cpp-sdk:`list
+<structrealm_1_1managed_3_01std_1_1vector_3_01T_01_5_01_4_01_4.html>` similar
+to working with a :cpp-sdk:`results
+<structrealm_1_1internal_1_1bridge_1_1results.html>` collection. You can also
+work with a list as a results set by calling the ``as_results()`` public member
+function of the managed list class.

source/includes/api-details/cpp/crud/read-query-mixed-properties-description.rst

@@ -0,0 +1,6 @@
+The C++ ``mixed`` data type is a union-like object that can represent a value
+any of the supported types. It is implemented using the class template 
+`std::variant <https://en.cppreference.com/w/cpp/utility/variant>`__.
+This implementation means that a ``mixed`` property holds a value of 
+one of its alternative types, or in the case of error - no value.
+Your app must handle the type when reading mixed properties.

source/includes/api-details/cpp/crud/read-query-set-properties-description.rst

@@ -0,0 +1,3 @@
+You can iterate, check the size of a set, and find values in a
+:cpp-sdk:`set property
+<structrealm_1_1managed_3_01std_1_1set_3_01T_01_5_01_4_01_4.html>`.

source/includes/api-details/cpp/crud/read-sdk-results-collections-description.rst

@@ -0,0 +1,20 @@
+The SDK's :cpp-sdk:`realm::results\<T\> <structrealm_1_1results.html>`
+collection is a struct representing objects retrieved from queries. A results
+collection represents the lazily-evaluated results of a query operation, and
+has these characteristics:
+
+- Results are immutable: you cannot manually add or remove elements to or from
+ the results collection.
+- Results have an associated query that determines their contents.
+- Results are **live** or **frozen** based on the query source. If they derive
+ from live objects, the results automatically update when the database
+ contents change. If they derive from frozen objects, they represent only a
+ snapshot and do not automatically update.
+- You cannot manually initialize an empty results set. Results can only
+ be initialized:
+
+ - As the result of a query.
+ - From a managed :ref:`list <sdks-read-list>`, using the
+ :cpp-sdk:`as_results()
+ <structrealm_1_1managed_3_01std_1_1vector_3_01T_01_5_01_4_01_4.html>`
+ member funcion.

source/includes/api-details/cpp/crud/read-sort-description.rst

@@ -0,0 +1,22 @@
+Unlike using `std::sort <https://en.cppreference.com/w/cpp/algorithm/sort>`__, 
+the SDK's sort implementation preserves the lazy loading of objects. It does
+not pull the entire set of results or list objects into memory, but only
+loads them into memory when you access them.
+
+To sort, call the ``.sort()`` function on a list or results set with one or more 
+:cpp-sdk:`sort_descriptors <structrealm_1_1internal_1_1bridge_1_1sort__descriptor.html>`.
+
+A ``sort_descriptor`` includes:
+
+- The desired key path to sort by, as a string.
+- A bool to specify sort order, where``true`` is ascending and ``false`` 
+ is descending.
+
+In this example, we sort a results set on ``priority`` in descending order.
+
+.. literalinclude:: /examples/generated/cpp/filter-data.snippet.sort-results-by-single-property.cpp
+ :language: cpp
+
+You can also sort a list or results set by multiple sort descriptors. In 
+this example, we sort a list property on ``assignee`` in ascending order, 
+and then on ``priority`` in descending order. 

source/includes/api-details/csharp/crud/read-access-results-description.rst

@@ -0,0 +1,5 @@
+In C#, the ``Realm.All<T>()`` method returns an ``IQueryable<T>`` instance.
+You can apply additional operators to work with the results.
+
+For a complete list of the available operators, refer to
+:dotnet-sdk:`LINQ support <linqsupport.html>` in the API reference.

source/includes/api-details/csharp/crud/read-aggregate-description.rst

@@ -0,0 +1,9 @@
+In C#, aggregations use the 
+:dotnet-sdk:`Filter() <reference/Realms.CollectionExtensions.html?q=Filter>` 
+method, which can be used to create more complex queries that are currently 
+unsupported by the LINQ provider.
+
+For more information on the available aggregate operators, refer to the 
+:ref:`Realm Query Language aggregate operator reference <rql-aggregate-operators>`.
+
+The following examples show different ways to aggregate data.

source/includes/api-details/csharp/crud/read-all-objects-of-type-description.rst

@@ -0,0 +1,3 @@
+To read all objects of a certain type, call
+:dotnet-sdk:`Realm.All\<T\> <reference/Realms.Realm.html#Realms_Realm_All__1>`,
+where ``T`` is the SDK object type.

source/includes/api-details/csharp/crud/read-database-objects-procedure.rst

@@ -0,0 +1,25 @@
+To find objects stored within a database:
+
+1. Query for objects of a given type in the database. Pass the object type 
+ to the :dotnet-sdk:`Realm.All\<T\> <reference/Realms.Realm.html#Realms_Realm_All__1>`
+ method.
+
+#. Optionally, pass any query conditions to further refine the results: 
+
+ - Specify a filter to only return objects that meet the condition. If 
+ you don't specify a filter, the SDK returns all objects of the specified 
+ type.
+
+ - Specify the sort order for the results. 
+ Because the database is unordered, if you don't include a sort order, 
+ the SDK cannot guarantee the query returns objects in any specific order.
+
+#. Work with the results. Objects may be frozen or live, depending on whether
+ you queried a frozen or live database, collection, or object.
+
+Note that any retrieved results don't actually hold matching database objects 
+in memory. Instead, the database uses **direct references**, or pointers. 
+Database objects in a results collection reference the matched objects, which
+map directly to data in the database file. This also means that you can
+traverse your graph of an object's :ref:`relationships <sdks-relationships>`
+directly through the results of a query.

source/includes/api-details/csharp/crud/read-define-geospatial-shapes-box-description.rst

@@ -0,0 +1,12 @@
+A :dotnet-sdk:`GeoBox <reference/Realms.GeoBox.html>` is a
+rectangular shape whose bounds are determined by :dotnet-sdk:`GeoPoint
+<reference/Realms.GeoPoint.html>` coordinates for a bottom-left
+and a top-right corner.
+
+In C#, you can optionally construct a ``GeoBox`` from a set of four doubles,
+which represent:
+
+- ``left``: The longitude of the left edge of the rectangle.
+- ``top``: The latitude of the top edge of the rectangle.
+- ``right``: The longitude of the right edge of the rectangle.
+- ``bottom``: The latitude of the bottom edge of the rectangle.

source/includes/api-details/csharp/crud/read-define-geospatial-shapes-circle-description.rst

@@ -0,0 +1,13 @@
+A :dotnet-sdk:`GeoCircle <reference/Realms.GeoCircle.html>` is a
+circular shape whose bounds originate from a central :dotnet-sdk:`GeoPoint
+<reference/Realms.GeoPoint.html>`, and has a size corresponding to
+a radius measured in radians. You can use the SDK's convenience
+:dotnet-sdk:`Distance <reference/Realms.Distance.html>` structure to 
+easily work with radii in different units.
+
+You can construct a ``Distance`` with a radius measurement in one of four units:
+
+- ``FromDegrees(double)``
+- ``FromKilometers(double)``
+- ``FromMiles(double)``
+- ``FromRadians(double)``

source/includes/api-details/csharp/crud/read-define-geospatial-shapes-polygon-description.rst

@@ -0,0 +1,12 @@
+A :dotnet-sdk:`GeoPolygon <reference/Realms.GeoPolygon.html>` is a polygon
+shape whose bounds consist of an outer ring, and 0 or more inner holes
+to exclude from the geospatial query. 
+
+A polygon's outer ring must contain at least three segments. The last 
+and the first :dotnet-sdk:`GeoPoint <reference/Realms.GeoPoint.html>`
+must be the same, which indicates a closed polygon. This means that it takes
+at least four ``GeoPoint`` values to construct a polygon.
+
+Inner holes in a ``GeoPolygon`` are optional, and must be entirely contained
+within the outer ring. Each ``GeoPoint`` collection in the ``Holes`` collection
+must contain at least three segments, with the same rules as the outer ring.

source/includes/api-details/csharp/crud/read-filter-full-text-search-property-description.rst

@@ -0,0 +1,11 @@
+In C#, you can query a FTS property using either LINQ or RQL.
+
+To query with LINQ, use :dotnet-sdk:`QueryMethods.FullTextSearch 
+<reference/Realms.QueryMethods.html#Realms_QueryMethods_FullTextSearch_System_String_System_String_>`.
+The following examples query the ``Person.Biography`` field.
+
+.. literalinclude:: /examples/generated/dotnet/Indexing.snippet.linq-query-fts.cs
+ :language: csharp
+
+To query with RQL, use the ``TEXT`` operator. The following example 
+queries the ``Person.Biography`` field.

source/includes/api-details/csharp/crud/read-filter-or-query-objects-description.rst

@@ -0,0 +1,35 @@
+To query, filter, and sort data in the database, use the SDK query engine. 
+There are two ways to use the query engine with C#:
+
+- :ref:`LINQ Syntax <sdks-dotnet-linq>`
+- :ref:`Realm Query Language (RQL) <realm-query-language>`
+
+Use LINQ syntax for querying when possible, as it provides compile-time checks
+for queries and aligns with .NET conventions.
+
+Filter Data with LINQ
+`````````````````````
+
+To filter data with LINQ syntax, call the :dotnet-sdk:`Where()
+<linqsupport.html#restriction-operators>` operator with a
+:dotnet-sdk:`Predicate <linqsupport.html#predicate-operations>` that describes
+the subset of data you want to access.
+
+.. literalinclude:: /examples/generated/dotnet/QueryEngineExamples.snippet.logical.cs
+ :language: csharp
+
+Filter Data with RQL
+````````````````````
+
+You can also use the :ref:`Realm Query Language <realm-query-language>` (RQL) 
+to query realms. RQL is a string-based query language used to access the query 
+engine. When using RQL, you use the 
+:dotnet-sdk:`Filter() <reference/Realms.CollectionExtensions.html?q=Filter>`
+method.
+
+.. important::
+
+ Because :ref:`LINQ <sdks-dotnet-linq>` provides compile-time error checking 
+ of queries, you should use it instead of RQL in most cases. If you require 
+ features beyond LINQ's current capabilities, such as using 
+ :ref:`aggregation <rql-aggregate-operators>`, use RQL.

source/includes/api-details/csharp/crud/read-find-object-by-primary-key-description.rst

@@ -0,0 +1,3 @@
+You can find a specific item by its primary key using the 
+:dotnet-sdk:`Find <reference/Realms.Realm.html#Realms_Realm_Find__1_System_String_>`
+method. The following example finds a single Project.

source/includes/api-details/csharp/crud/read-intro-description.rst

@@ -0,0 +1,7 @@
+:dotnet-sdk:`Query operations <linqsupport.html>`
+return an ``IQueryable<T>``, which represents a collection of all objects
+of the given type in the database. This collection may be either live or frozen.
+
+- **Live results** always contain the latest results of the associated query.
+- **Frozen results** represent a snapshot that cannot be modified and doesn't
+ reflect the latest changes to the database.

source/includes/api-details/csharp/crud/read-limit-description.rst

@@ -0,0 +1,7 @@
+The C# LINQ query engine does not provide an API to limit query results.
+Instead, rely on the SDK's lazy loading characteristics to implicitly limit
+the objects in memory by only accessing the objects you need for an operation.
+
+If you're using the Realm Query Language query engine with C#, you can use
+the :ref:`RQL LIMIT() operator <rql-sort-distinct-limit>` to limit query
+results.

source/includes/api-details/csharp/crud/read-query-dictionary-properties-description.rst

@@ -0,0 +1,9 @@
+You can query and iterate through a :ref:`RealmDictionary <sdks-dictionary-property-types>` 
+property as you would an
+`IDictionary <https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.idictionary-2?view=net-8.0>`__.
+
+The SDK also provides a convenience method to cast an ``IDictionary<T>`` to an
+``IRealmCollection<T>``. To convert a dictionary to an SDK collection, call the
+:dotnet-sdk:`AsRealmCollection\<T\>
+<reference/Realms.CollectionExtensions.html#Realms_CollectionExtensions_AsRealmCollection__1_System_Collections_Generic_IDictionary_System_String___0__>`
+method with the ``IDictionary<T>`` as its argument.

source/includes/api-details/csharp/crud/read-query-geospatial-data-description.rst

@@ -0,0 +1,10 @@
+The SDK provides two specialized non-persistable data types to define shapes:
+
+- :dotnet-sdk:`GeoPoint <reference/Realms.GeoPoint.html>`: A
+ struct that represents the coordinates of a point formed by a pair of
+ doubles consisting of these values:
+
+ - Latitude: ranges between -90 and 90 degrees, inclusive.
+ - Longitude: ranges between -180 and 180 degrees, inclusive.
+- :dotnet-sdk:`Distance <reference/Realms.Distance.html>`: A helper
+ struct to represent and convert a distance.

source/includes/api-details/csharp/crud/read-query-inverse-relationship-description.rst

@@ -0,0 +1,3 @@
+To query an inverse relationship in C#, you cannot use LINQ. Instead, pass a
+string predicate using RQL. The following example shows how you could find
+all Users who have Items that contain the word "oscillator".

source/includes/api-details/csharp/crud/read-query-list-properties-description.rst

@@ -0,0 +1,11 @@
+SDK lists implement the :dotnet-sdk:`IRealmCollection\<T\>
+<reference/Realms.IRealmCollection-1.html>` interface, which provides a range
+of properties and methods to simplify reading and querying from the list.
+You can query an SDK list using the same :ref:`query engines and operators
+<sdks-read-query-objects>` as a results set.
+
+The SDK also provides a convenience method to cast an ``IList<T>`` to an
+``IRealmCollection<T>``. To convert a list to an SDK collection, call the
+:dotnet-sdk:`AsRealmCollection\<T\>
+<reference/Realms.CollectionExtensions.html#Realms_CollectionExtensions_AsRealmCollection__1_System_Collections_Generic_IList___0__>`
+method with the ``IList<T>`` as its argument.

source/includes/api-details/csharp/crud/read-query-mixed-properties-description.rst

@@ -0,0 +1,7 @@
+You can query a :dotnet-sdk:`RealmValue <reference/Realms.RealmValue.html>`
+field just like any other data type. Operators that only work with certain
+types, such as string operators and arithmetic operators, ignore
+values that do not contain that type. Negating such operators matches
+values that do not contain the type. Type queries match the underlying
+type, rather than ``RealmValue``. Arithmetic operators convert numeric
+values implicitly to compare across types.

source/includes/api-details/csharp/crud/read-query-set-properties-description.rst

@@ -0,0 +1,11 @@
+SDK sets implement the :dotnet-sdk:`IRealmCollection\<T\>
+<reference/Realms.IRealmCollection-1.html>` interface, which provides a range
+of properties and methods to simplify reading and querying from the set.
+You can query an SDK set using the same :ref:`query engines and operators
+<sdks-read-query-objects>` as a results set.
+
+The SDK also provides a convenience method to cast an ``ISet<T>`` to an
+``IRealmCollection<T>``. To convert a set to an SDK collection, call the
+:dotnet-sdk:`AsRealmCollection\<T\>
+<reference/Realms.CollectionExtensions.html#Realms_CollectionExtensions_AsRealmCollection__1_System_Collections_Generic_ISet___0__>`
+method with the ``ISet<T>`` as its argument.

source/includes/api-details/csharp/crud/read-query-to-many-relationship-description.rst

@@ -0,0 +1,9 @@
+An application could use the following object schemas to indicate
+that a Person may own multiple Dogs by including them in its ``dog``
+property:
+
+.. literalinclude:: /examples/generated/dotnet/Relationships.snippet.one-to-many.cs
+ :language: csharp
+
+To see the to-many relationship of Person to Dog, you query for the 
+Person and get that person's Dogs.

source/includes/api-details/csharp/crud/read-query-to-one-relationship-description.rst

@@ -0,0 +1,2 @@
+To query a direct relationship, you can use LINQ syntax.
+See the following example for how to query a one-to-one relationship.

source/includes/api-details/csharp/crud/read-query-with-geospatial-shapes-description.rst

@@ -0,0 +1,11 @@
+You can query geospatial data in two ways:
+
+- Using the :dotnet-sdk:`GeoWithin()
+ <reference/Realms.QueryMethods.html#Realms_QueryMethods_GeoWithin_Realms_IEmbeddedObject_Realms_GeoShapeBase_>`
+ operator with the :ref:`LINQ <sdks-dotnet-linq>` query engine.
+- Using the :dotnet-sdk:`Filter()
+ <reference/Realms.CollectionExtensions.html?q=Filter>` method with the
+ :ref:`Realm Query Language <rql-geospatial>` ``geoWithin`` operator.
+
+The examples below show the results of queries using these two ``Company``
+objects.

source/includes/api-details/csharp/crud/read-sdk-results-collections-description.rst

@@ -0,0 +1,13 @@
+The SDK's results collection is a class representing objects retrieved from
+queries. A results collection represents the lazily-evaluated results of a
+query operation, and has these characteristics:
+
+- Results are immutable: you cannot manually add or remove elements to or from
+ the results collection.
+- Results have an associated query that determines their contents.
+- Results are **live** or **frozen** based on the query source. If they derive
+ from live objects, the results automatically update when the database
+ contents change in the isolate context. If they derive from frozen objects,
+ they represent only a snapshot and do not automatically update.
+- You cannot manually initialize an empty results set. Results can
+ only be initialized as the result of a query.

source/includes/api-details/csharp/crud/read-sort-description.rst

@@ -0,0 +1,2 @@
+The following code sorts the projects by name in reverse
+alphabetical order (i.e. "descending" order).