data_hash backends

A data_hash backend function reads an entire data source at one time, and returns its contents as a hash.

The built-in YAML, JSON, and HOCON backends are all data_hash functions. You can view their source on GitHub:

Arguments

Hiera calls a data_hash function with two arguments:

  • A hash of options

    • The options hash contains a path when the entry in hiera.yaml is using path, paths, glob, globs, or mapped_paths, and the backend receives one call per path to an existing file. When the entry in hiera.yaml is using uri or uris, the options hash has a uri key, and the backend function is called one time per given uri. When uri or uris are used, Hiera does not perform an existence check. It is up to the function to type the options parameter as wanted.

  • A Puppet::LookupContext object

Return type

The function must either call the context object’s not_found method, or return a hash of lookup keys and their associated values. The hash can be empty.

Puppet language example signature:

function mymodule::hiera_backend(
  Hash                  $options,
  Puppet::LookupContext $context,
)

Ruby example signature:

dispatch :hiera_backend do
  param 'Hash', :options
  param 'Puppet::LookupContext', :context
end

The returned hash can include the lookup_options key to configure merge behavior for other keys. See Configuring merge behavior in Hiera data for more information. Values in the returned hash can include Hiera interpolation tokens like %{variable} or %{lookup('key')}; Hiera interpolates values as needed. This is a significant difference between data_hash and the other two backend types; lookup_key and data_dig functions have to explicitly handle interpolation.

Related information