diff --git a/snooty.toml b/snooty.toml index 77ea6f83d8..c1b9e90e68 100644 --- a/snooty.toml +++ b/snooty.toml @@ -41,7 +41,8 @@ toc_landing_pages = [ "/node", "/react-native", "/web", - "/dotnet" + "/dotnet", + "/studio" ] [substitutions] diff --git a/source/images/realm-studio-click-into-list-of-tasks.png b/source/images/realm-studio-click-into-list-of-tasks.png new file mode 100644 index 0000000000..9568beb54f Binary files /dev/null and b/source/images/realm-studio-click-into-list-of-tasks.png differ diff --git a/source/images/realm-studio-create-task-from-category-work.png b/source/images/realm-studio-create-task-from-category-work.png new file mode 100644 index 0000000000..f1c2efc49d Binary files /dev/null and b/source/images/realm-studio-create-task-from-category-work.png differ diff --git a/source/images/realm-studio-task-creation-ui.png b/source/images/realm-studio-task-creation-ui.png new file mode 100644 index 0000000000..f0e860de22 Binary files /dev/null and b/source/images/realm-studio-task-creation-ui.png differ diff --git a/source/includes/find-realm-file-dotnet.rst b/source/includes/find-realm-file-dotnet.rst new file mode 100644 index 0000000000..91cdfa3183 --- /dev/null +++ b/source/includes/find-realm-file-dotnet.rst @@ -0,0 +1,4 @@ +.. code-block:: csharp + + var realm = Realm.GetInstance(); + Console.WriteLine($"Realm is located at: {realm.Config.DatabasePath}"); \ No newline at end of file diff --git a/source/includes/find-realm-file-java.rst b/source/includes/find-realm-file-java.rst new file mode 100644 index 0000000000..a10c9e89a6 --- /dev/null +++ b/source/includes/find-realm-file-java.rst @@ -0,0 +1,27 @@ +The filesystem used by Android emulators is not directly accessible +from the machine running Realm Studio. You must download the file +from the emulator before you can access it. + +First, find the path of the file on the emulator: + +.. code-block:: java + + // Run this on the device to find the path on the emulator + Realm realm = Realm.getDefaultInstance(); + Log.i("Realm", realm.getPath()); + +Then, download the file using ADB. You can do this while the app +is running. + +.. code-block:: java + + > adb pull + +You can also upload the modified file again using ADB, but only +when the app isn't running. Uploading a modified file while the +app is running can corrupt the file. + +.. code-block:: java + + > adb push + \ No newline at end of file diff --git a/source/includes/find-realm-file-javascript.rst b/source/includes/find-realm-file-javascript.rst new file mode 100644 index 0000000000..85a9fe4429 --- /dev/null +++ b/source/includes/find-realm-file-javascript.rst @@ -0,0 +1,6 @@ +.. code-block:: javascript + + // Get on-disk location of the default Realm + Realm.open({}).then(realm => { + console.log("Realm is located at: " + realm.path); + }); \ No newline at end of file diff --git a/source/includes/find-realm-file-swift.rst b/source/includes/find-realm-file-swift.rst new file mode 100644 index 0000000000..c0e7fb55cb --- /dev/null +++ b/source/includes/find-realm-file-swift.rst @@ -0,0 +1,6 @@ +.. code-block:: swift + + // Get on-disk location of the default Realm + let realm = try! Realm() + print("Realm is located at:", realm.configuration.fileURL!) + \ No newline at end of file diff --git a/source/includes/realm-studio-export-class-definitions.rst b/source/includes/realm-studio-export-class-definitions.rst new file mode 100644 index 0000000000..8d14b4dc0c --- /dev/null +++ b/source/includes/realm-studio-export-class-definitions.rst @@ -0,0 +1,11 @@ +To export updated class definitions: + +- Go to :guilabel:`File` > :guilabel:`Save model definitions`, and select + your preferred language. Supported languages include: Swift, JavaScript, + TypeScript, Java, Kotlin, and C#. +- Specify a name and destination for your new class definitions. Press + the :guilabel:`Save` button. + +If your destination directory does not already exist, Realm Studio creates +it. Inside, you'll find a file that contains a complete list of classes +and properties, including new additions. diff --git a/source/includes/realm-studio.rst b/source/includes/realm-studio.rst deleted file mode 100644 index 544dd0492e..0000000000 --- a/source/includes/realm-studio.rst +++ /dev/null @@ -1,13 +0,0 @@ -Realm Studio is a developer tool for desktop operating systems that -allows you to manage Realm Database instances. With Realm Studio, you -can open and edit local and synced realms. It supports Mac, Windows, and -Linux. - -.. image:: /images/realm-studio.png - :alt: A screenshot of Realm Studio - -See :github:`Releases on GitHub `: - -- `Download for Linux `__ -- `Download for Mac `__ -- `Download for Windows `__ diff --git a/source/includes/steps-create-realm-from-csv.yaml b/source/includes/steps-create-realm-from-csv.yaml new file mode 100644 index 0000000000..8b0073d473 --- /dev/null +++ b/source/includes/steps-create-realm-from-csv.yaml @@ -0,0 +1,33 @@ +title: Browse to the Create Realm from CSV option +ref: realm-studio-select-create-from-csv +content: | + In Realm Studio, go to: :guilabel:`File` > :guilabel:`Create Realm from` > :guilabel:`CSV` +--- +title: Open your CSV +ref: realm-studio-open-csv +content: | + Browse to the location of your CSV file, and select it. + + Press the :guilabel:`Open` button. +--- +title: Choose where to store the imported data +ref: realm-studio-choose-where-to-store-imported-data +content: | + Enter a name for the {+realm+} file that will be created from your CSV. + + Browse to the location where you want to save it. + + Press the :guilabel:`Save` button. +--- +title: Add more data to the {+realm+} +ref: realm-studio-add-data-to-realm-created-from-csv +content: | + When you create a new {+realm+} file from a CSV, you may get this message: + + "Failed to import data: Class name (name-of-file.csv) missing from schema" + + If this happens, press :guilabel:`OK`. You'll see that creating a {+realm+} + from your CSV has created a class definition, but there are no objects + in your {+realm+}. From here, you can :ref:`Import from a CSV` + to populate your {+realm+} with object that map to the class definition + you just created. diff --git a/source/includes/steps-install-realm-studio.yaml b/source/includes/steps-install-realm-studio.yaml new file mode 100644 index 0000000000..b33508b257 --- /dev/null +++ b/source/includes/steps-install-realm-studio.yaml @@ -0,0 +1,47 @@ +title: Select a version +ref: select-realm-studio-version +content: | + + The binaries listed on this page are always the latest version of + Realm Studio. + + If you open an older version of a {+realm+} file in a newer Realm Studio + version, you may see a prompt to upgrade your {+realm+} file. Once + upgraded, you cannot revert to the older file version. You may also + need to upgrade your SDK to a version that supports the newer file format. + + If you don't want to upgrade {+client-database+}, download an older + version of Realm Studio. You can see a list of all releases at + `Realm Studio Releases `_. + Click a version number to view a page listing enhancements, fixes, + and file downloads. + +--- +title: Download the binary +ref: download-realm-studio-binary +content: | + + Download and extract the correct binary for your operating system. + + .. list-table:: + :header-rows: 1 + :class: index-table + + * - Operating System + - Download + + * - Linux + - `.AppImage `_ + + * - MacOS + - `.dmg `_ + + * - Windows + - `.exe `_ + +--- +title: Run the executable file +ref: run-realm-studio-executable +content: | + + Run the executable file. Follow installer instructions. diff --git a/source/includes/steps-realm-studio-create-object.yaml b/source/includes/steps-realm-studio-create-object.yaml new file mode 100644 index 0000000000..fcb8c81a34 --- /dev/null +++ b/source/includes/steps-realm-studio-create-object.yaml @@ -0,0 +1,24 @@ +title: Select a class for the new object +ref: realm-studio-create-object-select-class +content: | + The left sidebar of Realm Studio displays the classes that comprise the + schema. Select the class for the type of object you want to create. +--- +title: Create the new object +ref: realm-studio-create-the-new-object +content: | + Once you've decided where to create your new object, you can do this in + two ways: + + - Click the :guilabel:`Create {Class name}` button in the upper right + corner of the app + - Right click (or control click) anywhere in the main window to bring + up the contextual menu, and select :guilabel:`Create new {Class name}` + + Either option will open a dialog where you can set the properties + for the object. When you've specified the required properties, press the + :guilabel:`Create` button. + + If you create an orphaned object that is not associated with a parent + object via a linking property, you'll need to add it manually to the + linked object. See: :ref:`Modify an Object `. diff --git a/source/includes/steps-realm-studio-import-from-csv.yaml b/source/includes/steps-realm-studio-import-from-csv.yaml new file mode 100644 index 0000000000..14bcb51171 --- /dev/null +++ b/source/includes/steps-realm-studio-import-from-csv.yaml @@ -0,0 +1,24 @@ +title: Browse to the Import from CSV option +ref: realm-studio-import-from-csv-option +content: | + In Realm Studio, go to: :guilabel:`File` > :guilabel:`Import data from` > :guilabel:`CSV` +--- +title: Select a CSV to import +ref: realm-studio-import-from-csv-select-csv +content: | + Browse to the location of your CSV file, and select it. + + Press the :guilabel:`Open` button. +--- +title: Choose the destination class for your objects +ref: realm-studio-import-from-csv-choose-destination-class +content: | + You'll see a drop-down selector containing the available classes in + your {+realm+} file. Select the class where the imported data should + become objects. + + Press the :guilabel:`Import data` button. + + Now you'll see newly-created objects created from the data you imported. + Each object's properties map to the properties of the class you selected + during import. diff --git a/source/studio.txt b/source/studio.txt index da99b96e2e..aab9ddafae 100644 --- a/source/studio.txt +++ b/source/studio.txt @@ -4,50 +4,39 @@ Realm Studio ============ +.. toctree:: + :titlesonly: + :hidden: + + Install Realm Studio + Open a Realm File + Explore a Realm File + Modify a Realm File + Modify Schema + Get Started with Realm Studio ----------------------------- -Realm Studio is a developer tool for desktop operating systems that -allows you to manage Realm Database instances. With Realm Studio, you -can open and edit local and synced realms. It supports Mac, Windows, and -Linux. +Realm Studio is a visual tool to view, edit, and design {+client-database+} +files. With Realm Studio, developers can: + +- Query objects in the database +- View live objects in realtime while running an app +- Create, modify, and delete objects +- Add classes and properties to the schema +- Export the schema as class definitions in C#, Java, JavaScript, Kotlin, + Swift, and TypeScript +- Save and import changes into a client app or production database .. image:: /images/realm-studio.png :alt: A screenshot of Realm Studio -See :github:`Releases on GitHub `: - -- `Download for Linux `_ -- `Download for Mac `_ -- `Download for Windows `_ - -.. _find-the-default-realm-path: - -Find the Realm File(s) ----------------------- - -{+client-database+} stores a binary encoded version of every object and type in a -realm in a single ``.realm`` file. The file is located at a specific path that -you define when you open the realm. - -.. tabs-realm-languages:: - - .. tab:: - :tabid: swift - - In Swift app development, you can find the current path of the - default {+realm+} by pausing the simulator and using the LLDB console: - - .. code-block:: swift - - (lldb) po Realm.Configuration.defaultConfiguration.fileURL - - .. tab:: - :tabid: objective-c - - In Objective-C app development, you can find the current path of the - default {+realm+} by pausing the simulator and using the LLDB console: +View Realm Studio Releases +-------------------------- - .. code-block:: objective-c +You can see a list of all releases at `Realm Studio Releases `_. +Click a version number to view a page listing enhancements, fixes, and +file downloads for that version. - (lldb) po [RLMRealmConfiguration defaultConfiguration].fileURL +Alternately, you can view :github:`Releases on GitHub `, +as well as track and file issues for Realm Studio. diff --git a/source/studio/explore-realm-file.txt b/source/studio/explore-realm-file.txt new file mode 100644 index 0000000000..6ae960127a --- /dev/null +++ b/source/studio/explore-realm-file.txt @@ -0,0 +1,79 @@ +.. _realm-studio-explore-realm-file: + +==================== +Explore a Realm File +==================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +When you open a {+realm+} file in Realm Studio, you can: + +- View live objects in realtime +- Query objects in the {+realm+} +- Export SDK model definitions + +This makes it a valuable tool for developing and debugging applications +backed by {+client-database+}. + +View Live Objects in Realtime +----------------------------- + +Realm Studio gives you the ability to view live objects while you're +running a client app in an emulator. You can see how functions in your +app are transforming objects in realtime. This is a powerful debugging +and development tool. + +To view live objects in Realm Studio, you'll need to :ref:`find your {+realm+} +file `. Once you know your {+realm+} file +path, you can open it in Realm Studio while your app is running. + +.. note:: + + Unfortunately, Android emulators do not support viewing live objects + in Realm Studio. If you're developing for Android, you must download + the file from the emulator before you can access it. + +Query Objects in the Realm +-------------------------- + +Realm Studio enables you to query the objects in the {+realm+} file. The +ability to do this in the {+realm+} via Realm Studio gives you a visual +tool to: + +- Quickly view query results +- Experiment with query syntax +- Validate the data in the {+realm+} file + +The Realm Studio query bar at the top of the main pane +accepts the :ref:`{+client-database+} JavaScript query syntax`. +You can query using: + +- Comparison operators +- Logical operators +- String operators + +You can also view a reference document that details the query options from +within Realm Studio. Press the :guilabel:`?` button next to the query bar. + +Export SDK Model Definitions +---------------------------- + +Realm Studio enables you to export model definitions, streamlining +cross-platform development. + +For example, you may be an iOS developer who has already created a +schema in an existing app. You now need to declare the same schema for +your Android app. Recreating that schema in another programming language +can be time-consuming and error-prone. Instead, you can open your {+realm+} +file in Realm Studio, and export the model definition in Java. + +.. include:: /includes/realm-studio-export-class-definitions.rst diff --git a/source/studio/install.txt b/source/studio/install.txt new file mode 100644 index 0000000000..2a989b01b8 --- /dev/null +++ b/source/studio/install.txt @@ -0,0 +1,32 @@ +.. _realm-studio-install: + +==================== +Install Realm Studio +==================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +Realm Studio is available for Linux, MacOS, and Windows. Installing it +is as easy as selecting a version, and downloading and running the +installer. + +.. tip:: + + If you want a file type that isn't listed here, such as a ``.zip`` + file, view `the release page `_ + for the version you want. You'll find a complete list of installers + for each version. + +Procedure +--------- + +.. include:: /includes/steps/install-realm-studio.rst diff --git a/source/studio/modify-objects.txt b/source/studio/modify-objects.txt new file mode 100644 index 0000000000..7326d4a371 --- /dev/null +++ b/source/studio/modify-objects.txt @@ -0,0 +1,202 @@ +.. _realm-studio-modify-objects: + +============================== +Modify Objects in a Realm File +============================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +Realm Studio gives you the ability to view and modify objects in your +{+realm+} file. You can: + +- Import data from a CSV +- Create new objects +- Modify and delete existing objects + +You can then save the data as JSON or a {+realm+} file, and import it +into your client app or production database. + +.. _realm-studio-import-from-a-csv: + +Import from a CSV +----------------- + +.. note:: + + If you want to use a new class when importing data, you must create + the class before starting the import. + +.. include:: /includes/steps/realm-studio-import-from-csv.rst + +.. _realm-studio-create-an-object: + +Create an Object +---------------- + +Consider Object Relationships +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When you create a new object, think about the relationships between the +objects. For example, a to-do app, 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. + +In {+client-database+}, a to-many relationship is represented as a +``list`` property linking the two objects. In the example of a to-do app, +the ``Category`` class has a ``list`` property whose value is all of the +related ``Task`` objects. + +In the Realm Studio UI, you would select the ``Category`` class. Click +into the ``[list-of-task]`` property for the category where you want to +add the task - for example, "Work". + +.. figure:: /images/realm-studio-click-into-list-of-tasks.png + :alt: Realm Studio screenshot showing the Category class selected and the "list of task" for category view. + +You'll see all the task objects that have an inverse relationship with +the Work category. When you create the new task object from within the Work +list, Realm Studio sets the inverse relationship with the Work parent category. + +.. figure:: /images/realm-studio-create-task-from-category-work.png + :alt: Realm Studio screenshot showing the task objects belonging to the "Work" category, and the "Create task" button. + +From here, you might create a new task object to "Review PR 1013." The new +task will be linked to the "Work" category through an inverse relationship. + +.. figure:: /images/realm-studio-task-creation-ui.png + :alt: Realm Studio screenshot showing a user entering properties for a new task object, and the "Create" button. + +If you select the ``Task`` class directly, you could create a new task +object. But that task object would not have an inverse relationship with +any parent category. You would then have to :ref:`manually add the orphaned +task object ` to the category +where it belongs. + +Create the Object +~~~~~~~~~~~~~~~~~ + +.. include:: /includes/steps/realm-studio-create-object.rst + +.. _realm-studio-modify-an-object: + +Modify an Object +---------------- + +There are a few ways you can modify a {+realm+} object in Realm Studio: + +- Change a field value +- Change an object relationship + +Change a Field Value +~~~~~~~~~~~~~~~~~~~~ + +You can manually change an object's field values: + +- Click into the field of an object +- Enter a different value + +Realm Studio provides simple type validation, such as providing a list of +acceptable boolean options: :guilabel:`Use "true", "false", "0", or "1"`, +or automatically converting a date into a valid datetime. However, this +validation may lead to unexpected behavior. For example, typing "123abc" +into an ``int`` field simply discards the non-numeric characters without +providing user feedback or errors. Therefore, it is up to you to ensure +the data you enter into a field value is of the correct type. + +.. _realm-studio-change-object-relationship: + +Change an Object's Relationships +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can change an object's relationship with other objects using Realm +Studio. + +To add a new object relationship: + +- Click into the property that defines the relationship +- Right-click (or control-click) anywhere in the main pane, and select + :guilabel:`Add existing {linked class name}` +- Select the object you want to link, and press the :guilabel:`Select` button + +.. important:: + + Adding an object relationship does not remove an existing object + relationship. If you want to change an object relationship; for example, + move a task from one category to another; you must also remove the + relationship that linked the task to the old category. + +To remove an object relationship: + +- Click into the property that defines the relationship. +- Right-click (or control-click) the object whose relationship you + want to remove, and select :guilabel:`Remove selected row from the list` + or :guilabel:`Delete selected object` depending on the type of relationship. +- You'll see a dialog asking you to confirm the action. Press the button + to confirm you want to remove or delete the object. + +Delete an Object +---------------- + +To delete an object from a {+realm+}: + +- Right-click (or control-click) the object you want to delete, and + select :guilabel:`Delete selected object`. +- You'll see a dialog asking you to confirm the action. Press the + :guilabel:`Delete selected object` button to confirm. + +.. tip:: + + If you don't see the :guilabel:`Delete selected object` option, you + may be viewing it in a linking relationship list view. Go directly to + the class where the object is stored. + + If you're in the class where the object is stored, and still don't + see the :guilabel:`Delete selected objects` option, it may be because + you have another object selected. Click to select the object you want + to delete, and then right-click (or control-click) to get the delete + option. + +.. _realm-studio-save-data: + +Save the Data +------------- + +Because {+realm+} objects are live objects, you can make changes to a +{+realm+} file and see them reflected in a client app in realtime. Realm +Studio gives you a few save options if you want to do other things with +the data. + +To save data from Realm Studio: + +- Go to :guilabel:`File` > :guilabel:`Save data` and select :guilabel:`JSON` + or :guilabel:`Local Realm`. +- Select the filename and destination where you want to save the file. +- Press the :guilabel:`Save` button. + +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 +JSON into your app. + +If you save the data as a {+realm+} file, and you haven't :ref:`modified +the schema `, you can use that {+realm+} +file as a direct replacement for the existing realm file in your client +app. Simply replace the existing {+realm+} file on your filesystem with +the new one. + +Alternately, you could save a copy of the {+realm+}, open the copy, and +make schema changes on the copy. This would preserve your intact original +{+realm+} file, but still enable you to iterate on schema. You would then +be able to continue to use your existing {+realm+} file in your client +app without performing a migration. You could test migrations for your +new schema with the second {+realm+} file at your leisure. diff --git a/source/studio/modify-schema.txt b/source/studio/modify-schema.txt new file mode 100644 index 0000000000..ff83280a50 --- /dev/null +++ b/source/studio/modify-schema.txt @@ -0,0 +1,145 @@ +.. _realm-studio-modify-schema: + +=============================== +Modify Schema in a Realm Studio +=============================== + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +Realm Studio gives you tools to make additive changes to your schema. You +can: + +- :ref:`Add classes to the schema` +- :ref:`Add properties to classes` + +.. important:: + + If you make changes to your schema in Realm Studio, you must migrate + the {+realm+} file when you use it in your client app. + +After you make schema changes, you can :ref:`add values ` +to the new properties and classes from within Realm Studio. You can also +:ref:`create new objects ` based on your +new classes and properties. This gives you a graphical user interface +(GUI) tool to experiment with changes to your schema until you get the +object model you need. + +When you've completed your changes, you can :ref:`export your model +definitions ` from Realm Studio. +This gives you new class definitions in your language of choice, which +you can drop into your code. + +You can also :ref:`save an updated version of the {+realm+} file +` to use in your app. When you save a {+realm+} +file with an updated schema, you must :ref:`perform a migration +` to use it in your app. + +.. _realm-studio-add-class-to-schema: + +Add a Class to the Schema +------------------------- + +To add a new class to your schema: + +- Press the :guilabel:`+` button next to the :guilabel:`Classes` header + in the upper-left hand corner of the Realm Studio window +- Name your new class +- Designate a primary key (Optional) +- Press the :guilabel:`Add class` button + +You'll now see a new class in the class list displayed in the left-hand +sidebar. + +.. _realm-studio-add-property-to-class: + +Add a Property to the Class +--------------------------- + +To add properties to a class: + +- Select the class where you want to add properties in the left-hand sidebar +- Press the :guilabel:`+` button under the :guilabel:`Create {Class Name}` + button in the upper-right hand corner of the Realm Studio window +- Name your new property +- Select a type for your new property from the drop-down selector +- Click the checkboxes to select :guilabel:`Make this a list of strings` + and :guilabel:`Optional: Allow a null value` if needed +- Press the :guilabel:`Add property` button + +You'll see your new property displayed alongside the other class properties. + +If you already have objects in your class, you can add values for this +property by clicking into the property's field for each value. If this is +a new class with no objects, you can create new objects in the class. + +.. seealso:: + + :ref:`Modify Objects in a Realm File ` + +.. _realm-studio-export-model-definitions: + +Save Model Definitions +---------------------- + +After you've made changes to your schema, you can export your new schema +as class definitions. + +.. include:: /includes/realm-studio-export-class-definitions.rst + +This is a great tool to iterate on your schema. You can also export class +definitions in multiple languages for cross-platform development. + +.. _realm-studio-perform-migration: + +Perform a Migration +------------------- + +After you make changes to your schema, you can :ref:`add values to new +properties ` and even :ref:`create new +objects `. If you want to then use this +updated {+realm+} file in your app, you can :ref:`save the data `. +Before you can use it in your client app, though, you'll need to perform +a migration. + +{+client-database+} requires you to increment the version monotonically when +you change the schema. If you try to open a realm with an updated object +schema without migrating, your client will throw an error. + +For instructions on how to complete this migration, consult your SDK's +migration guide. + +.. tabs-realm-sdks:: + + .. tab:: + :tabid: android + + :ref:`Schema Versions & Migrations - Android SDK` + + .. tab:: + :tabid: ios + + :ref:`Schema Versions & Migrations - iOS SDK` + + .. tab:: + :tabid: node + + :ref:`Schema Versions & Migrations - Node.js SDK` + + .. tab:: + :tabid: react-native + + :ref:`Schema Versions & Migrations - React Native SDK` + + .. tab:: + :tabid: dotnet + + :ref:`Schema Versions & Migrations - .NET SDK` diff --git a/source/studio/open-realm-file.txt b/source/studio/open-realm-file.txt new file mode 100644 index 0000000000..ca083fe793 --- /dev/null +++ b/source/studio/open-realm-file.txt @@ -0,0 +1,125 @@ +.. _realm-studio-open-realm-file: + +================= +Open a Realm File +================= + +.. default-domain:: mongodb + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +If you have a local {+realm+} file that you've created by running a client +application, you can open it in Realm Studio. + +If you don't already have a {+realm+} file, you can create one by +importing a CSV, or you can download a demo file. + +Open a Local Realm File +----------------------- + +You can use Realm Studio to open and explore a local {+realm+} file. +This could be a file generated from running an emulator on your local +machine, or a file from another source. Some development tools even +allow you to view and edit the {+realm+} file while the emulator is +running. This workflow supports fast, simple iteration for changes to +objects and schemas. + +.. _realm-studio-find-a-realm-file: +.. _find-the-default-realm-path: + +Find a Realm File +~~~~~~~~~~~~~~~~~ + +{+client-database+} stores a binary-encoded version of every object and +type in a single {+realm+} file. The file is located at a specific path +that you define when you open the realm. + +To find your default {+realm+} file path: + +.. tabs:: + + .. tab:: Swift + :tabid: swift + + .. include:: /includes/find-realm-file-swift.rst + + .. tab:: JavaScript + :tabid: javascript + + .. include:: /includes/find-realm-file-javascript.rst + + .. tab:: Java + :tabid: java + + .. include:: /includes/find-realm-file-java.rst + + .. tab:: .Net + :tabid: dotnet + + .. include:: /includes/find-realm-file-dotnet.rst + +Once you know the location of your local {+realm+} file, you can browse +to that location from the :guilabel:`Open Realm file` dialog. + +.. note:: Files at hidden paths + + On MacOS, the default location for Xcode emulator files is under the + ``~/Library`` folder. By default, this is a hidden directory. You may + not be able to browse to this location from the :guilabel:`Open Realm + file` dialog. + + Use another technique to view the file, such as ``Go to Folder`` in + Finder, and open the {+realm+} from there. + +Create from a CSV +----------------- + +If you don't have a local {+realm+} file, you can create one from a CSV +in Realm Studio. + +When you create a {+realm+} from CSV, Realm Studio infers these details: + +- The name of your CSV becomes the class name in the {+realm+} file +- The first row of your CSV becomes the class property names in the {+realm+} +- The values of each column shape the class property types. A column of + 'true' and 'false' values becomes a boolean property type. A column of + whole numbers becomes an integer property type, and so on. If Realm Studio + can't determine the property type, it becomes a string. + +For example, a CSV named ``data.csv`` with this formatting: + +.. code-block:: + :linenos: + + device,number,flag + gizmo,1,TRUE + widget,2,FALSE + +Becomes a class model named ``data`` that has three properties: + +- ``device``, with a type ``string`` +- ``number``, with a type ``int`` +- ``flag``, with a type ``bool`` + +.. include:: /includes/steps/create-realm-from-csv.rst + +Download an Example +------------------- + +If you're new to {+client-database+} and don't have a {+realm+} file or +CSV to import, you can still try out Realm Studio. + +When you open Realm Studio, you'll see an option to :guilabel:`Download +a demo Realm file`. + +When you click the link to download the demo file in Realm Studio, +you can specify a name and location to save a {+realm+} file containing +demo data. Once you have downloaded the file, you can use the +:guilabel:`Open Realm file` dialog to open it.