set.forEach()

Iterate over all values in a Set, executing a function on each value.

Signature

forEach(functionBody: (value: T) => any) => null

Description

The forEach() method iterates over all values in the Set and executes the provided functionBody on each value. It is used for mutations or writing documents based on each Set value.

Because this method scans the full Set, it returns an error if there are more than 16,000 documents in the Set. This method can timeout for large Sets under that limit.

Iterator methods

FQL provides several methods for iterating over a Set. set.forEach(), set.map(), set.flatMap() are similar but used for different purposes:

Method Primary use Notes

set.forEach()

Perform in-place writes on Set elements.

Doesn’t return a value.

set.map()

Returns a new Set.

Can’t perform writes.

set.flatMap()

Similar to set.map(), but flattens the resulting Set by one level.

Can’t perform writes.

For examples, see:

Parameters

Parameter Type Required Description

functionBody

Function

Yes

Anonymous Function that operates on a Set value and returns nothing.

functionBody parameters:

Parameter Type Required Description

value

Any

Yes

Value to process.

Return value

None

Examples

Basic example

// Get a Set of `Customer` collection documents with an
// `address` in the `state` of `DC`.
let customers = Customer.where(.address?.state == "DC")
// Use `forEach()` to update each document in the previous Set.
customers.forEach(doc => doc.update({
  address: {
    street: doc?.address?.street,
    city: doc?.address?.city,
    state: "District of Columbia",
    postalCode: doc?.address?.postalCode,
    country: doc?.address?.country,
  }
})) // `forEach()` returns `null`.
null

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

// Get all `Customer` collection documents
Customer.all()
  // The results contain `Customer` documents updated by
  // the previous `forEach()` call.
{
  data: [
    {
      id: "111",
      coll: Customer,
      ts: Time("2099-10-02T21:50:14.555Z"),
      cart: Order("410671593745809485"),
      orders: "hdW...",
      name: "Alice Appleseed",
      email: "alice.appleseed@example.com",
      address: {
        street: "87856 Mendota Court",
        city: "Washington",
        state: "District of Columbia", // `state` has been updated.
        postalCode: "20220",
        country: "US"
      }
    },
    ...
  ]
}

set.forEach() vs. set.map()

You can use both set.forEach() and set.map() to iterate through a Set.

Use set.forEach() to perform in-place writes on the calling Set:

// Gets the frozen category.
let frozen = Category.byName("frozen").first()

// Uses `forEach()` to delete each product in
// the frozen category.
Product.byCategory(frozen).forEach(product => {
  product.delete()
})
null

Although it returns null, set.forEach() still performs the requested operations.

Unlike set.forEach(), set.map() can’t perform writes:

// Gets the produce category.
let produce = Category.byName("produce").first()

// Attempts to use `map()` to delete each product in
// the produce category.
Product.byCategory(produce).map(product => {
  product.delete()
})
invalid_effect: `delete` performs a write, which is not allowed in set functions.

error: `delete` performs a write, which is not allowed in set functions.
at *query*:7:17
  |
7 |   product.delete()
  |                 ^^
  |

Instead, you can use set.map() to output a new Set containing extracted or transformed values:

// Gets the produce category.
let produce = Category.byName("produce").first()

// Uses `map()` to outputs a new Set containing products in
// the produce category. The new Set transforms each product's
// name.
Product.byCategory(produce).map(product => {
  let product: Any = product
  let category: Any = product.category
  {
    name: category.name + ": " + product.name,
  }
})
{
  data: [
    {
      name: "produce: avocados"
    },
    {
      name: "produce: single lime"
    },
    {
      name: "produce: organic limes"
    },
    {
      name: "produce: limes"
    },
    {
      name: "produce: cilantro"
    }
  ]
}

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!