community.general.replace_keys filter – Replace specific keys in a list of dictionaries

Note

This filter plugin is part of the community.general collection (version 9.4.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.replace_keys.

New in community.general 9.1.0

Synopsis

  • This filter replaces specified keys in a provided list of dictionaries.

Input

This describes the input of the filter, the value before | community.general.replace_keys.

Parameter

Comments

Input

list / elements=dictionary / required

A list of dictionaries.

Top level keys must be strings.

Keyword parameters

This describes keyword parameters of the filter. These are the values key1=value1, key2=value2 and so on in the following example: input | community.general.replace_keys(key1=value1, key2=value2, ...)

Parameter

Comments

matching_parameter

string

Specify the matching option of target keys.

Choices:

  • "ends_with": Matches keys that end with one of the target[].before items.

  • "equal" (default): Matches keys of exactly one of the target[].before items.

  • "regex": Matches keys that match one of the regular expressions provided in target[].before.

  • "starts_with": Matches keys that start with one of the target[].before items.

target

list / elements=dictionary / required

A list of dictionaries with attributes before and after.

The value of target[].after replaces key matching target[].before.

after

string

A matching key change to.

before

string

A key or key pattern to change.

The interpretation of target[].before depends on matching_parameter.

For a key that matches multiple target[].befores, the first matching target[].after will be used.

Examples

l:
  - {k0_x0: A0, k1_x1: B0, k2_x2: [C0], k3_x3: foo}
  - {k0_x0: A1, k1_x1: B1, k2_x2: [C1], k3_x3: bar}

# 1) By default, replace keys that are equal any of the attributes before.
t:
  - {before: k0_x0, after: a0}
  - {before: k1_x1, after: a1}
r: "{{ l | community.general.replace_keys(target=t) }}"

# 2) Replace keys that starts with any of the attributes before.
t:
  - {before: k0, after: a0}
  - {before: k1, after: a1}
r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}"

# 3) Replace keys that ends with any of the attributes before.
t:
  - {before: x0, after: a0}
  - {before: x1, after: a1}
r: "{{ l | community.general.replace_keys(target=t, matching_parameter='ends_with') }}"

# 4) Replace keys that match any regex of the attributes before.
t:
  - {before: "^.*0_x.*$", after: a0}
  - {before: "^.*1_x.*$", after: a1}
r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}"

# The results of above examples 1-4 are all the same.
r:
  - {a0: A0, a1: B0, k2_x2: [C0], k3_x3: foo}
  - {a0: A1, a1: B1, k2_x2: [C1], k3_x3: bar}

# 5) If more keys match the same attribute before the last one will be used.
t:
  - {before: "^.*_x.*$", after: X}
r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}"

# gives

r:
  - X: foo
  - X: bar

# 6) If there are items with equal attribute before the first one will be used.
t:
  - {before: "^.*_x.*$", after: X}
  - {before: "^.*_x.*$", after: Y}
r: "{{ l | community.general.replace_keys(target=t, matching_parameter='regex') }}"

# gives

r:
  - X: foo
  - X: bar

# 7) If there are more matches for a key the first one will be used.
l:
  - {aaa1: A, bbb1: B, ccc1: C}
  - {aaa2: D, bbb2: E, ccc2: F}
t:
  - {before: a, after: X}
  - {before: aa, after: Y}
r: "{{ l | community.general.replace_keys(target=t, matching_parameter='starts_with') }}"

# gives

r:
  - {X: A, bbb1: B, ccc1: C}
  - {X: D, bbb2: E, ccc2: F}

Return Value

Key

Description

Return value

list / elements=dictionary

The list of dictionaries with replaced keys.

Returned: success

Authors

  • Vladimir Botka (@vbotka)

  • Felix Fontein (@felixfontein)

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.