map

The map() function will create a new list populated with the results of calling the expression on every item in the original list.

map(list, current)
map(list, index)

list.map(current)
list.map(index)
Code language: JavaScript (javascript)

In other words, map() lets you build a machine that will do something to every element in a list, returning a new list containing all elements after they’ve gone through that machine.

Within your expression/machine’s rules, the current keyword represents the element of the input list that is currently going through the machine.

[1, 2, 3].map(current * 2)
/* Output: [2, 4, 6] */
Code language: JavaScript (javascript)

You can also use the index keyword, which represents the index (or position) of the current item in the input list. Since lists use zero-based indexing, the first element has an index of 0.

[1, 2, 3].map(index)
/* Output: [0, 1, 2] */

[1, 2, 3].map(current * index)
/* Output: [0, 2, 6] */
Code language: JavaScript (javascript)

Here’s a more illustrative example of what map() does. Here, the “machine” we’ve built runs a fictional process called evolve() on whatever input goes into that machine. (evolve() isn’t a real function – it’s just useful as a teaching tool here.)

Each element from the Starter Pokémon input list goes into the machine, one at a time.

My Notion Formulas 2.0 Masterclass video deals heavily with map(), so you may want to watch it in order to gain a better understanding of everything this function can do. You’ll find a presentation about map() specifically around the 06:56 mark.

Example Formulas

["Luffy", "Nami", "Chopper", "Brooke"].map(
  current.length()
)

/* Output: 5, 4, 7, 6 */
Code language: JavaScript (javascript)

map() is also extremely useful for accessing the properties of Notion pages within a Relation property. Since Relation properties always contain a list of pages (even when there’s only one element), you either need to access specific elements with functions like first, last, or at – or you need to use map() to access properties in every page in the list.

/* In a Projects database with a Tasks relation: */

prop("Tasks").map(
  current.prop("Status")
)

/* Sample Output: [To Do, Done, To Do, Doing, Done] */
Code language: Java (java)

Among many other things, you can use this to aggregate data from all pages in a Relation property.

Consider a Tasks database with a connected Work Sessions database for time-tracking (like the one in Ultimate Brain). To get the total number of minutes tracked on a task – across many work sessions – we can use map():

/* In a Tasks database with a Time Tracking Sessions relation: */

prop("Sessions").map(
  current.prop("Duration")
).sum()

/* Sample Output: 225 */
Code language: JavaScript (javascript)