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.

NameTypeDescription
%%true
booleanAlways evaluates to true. This is useful when comparing with a function (%function) that returns a boolean value.
%%false
booleanAlways 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.

NameTypeDescription
%%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.

Beaker IconExample

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
DocumentA document that includes context request information about the external HTTP request that triggered the function call.

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.

NameTypeDescription
%%user
DocumentA document containing information and data about the authenticated user.
%%user.id
StringThe authenticated user's id.
%%user.type
StringThe 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.

Beaker IconExample
"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.

Beaker IconExample
"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:

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

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:

NameTypeDescription
%%this
anyThe value of a particular field as it exists at the end of a database operation.
%%prev
anyThe value of a particular field before it is changed by a write operation.
%%root
DocumentThe full document as it exists at the end of a database operation.
%%prevRoot
DocumentThe full document before it is changed by a write operation.
Beaker IconExample

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:

NameTypeDescription
%%args
DocumentA document containing the values passed as arguments to a service action. You can access each argument by its parameter name.
Beaker IconExample

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:

NameTypeDescription
%%partition
anyThe 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:

OperatorDescription
%stringToOid

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

Beaker IconExample
{
"_id": {
"%stringToOid": "%%user.id"
}
}
%oidToString

Converts an EJSON objectId object to a string.

Beaker IconExample
{
"string_id": {
"%oidToString": "%%root._id"
}
}
Important With Circle IconCreated with Sketch.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:

OperatorDescription
%function

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

Beaker IconExample
{
"%%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:

OperatorDescription
%exists

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

Beaker IconExample
{
"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.

Beaker IconExample
{
"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.

Beaker IconExample
{
"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:

OperatorDescription
%eq

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

Beaker IconExample
{ "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.

Beaker IconExample
{ "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.

Beaker IconExample
{ "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.

Beaker IconExample
{ "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.

Beaker IconExample
{ "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.

Beaker IconExample
{ "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