open-realm-file.txt

.. _realm-studio-open-realm-file:

=================
Open a Realm File
=================

.. 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
~~~~~~~~~~~~~~~~~

Realm 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
      
      .. 
         [editor's note]: This example is JavaScript, but lives in a TypeScript file.

      .. literalinclude:: /examples/generated/node/open-and-close-a-realm.snippet.find-realm-file.ts
         :language: typescript

   .. tab:: Java
      :tabid: java
    
      .. include:: /includes/find-realm-file-java.rst

   .. tab:: .NET
      :tabid: dotnet

      .. include:: /includes/find-realm-file-dotnet.rst

   .. tab:: Flutter
      :tabid: flutter

      .. include:: /includes/find-realm-file-flutter.rst
   
   .. tab:: Kotlin
      :tabid: kotlin

      .. include:: /includes/find-realm-file-kotlin.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``

.. procedure::

   .. step:: Browse to the Create Realm from CSV option

      In Realm Studio, go to: :guilabel:`File` > :guilabel:`Create Realm from` > :guilabel:`CSV`


   .. step:: Open your CSV

      Browse to the location of your CSV file, and select it.

      Press the :guilabel:`Open` button.


   .. step:: Choose where to store the imported data

      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.


   .. step:: Add more data to the realm

      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<realm-studio-import-from-a-csv>`
      to populate your realm with object that map to the class definition
      you just created.

Download an Example
-------------------

If you're new to Realm 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.

Error Opening Realm File
------------------------

If you get an error when you try to open a realm file, this may be due to 
a version mismatch between the Realm file format supported in Realm Studio
and the Realm file format produced by the SDK.

To verify compatibility, check the release notes for your SDK version or
your :github:`Realm Studio version <realm/realm-studio/releases/>`. 
You may need to upgrade or downgrade Realm Studio or the Realm SDK version. 

These error messages may resemble:

.. code-block:: console

   Realm file is currently open in another process which cannot share access 
   with this process. All processes sharing a single file must be the same 
   architecture.

.. code-block:: console

   The file is already opened by another process, with an incompatible 
   lock file format. Try up- or downgrading Realm Studio or SDK to match 
   their versions of Realm Core.