Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

set.map()

Apply a provided function to each element of a Set. Can’t perform writes.

Loading strategy:

Lazy loading

Signature

map(mapper: (A => B)) => Set<B>

Description

Creates a Set by applying a mapper function to each element in the calling Set.

Writes are not permitted. The calling Set isn’t changed.

If map() is the last value in a query, the first page of the new Set is returned.

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

mapper

Function

Yes

Anonymous FQL function to call on each element of the calling Set. Each call returns a value that’s returned in the result Set.

Return value

Type Description

Set<Generic>

Set containing values returned by each mapper function call.

Examples

Basic example

For all Customer documents, combine the address.city and address.state properties into a single string:

Customer.all().map(
  customer => {
    name: customer.name,
    city: "#{customer.address.city}, #{customer.address.state}"
  }
)
{
  data: [
    {
      name: "Alice Appleseed",
      city: "Washington, DC"
    },
    {
      name: "Bob Brown",
      city: "Washington, DC"
    },
    {
      name: "Carol Clark",
      city: "Washington, DC"
    }
  ]
}

Project Sets using set.map()

You can use set.map() to project a Set, similar to using Set projection.

For example, the following projection query:

Product.sortedByPriceLowToHigh() {
  name,
  description,
  price
}

Is equivalent to the following set.map() query:

Product.sortedByPriceLowToHigh().map(prod => {
  name: prod.name,
  description: prod.description,
  price: prod.price,
})

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
  {
    name: product.category.name + ": " + product.name,
  }
})
{
  data: [
    {
      name: "produce: avocados"
    },
    {
      name: "produce: single lime"
    },
    {
      name: "produce: organic limes"
    },
    {
      name: "produce: limes"
    },
    {
      name: "produce: cilantro"
    }
  ]
}

set.map() vs. set.flatMap()

set.flatMap() is similar to set.map(), except set.flatMap() also flattens the resulting Set by one level.

In the following example, set.map() returns a two-dimensional Set:

// Get a Set of all `Category` collection documents.
let categories = Category.all()

// Use `map()` to get a Set of `Product` documents
// for each category.
categories.map(category => {
  Product.byCategory(category)
})
// Two-dimensional Set.
{
  data: [
    {
      data: [
        {
          id: "111",
          coll: Product,
          ts: Time("2099-10-02T22:37:39.583Z"),
          name: "cups",
          description: "Translucent 9 Oz, 100 ct",
          price: 698,
          stock: 100,
          category: Category("123")
        },
        ...
      ]
    },
    {
      data: [
        {
          id: "333",
          coll: Product,
          ts: Time("2099-10-02T22:37:39.583Z"),
          name: "pizza",
          description: "Frozen Cheese",
          price: 499,
          stock: 100,
          category: Category("456")
        }
      ]
    },
    {
      data: [
        {
          id: "444",
          coll: Product,
          ts: Time("2099-10-02T22:37:39.583Z"),
          name: "avocados",
          description: "Conventional Hass, 4ct bag",
          price: 399,
          stock: 1000,
          category: Category("789")
        },
        ...
      ]
    }
  ]
}

To flatten the result to a one-dimensional array, use set.flatMap() instead:

// Get a Set of all `Category` collection documents.
let categories = Category.all()

// Use `flatMap()` to get a Set of `Product` documents
// for each category. Then flatten the resulting Set.
categories.flatMap(category => {
  Product.byCategory(category)
})
// One-dimensional Set.
{
  data: [
    {
      id: "111",
      coll: Product,
      ts: Time("2099-10-02T22:37:39.583Z"),
      name: "cups",
      description: "Translucent 9 Oz, 100 ct",
      price: 698,
      stock: 100,
      category: Category("123")
    },
    ...
    {
      id: "333",
      coll: Product,
      ts: Time("2099-10-02T22:37:39.583Z"),
      name: "pizza",
      description: "Frozen Cheese",
      price: 499,
      stock: 100,
      category: Category("456")
    },
    ...
    {
      id: "444",
      coll: Product,
      ts: Time("2099-10-02T22:37:39.583Z"),
      name: "avocados",
      description: "Conventional Hass, 4ct bag",
      price: 399,
      stock: 1000,
      category: Category("789")
    }
  ]
}

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!