A MongoDB Function can be used to read, insert, update, or delete data from your MongoDB database. When you connect your database to Internal, basic functions corresponding to each collection in your database are automatically generated for you. You can create additional custom functions to read, insert, update, and delete data from your MongoDB using the Function Editor.

Getting Started with the Function Editor

To create or edit a Function, you’ll need to use the Function Editor. You can access the Function Editor from one of two places:

From a Space: Go into Edit Mode and click on the App Data icon in the left nav.
From Company Settings: Go to Data & Functions, click on the desired database, and click on the Functions tab.

Once you open the Function Editor, name your Function and select the database (if not selected already) for which you want to create a function.

Configure

To configure your Function, first select the type of function you want to create.

Insert Functions

To create an insert function, first select the collection and then specify the document you want to insert into the collection. You can either set a specific value for each field in the document or use dynamic parameters for variable inputs (i.e. button or form inputs).

Example: Function that creates a new user. Variable inputs are email, first name, last name, and password.

Here's a quick tutorial:

Update Functions

To create an update function, first select the collection and then specify the record(s) that this function will modify in the filter section. You can set a specific filter (e.g. _id:1) or use dynamic parameters to create variable inputs that the end user can set later.

Then, in the Update section, specify how the document(s) matched by your filter should be updated. Similar to the filter section, you can set a specific value (e.g. name: John) or use dynamic parameters to create variable inputs that the end user can set later.

If the function is meant to update many records at once (e.g. all records where status: pending), you can check the checkbox “allow multiple records to be updated”.

Example: Function that updates a user. The function updates the user record where _id is equal to the value specified by the user — and sets the name, email, and password to the new values specified by the user.

Delete Functions

To create a delete function, first select the collection and then specify the record(s) that this function will delete in the filter section. You can set a specific filter (e.g. _id:1) or use dynamic parameters to create variable inputs that the end user can set later.

If the function is meant to delete many records at once (e.g. all records where status: pending), you can check the checkbox “allow multiple records to be updated”.

Example: Function that deletes users where _id is equal to the value specified by the user.

Aggregate Functions

To create an aggregate function, first select the collection and enter your aggregation pipeline in strict JSON format. You can optionally include a dynamic parameter or reserved filter parameter within your aggregate pipeline to set a variable input for your function.

Example: A MongoDB function to get users with a bad password. The password field is a dynamic parameter that users can input to generate the appropriate list of users.

For more information on aggregation, you can refer to the MongoDB documentation for quick reference and SQL-to-aggregation mapping chart.

Run Function

If you want to run a function to confirm it is working as intended, select an environment and click the button to "Run Function".

Note: These functions run against your database. If you are creating an Insert, Update, or Delete function, be extra careful as running your function will modify data in your database. We recommend setting up a staging environment and running your function against it.

Transform

There are a number of reasons why you may want to transform your response using a Transformer. For example, you may want to:

Transform the response using Javascript to return a specific set of fields. In many cases, your request may return too many objects, objects that are deeply nested, or otherwise in a format that doesn’t work for the tools you want to build.
Transform the response using Javascript to return fields with manipulated values (e.g. split or join fields values).

You can find examples in our documentation for Data Transformation. Let's look at some here:

Example:

Below is the response we’re starting with. It currently returns the fields _id, date, email, movie_id, name, and text.

To return an additional field “domain” from the email field, we wrote this simple Transformer:

And here’s the new Transformed Response:

Inputs

This section is where you can view and configure function inputs. Think of inputs as fields in a form component, a primary key input that is used to retrieve a record, or filter/sorting inputs for a table component. If you include a dynamic parameter or reserved filter parameter in your function, be sure to add them to the Inputs tab as well.

Outputs

This section is where you configure the outputs of your Function. You can manually add outputs or click the Update button to infer outputs from the last execution of your function. Think of Outputs as table columns or fields displayed in a detail component.

‍Name: This is the name of the attribute (e.g. column name in a table or field name in a Detail Component)‍
Type: This is where you can specify the field type that should be returned.‍
Key: This is the combination of attributes that make the row unique. Key(s) are used by additional features like automatic row updates and auto linking.

Permissions

You can configure permissions for MongoDB Functions in Roles & Permissions within Company Settings. Learn more.

‍

Using Aggregate Pipelines to Match by ObjectId

As a workaround for a current lack of natively-supported BSON types to support a custom function that queries a MongoDB document by it's `_id`:


[
  {
    $addFields: {
      _id: "$user"
    }
  },
  {
    $match: {
        _id: {
          $eq: user_id
        }
      }
  }
]

`user_id` will be a string parameter (in Internal). Internal has special handling for the `_id` property and converts it to a `ObjectId` type when using `$match` in an aggregate function. Internal only treats `_id` as special so if you need to match based on an `ObjectId` type in the named "user", then you need to alias the "user" property to `_id`.

We plan to have better support for native BSON types soon.