Rule Expressions

Embedded Expressions

You can embed multiple expression documents in the fields of another expression document to handle complex evaluation logic. MongoDB Realm evaluates expressions depth-first, post-order, i.e. it starts at the bottom of the expression tree and works back to the root-level fields by evaluating each expression after all of its embedded expressions.

{
  "%%args.someNumber": {
     "%and": [
        { "$gt": 0 },
        { "$lte": 42 }
     ]
  }
}

Multi-Field Expressions

When you have more than one field in an expression, that expression evaluates to true if and only if every field in the expression evaluates to true. In other words, Realm treats multiple fields in a single expression as an "AND" operation.

{
  "%%args.url": { "$exists": true },
  "%%args.body.userId": "%%user.id"
}

Logical Expansions

%%true

Type: boolean

Usable In: Any Expression

Evaluates to true. Use this to assert that a nested expression must evaluate to true.

%%false

Type: boolean

Usable In: Any Expression

Evaluates to false. Use this to assert that a nested expression must evaluate to false.

Value Expansions

%%values

Type: object

Usable In: Any Expression

Represents your application's values. Each field of the object maps a value name to its corresponding JSON value or secret.

Example

The following expression evaluates to true if the value admin_ids is a list that contains the user's account ID:

{
  "%%user.id": { "$in": "%%values.admin_ids" }
}

Environment Expansions

%%environment

Type: object

Usable In: Any Expression

Represents the current environment. You can read the environment name (tag) and access environment values.

Each property of the object maps the name of an environment value to its value in the current environment.

{
  "tag": "<Environment Name>"
  "values": {
    "<ValueName>": <Value>
  }
}

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

Request Expansions

%%request

Type: object

Usable In: Any Expression

Represents the incoming request.

{
  "httpMethod": "<HTTP Method>",
  "httpReferrer": "<HTTP Referer Header>",
  "httpUserAgent": "<HTTP User Agent>",
  "rawQueryString": "<URL Query String>",
  "remoteIPAddress": "<IP Address>",
  "requestHeaders": {
    "<Header Name>": ["<Header Value>", ...]
  },
  "service": "<Service Name>",
  "action": "<Endpoint Function or Service Action Name>",
  "webhookUrl": "<HTTPS Endpoint Route>"
}

User Expansions

%%user

Type: object

Usable In: Any Expression

Represents the user that initiated the request. The user object contains account information, metadata from authentication providers, and custom data from your app.

{
  "id": "<User Account ID>",
  "type": "<normal | server>",
  "data": {
    "<Field Name>": <Value>,
    ...
  }
  "custom_data": {
    "<Field Name>": <Value>,
    ...
  }
  "identities": [
    {
      "providerType": "<Auth Provider Name>",
      "id": "<Provider User ID"
    }
}

%%user.id

Type: string

Usable In: Any Expression

The authenticated user's id.

%%user.type

Type: "normal" | "server"

Usable In: Any Expression

The type of user that initiated the request. Evaluates to "server" for API key users and "normal" for all other users.

%%user.custom_data

Type: object

Usable In: Any Expression

The user's custom data. The exact contents vary depending on your custom user data configuration.

Example

"custom_data": {
  "primaryLanguage": "English",
}

%%user.data

Type: object

Usable In: Any Expression

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

Type: object[]

Usable In: Any Expression

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

MongoDB Document Expansions

%%this

Type: any

Usable In: MongoDB Atlas Data Sources

The value of a particular field as it exists at the end of a database operation.

%%prev

Type: any

Usable In: MongoDB Atlas Data Sources

The value of a particular field before it is changed by a write operation.

%%root

Type: object

Usable In: MongoDB Atlas Data Sources

The full document as it exists at the end of a database operation.

%%prevRoot

Type: object

Usable In: MongoDB Atlas Data Sources

The full document before it is changed by a write operation.

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

Service Expansions

%%args

Type: object

Usable In: Third-Party Services [Deprecated]

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

%%partition

Type: string | number | BSON.ObjectId

Usable In: Partion-based Sync

The partition key value of the current partition being evaluated.

Convert EJSON Values

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

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

Call a Function

The following operators allow you to call functions in your Realm application:

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

Check Existence

The following operators allow you to determine if a value exists in an object or array:

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

Compare Values

The following operators allow you to compare values, including expanded values:

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