github.com/muratcelep/terraform@v1.1.0-beta2-not-internal-4/website/docs/language/expressions/splat.html.md (about)

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