---
title: Define custom functions
seotitle: Define custom Flux functions
list_title: Define functions
description: >
  Flux's functional syntax lets you define custom functions.
  Learn the basics of creating your own functions.
menu:
  flux_v0:
    name: Define functions
weight: 6
related:
  - /flux/v0/data-types/composite/function/
---

Flux's functional syntax lets you define custom functions.
Learn the basics of creating your own functions.

###### On this page:

- [Function definition syntax](#function-definition-syntax)
- [Custom function examples](#custom-function-examples)
- [Create a custom transformation](#create-a-custom-transformation)
  - [Custom transformation examples](#custom-transformation-examples)
- [Define functions with scoped variables](#define-functions-with-scoped-variables)
  - [Example functions with scoped variables](#example-functions-with-scoped-variables)

## Function definition syntax
The basic syntax for defining functions in Flux is as follows:

```js
// Basic function definition syntax
functionName = (functionParameters) => functionBody
```

- **functionName**: Name to use to execute the function.
- **functionParameters**: Comma-separated list of parameters passed into the function.
- **functionBody**: Operations on function parameters.

### Define parameter defaults
Use the `=` assignment operator to assign a default value to function parameters
in your function definition:

```js
functionName = (param1=defaultVal1, param2=defaultVal2) => functionBody
```

Defaults are overridden by explicitly defining the parameter in the function call.
Parameters without default values are considered **required parameters**.

## Custom function examples

{{< expand-wrapper >}}
{{% expand "Square a number" %}}
```js
square = (n) => n * n

square(n:3)
// Returns 9
```
{{% /expand %}}
{{% expand "Multiple two values" %}}
```js
multiply = (x, y) => x * y

multiply(x: 2, y: 15)
// Returns 30
```
{{% /expand %}}
{{% expand "Calculate n to the p power (with default parameters)" %}}
```js
pow = (n, p=10) => n ^ p

pow(n: 2)
// Returns 1024
```
{{% /expand %}}
{{< /expand-wrapper >}}

## Create a custom transformation
A [transformation](/flux/v0/function-types/#transformations) is a function that
takes a [stream of tables](/flux/v0/get-started/data-model/#stream-of-tables)
as input, operates on the input, and then outputs a new stream of tables.

The [pipe-forward operator](/flux/v0/get-started/syntax-basics/#pipe-forward-operator) (`|>`)
pipes data from the previous identifier or function forward into a transformation.
To use piped-forward data, assign a function parameter to the 
[pipe-receive operator](/flux/v0/spec/operators/#function-operators) (`<-`).

In the following example, the function `x()` receives piped-forwarded data and assigns it to the `t` parameter.
In the function body, `t` is piped forward into other operations to generate output.

```js
x = (t=<-) => t |> //...
```

### Custom transformation examples

{{< expand-wrapper >}}
{{% expand "Multiply values by x" %}}
#### Multiply values by x
The following example defines a `multByX` function that multiplies the `_value` column
of each input row by the `x` parameter.
The example uses the [`map()` function](/flux/v0/stdlib/universe/map/) to iterate over
each row, modify the `_value`, and then return the updated row.

##### Function definition
```js
multByX = (tables=<-, x) =>
    tables
        |> map(fn: (r) => ({r with _value: r._value * x}))
```

##### Example usage 
```js
data
    |> multByX(x: 2.0)
```

{{< flex >}}
{{% flex-content %}}
###### Given the following input data:

| srcID | _field | _value |
| :---- | :----- | -----: |
| t1a   | foo    |    1.2 |
| t1a   | foo    |    3.4 |
| t1a   | foo    |    5.6 |

| srcID | _field | _value |
| :---- | :----- | -----: |
| t2b   | foo    |    0.8 |
| t2b   | foo    |    1.9 |
| t2b   | foo    |    2.7 |
{{% /flex-content %}}
{{% flex-content %}}
###### The example above returns:

| srcID | _field | _value |
| :---- | :----- | -----: |
| t1a   | foo    |    2.4 |
| t1a   | foo    |    6.8 |
| t1a   | foo    |   11.2 |

| srcID | _field | _value |
| :---- | :----- | -----: |
| t2b   | foo    |    1.6 |
| t2b   | foo    |    3.8 |
| t2b   | foo    |    5.4 |
{{% /flex-content %}}
{{< /flex >}}

{{% /expand %}}
{{% expand "Calculate speed" %}}
#### Calculate speed
The following example defines a `speed` function that calculates speed using an
`elapsed` and `distance` column in input tables.
The example uses the [`map()` function](/flux/v0/stdlib/universe/map/) to iterate over
each row, calculate the speed per specified unit of distance, and then return
the updated row with a new `speed` column.

##### Function definition
```js
speed = (tables=<-, unit="m") =>
    tables
        |> map(
            fn: (r) => {
                elapsedHours = float(v: int(v: duration(v: r.elapsed))) / float(v: int(v: 1h))
                distance = float(v: r.distance)
                speed = distance / elapsedHours

                return {r with speed: "${speed} ${unit}ph"}
            },
        )
```

##### Example usage
```js
data
    |> speed()
```

{{< flex >}}
{{% flex-content %}}
##### Given the following input data:

| id  | elapsed | distance |
| :-- | ------: | -------: |
| t1  |   1h15m |      101 |
| t2  |   1h32m |      138 |
| t3  |     56m |      112 |
{{% /flex-content %}}
{{% flex-content %}}
##### The example above returns:

| id  | elapsed | distance |    speed |
| :-- | ------: | -------: | -------: |
| t1  |   1h15m |      101 | 88.8 mph |
| t2  |   1h32m |      138 |   90 mph |
| t3  |     56m |      112 |  120 mph |
{{% /flex-content %}}
{{< /flex >}}

{{% /expand %}}
{{< /expand-wrapper >}}


## Define functions with scoped variables
To create custom functions with variables scoped to the function,

1. Enclose your [function body](#function-definition-syntax) in a
   [block (`{}`)](/flux/v0/spec/blocks/).
2. Use a `return` statement to return a specific variable.

```js
functionName = (param) => {
    exampleVar = "foo"

    return exampleVar
}
```

### Example functions with scoped variables

{{< expand-wrapper >}}
{{% expand "Return an alert level based on a value" %}}

#### Return an alert level based on a value
The following function uses conditional logic to return an alert level based on
a numeric input value:

```js
alertLevel = (v) => {
    level =
        if float(v: v) >= 90.0 then
            "crit"
        else if float(v: v) >= 80.0 then
            "warn"
        else if float(v: v) >= 65.0 then
            "info"
        else
            "ok"

    return level
}

alertLevel(v: 87.3)
// Returns "warn"
```
{{% /expand %}}

{{% expand "Convert a HEX color code to a name" %}}
#### Convert a HEX color code to a name
The following function converts a hexadecimal (HEX) color code to the equivalent HTML color name.
The functions uses the [Flux dictionary package](/flux/v0/stdlib/dict/)
to create a dictionary of HEX codes and their corresponding names.

```js
import "dict"

hexName = (hex) => {
    hexNames =
        dict.fromList(
            pairs: [
                {key: "#00ffff", value: "Aqua"},
                {key: "#000000", value: "Black"},
                {key: "#0000ff", value: "Blue"},
                {key: "#ff00ff", value: "Fuchsia"},
                {key: "#808080", value: "Gray"},
                {key: "#008000", value: "Green"},
                {key: "#00ff00", value: "Lime"},
                {key: "#800000", value: "Maroon"},
                {key: "#000080", value: "Navy"},
                {key: "#808000", value: "Olive"},
                {key: "#800080", value: "Purple"},
                {key: "#ff0000", value: "Red"},
                {key: "#c0c0c0", value: "Silver"},
                {key: "#008080", value: "Teal"},
                {key: "#ffffff", value: "White"},
                {key: "#ffff00", value: "Yellow"},
            ],
        )
    name = dict.get(dict: hexNames, key: hex, default: "No known name")

    return name
}

hexName(hex: "#000000")
// Returns "Black"

hexName(hex: "#8b8b8b")
// Returns "No known name"
```
{{% /expand %}}
{{< /expand-wrapper >}}