Collection Functions

Collection functions provide operations for manipulating lists, maps, and sets in HCL expressions.

Function Reference

chunklist

Splits a list into fixed-size chunks.

1
chunklist(list, chunk_size)

Parameters:

list - List to split
chunk_size - Size of each chunk

Returns: List of lists

Example:

1
chunklist(["a", "b", "c", "d", "e"], 2)
2
# Returns: [["a", "b"], ["c", "d"], ["e"]]
3

4
chunklist([1, 2, 3, 4, 5, 6], 3)
5
# Returns: [[1, 2, 3], [4, 5, 6]]

coalescelist

Returns the first non-empty list from the arguments.

1
coalescelist(lists...)

Parameters:

lists... - One or more lists

Returns: First non-empty list

Example:

1
coalescelist([], ["a", "b"], ["c", "d"])      # Returns: ["a", "b"]
2
coalescelist(var.custom_list, ["default"])     # Returns: custom_list or ["default"]
3
coalescelist([], [], ["fallback"])             # Returns: ["fallback"]

compact

Removes null and empty string elements from a list.

1
compact(list)

Parameters:

list - List of strings

Returns: List with null and empty strings removed

Example:

1
compact(["a", "", "b", null, "c"])     # Returns: ["a", "b", "c"]
2
compact(["", "", ""])                   # Returns: []
3
compact(["hello", "world"])             # Returns: ["hello", "world"]

concat

Combines multiple lists into a single list.

1
concat(lists...)

Parameters:

lists... - Lists to combine

Returns: Combined list

Example:

1
concat(["a", "b"], ["c", "d"])         # Returns: ["a", "b", "c", "d"]
2
concat([1, 2], [3], [4, 5])            # Returns: [1, 2, 3, 4, 5]
3
concat([], ["a"], [])                  # Returns: ["a"]

contains

Checks if a collection contains a specific value.

1
contains(list, value)

Parameters:

list - List, tuple, or set to search
value - Value to find

Returns: Boolean (true if value is found)

Example:

1
contains(["a", "b", "c"], "b")         # Returns: true
2
contains([1, 2, 3], 4)                 # Returns: false
3
contains(["web", "api"], "web")        # Returns: true

distinct

Removes duplicate elements from a list.

1
distinct(list)

Parameters:

list - List with potential duplicates

Returns: List with unique elements

Example:

1
distinct([1, 2, 2, 3, 1, 4])           # Returns: [1, 2, 3, 4]
2
distinct(["a", "b", "a", "c"])         # Returns: ["a", "b", "c"]
3
distinct([])                           # Returns: []

element

Retrieves an element at a specific index.

1
element(list, index)

Parameters:

list - List to access
index - Index position (wraps around if out of bounds)

Returns: Element at the index

Example:

1
element(["a", "b", "c"], 1)            # Returns: "b"
2
element(["a", "b", "c"], 3)            # Returns: "a" (wraps to index 0)
3
element(["a", "b", "c"], -1)           # Returns: "c" (negative wraps)

flatten

Flattens nested lists into a single list.

1
flatten(list)

Parameters:

list - List potentially containing nested lists

Returns: Flattened list

Example:

1
flatten([["a", "b"], ["c"]])           # Returns: ["a", "b", "c"]
2
flatten([[1, 2], [3, [4, 5]]])         # Returns: [1, 2, 3, 4, 5]
3
flatten(["a", ["b", ["c"]]])           # Returns: ["a", "b", "c"]

keys

Returns the keys from a map.

1
keys(map)

Parameters:

map - Map to extract keys from

Returns: List of keys (sorted)

Example:

1
keys({a = 1, b = 2, c = 3})            # Returns: ["a", "b", "c"]
2
keys({web = 80, api = 8080})           # Returns: ["api", "web"]
3
keys({})                               # Returns: []

length

Returns the number of elements in a collection.

1
length(value)

Parameters:

value - List, map, string, or tuple

Returns: Number of elements

Example:

1
length([1, 2, 3])                      # Returns: 3
2
length({a = 1, b = 2})                 # Returns: 2
3
length("hello")                        # Returns: 5
4
length([])                             # Returns: 0

merge

Combines multiple maps into a single map.

1
merge(maps...)

Parameters:

maps... - Maps to merge (later values override earlier)

Returns: Merged map

Example:

1
merge({a = 1}, {b = 2})                # Returns: {a = 1, b = 2}
2
merge({a = 1}, {a = 2})                # Returns: {a = 2}
3
merge({a = 1}, {b = 2}, {c = 3})      # Returns: {a = 1, b = 2, c = 3}

range

Generates a sequence of numbers.

1
range(limit)
2
range(start, limit)
3
range(start, limit, step)

Parameters:

start - Starting value (default: 0)
limit - Upper limit (exclusive)
step - Increment (default: 1)

Returns: List of numbers

Example:

1
range(3)                               # Returns: [0, 1, 2]
2
range(1, 4)                            # Returns: [1, 2, 3]
3
range(0, 10, 2)                        # Returns: [0, 2, 4, 6, 8]
4
range(5, 0, -1)                        # Returns: [5, 4, 3, 2, 1]

reverse

Reverses the order of elements.

1
reverse(list)

Parameters:

list - List or tuple to reverse

Returns: Reversed sequence

Example:

1
reverse([1, 2, 3])                     # Returns: [3, 2, 1]
2
reverse(["a", "b", "c"])               # Returns: ["c", "b", "a"]
3
reverse([])                            # Returns: []

setintersection

Finds common elements across sets.

1
setintersection(sets...)

Parameters:

sets... - Sets to intersect

Returns: Set of common elements

Example:

1
setintersection([1, 2, 3], [2, 3, 4])  # Returns: [2, 3]
2
setintersection(["a", "b"], ["b", "c"], ["b", "d"])  # Returns: ["b"]
3
setintersection([1, 2], [3, 4])        # Returns: []

setproduct

Calculates the Cartesian product of sets.

1
setproduct(sets...)

Parameters:

sets... - Sets to combine

Returns: List of all combinations

Example:

1
setproduct(["a", "b"], [1, 2])
2
# Returns: [["a", 1], ["a", 2], ["b", 1], ["b", 2]]
3

4
setproduct(["dev", "prod"], ["us", "eu"])
5
# Returns: [["dev", "us"], ["dev", "eu"], ["prod", "us"], ["prod", "eu"]]

setsubtract

Removes elements of one set from another.

1
setsubtract(set1, set2)

Parameters:

set1 - Set to subtract from
set2 - Set of elements to remove

Returns: Set with elements removed

Example:

1
setsubtract([1, 2, 3], [2, 3])         # Returns: [1]
2
setsubtract(["a", "b", "c"], ["d"])    # Returns: ["a", "b", "c"]
3
setsubtract(["a", "b"], ["a", "b"])    # Returns: []

setunion

Combines multiple sets removing duplicates.

1
setunion(sets...)

Parameters:

sets... - Sets to combine

Returns: Combined set without duplicates

Example:

1
setunion([1, 2], [2, 3])               # Returns: [1, 2, 3]
2
setunion(["a"], ["b"], ["c"])          # Returns: ["a", "b", "c"]
3
setunion([1, 2], [2, 3], [3, 4])       # Returns: [1, 2, 3, 4]

slice

Extracts a portion of a list.

1
slice(list, start, end)

Parameters:

list - List to slice
start - Starting index (inclusive)
end - Ending index (exclusive)

Returns: Extracted portion

Example:

1
slice(["a", "b", "c", "d"], 1, 3)      # Returns: ["b", "c"]
2
slice([1, 2, 3, 4, 5], 0, 2)           # Returns: [1, 2]
3
slice(["a", "b", "c"], 2, 10)          # Returns: ["c"]

sort

Sorts a list of strings lexicographically.

1
sort(list)

Parameters:

list - List of strings to sort

Returns: Sorted list

Example:

1
sort(["banana", "apple", "cherry"])    # Returns: ["apple", "banana", "cherry"]
2
sort(["3", "1", "2"])                  # Returns: ["1", "2", "3"]
3
sort(["Z", "a", "B"])                  # Returns: ["B", "Z", "a"]

values

Returns the values from a map.

1
values(map)

Parameters:

map - Map to extract values from

Returns: List of values

Example:

1
values({a = 1, b = 2, c = 3})          # Returns: [1, 2, 3]
2
values({web = "nginx", db = "postgres"}) # Returns: ["nginx", "postgres"]
3
values({})                             # Returns: []

zipmap

Creates a map from parallel lists of keys and values.

1
zipmap(keys, values)

Parameters:

keys - List of keys
values - List of values

Returns: Map combining keys and values

Example:

1
zipmap(["a", "b", "c"], [1, 2, 3])
2
# Returns: {a = 1, b = 2, c = 3}
3

4
zipmap(["web", "api"], ["80", "8080"])
5
# Returns: {web = "80", api = "8080"}

Common Use Cases

Dynamic Resource Creation

1
variable "environments" {
2
  default = ["dev", "staging", "prod"]
3
}
4

5
resource "container" "app" {
6
  for_each = toset(var.environments)
7

8
  image {
9
    name = "app:${each.value}"
10
  }
11
}

Configuration Merging

1
locals {
2
  default_config = {
3
    timeout = 30
4
    retries = 3
5
  }
6

7
  final_config = merge(
8
    local.default_config,
9
    var.custom_config
10
  )
11
}

List Processing

1
locals {
2
  # Remove empty values and duplicates
3
  clean_domains = distinct(compact(var.domains))
4

5
  # Create pairs of services and ports
6
  service_ports = zipmap(
7
    var.service_names,
8
    var.service_ports
9
  )
10
}

Set Operations

1
locals {
2
  # Find common regions
3
  available_regions = setintersection(
4
    var.requested_regions,
5
    data.cloud.available_regions
6
  )
7

8
  # Remove blocked IPs
9
  allowed_ips = setsubtract(
10
    var.all_ips,
11
    var.blocked_ips
12
  )
13
}

Best Practices

Use Type-Appropriate Functions: Choose functions that match your data structure
```
1
# For unique values, use sets
2
locals {
3
  unique_tags = toset(var.tags)
4
}
```

Handle Empty Collections: Consider edge cases with empty inputs

1
locals {
2
  safe_list = coalescelist(var.custom_list, ["default"])
3
  first_item = length(var.items) > 0 ? element(var.items, 0) : "none"
4
}

Maintain Readability: Break complex operations into steps

1
locals {
2
  # Step 1: Clean the data
3
  cleaned = compact(var.raw_data)
4
  # Step 2: Remove duplicates
5
  unique = distinct(local.cleaned)
6
  # Step 3: Sort the result
7
  final = sort(local.unique)
8
}

Consider Performance: Use efficient operations for large collections

1
# Use contains() instead of looping
2
locals {
3
  has_prod = contains(var.environments, "production")
4
}