Docs Menu

Rule Expressions

On this page

A rule expression is a JSON document that you use to configure data access in your application. For example, you can write a rule expression to control whether a user can read or write to a given document or synced partition.

Realm evaluates expressions to boolean values and uses the result to control your app's behavior and determine whether or not to allow specific user actions.

Each field name in an expression must be an expansion, a string that represents dynamic, runtime information, such as the logged in user that called an action (%%user) or the arguments that were passed the action (%%args).

Expressions documents have the following general format:

{
<field1>: <value1|expression1>,
<field2>: <value2|expression2>,
...
}

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.

Example

This expression evaluates to true only if the number provided as the someNumber argument falls in a specific range.

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

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.

Example

This third-party service rule expression evaluates to true only if both the url argument was provided and the body.userId argument matches the id of the user that called the action.

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

MongoDB Realm evaluates expressions by first replacing expansions with their runtime values and then evaluating each field of the expanded expression document to a boolean expression. If all fields in an expression evaluate to true, the expression also evaluates to true.

Expression fields evaluate based on the following rules:

  • If an expanded field name matches its value, it evaluates to true.
  • If a field's value is an embedded expression, it evaluates to the same value as the embedded expression. See embedded expressions.
Note

If a rule does not explicitly use the %%args or %%root expansion, expression field names default to checking for arguments or document fields of the same name. For example, the expression { "url": "https://www.example.com" } defaults to evaluating the value against %%args.url in a service rule and %%root.url in a MongoDB rule.

An expression expansion is a variable that represents a dynamic, runtime value in your app. Depending on the rule, these might represent the user that issued a given request, the metadata for that request, a document that the user is trying to access, and more.

Expansion variables are denoted by strings that begin with two percent signs (%%).

You can use the following expansions in any 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 expression to access components of your application.

Name
Type
Description
%%values
Object

An object that includes all global values. You can access a specific value from this document. Each property of the object maps the name of a value to its corresponding JSON or a secret.

Example

The following JSON expression evaluates to true if the current user's id value is listed in the admin_ids value:

{
"%%user.id": { "%in": "%%values.admin_ids" }
}
%%environment
Object

An object that represents the current environment as well as its environment values. Each property of the object maps the name of an environment value to its value in the current environment.

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
Document
A 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.

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 rule expressions and 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 third-party 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.

An expression operator represents an action or operation that Realm executes whenever it evaluates an expression. Operators take in one or more arguments and evaluate to a result value. The type and value of the result depends on the operator you use and the arguments you pass to it.

Expression operators are denoted by strings that begin with a single 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 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 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 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 } }
Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.