Navigation

Expression Variables

Overview

You can use special variables in JSON expressions to represent dynamic values and operations. There are two types of expression variables:

  • Expansions, which represent dynamic values and begin with two percent signs (%%).
  • Operators, which represent runtime operations and begin with one percent sign (%).

Expansions

Expansions represent dynamic values that Realm replaces when it evaluates an expression. Expansion variables begin with two percent signs (%%).

General Logic

You can use the following expansions in any JSON expression to represent boolean values.

Name Type Description
%%true
boolean Always evaluates to true. This is useful when comparing with a function (%function) that returns a boolean value.
%%false
boolean Always evaluates to false. This is useful when comparing with a function (%function) that returns a boolean value.

Application Components

You can use the following expansions in any JSON expression to represent components of your application.

Name Type Description
%%values
Document

A document that includes all global values that you have defined in your Realm app. You can access a specific value from this document.

Example

The following is a MongoDB schema validation expression that evaluates to true if the document’s secret field matches the used-defined value named secretString:

{
  "%%root.secret": "%%values.secretString"
}
%%request
Document A document that includes context request information about the external HTTP request that triggered the function call.

Authenticated User

The %%user expansion represents the currently authenticated user and allows you to access their information. You can use this expansion to create expressions that evaluate based on the user that initiated a request or action.

Name Type Description
%%user
Document A document containing information and data about the authenticated user.
%%user.id
String The authenticated user’s id.
%%user.type
String The type of user that initiated the request. Evaluates to "server" for API key users and "normal" for all other users.
%%user.custom_data
Document

The user’s custom data. The exact contents vary depending on the custom user data available.

Example

"custom_data": {
  "primaryLanguage": "English",
}
%%user.data
Document

The user’s metadata. The exact contents will vary depending on the authentication provider identities associated with the user.

Example

"data": {
  "name": "Joe Mango",
  "email": "joe.mango@example.com"
}
%%user.identities
Array of Documents

A list of all authentication provider identities associated with the user. An identity consists of a unique identifier given to a user by an authorization provider along with the provider’s type:

Example

"identities": [
  {
    "id": "5bce299457c70db9bd73b8-aajddbkuvomsvcrjjfoxs",
    "providerType": "local-userpass"
  }
]

Example

The following is a MongoDB role’s Apply When expression that evaluates to true only if a document’s owner_id and owner_name values match the values of %%user.id and %%user.data.name:

{
  "owner_id": "%%user.id",
  "owner_name": "%%user.data.name"
}

MongoDB Documents

You can use the following expansions in MongoDB Rules and Document Schema validation expressions:

Name Type Description
%%this
any The value of a particular field as it exists at the end of a database operation.
%%prev
any The value of a particular field before it is changed by a write operation.
%%root
Document The full document as it exists at the end of a database operation.
%%prevRoot
Document The full document before it is changed by a write operation.

Example

The following is a MongoDB schema validation expression that evaluates to true if either the document previously existed (i.e. the action is not an insert) or the document’s status field has a value of "new":

{
  "%or": [
    { "%%prevRoot": { "%exists": %%true } },
    { "%%root.status": "new" }
  ]
}

Service Expansions

You can use the following expansions in external service rules:

Name Type Description
%%args
Document A document containing the values passed as arguments to a service action. You can access each argument by its parameter name.

Example

The following is a Twilio service rule that evaluates to true if the sender’s phone number (the from argument) matches a specific value:

{
  "%%args.from": "+15558675309"
}

Sync Expansions

You can use the following expansions in sync rules:

Name Type Description
%%partition
any The partition key value of the current partition being evaluated.

Operators

Operators represent runtime operations that Realm executes when it evaluates an expression. Operator variables begin with one percent sign (%).

Application Components

The following operators allow you access other components of your Realm application and are available in all JSON expressions:

Operator Description
%function

Calls a function with the specified name and arguments. Evaluates to the value that the function returns.

Example

{
  "%%true": {
    "%function": {
      "name": "isEven",
      "arguments": [42]
    }
  }
}

Existence Operators

The following operators allow you to determine if a value exists in a given context and are available in all JSON expressions:

Operator Description
%exists

Checks if the field it is assigned to has any value. Evaluates to a boolean representing the result.

Example

{
  "url": { "%exists": true }
}
%in

Checks a specified array of values to see if the array contains the value of the field that this operator is assigned to. Evaluates to a boolean representing the result.

Example

{
  "url": {
    "%in": [
      "https://www.example.com",
      "https://www.mongodb.com"
    ]
  }
}
%nin

Checks a specified array of values to see if the array does not contain the value of the field that this operator is assigned to. Evaluates to a boolean representing the result.

Example

{
  "url": {
    "%nin": [
      "https://www.example.com",
      "https://www.mongodb.com"
    ]
  }
}

Comparison Operators

The following operators allow you to compare values, including expanded values, and are available in all JSON expressions:

Operator Description
%eq

Checks if the field it is assigned to is equal to the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "%eq": 42 } }
%neq

Checks if the field it is assigned to is not equal to the specified value. Evaluates to a boolean representing the result.

Example

{ "numPosts": { "%neq": 0 } }
%gt

Checks if the field it is assigned to is strictly greater than the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "%gt": 0 } }
%gte

Checks if the field it is assigned to is greater than or equal to the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "%gte": 0 } }
%lt

Checks if the field it is assigned to is strictly less than the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "%lt": 0 } }
%lte

Checks if the field it is assigned to is less than or equal to the specified value. Evaluates to a boolean representing the result.

Example

{ "score": { "%lte": 0 } }

Summary

  • You can use expression variables in JSON expressions to represent dynamic values and operations.
  • Expansions represent dynamic values and begin with two percent signs (%%).
  • Operators represent runtime operations and begin with one percent sign (%).