| --- | |
| 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. |