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.

%%environment¶

Document

A document that includes environment values and the current environment tag.

Example

The following is a rule expression that evaluates to true if the current environment is "production" and the "baseUrl" environment value is defined:

{
  "%%environment.tag": "production",
  "%%environment.values.baseUrl": { "%exists": true }
}

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

EJSON Conversion¶

The following operators allow you to convert values between BSON/EJSON and JSON representations:

Operator

Description

%stringToOid¶

Converts a 12-byte or 24-byte string to an EJSON objectId object.

Example

{
  "_id": {
    "%stringToOid": "%%user.id"
  }
}

%oidToString¶

Converts an EJSON objectId object to a string.

Example

{
  "string_id": {
    "%oidToString": "%%root._id"
  }
}

Important

No Inner Operations

%stringToOid and %oidToString do not evaluate JSON operators. You must provide either a literal string/EJSON object or an expansion that evaluates to one.

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 } }

%ne¶

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

Example

{ "numPosts": { "%ne": 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 (%).

Give Feedback

← Authenticate HTTP Client Requests JSON Expressions →