array.forEach()

This method operates on an array. You typically fetch documents from a collection as a set, not an Array. For the equivalent Set method, see set instance methods.

For differences between Sets and Arrays, see Sets vs. Arrays.

Invoke a Function for each Array element.

Signature

forEach(function: (val: Any) => Any) => Null

Description

The forEach() method sequentially calls function for each Array element, passing the element value as an argument to function.

The calling Array isn’t changed.

Array iteration methods

FQL provides several methods for iterating over an Array. array.forEach(), array.map(), and array.flatMap() are similar but return different values.

Method Return value

array.forEach()

Null.

array.map()

Array.

array.flatMap()

Array, flattened by one level.

For examples, see:

Parameters

Parameter Type Required Description

function

Function

Yes

Function to invoke for each Array element in the calling Array. Each Array element is passed to function as an argument.

function parameters:

Parameter Type Required Description

val

Any

Current Array element.

Return value

Type Description

Null

The return value of function is discarded.

Examples

Basic

// Create an Array of objects that contain document data.
let customers = [
  {
    "name": "Ruby Von Rails",
    "email": "ruby@example.com",
    "address": {
      "street": "87856 Mendota Court",
      "city": "Washington",
      "state": "DC",
      "postalCode": "20220",
      "country": "US"
    }
  },
  {
    "name": "Scott Chegg",
    "email": "chegg@example.com",
    "address": {
      "street": "87856 Mendota Court",
      "city": "Washington",
      "state": "DC",
      "postalCode": "20220",
      "country": "US"
    }
  },
  {
    "name": "Hilary Ouse",
    "email": "ouse@example.com",
    "address": {
      "street": "87856 Mendota Court",
      "city": "Washington",
      "state": "DC",
      "postalCode": "20220",
      "country": "US"
    }
  }
]

// Use `forEach()` to create a `Customer` collection document for each
// element of the previous Array.
customers.forEach(doc => Customer.create({ doc }))
// `forEach()` returns `null`.
null

Although it returns null, array.forEach() still performed the requested operations. To verify:

// Get all `Customer` collection documents
Customer.all()
{
  // The results contain `Customer` documents created by
  // the previous `forEach()` call.
  data: [
    {
      id: "410652919999758409",
      coll: Customer,
      ts: Time("2099-10-02T16:53:12.770Z"),
      cart: null,
      orders: "hdW...",
      name: "Ruby Von Rails",
      email: "ruby@example.com",
      address: {
        street: "87856 Mendota Court",
        city: "Washington",
        state: "DC",
        postalCode: "20220",
        country: "US"
      }
    },
    {
      id: "410652919999759433",
      coll: Customer,
      ts: Time("2099-10-02T16:53:12.770Z"),
      cart: null,
      orders: "hdW...",
      name: "Scott Chegg",
      email: "chegg@example.com",
      address: {
        street: "87856 Mendota Court",
        city: "Washington",
        state: "DC",
        postalCode: "20220",
        country: "US"
      }
    },
    {
      id: "410652919999760457",
      coll: Customer,
      ts: Time("2099-10-02T16:53:12.770Z"),
      cart: null,
      orders: "hdW...",
      name: "Hilary Ouse",
      email: "ouse@example.com",
      address: {
        street: "87856 Mendota Court",
        city: "Washington",
        state: "DC",
        postalCode: "20220",
        country: "US"
      }
    }
  ]
}

array.forEach() vs. array.map()

You can use both array.forEach() and array.map() to iterate through an Array. However, each method returns a different value type.

array.forEach() returns null:

// Create an Array of objects that contain category data.
let categories = [
  {
    "name": "Electronics",
    "description": "Bargain electronics!"
  },
  {
    "name": "Books",
    "description": "Bargain books!"
  }
]

// Use `forEach()` to create a `Category` collection document for each
// element of the previous Array.
categories.forEach(doc => Category.create({ doc }))
null

Although it returns null, array.forEach() still performed the requested operations. To verify:

// Get all `Category` collection documents
Category.all()
  // The results contain `Customer` documents created by
  // the previous `forEach()` call.
{
  data: [
    ...
    {
      id: "410665732340187209",
      coll: Category,
      ts: Time("2099-10-02T20:16:51.560Z"),
      products: "hdW...",
      name: "Electronics",
      description: "Bargain electronics!"
    },
    {
      id: "410665732340188233",
      coll: Category,
      ts: Time("2099-10-02T20:16:51.560Z"),
      products: "hdW...",
      name: "Books",
      description: "Bargain books!"
    }
  ]
}

array.map() returns an Array:

// Create an Array of objects that contain category data.
let categories = [
  {
    "name": "Movies",
    "description": "Bargain movies!"
  },
  {
    "name": "Music",
    "description": "Bargain music!"
  }
]

// Use `map()` to create a `Category` collection document for each
// element of the previous Array.
categories.map(doc => Category.create({ doc }))

In this case, the Array contains documents created by the array.map() call:

[
  {
    id: "410655308219678797",
    coll: Category,
    ts: Time("2099-10-02T17:31:10.366Z"),
    products: "hdW...",
    name: "Movies",
    description: "Bargain movies!"
  },
  {
    id: "410655308219679821",
    coll: Category,
    ts: Time("2099-10-02T17:31:10.366Z"),
    products: "hdW...",
    name: "Music",
    description: "Bargain music!"
  }
]

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!