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.
A basic function that returns a greeting
exports = function(name) { return `Hello, ${name ?? "stranger"}!`}When a function is called, your app routes the request to a managed app server that evaluates your code and returns the result. This model makes functions serverless, which means that you don't have to deploy and manage a server to run the code. Instead, you write the function source code and your app handles the execution environment.
A function runs in a context that reflects its execution environment. The context includes the user that called the function, how they called it, and the state of your app when they called it. You can use context to run user-specific code and work with other parts of your app.
To learn more about how to work with function context, see Context.
Functions can run arbitrary JavaScript code that you define, which means you can use them for almost anything. Common use cases include low-latency, short-running tasks like data movement, transformations, and validation. You can also use them to connect to external services and abstract away implementation details from your client applications.
In addition to functions that you invoke directly, you also write functions for various services like HTTPS Endpoints, Triggers, and GraphQL custom resolvers (GraphQL is deprecated, learn more). These services automatically call functions to handle specific events. For example, whenever a database trigger observes a change event it calls its associated function with the change event as an argument. In the trigger function, you can then access information from the change event and respond appropriately.
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:
const uppercase = (str) => { return str.toUpperCase();};exports = async function GetWeather() { const city = context.user.custom_data.city; const { URL } = require("url"); const weatherUrl = new URL("https://example.com"); weatherUrl.pathname = "/weather"; weatherUrl.search = `?location="${city}"`; 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 sunnyFunctions 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\"}"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.
References to context.user always resolve to the authenticated user that called a function if there was one, even if the function runs as a system function. To determine if a function is running as a system function, call context.runningAsSystem().
If a function executes without being called by an authenticated user, such as in a trigger or webhook, then dynamic references resolve to the system user which has no id or other associated data.
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.
To define a new server-side function from the App Services UI:
Click Functions in the left navigation menu.
Click New Function in the top right of the Functions page.
Enter a unique, identifying name for the function in the Name field. This name must be distinct from all other functions in the application.
TipYou 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.
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 }.
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.
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.
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.
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.
NoteYou can use most modern (ES6+) JavaScript features in functions, including async/await, destructuring, and template literals.
From the function's Settings page:
Click the Function Editor tab.
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!";};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.
appservices pull --remote=<App ID>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.jsYou 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) { const assert = require("assert") assert(typeof args[0] === "string") const sayHello = (name = "world") => { console.log(`Hello, ${name}.`) } return sayHello(args[0])}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.
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>"}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>"}To include any values that the function receives as arguments in its log entry, set disable_arg_logs to false.
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.
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" ] }}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.
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.
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:
exports = function sum(a, b) { return a + b;};You can call a function from another function through the context.functions interface, which is available as a global variable in any function. This include HTTPS endpoints, triggers, and GraphQL custom resolvers (deprecated, learn more). The called function runs in the same context as the function that called it.
exports = function difference(a, b) { return context.functions.execute("sum", a, -1 * b);};You can call a function through App Services CLI with the function run command. The command returns the function result as EJSON as well as any log or error messages.
appservices function run \ --name=sum \ --args=1 --args=2By default, functions run in the system context. To call a function in the context of a specific user, include their User ID in the --user argument.
appservices function run \ --name=sum \ --args=1 --args=2 \ --user=61a50d82532cbd0de95c7c89You can call a function from a rule expression by using the %function operator. The operator evaluates to the return value of the function. If the function throws an error, the expression evaluates to false.
{ "numGamesPlayed": { "%function": { "name": "sum", "arguments": [ "%%root.numWins", "%%root.numLosses" ] } }}Make sure to sanitize client data to protect against code injection when using Functions.
You can call a function from client applications that are connected with a Realm SDK or over the wire protocol. For code examples that demonstrate how to call a function from a client application, see the documentation for the Realm SDKs:
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.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4