---
description: >-
  Functions transform and combine values. Learn about OpenTofu's built-in
  functions.
---

# Function Calls

The OpenTofu language has a number of
[built-in functions](../../language/functions/index.mdx) that can be used
in expressions to transform and combine values. These
are similar to the operators but all follow a common syntax:

```hcl
<FUNCTION NAME>(<ARGUMENT 1>, <ARGUMENT 2>)
```

The function name specifies which function to call. Each defined function
expects a specific number of arguments with specific value types, and returns a
specific value type as a result.

Some functions take an arbitrary number of arguments. For example, the `min`
function takes any amount of number arguments and returns the one that is
numerically smallest:

```hcl
min(55, 3453, 2)
```

A function call expression evaluates to the function's return value.

## Available Functions

For a full list of available functions, see
[the function reference](../../language/functions/index.mdx).

## Expanding Function Arguments

If the arguments to pass to a function are available in a list or tuple value,
that value can be _expanded_ into separate arguments. Provide the list value as
an argument and follow it with the `...` symbol:

```hcl
min([55, 2453, 2]...)
```

The expansion symbol is three periods (`...`), not a Unicode ellipsis character
(`…`). Expansion is a special syntax that is only available in function calls.

## Using Sensitive Data as Function Arguments

When using sensitive data, such as [an input variable](../../language/values/variables.mdx#suppressing-values-in-cli-output)
or [an output defined](../../language/values/outputs.mdx#sensitive-suppressing-values-in-cli-output) as sensitive
as function arguments, the sensitive information in the arguments will be tracked during the function call.

For example, passing an object containing a sensitive input variable to the `keys()` function
will return a list with all keys we expected, but the `values()` function will result in
a list with first item as sensitive, because the value of key "a" is sensitive.

```shell
> local.baz
{
  "a" = (sensitive value)
  "b" = "dog"
}
> keys(local.baz)
[
  "a",
  "b",
]
> values(local.baz)
[
  (sensitive value),
  "dog",
]
```

## When OpenTofu Calls Functions

Most of OpenTofu's built-in functions are, in programming language terms,
[pure functions](https://en.wikipedia.org/wiki/Pure_function). This means that
their result is based only on their arguments and so it doesn't make any
practical difference when OpenTofu would call them.

However, a small subset of functions interact with outside state and so for
those it can be helpful to know when OpenTofu will call them in relation to
other events that occur in an OpenTofu run.

The small set of special functions includes
[`file`](../../language/functions/file.mdx),
[`templatefile`](../../language/functions/templatefile.mdx),
[`timestamp`](../../language/functions/timestamp.mdx),
and [`uuid`](../../language/functions/uuid.mdx).
If you are not working with these functions then you don't need
to read this section, although the information here may still be interesting
background information.

The `file` and `templatefile` functions are intended for reading files that
are included as a static part of the configuration and so OpenTofu will
execute these functions as part of initial configuration validation, before
taking any other actions with the configuration. That means you cannot use
either function to read files that your configuration might generate
dynamically on disk as part of the plan or apply steps.

The `timestamp` function returns a representation of the current system time
at the point when OpenTofu calls it, and the `uuid` function returns a random
result which differs on each call. Without any special behavior, these would
both cause the final configuration during the apply step not to match the
actions shown in the plan, which violates the OpenTofu execution model.

For that reason, OpenTofu arranges for both of those functions to produce
[unknown value](references.mdx#values-not-yet-known) results during the
plan step, with the real result being decided only during the apply step.
For `timestamp` in particular, this means that the recorded time will be
the instant when OpenTofu began applying the change, rather than when
OpenTofu _planned_ the change.

For more details on the behavior of these functions, refer to their own
documentation pages.
