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 10.0.1).

You might already have this collection installed if you are using the ansible package. 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.