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 |
---|---|---|
| boolean | Always evaluates to true . This is useful when comparing with
a function (%function ) that returns a boolean
value. |
| 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 | |||
---|---|---|---|---|---|
| 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
| |||
| Document | A document that includes context request information about the external HTTP request that triggered the function call. |
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 | ||||||
---|---|---|---|---|---|---|---|---|
| Document | A document containing information and data about the authenticated user. | ||||||
| String | The authenticated user's id. | ||||||
| String | The type of user that initiated the request. Evaluates to
"server" for API key users
and "normal" for all other users. | ||||||
| Document | The user's custom data. The exact contents vary depending on the custom user data available. Example
| ||||||
| Document | The user's metadata. The exact contents will vary depending on the authentication provider identities associated with the user. Example
| ||||||
| 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
|
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 |
---|---|---|
| any | The value of a particular field as it exists at the end of a database operation. |
| any | The value of a particular field before it is changed by a write operation. |
| Document | The full document as it exists at the end of a database operation. |
| Document | The full document before it is changed by a write operation. |
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 |
---|---|---|
| Document | A document containing the values passed as arguments to a service action. You can access each argument by its parameter name. |
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 |
---|---|---|
| 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 | |||||
---|---|---|---|---|---|---|
| Converts a 12-byte or 24-byte string to an EJSON Example
| |||||
| Converts an EJSON Example
|
%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 | ||||||||
---|---|---|---|---|---|---|---|---|---|
| Calls a function with the specified name and arguments. Evaluates to the value that the function returns. Example
|
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 | ||||||||
---|---|---|---|---|---|---|---|---|---|
| Checks if the field it is assigned to has any value. Evaluates to a boolean representing the result. Example
| ||||||||
| 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
| ||||||||
| 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
|
Comparison Operators¶
The following operators allow you to compare values, including expanded values, and are available in all JSON expressions:
Operator | Description | |
---|---|---|
| Checks if the field it is assigned to is equal to the specified value. Evaluates to a boolean representing the result. Example
| |
| Checks if the field it is assigned to is not equal to the specified value. Evaluates to a boolean representing the result. Example
| |
| Checks if the field it is assigned to is strictly greater than the specified value. Evaluates to a boolean representing the result. Example
| |
| 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
| |
| Checks if the field it is assigned to is strictly less than the specified value. Evaluates to a boolean representing the result. Example
| |
| 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
|
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 (
%
).