(DOCSP-39503): Consolidate Relationships page #3287

dacharyc · 2024-06-06T17:31:01Z

Pull Request Info - SDK Docs Consolidation

Jira ticket: https://jira.mongodb.org/browse/DOCSP-39503

Staged Page

Relationships

Page Source

Add links to every SDK's pages where you got the SDK-specific information:

PR Author Checklist

Before requesting a review for your PR, please check these items:

Open the PR against the feature-consolidated-sdk-docs branch instead of master
Tag the consolidated page for:
- genre
- meta.keywords
- meta.description

Naming

Update Realm naming and the language around persistence layer/local/device per this document
Include .rst files comply with the naming guidelines

Links and Refs

Create new consolidated SDK ref targets starting with "_sdks-" for relevant sections
Remove or update any SDK-specific refs to use the new consolidated SDK ref targets
Update any Kotlin API links to use the new Kotlin SDK roles

Content

Shared code boxes have snippets or placeholders for all 9 languages
API description sections have API details or a generic placeholder for all 9 languages
Check related pages for relevant content to include
Create a ticket for missing examples in each relevant SDK: Consolidation Gaps epic

Reviewer Checklist

As a reviewer, please check these items:

Shared code example boxes contain language-specific snippets or placeholders for every language
API reference details contain working API reference links or generic content
Realm naming/language has been updated
All relevant content from individual SDK pages is present on the consolidated page

github-actions · 2024-06-06T17:32:22Z

Readability for Commit Hash: a9d25d6

You can see any previous Readability scores (if they exist) by looking
at the comment's history.

Readability scores for changed documents:

source/sdk/model-data/relationships: Grade Level: 11.1, Reading Ease: 45.66

For Grade Level, aim for 8 or below.

For Reading Ease scores, aim for 60 or above:

Score	Difficulty
90-100	Very Easy
80-89	Easy
70-79	Fairly Easy
60-69	Medium
50-59	Fairly Hard
30-49	Hard
0-29	Very Hard

For help improving readability, try Hemingway App.

lindseymoore

Overall, very good! A couple comments to aid in clarity.

lindseymoore · 2024-06-17T21:33:40Z

source/sdk/model-data/relationships.txt

+implicitly "many-to-one" or "many-to-many." The only way to restrict a 
+relationship to "one to one/one to many" instead of "many to one/many 
+to many" is to use an :ref:`embedded object <sdks-embedded-objects>`, 


Suggested change

to many" is to use an :ref:`embedded object <sdks-embedded-objects>`,

to many" is to use an embedded object,

Suggestion: Is it necessary to link to embedded objects twice within this intro?

lindseymoore · 2024-06-17T21:43:54Z

source/sdk/model-data/relationships.txt

Suggestion: I had to Google what 'lazily' meant. Is the technical detail necessary? Or perhaps reword to make clearer.

Suggested change

defines the relationship. The SDK executes read operations lazily as they

come in, so querying a relationship is just as performant as reading a regular

defines the relationship. Querying a relationship is just as performant as reading a regular

Lazily is important, because it means the memory footprint of these relationships does not add substantially to the app's memory requirements until the objects are accessed. I think this is a term that developers will be familiar with, so I don't think it warrants additional explanation and I do think it's important to keep it here.

lindseymoore · 2024-06-17T21:57:53Z

source/sdk/model-data/relationships.txt

+The SDK *does not* inherently limit object references from other 
+objects within the same database. This means that SDK relationships are 
+implicitly "many-to-one" or "many-to-many." The only way to restrict a 


Suggested change

implicitly "many-to-one" or "many-to-many." The only way to restrict a

implicitly "many-to-one" or "many-to-many", so an object can be linked to any number of other objects in the database. The only way to restrict a

Think the extra clarification would be helpful since this is the intro paragraph, and we haven't yet defined what a relationships like 'many-to-one' means.

People who are looking for info about relationships are coming from a relational database. These terms are very common in relational databases and I don't think they need additional explanation here.

lindseymoore · 2024-06-17T22:10:30Z

source/sdk/model-data/relationships.txt

I'm confused by this.

Is an embedded object considered to be in a to-one relationship with the parent object, and that's why it gets deleted? If so, I'm thinking this information might be best left for the embedded object page.

Or are you saying that it is possible for an embedded object to be in a to-one relationship with another object and in that case it will be deleted if set to null? If so, perhaps make this clearer.

Embedded objects are a weird grey area. We don't explicitly define them as a relationship, because they're a different object type and they can't have a lifecycle outside of the parent object. They're not related - they're nested. So we don't say it's a related object - we say it's an embedded object. But we do say right above this:

The only way to restrict a relationship to "one to one/one to many" instead of "many to one/many to many" is to use an embedded object, which is a nested object with exactly one parent.

So - it felt important to call out here that embedded objects do get deleted, in case anyone takes that comment above as an implication that embedded objects behave like related objects.

lindseymoore · 2024-06-17T22:15:55Z

source/sdk/model-data/relationships.txt

Suggested change

and sets are not associated with a query and are declared as a property of the

object model.

and sets are not associated with a query, meaning ... . They are declared as a property of the

object model.

I'm not sure what it would mean that they are not associated with a query. Can you add a little bit more detail?

In relational databases, it may be reasonable to infer that these collection types are transient and come from a query. It's important to distinguish for Realm/Device SDK, these aren't transient collections created by querying, but are defined properties on the model. This is also conceptual information that should be familiar to people who are coming from relational databases, so I don't think it warrants additional explanation here.

lindseymoore · 2024-06-18T21:45:49Z

...ce/includes/api-details/kotlin/model-data/relationships-inverse-relationship-description.rst

+collection property in the parent object whose type is a 
+``RealmList<E>``, ``RealmSet<E>``, or ``RealmDictionary<E>``, where 
+``<E>`` is a ``RealmObject`` object type defined in your data model. 
+This can be a different Realm object type or the same Realm object 


Suggested change

This can be a different Realm object type or the same Realm object

This can be a different object type or the same object

Should Realm be deleted here or is it necessary to differentiate the object types from normal ones?

Yeah, relationships are specifically between Realm objects. I thought about saying "SDK" instead of "Realm" here, but since we have just enumerated the different object types and they are all Realm object types, I thought it made sense to leave the Realm naming for clarity.

lindseymoore · 2024-06-18T22:04:05Z

source/sdk/model-data/relationships.txt

+~~~~~~~~~~~~~~~~~~~~
+
+Relationship definitions in Realm are unidirectional. An 


Suggested change

Relationship definitions in Realm are unidirectional. An

Relationship definitions for Atlas Device SDK are unidirectional. An

realm naming

lindseymoore

LGTM! Only lingering question is that the Kotlin page includes how to make the different types of relationship for embedded objects. Is this specific to Kotlin and will this information be included in the embedded object section for Kotlin? @dacharyc
Link to Kotlin page: https://www.mongodb.com/docs/atlas/device-sdks/sdk/kotlin/realm-database/schemas/relationships/#define-an-embedded-object

dacharyc · 2024-07-12T20:59:40Z

LGTM! Only lingering question is that the Kotlin page includes how to make the different types of relationship for embedded objects. Is this specific to Kotlin and will this information be included in the embedded object section for Kotlin? @dacharyc Link to Kotlin page: https://www.mongodb.com/docs/atlas/device-sdks/sdk/kotlin/realm-database/schemas/relationships/#define-an-embedded-object

Totally reasonable question, @lindseymoore ! In the consolidated docs set, the Embedded Object info is on the "Define an Object Model" page - you can see the details in this PR: #3314

Here's the section about Embedded Objects: https://preview-mongodbdacharyc.gatsbyjs.io/realm/DOCSP-39502/sdk/model-data/object-models/#define-an-embedded-object

I removed the info from here because embedded objects aren't related objects in the same way as the other relationships here. They can't exist independent of their parent object. The relationships described here are about linking two object types that each have independent lifecycles. The concept info here does mention embedded objects and link out to the other page, but obviously the page content isn't populated here - it's in the PR for the consolidated "Define an Object Model" page.

docs-builder-bot · 2024-07-12T21:19:16Z

✨ Staging URL: https://preview-mongodbmongodb.gatsbyjs.io/realm/feature-consolidated-sdk-docs/

🪵 Logs

job log: 81be17cca4da0f4670b4ccc17c3a0f9617a2c0e8

Draft a consolidated relationships page

94d6725

dacharyc added 2 commits June 6, 2024 13:57

Fix snooty build error

f5ffe46

Fix snooty build error

f2bed50

dacharyc marked this pull request as ready for review June 6, 2024 19:08

dacharyc added the merge to feature branch Unreleased feature - do not merge to Master label Jun 7, 2024

lindseymoore requested changes Jun 18, 2024

View reviewed changes

Apply review suggestions

5668d2e

lindseymoore approved these changes Jul 12, 2024

View reviewed changes

Merge branch 'feature-consolidated-sdk-docs' into DOCSP-39503

a9d25d6

dacharyc merged commit 81be17c into mongodb:feature-consolidated-sdk-docs Jul 12, 2024
6 checks passed

dacharyc deleted the DOCSP-39503 branch July 12, 2024 21:16

	to many" is to use an :ref:`embedded object <sdks-embedded-objects>`,
	to many" is to use an embedded object,

	defines the relationship. The SDK executes read operations lazily as they
	come in, so querying a relationship is just as performant as reading a regular
	defines the relationship. Querying a relationship is just as performant as reading a regular

	implicitly "many-to-one" or "many-to-many." The only way to restrict a
	implicitly "many-to-one" or "many-to-many", so an object can be linked to any number of other objects in the database. The only way to restrict a

-and sets are not associated with a query and are declared as a property of the
-object model.
+and sets are not associated with a query, meaning ... . They are declared as a property of the
+object model.

	This can be a different Realm object type or the same Realm object
	This can be a different object type or the same object

		~~~~~~~~~~~~~~~~~~~~

		Relationship definitions in Realm are unidirectional. An

	Relationship definitions in Realm are unidirectional. An
	Relationship definitions for Atlas Device SDK are unidirectional. An

(DOCSP-39503): Consolidate Relationships page #3287

(DOCSP-39503): Consolidate Relationships page #3287

Uh oh!

Conversation

dacharyc commented Jun 6, 2024 • edited by lindseymoore Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Info - SDK Docs Consolidation

PR Author Checklist

Naming

Links and Refs

Content

Reviewer Checklist

Uh oh!

github-actions bot commented Jun 6, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lindseymoore left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lindseymoore left a comment

Choose a reason for hiding this comment

Uh oh!

dacharyc commented Jul 12, 2024

Uh oh!

Uh oh!

docs-builder-bot commented Jul 12, 2024

🪵 Logs

Uh oh!

Uh oh!

dacharyc commented Jun 6, 2024 •

edited by lindseymoore

Loading

github-actions bot commented Jun 6, 2024 •

edited

Loading