map

Maps each list element to an expression.

map(xs:list, capture:field, any->any) -> list

Description

The map function applies an expression to each element within a list, returning a list of the same length.

If xs is null, map returns null without evaluating the lambda. When you spread that result into a list, the null contributes no elements.

`xs: list`

A list of values.

`function: any -> any`

A lambda function that is applied to each list element.

If the lambda evaluates to different but compatible types for the elements of the list a unification is performed. For example, records are compatible with other records, and the resulting record will have the keys of both.

If the lambda evaluates to incompatible types for different elements of the list, the largest possible group of compatible values will be chosen and all other values will be null.

Examples

Check a predicate for all members of a list

from {
  hosts: [1.2.3.4, 127.0.0.1, 10.0.0.127]
}
hosts = hosts.map(x => x in 10.0.0.0/8)

{
  hosts: [false, false, true]
}

Reshape a record inside a list

from {
  answers: [
    {
      rdata: 76.76.21.21,
      rrname: "tenzir.com"
    }
  ]
}
answers = answers.map(x => {hostname: x.rrname, ip: x.rdata})

{
  answers: [
    {
      hostname: "tenzir.com",
      ip: "76.76.21.21",
    }
  ]
}

Null values

In the below example, the first entry does not match the given grok pattern, causing parse_grok to emit a null.

map will promote null values to typed null values, allowing you to still get all valid parts of the list mapped.

let $pattern = "%{WORD:w} %{NUMBER:n}"

from {
  l: ["hello", "world 42"]
}
l = l.map(str => str.parse_grok($pattern))

{
  l: [
    null,
    { w: "world", n: 42, },
  ],
}

Map a nullable list before spreading

If the input list is null, fnmap returns null, and list spread contributes no elements:

from {xs: null}
ys = [
  ...xs.map(x => x + 1),
  0,
]

{
  xs: null,
  ys: [
    0,
  ],
}

Incompatible types between elements

In the below example the list l contains three strings. Two of those are JSON objects and one is a JSON list. While all three can be parsed as JSON by parse_json, the resulting record and list are incompatible types.

map will resolve this by picking the “largest compatible group”, in this case preferring the two records over one list.

from {
  l: [
    r#"{ "x": 0 }"#,
    r#"{ "y": 0 }"#,
    r#"[ 3 ]"#,
  ]
}
l = l.map(str => str.parse_json())

{
  l: [
    {x: 0, y: null},
    {x: null, y: 0},
    null,
  ]
}

map