Query Roles¶

Role Evaluation Process¶

When MongoDB Realm receives a query request, it determines which documents in the collection the query applies to and evaluates a separate role for each document. To assign a role to a document, MongoDB Realm steps through each role definition in order and evaluates the Apply When JSON expression that you defined for the role. If a role's Apply When expression evaluates to true, MongoDB Realm assigns the role to the current document and moves on to the next document. If the expression evaluates to false, MongoDB Realm evaluates the next role definition. If no roles apply to a document, MongoDB Realm withholds the entire document and prevents any modifications.

Apply When Expressions¶

MongoDB Realm determines if a role applies to a given document by evaluating the Apply When expression that you define for each role.

This section contains Apply When templates for common scenarios. To apply an expression to a role, find the scenario that most closely matches your use case and then copy and paste the provided template into the Apply When field of the role. You may need to modify placeholder values (denoted by <angle brackets>) in the template to match your collection.

{
  "<Owner ID Field>": "%%user.id"
}

{
  "<Array Field>": "%%user.id"
}

{
  "%%user.data.email": { "%exists": true }
}

{
  "%%user.data.email": "<Email Address>"
}

{
  "%%root.email": "%%user.data.email"
}

{
  "<Array Field>": "%%user.data.email"
}

{
  "%%true": {
    "%function": {
      "name": "isAuthorizedUser",
      "arguments": ["%%user.id"]
    }
  }
}

CRUD Permissions¶

MongoDB Realm uses a role's permissions configuration to determine if the active user can insert or delete a document as well as which fields in the document they can read and write.

This section contains templates that define role permissions for common scenarios. To apply a set of permissions to a role, find the scenario that most closely matches your use case. Update the role's permissions table to match the provided screenshot or copy and paste the provided template into the collection's advanced mode configuration. Make sure that you modify any placeholder values (denoted by <angle brackets>) in the template to match your needs.

The Role Can Read All Fields but Cannot Write¶

To allow a role to read any field, set the document-level read field to true.

	{ "name": "<Role Name>", "apply_when": <JSON Expression>, "insert": <boolean>, "delete": <boolean>, "read": true, }

The Role Can Read & Write All Fields¶

To allow a role to read or write any field, set the document-level write field to true. Document-level writes require read permission, so the role will be able to read all fields.

	{ "name": "<Role Name>", "apply_when": <JSON Expression>, "insert": <boolean>, "delete": <boolean>, "write": true, }

The Role Can Read All Fields & Write to Specific Fields¶

To allow a role to read all fields, set the document-level read field to true. To specify a field that the role can write to, set the write field to true in the field's configuration document, which is embedded in the fields document.

	{ "name": "<Role Name>", "apply_when": <JSON Expression>, "insert": <boolean>, "delete": <boolean>, "read": true, "fields": { "<Field Name>": { "write": true }, ... } }

The Role Can Read & Write All Fields but Cannot Insert New Documents¶

To allow a role to read or write any field, set the document-level write field to true. Document-level writes require read permission, so the role will be able to read all fields.

To prevent the role from inserting new documents, set the document-level insert field to false.

	{ "name": "<Role Name>", "apply_when": <JSON Expression>, "insert": false, "delete": <boolean>, "write": true, }

The Role Cannot Write to Specific Fields¶

To allow a role to write to any field except for those you specify, set the corresponding field-level write fields to false in the fields document and set the additional_fields.write field to true.

	{ "name": "<Role Name>", "apply_when": <JSON Expression>, "insert": <boolean>, "delete": <boolean>, "read": true, "fields": { "<Field Name>": { "read": true, "write": false }, ... }, "additional_fields": { "write": true } }

Insert-Only Roles¶

To allow a role to insert new documents but otherwise prevent them from reading or modifying any data, set insert to true and set the value of document-level write to a JSON expression that evaluates to true only if the document didn't exist prior to the operation.

{
  "name": "insertOnly",
  "apply_when": <JSON Expression>,
  "delete": false,
  "insert": true,
  "write": {
    "%%prevRoot": { "%exists": false }
  },
  "additional_fields": {}
}

Field-level Permissions for Embedded Documents¶

To allow a role to read or write some but not all fields of an embedded document, add embedded documents that match the path of the embedded field to the fields document.

{
  "name": "canReadEmbeddedField",
  "apply_when": {},
  "delete": true,
  "insert": true,
  "fields": {
    "someEmbeddedDocument": {
      "fields": {
        "someEmbeddedField": {
          "read": true,
          "write": true
        }
      }
    }
  },
  "additional_fields": {}
}