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