Navigation

Expression Variables

On this page

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:

copy 
{
  "%%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

copy 
"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

copy 
"data": {
  "name": "Joe Schmoe",
  "email": "joe.schmoe@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

copy 
"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:

copy 
{
  "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":

copy 
{
  "%or": [
    { "%%prevRoot": { "%exists": %%true } },
    { "%%root.name": "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 ruel that evaluates to true if the sender’s phone number (the from argument) matches a specific value:

copy 
{
  "%%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

copy 
{
  "%%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

copy 
{
  "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

copy 
{
  "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

copy 
{
  "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

copy 
{ "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

copy 
{ "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

copy 
{ "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

copy 
{ "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

copy 
{ "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

copy 
{ "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 (%).

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.