| --- |
| page_title: Function Calls - Configuration Language |
| description: >- |
| Functions transform and combine values. Learn about Terraform's built-in |
| functions. |
| --- |
| |
| # Function Calls |
| |
| > **Hands-on:** Try the [Perform Dynamic Operations with Functions](https://learn.hashicorp.com/tutorials/terraform/functions?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. |
| |
| The Terraform language has a number of |
| [built-in functions](/language/functions) 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). |
| |
| ## 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#suppressing-values-in-cli-output) |
| or [an output defined](/language/values/outputs#sensitive-suppressing-values-in-cli-output) as sensitive |
| as function arguments, the result of the function call will be marked as sensitive. |
| |
| This is a conservative behavior that is true irrespective of the function being |
| called. For example, passing an object containing a sensitive input variable to |
| the `keys()` function will result in a list that is sensitive: |
| |
| ```shell |
| > local.baz |
| { |
| "a" = (sensitive value) |
| "b" = "dog" |
| } |
| > keys(local.baz) |
| (sensitive value) |
| ``` |
| |
| ## When Terraform Calls Functions |
| |
| Most of Terraform'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 Terraform would call them. |
| |
| However, a small subset of functions interact with outside state and so for |
| those it can be helpful to know when Terraform will call them in relation to |
| other events that occur in a Terraform run. |
| |
| The small set of special functions includes |
| [`file`](/language/functions/file), |
| [`templatefile`](/language/functions/templatefile), |
| [`timestamp`](/language/functions/timestamp), |
| and [`uuid`](/language/functions/uuid). |
| 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 Terraform 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 Terraform 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 Terraform execution model. |
| |
| For that reason, Terraform arranges for both of those functions to produce |
| [unknown value](/language/expressions/references#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 Terraform began applying the change, rather than when |
| Terraform _planned_ the change. |
| |
| For more details on the behavior of these functions, refer to their own |
| documentation pages. |