data_dig backends

Hiera lets you look up individual members of hash and array values using key.subkey notation. Use data_dig types in cases where:

• Lookups are relatively expensive.

• The data source knows how to extract elements from hash and array values.

• Users are likely to pass key.subkey requests to the lookup function to access subsets of large data structures.

Arguments

Hiera calls a data_dig function with three arguments:

• An array of lookup key segments, made by splitting the requested lookup key on the dot (.) subkey separator. For example, a lookup for users.dbadmin.uid results in ['users', 'dbadmin', 'uid']. Positive base-10 integer subkeys (for accessing array members) are converted to Integer objects, but other number subkeys remain as strings.

• A hash of options.

• A Puppet::LookupContext object.

Return type

The function must either call the context object’s not_found method, or return a value for the requested sequence of key segments. Note that returning undef (nil in Ruby) means that the key was found but that the value for that key was specified to be undef. Puppet language example signature:

function mymodule::hiera_backend(
  Array[Variant[String, Numeric]] $segments,
  Hash                            $options,
  Puppet::LookupContext           $context,
)

Ruby example signature:

dispatch :hiera_backend do
  param 'Array[Variant[String, Numeric]]', :segments
  param 'Hash', :options
  param 'Puppet::LookupContext', :context
end

A data_dig function can return a hash for the the lookup_options key to configure merge behavior for other keys. See Configuring merge behavior in Hiera data for more info.

To support Hiera interpolation tokens like %{variable} or %{lookup('key')} in your data, call context.interpolate on your values before returning them.

Related information

• Merge behaviors

• Access hash and array elements using a key.subkey notation