Map Type
Map types store an ordered collection of single element type.
By default, maps from schema (configuration, plan, and state) data are represented in the framework by types.MapType
and its associated value storage type of types.Map
. These types fully support Terraform's type system concepts that cannot be represented in Go built-in types, such as a map. Framework types can be extended by provider code or shared libraries to provide specific use case functionality.
Schema Definitions
Use one of the following attribute types to directly add a map of a single element type to a schema or nested attribute type:
Schema Type | Attribute Type |
---|---|
Data Source | schema.MapAttribute |
Provider | schema.MapAttribute |
Resource | schema.MapAttribute |
Ephemeral Resource | schema.MapAttribute |
Use one of the following attribute types to directly add a map of a nested attributes to a schema or nested attribute type:
Schema Type | Attribute Type |
---|---|
Data Source | schema.MapNestedAttribute |
Provider | schema.MapNestedAttribute |
Resource | schema.MapNestedAttribute |
Ephemeral Resource | schema.MapNestedAttribute |
If the map value should be the element type of another collection attribute type, set the ElementType
field to types.MapType{ElemType: /* ... */}
or the appropriate custom type.
If the map value should be a value type of an object attribute type, set the AttributeTypes
map value to types.MapType{ElemType: /* ... */}
or the appropriate custom type.
Accessing Values
Tip
Review the attribute documentation to understand how schema-based data gets mapped into accessible values, such as a types.Map
in this case.
Access types.Map
information via the following methods:
(types.Map).IsNull() bool
: Returnstrue
if the map is null.(types.Map).IsUnknown() bool
: Returnstrue
if the map is unknown. Returnsfalse
if the number of elements is known, any of which may be unknown.(types.Map).Elements() map[string]attr.Value
: Returns the knownmap[string]attr.Value
value, ornil
if null or unknown.(types.Map).ElementsAs(context.Context, any, bool) diag.Diagnostics
: Converts the known values into the given Go type, if possible. It is recommended to use a map of framework types to account for elements which may be unknown.
In this example, a map of strings value is checked for being null or unknown value first, before accessing its known value elements as a map[string]types.String
:
Setting Values
Call one of the following to create a types.Map
value:
types.MapNull(attr.Type) types.Map
: A null list value with the given element type.types.MapUnknown(attr.Type) types.Map
: An unknown list value with the given element type.types.MapValue(attr.Type, map[string]attr.Value) (types.Map, diag.Diagnostics)
: A known value with the given element type and values.types.MapValueFrom(context.Context, attr.Type, any) (types.Map, diag.Diagnostics)
: A known value with the given element type and values. This can convert the source data from standard Go types into framework types as noted in the documentation for each element type, such as givingmap[string]*string
for atypes.Map
oftypes.String
.types.MapValueMust(map[string]attr.Type, map[string]attr.Value) types.Map
: A known value with the given element type and values. Any diagnostics are converted to a runtime panic. This is recommended only for testing or exhaustively tested logic.
In this example, a known map value is created from framework types:
Otherwise, for certain framework functionality that does not require types
implementations directly, such as:
(tfsdk.State).SetAttribute()
types.ListValueFrom()
types.MapValueFrom()
types.ObjectValueFrom()
types.SetValueFrom()
A Go built-in map of string key type (map[string]T
) or type alias of a map of string key type such as type MyMapType map[string]T
can be used instead.
In this example, a map[string]string
is directly used to set a map attribute value:
In this example, a types.Map
of types.String
is created from a map[string]string
:
Extending
The framework supports extending its base type implementations with custom types. These can adjust expected provider code usage depending on their implementation.