github.com/hugorut/terraform@v1.1.3/website/docs/language/expressions/splat.mdx (about)

     1  ---
     2  page_title: Splat Expressions - Configuration Language
     3  description: >-
     4    Splat expressions concisely represent common operations. In Terraform, they
     5    also transform single, non-null values into a single-element tuple.
     6  ---
     7  
     8  # Splat Expressions
     9  
    10  > **Hands-on:** Try the [Create Dynamic Expressions](https://learn.hashicorp.com/tutorials/terraform/expressions?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
    11  
    12  A _splat expression_ provides a more concise way to express a common
    13  operation that could otherwise be performed with a `for` expression.
    14  
    15  If `var.list` is a list of objects that all have an attribute `id`, then
    16  a list of the ids could be produced with the following `for` expression:
    17  
    18  ```hcl
    19  [for o in var.list : o.id]
    20  ```
    21  
    22  This is equivalent to the following _splat expression:_
    23  
    24  ```hcl
    25  var.list[*].id
    26  ```
    27  
    28  The special `[*]` symbol iterates over all of the elements of the list given
    29  to its left and accesses from each one the attribute name given on its
    30  right. A splat expression can also be used to access attributes and indexes
    31  from lists of complex types by extending the sequence of operations to the
    32  right of the symbol:
    33  
    34  ```hcl
    35  var.list[*].interfaces[0].name
    36  ```
    37  
    38  The above expression is equivalent to the following `for` expression:
    39  
    40  ```hcl
    41  [for o in var.list : o.interfaces[0].name]
    42  ```
    43  
    44  ## Splat Expressions with Maps
    45  
    46  The splat expression patterns shown above apply only to lists, sets, and
    47  tuples. To get a similar result with a map or object value you must use
    48  [`for` expressions](/language/expressions/for).
    49  
    50  Resources that use the `for_each` argument will appear in expressions as a map
    51  of objects, so you can't use splat expressions with those resources.
    52  For more information, see
    53  [Referring to Resource Instances](/language/meta-arguments/for_each#referring-to-instances).
    54  
    55  ## Single Values as Lists
    56  
    57  Splat expressions have a special behavior when you apply them to a value that
    58  isn't a list, set, or tuple.
    59  
    60  If the value is anything other than a null value then the splat expression will
    61  transform it into a single-element list, or more accurately a single-element
    62  tuple value. If the value is _null_ then the splat expression will return an
    63  empty tuple.
    64  
    65  This special behavior can be useful for modules that accept optional input
    66  variables whose default value is `null` to represent the absence of any value. This allows the module to adapt the variable value for Terraform language features designed to work with collections. For example:
    67  
    68  ```
    69  variable "website" {
    70    type = object({
    71      index_document = string
    72      error_document = string
    73    })
    74    default = null
    75  }
    76  
    77  resource "aws_s3_bucket" "example" {
    78    # ...
    79  
    80    dynamic "website" {
    81      for_each = var.website[*]
    82      content {
    83        index_document = website.value.index_document
    84        error_document = website.value.error_document
    85      }
    86    }
    87  }
    88  ```
    89  
    90  The above example uses a [`dynamic` block](/language/expressions/dynamic-blocks), which
    91  generates zero or more nested blocks based on a collection value. The input
    92  variable `var.website` is defined as a single object that might be null,
    93  so the `dynamic` block's `for_each` expression uses `[*]` to ensure that
    94  there will be one block if the module caller sets the website argument, or
    95  zero blocks if the caller leaves it set to null.
    96  
    97  This special behavior of splat expressions is not obvious to an unfamiliar
    98  reader, so we recommend using it only in `for_each` arguments and similar
    99  situations where the context implies working with a collection. Otherwise,
   100  the meaning of the expression may be unclear to future readers.
   101  
   102  ## Legacy (Attribute-only) Splat Expressions
   103  
   104  Earlier versions of the Terraform language had a slightly different version
   105  of splat expressions, which Terraform continues to support for backward
   106  compatibility. This older variant is less useful than the modern form described
   107  above, and so we recommend against using it in new configurations.
   108  
   109  The legacy "attribute-only" splat expressions use the sequence `.*`, instead of
   110  `[*]`:
   111  
   112  ```
   113  var.list.*.interfaces[0].name
   114  ```
   115  
   116  This form has a subtly different behavior, equivalent to the following
   117  `for` expression:
   118  
   119  ```
   120  [for o in var.list : o.interfaces][0].name
   121  ```
   122  
   123  Notice that with the attribute-only splat expression the index operation
   124  `[0]` is applied to the result of the iteration, rather than as part of
   125  the iteration itself. Only the attribute lookups apply to each element of
   126  the input. This limitation was confusing some people using older versions of
   127  Terraform and so we recommend always using the new-style splat expressions,
   128  with `[*]`, to get the more consistent behavior.