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

2 files changed, 23 insertions, 6 deletions

diff --git a/docs/docsite/rst/user_guide/playbooks_conditionals.rst b/docs/docsite/rst/user_guide/playbooks_conditionals.rst
index 49fb659714..97e738be31 100644
--- a/docs/docsite/rst/user_guide/playbooks_conditionals.rst
+++ b/docs/docsite/rst/user_guide/playbooks_conditionals.rst
@@ -134,7 +134,7 @@ If you need to skip the whole task depending on the loop variable being defined,
 If using a dict in a loop::
 
         - command: echo {{ item.key }}
-          loop: "{{ lookup('dict', mydict|default({})) }}"
+          loop: "{{ query('dict', mydict|default({})) }}"
           when: item.value > 5
 
 .. _loading_in_custom_facts:
@@ -251,7 +251,7 @@ The following example shows how to template out a configuration file that was ve
       template:
           src: "{{ item }}"
           dest: /etc/myapp/foo.conf
-      loop: "{{lookup('first_found', { 'files': myfiles, 'paths': mypaths})}}"
+      loop: "{{ query('first_found', { 'files': myfiles, 'paths': mypaths}) }}"
       vars:
         myfiles:
           - "{{ansible_distribution}}.conf"
diff --git a/docs/docsite/rst/user_guide/playbooks_loops.rst b/docs/docsite/rst/user_guide/playbooks_loops.rst
index a9d5f72b80..b1e7f8271d 100644
--- a/docs/docsite/rst/user_guide/playbooks_loops.rst
+++ b/docs/docsite/rst/user_guide/playbooks_loops.rst
@@ -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`