Navigation

Functions

Realm Functions allow you to define and execute server-side logic for your application. You can call functions from your client applications as well as from other functions and in JSON expressions throughout Realm.

Functions are written in modern JavaScript (ES6+) and execute in a serverless manner. When you call a function, you can dynamically access components of the current application as well as information about the request to execute the function and the logged in user that sent the request.

By default, Realm Functions have no Node.js modules available for import. If you would like to make use of any such modules, you can upload external dependencies to make them available to import into your Realm Functions.

You can use functions to handle low-latency, short-running connection logic and other server-side interactions. Functions are particularly useful when you want to work with multiple services, behave dynamically based on the current user, or abstract away implementation details from your client applications. You can upload external Node.js packages and import them into your functions to streamline data processing and reuse shared code.

Realm also uses functions internally for incoming webhooks and triggers. The functions that you create for these components are regular Realm functions that take specific arguments depending on the service.

  • Realm automatically serializes values returned from functions to Extended JSON.

    Tip
    Return JSON instead of EJSON

    If you return a JavaScript object from a function, it may include EJSON value documents instead of raw JSON values. This is useful to preserve type information but may not be what your application expects.

    Instead, to return an object as JSON, call JSON.stringify() on the object and then return the stringified result, as in the following example:

    const plants = context.services.get("mongodb-atlas").db("example").collection("plants");
    const plant = await plants.findOne();
    // Return e.g. { "_id": "5f87976b7b800b285345a8b6", ... }
    // instead of { "_id": { "$oid": "5f87976b7b800b285345a8b6" } }
    return JSON.stringify(plant);
  • Functions do not continue to execute after they return. You cannot use functions with asynchronous callbacks or event listeners. If you need to do asynchronous work in a function, use a Promise.

When building a function that accesses your databases and collections, you can use MongoDB Actions to simplify your calls to Atlas. For more information on the actions that are available to you, see MongoDB Actions.

  • Function runtime is limited to 90 seconds.
  • Function memory usage is limited to 256MB.
  • Functions support most commonly used ES6+ features, but some features that are uncommon or unsuited to serverless workloads are not supported. For more information, see JavaScript Feature Compatibility.
  • A function may open a maximum of 5 sockets using the net built-in module.
  • Realm supports a subset of built-in Node modules. For a full list of supported and unsupported modules, see Built-In Module Support.
  • There is an 18 MB limit for incoming webhook and function requests. For functions called from an SDK, this limit applies to the total size of all arguments you pass to the function.

The active user of a given function execution is the authenticated user that called the function. Functions inherit the user context of other functions that call them.

MongoDB Realm evaluates rules in the context of the active user and resolves dynamic references like context.user and %%user to their user object.

A System Function is a function that runs as the system user rather than an application user. System functions have full access to MongoDB CRUD and Aggregation APIs and bypass all rules and schema validation.

You can configure a Function to run as the system user by enabling its Run As System configuration option. To determine if a function executes as a system user at runtime, call context.runningAsSystem().

Note
System Function Active User

Realm always resolves dynamic references like context.user and %%user to the authenticated user that called a function if there was one. If a function executes without being called by an authenticated user, such as in a trigger or webhook, then Realm resolves the dynamic references to the system user instead.

An external dependency is an external library that includes logic you'd rather not implement yourself, such as string parsing, convenience functions for array manipulations, and data structure or algorithm implementations.

Realm allows you to upload external dependencies from the npm registry and then import those dependencies into your functions using standard JavaScript module syntax. Realm automatically transpiles dependencies and supports most built-in Node.js modules. To get started with external dependencies, check out the following guides:

Note
Create Your Own Modules

Though most npm modules are written by third parties, you can also create and publish your own npm modules to house logic specific to your application. You can make your modules available to the Node.js community or reserve them for private use. For more information, check out npm's guide on Contributing packages to the registry.

Guide
Description
Learn how to write and add new functions to your Realm app.
Learn how to make Node.js packages available for import in your Realm Functions.
Learn how to execute functions that you've defined from a client application or from another Realm component.
Learn how to import and call uploaded Node.js packages within a Realm Function.
Learn how to access runtime information and interfaces to other components of your application from within a function.
Subject
Description
Includes detailed information about specific application context modules as well as examples of runtime data objects.
Includes detailed information about global utility packages.
Details built-in global modules for working with JavaScript and MongoDB data formats.
Details which standard Node modules and APIs are available in Realm functions.
Details the JavaScript syntax and built-ins that are available in Realm functions.
Give Feedback

On this page

  • Introduction
  • Use Cases
  • Behavior
  • MongoDB Actions
  • Constraints
  • Concepts
  • Active User
  • System Functions
  • External Dependencies
  • Guides
  • Reference Documentation