community.general.keep_keys filter – Keep specific keys from dictionaries in a list

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.keep_keys.

New in community.general 9.1.0

Synopsis

  • This filter keeps only specified keys from a provided list of dictionaries.

Input

This describes the input of the filter, the value before | community.general.keep_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.keep_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 items.

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

  • "regex": Matches keys that match the regular expresion provided in target.

    In this case, target must be a regex string or a list with single regex string.

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

target

any / required

A single key or key pattern to keep, or a list of keys or keys patterns to keep.

If matching_parameter=regex there must be exactly one pattern provided.

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 match keys that equal any of the items in the target.
t: [k0_x0, k1_x1]
r: "{{ l | community.general.keep_keys(target=t) }}"

# 2) Match keys that start with any of the items in the target.
t: [k0, k1]
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='starts_with') }}"

# 3) Match keys that end with any of the items in target.
t: [x0, x1]
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='ends_with') }}"

# 4) Match keys by the regex.
t: ['^.*[01]_x.*$']
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}"

# 5) Match keys by the regex.
t: '^.*[01]_x.*$'
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}"

# The results of above examples 1-5 are all the same.
r:
  - {k0_x0: A0, k1_x1: B0}
  - {k0_x0: A1, k1_x1: B1}

# 6) By default match keys that equal the target.
t: k0_x0
r: "{{ l | community.general.keep_keys(target=t) }}"

# 7) Match keys that start with the target.
t: k0
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='starts_with') }}"

# 8) Match keys that end with the target.
t: x0
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='ends_with') }}"

# 9) Match keys by the regex.
t: '^.*0_x.*$'
r: "{{ l | community.general.keep_keys(target=t, matching_parameter='regex') }}"

# The results of above examples 6-9 are all the same.
r:
  - {k0_x0: A0}
  - {k0_x0: A1}

Return Value

Key

Description

Return value

list / elements=dictionary

The list of dictionaries with selected 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.