Navigation

Expansions

Expansions are special variables for use with MongoDB Stitch rules and pipelines.

General

The following expansions are available in any pipeline stage or rule in any MongoDB Stitch app.

Name Type Description
%%true
boolean True.
%%false
boolean False.
%%user
document Holds user information. See %%user object.
%%values
any Expand a value (e.g. %%values.foo)

Stage-Specific

For use within a let statement (see the example below). These expansions can be used in any stage except those that do not accept items as input (either single items or lists of items). Lists of items can include literal expressions or the results of MongoDB read operations.

Name Type Description
%%args
document Arguments passed to the current pipeline stage.
%%item
any Item currently exposed to pipeline stage.
%%vars
any Contains the results of a let statement, which can be passed as arguments to a pipeline.
%%pipelines
any Expand a pipeline (e.g. %%piplines.my_pipeline)

MongoDB-Specific

The following expansions are for use in MongoDB service rules rules. %%this and %%prev represent document fields, while %%root and %%prevRoot represent documents. %%prev and %%prevRoot represent the original values of fields and documents which are changed during a stage which includes write operations.

Name Type Description
%%this
any Field value as it exists at the end of a database operation.
%%root
document Root document as it exists at the end of a database operation.
%%prev
any Field value referenced in a rules expression before it is changed by a write operation (insert, update, delete).
%%prevRoot
document Root document referenced in a rules expression before it is changed by a write operation.

The %%user Object

The %%user object has several fields with information about the app user.

Name Type Description
%%user.id
String User’s ID.
%%user.type
String Evaluates to "server" if the user request comes via an API key. Evaluates to "normal" for other user requests (via OAuth2, SAML, local, or anonymous).
%%user.data
document User metadata, including name and email (via login authentication).
%%user.identities
array A list of all identities associated with a MongoDB Stitch user. An identity consists of a unique identifier given to a user by an authorization provider along with the provider’s name.

Examples

The %%user Object

The %%user object is useful for identifying users in database rules. When an app user logs in to an app, the %%user object is populated with the user’s authentication information, which can include name and ID.

The following database rule example evaluates to true only if the owner_id field value matches the value of %%user.id and the owner_name field value matches the value of %%user.data.name.

{
  "owner_id": "%%user.id",
  "owner_name": "%%user.data.name"
}

An app can allow certain actions, such as updating and deleting, to be taken only by a document’s owner. Other users may only have permission to perform other actions, such as reading. The above rule allows the app to distinguish between the owner and other users.

MongoDB Validation Rule

The following example is a MongoDB validation rule. It evaluates to valid if either:

  • The document already exists
  • The value specified in the name field of the document is not in the name array which is part of the named value myBoards.
{
  "%or": [
    {
      "%%prevRoot": {
        "%exists": %%true
      }
    },
    {
      "%%root.name": {
        "%nin": "%%values.myBoards.name"
      }
    }
  ]
}

Pipeline with let

The following example illustrates a pipeline which is sourced with an array of documents containing records for a set of people. The service stage defines a Twilio service to send a text message to and from the specified phone numbers. On each iteration of the stage, the message body updates to contain a concatenation of the word hello and the person’s name.

Within a let statement, you can access the pipeline arguments through a %%vars expansion. %%vars can only be used within a let statement. When a %%vars expansion is in use, arguments for the stage are processed on each iteration.

[
  {
    "action": "literal",
    "args": {
              "items": [
                         { "name": "Lara", "age": 48 },
                         { "name": "Bob", "age": 30 }
                       ]
            }
  },
  {
    "service": "tw1",
    "action": "send",
    "args": {
              "to": "+15557349150",
              "from": "%%values.ourNumber",
              "body": "%%vars.body"
            },
    "let": {
             "body": { "%concat": [ "hello ", "%%item.name" ] }
           }
  }
]

%%this

The %%this object refers to the current document or field. This expansion is typically used to construct field and document-level permissions on a database collection. For example, the following MongoDB service write rule verifies that the value of a field is greater than 3 before allowing a write to the collection.

{ "%%this": { "%gt": 3 } }

%%item

The following example uses a MongoDB collection called users with the following records:

{ "_id" : 1, "name" : "Sam", "dob" : "October 18" }
{ "_id" : 2, "name" : "Jennifer", "dob" : "March 4" }
{ "_id" : 3, "name" : "Arnold", "dob" : "July 22" }

In this example, the first pipeline stage receives an argument called todaysDate and performs a find action on a MongoDB collection to find users whose birthday is today. It passes the results to the next stage, which uses a send action with an SES service to email a birthday greeting to each user in the result set. The final pipeline stage is null, indicating that nothing is returned to the application client.

The SES pipeline stage uses %%this to iterate over the input records and use the email address associated with each one.

{
  "action": "find",
  "args": {
    "collection": "users",
    "database": "people",
    "query": {
      "dob": "%%vars.todaysDate"
    }
  },
  "let": {
    "todaysDate": "%%args.todaysDate"
  },
  "service": "mdb1"
},
{
  "action": "send",
  "args": {
    "body": "%%vars.body",
    "fromAddress": "%%values.ourEmail",
    "subject": "Birthday greetings",
    "toAddress": "%%vars.toAddress"
  },
  "let": {
    "body": {
      "%concat": [
        "Happy birthday, ",
        "%%this.name",
                "!"
      ]
    },
    "toAddress": "%%item.email"
  },
  "service": "ses1"
},
{
  "action": "null"
}
←   Named Pipelines Values  →