Map Function Parameter

Map function parameters expect a mapping of arbitrary string keys to values of single element type from a practitioner configuration. Values are accessible in function logic by a Go map of string keys to values of an appropriate pointer type to match the element type map[string]*T or the framework map type.

In this Terraform configuration example, a map of string parameter is set to the mapped values of "key1" to "value1" and "key2" to "value2":

provider::example::example({
    "key1" = "value1",
    "key2" = "value2",
})

Function Definition

Use the function.MapParameter type in the function definition to accept a map value.

The ElementType field must be defined, which represents the single framework value type of every element of the map. An element type may itself contain further collection or object types, if necessary.

In this example, a function definition includes a first position map of string parameter:

func (f ExampleFunction) Definition(ctx context.Context, req function.DefinitionRequest, resp *function.DefinitionResponse) {
    resp.Definition = function.Definition{
        // ... other Definition fields ...
        Parameters: []function.Parameter{
            function.MapParameter{
                ElementType: types.StringType,
                Name: "map_param",
                // ... potentially other MapParameter fields ...
            },
        },
    }
}

If the map value should be the element type of another collection parameter type, set the ElementType field according to the framework map type. Refer to the collection parameter type documentation for additional details.

If the map value should be a value type of an object parameter type, set the AttributeTypes map value according to the framework map type. Refer to the object parameter type documentation for additional details.

Allow Null Values

By default, Terraform will not pass null values to the function logic. Use the AllowNullValue field to explicitly allow null values, if there is a meaningful distinction that should occur in function logic. Enabling AllowNullValue requires no changes when reading argument data.

Allow Unknown Values

By default, Terraform will not pass unknown values to the function logic. Use the AllowUnknownValues field to explicitly allow unknown values, if there is a meaningful distinction that should occur in function logic. Enabling AllowUnknownValues requires using a framework map type when reading argument data.

Custom Types

You may want to build your own data value and type implementations to allow your provider to combine validation and other behaviors into a reusable bundle. This helps avoid duplication and ensures consistency. These implementations use the CustomType field in the parameter type.

Refer to Custom Types for further details on creating provider-defined types and values.

Documentation

Refer to function documentation for information about the Name, Description, and MarkdownDescription fields available.

Reading Argument Data

The function implementation documentation covers the general methods for reading function argument data in function logic.

When retrieving the argument value for this parameter:

• If CustomType is set, use its associated value type.
• If AllowUnknownValues is enabled, you must use the framework map type.
• Otherwise, use the Go map of string keys to values of an appropriate pointer type to match the element type map[string]*T or framework map type.

In this example, a function defines a single map of string parameter and accesses its argument value:

func (f ExampleFunction) Definition(ctx context.Context, req function.DefinitionRequest, resp *function.DefinitionResponse) {
    resp.Definition = function.Definition{
        // ... other Definition fields ...
        Parameters: []function.Parameter{
            function.MapParameter{
                ElementType: types.StringType,
                Name: "map_param",
                // ... potentially other MapParameter fields ...
            },
        },
    }
}

func (f ExampleFunction) Run(ctx context.Context, req function.RunRequest, resp *function.RunResponse) {
    var mapArg map[string]*string // Go nil equals Terraform null
    // var mapArg types.Map // e.g. with AllowUnknownValues

    resp.Error = function.ConcatFuncErrors(resp.Error, req.Arguments.Get(ctx, &mapArg))

    // mapArg is now populated
    // ... other logic ...
}