Atlas Functions

Overview

An Atlas Function is a piece of server-side JavaScript code that you write to define your app's behavior. You can call your app's functions directly from a client app or define services that integrate and call functions automatically.

Functions can call other functions and include a built-in client for working with data in MongoDB Atlas clusters. They also include helpful global utilities, support common Node.js built-in modules, and can import and use external packages from the npm registry.

exports = function(name) {
  return `Hello, ${name ?? "stranger"}!`
}

How to Write a Function

The code for a function is essentially a named JavaScript source file, which means you can define multiple JavaScript functions in a single function file. The file must export a single JavaScript function to serve as the entrypoint for incoming calls. When you call a function by name, you're actually calling the JavaScript function assigned to exports in the function's source file.

For example, here's a simple function that accepts a name argument, adds a log message, and returns a greeting for the provided name:

exports = function Hello(name) {
  console.log(`Said hello to ${name}`);
  return `Hello, ${name}!`;
};

You can use modern JavaScript syntax and import packages to define more complex functions:

// You can use ES6 arrow functions
const uppercase = (str) => {
  return str.toUpperCase();
};
// You can use async functions and await Promises
exports = async function GetWeather() {
  // You can get information about the user called the function
  const city = context.user.custom_data.city;
  // You can import Node.js built-ins and npm packages
  const { URL } = require("url");
  const weatherUrl = new URL("https://example.com");
  weatherUrl.pathname = "/weather";
  weatherUrl.search = `?location="${city}"`;
  // You can send HTTPS requests to external services
  const weatherResponse = await context.http.get({
    url: url.toString(),
    headers: {
      Accept: ["application/json"],
    },
  });
  const { current, forecasts } = JSON.parse(weatherResponse.body.text());
  return [
    `Right now ${uppercase(city)} is ${current.temperature}°F and ${current.weather}.`,
    `Here's the forecast for the next 7 days:`,
    forecasts
      .map((f) => `${f.day}: ${f.temperature}°F and ${f.weather}`)
      .join("\n  "),
  ].join("\n");
};

Right now NEW YORK CITY is 72°F and sunny.
Here's the forecast for the next 7 days:
  Tuesday: 71°F and sunny
  Wednesday: 72°F and sunny
  Thursday: 73°F and partly cloudy
  Friday: 71°F and rainy
  Saturday: 77°F and sunny
  Sunday: 76°F and sunny
  Monday: 74°F and sunny

Functions automatically serialize returned values to Extended JSON. This is useful to preserve type information but may not be what your application expects.

For example, the values in the object returned from the following function are converted into structured EJSON values:

exports = function() {
  return {
    pi: 3.14159,
    today: new Date(),
  }
}

{
  "pi": {
    "$numberDouble": "3.14159"
  },
  "today": {
    "$date": {
      "$numberLong": "1652297239913"
    }
  }
}

To return a value as standard JSON, call JSON.stringify() on the value and then return the stringified result:

exports = function() {
  return JSON.stringify({
    pi: 3.14159,
    today: new Date(),
  })
}

"{\"pi\":3.14159,\"today\":\"2022-05-11T19:27:32.207Z\"}"

User and System Functions

A function can run in two contexts depending on how they're configured and called:

• A user function runs in the context of a specific user of your application. Typically this is the logged in user that called the function. User functions are subject to rules and schema validation.

• A system function runs as the system user instead of a specific application user. System functions have full access to MongoDB CRUD and Aggregation APIs and bypass all rules and schema validation.

Define a Function

You can create and manage functions in your application from the App Services UI or by importing the function configuration and source code with App Services CLI or GitHub deployment.

App Services UI

App Services CLI

1

Create a New Function

To define a new server-side function from the App Services UI:

1. Click Functions in the left navigation menu.

2. Click New Function in the top right of the Functions page.

2

Name the New Function

Enter a unique, identifying name for the function in the Name field. This name must be distinct from all other functions in the application.

Tip

You can define functions inside of nested folders. Function names are slash-separated paths, so a function named utils/add maps to functions/utils/add.js in the app's configuration files.

3

Configure User Authentication

Functions in App Services always execute in the context of a specific application user or as a system user that bypasses rules. To configure the function's execution user, specify the type of authentication that App Services should use.

Authentication Type	Description
Application Authentication	This type of authentication configures a function to run in the context of the existing application user that was logged in when the client application called the function. If the function was called from another function then it inherits the execution user from that function.
System	This type of authentication configures a function to run as a system user that has full access to MongoDB CRUD and Aggregation APIs and is not affected by any rules, roles, or permissions.
User ID	This type of authentication configures a function to always run as a specific application user.
Script	This type of authentication configures a function to run as a specific application user determined based on the result of a custom function that you define. The function must return a specific user's id string or can specify a system user by returning { "runAsSystem": true }.

click to enlarge

4

Configure Function Execution Logs

By default, App Services includes the arguments that a function received in the log entry for each execution of the function. If you want to prevent App Services from logging the arguments, disable Log Function Arguments.

5

Specify an Authorization Expression

You can dynamically authorize requests based on the contents of each request by defining a Can Evaluate expression. App Services evaluates the expression whenever the function is called. If you do not specify an expression then App Services automatically authorizes all authenticated incoming requests.

The expression can expand standard expression variables, including the %%request and %%user expansions.

click to enlarge

6

Configure the Function's Privacy Level

By default, you can call a function from client applications as well as other functions in the same application. You can prevent client applications from seeing or calling a function by setting Private to true.

You can still call a private function from expression and other functions, including incoming webhooks and triggers.

click to enlarge

7

Write the Function Code

Once you've created and configured the new function, it's time to write the JavaScript code that runs when you call the function. You can write the code directly in the App Services UI using the function editor.

Note

You can use most modern (ES6+) JavaScript features in functions, including async/await, destructuring, and template literals.

From the function's Settings page:

1. Click the Function Editor tab.

2. Add javascript code to the function. At minimum, the code must assign a function to exports, as in the following example:

   exports = function() {
     return "Hello, world!";
   };

8

Save the Function

Once you've written the function code, click Save from either the Function Editor or Settings tab.

After you save the function, you can begin using it immediately.

1

Pull Your App's Latest Configuration Files

appservices pull --remote=<App ID>

2

Write the Function Source Code

Atlas Functions run standard ES6+ JavaScript functions that you export from individual files. Create a .js file with the same name as the function in the functions directory or one of its subdirectories.

touch functions/myFunction.js

Tip

You can define functions inside of nested folders in the functions directory. Use slashes in a function name to indicate its directory path.

Once you've created the function's .js file, write the function source code, e.g.:

exports = async function hello(...args) {
  // Write your function logic here! You can...
  // Import dependencies
  const assert = require("assert")
  assert(typeof args[0] === "string")
  // Use ES6+ syntax
  const sayHello = (name = "world") => {
    console.log(`Hello, ${name}.`)
  }
  // Return values back to clients or other functions
  return sayHello(args[0])
}

Note

You can use most modern (ES6+) JavaScript features in functions, including async/await, destructuring, and template literals. To see if App Services supports a specific feature, see JavaScript Support.

3

Configure the Function

In the functions directory of your application, open the config.json file and add a configuration object for your new function to the array. The object must have the following form:

{
  "name": "<Function Name>",
  "private": <Boolean>,
  "can_evaluate": { <JSON Expression> },
  "disable_arg_logs": <Boolean>,
  "run_as_system": <Boolean>,
  "run_as_user_id": "<App Services User ID>",
  "run_as_user_id_script_source": "<Function Source Code>"
}

1

Set User Authentication

Functions in App Services always execute in the context of a specific application user or as a system user (which bypasses rules). To configure the function's execution user, specify the type of authentication that App Services should use:

• System

  To execute a function as a System user, use the following configuration:

  {
    "run_as_system": true,
    "run_as_user_id": "",
    "run_as_user_id_script_source": ""
  }

• User

  To execute a function as a specific user, use the following configuration:

  {
    "run_as_system": false,
    "run_as_user_id": "<App Services User Id>",
    "run_as_user_id_script_source": ""
  }

• Script

  The third way to execute a function is to specify another function that returns a user id. Your function will execute as this user. To do this, use the following configuration:

  {
    "run_as_system": false,
    "run_as_user_id": "",
    "run_as_user_id_script_source": "<Function Source Code>"
  }

2

Set Execution Logging

To include any values that the function receives as arguments in its log entry, set disable_arg_logs to false.

3

Specify an Authorization Expression

You can dynamically authorize requests based on the contents of each request by defining a Can Evaluate expression. App Services evaluates the expression whenever the function is called. If you do not specify an expression then App Services automatically authorizes all authenticated incoming requests.

The expression can expand standard expression variables, including the %%request and %%user expansions.

Example

The following expression only authorizes incoming requests if the sender's IP address is not included in the specified list of addresses.

{
    "%%request.remoteIPAddress": {
        "$nin": [
            "248.88.57.58",
            "19.241.23.116",
            "147.64.232.1"
        ]
    }
}

4

Configure the Function's Privacy Level

By default, you can call a function from client applications as well as other functions in the same application. You can prevent client applications from seeing or calling a function by setting private to true.

You can call a private function from a rule expression or another function, including HTTPS endpoints and triggers.

4

Deploy the Function

Push the function configuration and source code to deploy it to your app. Once you have pushed the function, you can begin using it immediately.

appservices push

Call a Function

You can call a function from other functions, from a connected client application, or with App Services CLI.

The examples in this section demonstrate calling a simple function named sum that takes two arguments, adds them, and returns the result:

// sum: adds two numbers
exports = function sum(a, b) {
  return a + b;
};

// difference: subtracts b from a using the sum function
exports = function difference(a, b) {
  return context.functions.execute("sum", a, -1 * b);
};

appservices function run \
  --name=sum \
  --args=1 --args=2

appservices function run \
  --name=sum \
  --args=1 --args=2 \
  --user=61a50d82532cbd0de95c7c89

{
  "numGamesPlayed": {
    "%function": {
      "name": "sum",
      "arguments": [
        "%%root.numWins",
        "%%root.numLosses"
      ]
    }
  }
}

Constraints

• Functions are capped at 300 seconds of runtime per request, after which a function will time out and fail.

• Functions may use up to 350MB of memory at any time.

• Functions are limited to 1000 async operations.

• Functions support most commonly used ES6+ features and Node.js built-in modules. However, some features that are uncommon or unsuited to serverless workloads are not supported. For more information, see JavaScript Support.

• A function may open a maximum of 25 sockets using the net built-in module.

• Incoming requests are limited to a maximum size of 18 MB. This limit applies to the total size of all arguments passed to the function as well as any request headers or payload if the function is called through an HTTPS endpoint.