ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-07-28 07:31:23 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Documentation for query/q. Fixes #38275 (#38558)

Browse source
This commit is contained in:
Matt Martz 2018-04-25 12:55:34 -05:00 • committed by GitHub
commit 476d1f818e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 47 additions and 6 deletions
Download patch file Download diff file Expand all files Collapse all files

25
docs/docsite/rst/user_guide/playbooks_loops.rst
View file

@ -80,7 +80,7 @@ To loop over a dict, use the ``dict2items`` :ref:`dict_filter`::
- name: create a tag dictionary of non-empty tags
set_fact:
tags_dict: "{{ (tags_dict|default({}))|combine({item.key: item.value}) }}"
with_items: "{{ tags|dict2items }}"
loop: "{{ tags|dict2items }}"
vars:
tags:
Environment: dev
@ -105,10 +105,27 @@ For example, using the 'nested' lookup, you can combine lists::
priv: "{{ item[1] }}.*:ALL"
append_privs: yes
password: "foo"
loop: "{{ lookup('nested', [ 'alice', 'bob' ], [ 'clientdb', 'employeedb', 'providerdb' ]) }}"
loop: "{{ query('nested', [ 'alice', 'bob' ], [ 'clientdb', 'employeedb', 'providerdb' ]) }}"
.. note:: ``with_`` loops are actually a combination of things ``with_`` + ``lookup()``, even ``items`` is a lookup. ``loop`` can be used in the same way as shown above.
Using lookup vs query with loop
```````````````````````````````
In Ansible 2.5 a new jinja2 function was introduced named :ref:`query`, that offers several benefits over ``lookup`` when using the new ``loop`` keyword.
This is described more in the lookup documentation, however, ``query`` provides a more simple interface and a more predictable output from lookup plugins, ensuring better compatibility with ``loop``.
In certain situations the ``lookup`` function may not return a list which ``loop`` requires.
The following invocations are equivalent, using ``wantlist=True`` with ``lookup`` to ensure a return type of a list::
loop: "{{ query('nested', ['alice', 'bob'], ['clientdb', 'employeedb', 'providerdb']) }}"
loop: "{{ lookup('nested', ['alice', 'bob'], ['clientdb', 'employeedb', 'providerdb'], wantlist=True) }}"
.. _do_until_loops:
Do-Until Loops
@ -224,12 +241,12 @@ There is also a specific lookup plugin ``inventory_hostnames`` that can be used
# show all the hosts in the inventory
- debug:
msg: "{{ item }}"
loop: "{{ lookup('inventory_hostnames', 'all') }}"
loop: "{{ query('inventory_hostnames', 'all') }}"
# show all the hosts matching the pattern, ie all but the group www
- debug:
msg: "{{ item }}"
loop: "{{ lookup('inventory_hostnames', 'all!www') }}"
loop: "{{ query('inventory_hostnames', 'all!www') }}"
More information on the patterns can be found on :doc:`intro_patterns`