Add info about sectioned results and projections

Author: dacharyc

source/includes/api-details/generic/crud/read-query-projections-not-supported.rst

@@ -0,0 +1 @@
+The selected language does not currently support the class projection APIs.

source/includes/api-details/generic/crud/read-section-query-results-not-supported.rst

@@ -0,0 +1,3 @@
+The selected language does not currently support the sectioned results APIs.
+Instead, you can manually define logic to display only a subset of query
+results based on the needs of your app.

source/includes/api-details/objectivec/crud/read-query-projections-missing-description.rst

@@ -0,0 +1,2 @@
+The documentation does not currently have information for how to query
+class projections in Objective-C.

source/includes/api-details/objectivec/crud/read-section-query-results-description.rst

@@ -0,0 +1,14 @@
+In Objective-C, you can create a :objc-sdk:`RLMSectionedResults
+<Classes/RLMSectionedResults.html>` type-safe collection in two ways:
+
+- Using a keyPath: :objc-sdk:`-sectionedResultsSortedUsingKeyPath:ascending:keyBlock:
+  <Protocols/RLMCollection.html#/c:objc(pl)RLMCollection(im)sectionedResultsSortedUsingKeyPath:ascending:keyBlock:>`
+- Using a sort descriptor: :objc-sdk:`-sectionedResultsUsingSortDescriptors:keyBlock:
+  <Protocols/RLMCollection.html#/c:objc(pl)RLMCollection(im)sectionedResultsUsingSortDescriptors:keyBlock:>`
+
+You can get a count of the sections, get a list of keys, or access an individual
+:objc-sdk:`RLMSectionedResult segment <Protocols/RLMSectionedResult.html>` by
+key or index.
+
+You can :ref:`observe <sdks-react-to-changes>` ``RLMSectionedResults`` and
+``RLMSectionedResult`` instances.

source/includes/api-details/swift/crud/read-query-projections-description.rst

@@ -0,0 +1,8 @@
+To query for class projections, pass the metatype instance
+``YourProjectionName.self`` to :swift-sdk:`Realm.objects(_:)
+<Structs/Realm.html#/s:10RealmSwift0A0V7objectsyAA7ResultsVyxGxmSo0aB6ObjectCRbzlF>`.
+This returns a :swift-sdk:`Results <Structs/Results.html>` object
+representing all of the class projection objects in the database.
+
+.. literalinclude:: /examples/generated/code/start/ClassProjection.snippet.retrieve-data-through-class-projection.swift
+   :language: swift

source/includes/api-details/swift/crud/read-section-query-results-description.rst

@@ -0,0 +1,29 @@
+For example, you might add a computed variable to your object to get the 
+first letter of the ``name`` property:
+
+.. literalinclude:: /examples/generated/code/start/ReadRealmObjects.snippet.sectioned-result-variable.swift
+   :language: swift
+
+Then, you can create a :swift-sdk:`SectionedResults <Structs/SectionedResults.html>`
+type-safe collection for that object, and use it to retrieve objects sectioned
+by that computed variable: 
+
+.. literalinclude:: /examples/generated/code/start/ReadRealmObjects.snippet.get-sectioned-results.swift
+   :language: swift
+
+You can get a count of the sections, get a list of keys, or access an individual
+:swift-sdk:`ResultSection <Structs/ResultsSection.html>` by index:
+
+.. literalinclude:: /examples/generated/code/start/ReadRealmObjects.snippet.section-query-results.swift
+   :language: swift
+
+You can also section using a callback. This enables you to section a 
+collection of primitives, or have more control over how the section key is 
+generated.
+
+.. literalinclude:: /examples/generated/code/start/ReadRealmObjects.snippet.section-query-results-callback.swift
+   :language: swift
+
+You can :ref:`observe <sdks-react-to-changes>` ``SectionedResults`` and
+``ResultsSection`` instances, and both conform to 
+:swift-sdk:`ThreadConfined <Protocols/ThreadConfined.html>`.

source/sdk/crud/read.txt

@@ -766,11 +766,132 @@ specified numerical property or collection.
 Section Query Results
 ~~~~~~~~~~~~~~~~~~~~~
 
+Some of the SDK languages provide an API to split results collections into
+individual sections. Each section corresponds to a key generated from a
+property on the object it represents. This simplifies working with logical
+subsets of query results.
+
+.. tabs-drivers::
+
+   .. tab::
+      :tabid: cpp-sdk
+
+      .. include:: /includes/api-details/generic/crud/read-section-query-results-not-supported.rst
+
+   .. tab::
+      :tabid: csharp
+
+      .. include:: /includes/api-details/generic/crud/read-section-query-results-not-supported.rst
+      
+   .. tab::
+      :tabid: dart
+
+      .. include:: /includes/api-details/generic/crud/read-section-query-results-not-supported.rst
+
+   .. tab::
+      :tabid: java
+
+      .. include:: /includes/api-details/generic/crud/read-section-query-results-not-supported.rst
+
+   .. tab::
+      :tabid: java-kotlin
+
+      .. include:: /includes/api-details/generic/crud/read-section-query-results-not-supported.rst
+
+   .. tab::
+      :tabid: javascript
+
+      .. include:: /includes/api-details/generic/crud/read-section-query-results-not-supported.rst
+
+   .. tab::
+      :tabid: kotlin
+
+      .. include:: /includes/api-details/generic/crud/read-section-query-results-not-supported.rst
+
+   .. tab::
+      :tabid: objectivec
+
+      .. include:: /includes/api-details/objectivec/crud/read-section-query-results-description.rst
+
+   .. tab::
+      :tabid: swift
+
+      .. include:: /includes/api-details/swift/crud/read-section-query-results-description.rst
+
+   .. tab::
+      :tabid: typescript
+
+      .. include:: /includes/api-details/generic/crud/read-section-query-results-not-supported.rst
+
 .. _sdks-read-query-projections:
 
 Query Projections
 ~~~~~~~~~~~~~~~~~
 
+If your app defines a :ref:`class projection <sdks-define-model-projection>`
+to work with persisted data in a different way in a view model or based on
+certain business logic, you can query on that projection.
+
+.. tabs-drivers::
+
+   .. tab::
+      :tabid: cpp-sdk
+
+      .. include:: /includes/api-details/generic/crud/read-query-projections-not-supported.rst
+
+   .. tab::
+      :tabid: csharp
+
+      .. include:: /includes/api-details/generic/crud/read-query-projections-not-supported.rst
+      
+   .. tab::
+      :tabid: dart
+
+      .. include:: /includes/api-details/generic/crud/read-query-projections-not-supported.rst
+
+   .. tab::
+      :tabid: java
+
+      .. include:: /includes/api-details/generic/crud/read-query-projections-not-supported.rst
+
+   .. tab::
+      :tabid: java-kotlin
+
+      .. include:: /includes/api-details/generic/crud/read-query-projections-not-supported.rst
+
+   .. tab::
+      :tabid: javascript
+
+      .. include:: /includes/api-details/generic/crud/read-query-projections-not-supported.rst
+
+   .. tab::
+      :tabid: kotlin
+
+      .. include:: /includes/api-details/generic/crud/read-query-projections-not-supported.rst
+
+   .. tab::
+      :tabid: objectivec
+
+      .. include:: /includes/api-details/objectivec/crud/read-query-projections-missing-description.rst
+
+   .. tab::
+      :tabid: swift
+
+      .. include:: /includes/api-details/swift/crud/read-query-projections-description.rst
+
+   .. tab::
+      :tabid: typescript
+
+      .. include:: /includes/api-details/generic/crud/read-query-projections-not-supported.rst
+
+.. tip::
+
+   Don't do derived queries on top of class projection results. Instead, run a 
+   query against the SDK object directly and then project the result. If you 
+   try to do a derived query on top of class projection results, querying a 
+   field with the same name and type as the original object works, but querying 
+   a field with a name or type that isn't in the original object fails.
+
 .. _sdks-read-filter-by-property-type:
 
 Filter by Property Type