(DOCSP-12426): Build out Realm Studio documentation #1053
Conversation
| Consider the relationships of the objects in your schema. In a to-do | ||
| app, you might have categories and tasks. The categories have a to-many | ||
| relationship to the tasks; one category may have many tasks. The tasks | ||
| have an inverse relationship to the category. |
There was a problem hiding this comment.
Maybe add "Therefore" at the start of the last sentence here: Therefore, the tasks have an inverse...
There was a problem hiding this comment.
I'm not sure "Therefore" really fits here. I'm going on what I understand from the iOS SDK's explanation of these relationships:
An inverse relationship links an object back to any other objects that refer to it in a defined to-one or to-many relationship. Relationship definitions are unidirectional, so you must explicitly define a property in the object's model as an inverse relationship.
If this is accurate, then "therefore" does not belong here. The tasks don't have an inverse relationship with the parent category "as a consequence of the fact" that the parent category has a to-many relationship to the tasks (which is what "therefore" would mean if we used it here); instead, these are each two uni-directional relationships that we've defined in the model. That's why I've stated them as two independent facts. If we want a linking word here, maybe "Additionally," would work better given the relationships?
I could be misunderstanding how these relationships work, though - let me know if that's the case!
There was a problem hiding this comment.
I beleive it's like this:
Categories have a one-to-many relationship to Tasks. Any given Category has 0 or more Tasks in its collection. Thus, any given task has an inverse relationship to the Category in which is it listed.
There was a problem hiding this comment.
I follow the logic, but I believe in the iOS SDK, anyway, you have to explicitly define the inverse relationship using LinkingObjects - it isn't implicitly created just because the Category has a to-many reference to it.
My resistance to using a word like "thus" or "therefore" is that it implies the inverse relationship is automagically created by the category's to-many relationship with the task. In reality, the reader needs to take an additional step to define the inverse relationship. Maybe explicitly stating that in the next paragraph after I describe the list property that represents the to-many relationship would make this clearer?
source/studio/modify-objects.txt
Outdated
| Because {+realm+} objects are live objects, you can make changes to a | ||
| {+realm+} file and see them reflected in a client app in realtime. However, | ||
| if you want to persist your changes after you close the {+realm+} file, | ||
| you must save the data from Realm Studio. |
There was a problem hiding this comment.
This is surprising, and I wonder if it deserves some kind of admonition?
There was a problem hiding this comment.
I will poke this more on Monday AM and come back to it. There is a transaction option in a drop-down menu, and I wonder if I make changes while in a transaction, it will persist the data even without saving the realm. My example realm file is borked now from making schema changes, so I'll create a new one on Monday AM and come back to this.
There was a problem hiding this comment.
It'll be good to know! :)
There was a problem hiding this comment.
So, fun fact - I tried this again and the data did seem to persist. I'm not sure why it didn't before, or what the "transaction" option is for, or why bother to provide the ability to "Save data as a Local Realm" in the UI. I'll modify this "Save the Data" section to say that you can save the data as a Local Realm. Maybe the "Save" as "Local Realm" option is for creating a new Realm file containing your data? But with it being a live object db, the existing realm file is also getting changed. Hrm.
Yeah, I'll make that change for now, because I don't want to block this from publishing, but will make a Jira ticket for next sprint to get an answer about transactions, and what the use case is for "Save Data as a Local Realm." So for the moment, the documentation will omit transactions, since the old docs didn't discuss them and we don't seem to need them to do the tasks listed in this doc set?
There was a problem hiding this comment.
Updated the "Save" section. What do we think now?
|
|
||
| Once you have saved the data, you can import it back into your app. | ||
|
|
||
| If you save it as JSON, you can use your preferred method to import the |
There was a problem hiding this comment.
This sounds scary. Do we want to provide any guidance (even generic) on what the process would look like? I'm tempted to avoid that potential train wreck, but it would serve our users well, I think.
There was a problem hiding this comment.
Re: JSON, I think there are too many ways users might want to use that data to provide guidance on what that would look like. They could theoretically import it into Atlas; they could use one of any number of JSON parsers to feed it back into their client app, or they could... do who knows what with it? I'm inclined to not touch it, personally, but will tackle it if other folks feel strongly about providing guidance around it.
| You can also :ref:`save an updated version of the {+realm+} file | ||
| <realm-studio-save-data>` to use in your app. When you save a {+realm+} | ||
| file with an updated schema, you must :ref:`perform a migration | ||
| <realm-studio-perform-migration>` to use it in your app. |
There was a problem hiding this comment.
Maybe my comment above is wrong? If we're doing a schema migration, then I would think this supports non-additive changes...but then, my understanding of schema changes is still rather foggy.
There was a problem hiding this comment.
So here's what happens when I make changes to a schema in Realm Studio...
If I make changes to the objects, my client app chugs along quite happily and will stop and start again and again with no issue.
If I make changes to the schema, such as adding a property, and then try to use that realm file with my app, Xcode throws this error:
Fatal error: 'try!' expression unexpectedly raised an error: Error Domain=io.realm Code=1 "Provided schema version 0 is less than last set version 2."
The iOS SDK docs say:
Schema versions are integers that you may include in the realm configuration when you open a realm. If a client application does not specify a version number when it opens a realm then the realm defaults to version 0.
And then points me to this page about performing a schema migration: https://docs.mongodb.com/realm/sdk/ios/examples/modify-an-object-schema/#std-label-ios-modify-an-object-schema
I could be wrong about a migration being required; maybe just specifying a new version when you open the realm file is sufficient? But I don't think we provide an example of that anywhere in the docs. I do see a schemaVersion configuration property in the RealmSwift reference docs - I'll try playing with that a bit more on Monday AM.
There was a problem hiding this comment.
@dacharyc
I think your changes are looking good. Open questions:
- do you and I understand inverse relationships enough that you are confident in the writing there?
- did you follow up on the 2 "Monday morning" tasks?
- Is it time for more coffee? (hint: yes)
There was a problem hiding this comment.
@MongoCaleb Here's where I am:
- I've commented further on the inverse relationship convo. I think it can stand as it is, but am not opposed to adding some more text in the next paragraph to clarify things for a reader if you think that's valuable.
- I've added screenshots for the object relationship section - do we think this is clearer?
- I updated the Save the Data section to reflect my additional spelunking, and will put in a ticket to research further the "transaction" option that's in the UI. But I think this section can now stand as-is for publishing, with later refinement.
- I added an admonition about migrating the Realm file after modifying the schema, because that was kind of a pain! But I did make an additive change, verify that I couldn't use the {+realm+} and had to do a migration, and successfully completed a migration that enabled me to use the {+realm+} again
I think this is ready to go, pending any further comments you might have.
Pull Request Info
Jira
Note: this Jira ticket makes a smaller ask, but as a team, we have discussed building out a more complete version of the Realm Studio documentation. The scope of this PR is larger than what is requested by this Jira ticket.
Staged Changes (Requires MongoDB Corp SSO)
Review Guidelines
REVIEWING.md