Navigation

Expression Variables

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 represent dynamic values that Realm replaces when it evaluates an expression. Expansion variables begin with two percent signs (%%).

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.

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

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

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

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

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 represent runtime operations that Realm executes when it evaluates an expression. Operator variables begin with one percent sign (%).

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.

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

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

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

On this page