Define a Value


You can define a new Realm Value from the Realm UI or by importing an application directory that contains one or more Value configuration files. Select the tab below that corresponds to the method that you want to use.



Create a New Value

You can define a new Value for your application in the Realm UI. To navigate to the Value configuration screen, click Values & Secrets in the left navigation menu. Ensure that the Values tab is selected and then click Create New Value.


Name the Value

Enter a unique Value Name. This name is how you refer to the value in functions and rules.

The value name input in the UI

Value Name Restrictions

Value names must not exceed 64 characters and may only contain ASCII letters, numbers, underscores, and hyphens. The first character must be a letter or number.


Define the Value

Specify the Value Type. You can define two different types of Value: plain text and secret.

A plain text value is a string, array, or object that you define manually using standard JSON syntax.

To define a plain text value, select the Plain Text radio button and then enter the value in the input box.

The plain text value input in the UI

A secret value exposes a Secret for use in Functions and rules.

To reference an existing Secret, select the Secret radio button and then select the name of the Secret that the value should reference from the Secret Name dropdown.

Alternatively, you can create and reference a new Secret by entering the new Secret’s name in the Secret Name dropdown and then clicking Create. Enter the new Secret Value in the input box that appears.

The value secret selection dropdown in the UI

Save the Value

After you have named and defined the new Value, click Save. Once saved, you can immediately access the Value in Functions and rules.


Export Your Realm Application

To define a Value using realm-cli you need to export an application directory for your application.

You can export your application from the Import/Export App tab of the Deploy page in the Realm UI, or by running the following command from an authenticated instance of realm-cli:

realm-cli export --app-id=<App ID>

Add a Value Configuration File

Each Value is defined in its own JSON file in the values subdirectory of your exported application. For example, a Value named myValue would be defined in the file /values/myValue.json.

Add a configuration file for the new Value to the values directory:

touch values/<Value Name>.json

The configuration file should have the following general form:

  "name": "<Value Name>",
  "from_secret": <boolean>,
  "value": <Stored JSON Value|Secret Name>
Field Description
name A unique name for the value. This name is how you refer to the value in functions and rules.
from_secret Default: false. If true, the Value exposes a Secret instead of a plain-text JSON value.

The stored data that Realm exposes when the Value is referenced.

If from_secret is false, value can be a standard JSON string, array, or object.

If from_secret is true, value is a string that contains the name of the Secret the value exposes.


Import Your Application Directory

Ensure that the Value configuration file is saved and then navigate to the root of your exported application directory. Log in to MongoDB Atlas with realm-cli:

realm-cli login --api-key="<my api key>" --private-api-key="<my private api key>"

Once you’re logged in, import the directory:

realm-cli import

Once the import completes, you can immediately begin to access the Value in rules and functions.