From 3bcca725fc417fb3939d7403d0f6a3379a0e628a Mon Sep 17 00:00:00 2001
From: Matt Martz <matt@sivel.net>
Date: Wed, 25 Apr 2018 13:34:19 -0500
Subject: [PATCH] Documentation for query/q. Fixes #38275 (#38558) (#39316)

(cherry picked from commit 476d1f818e4ec0402568946b3c7514179a29b7d7)
---
 docs/docsite/rst/plugins/lookup.rst           | 24 +++++++++++++++++++
 .../rst/user_guide/playbooks_conditionals.rst |  4 ++--
 .../rst/user_guide/playbooks_loops.rst        | 23 +++++++++++++++---
 3 files changed, 46 insertions(+), 5 deletions(-)

diff --git a/docs/docsite/rst/plugins/lookup.rst b/docs/docsite/rst/plugins/lookup.rst
index 5c61d20332385a..240a6bc9c03cbb 100644
--- a/docs/docsite/rst/plugins/lookup.rst
+++ b/docs/docsite/rst/plugins/lookup.rst
@@ -65,6 +65,30 @@ You can combine lookups with :ref:`playbooks_filters`, :ref:`playbooks_tests` an
         - "{{lookup('sequence', 'end=42 start=2 step=2')|map('log', 4)|list)}}"
         - ['a', 'c', 'd', 'c']
 
+.. _query:
+
+query
++++++
+
+.. versionadded:: 2.5
+
+In Ansible 2.5, a new jinja2 function called ``query`` was added for invoking lookup plugins. The difference between ``lookup`` and ``query`` is largely that ``query`` will always return a list.
+The default behavior of ``lookup`` is to return a string of comma separated values. ``lookup`` can be explicitly configured to return a list using ``wantlist=True``.
+
+This was done primarily to provide an easier and more consistent interface for interacting with the new ``loop`` keyword, while maintaining backwards compatibiltiy with other uses of ``lookup``.
+
+The following examples are equivalent::
+
+    lookup('dict', dict_variable, wantlist=True)
+
+    query('dict', dict_variable)
+
+As demonstrated above the behavior of ``wantlist=True`` is implicit when using ``query``.
+
+Additionally, ``q`` was introduced as a shortform of ``query``::
+
+    q('dict', dict_variable)
+
 
 .. _lookup_plugins_list:
 
diff --git a/docs/docsite/rst/user_guide/playbooks_conditionals.rst b/docs/docsite/rst/user_guide/playbooks_conditionals.rst
index 1a461cac0851a1..1f5881cddae15f 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:
@@ -250,7 +250,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 289ee9f3f673cb..397b52e5b9f44c 100644
--- a/docs/docsite/rst/user_guide/playbooks_loops.rst
+++ b/docs/docsite/rst/user_guide/playbooks_loops.rst
@@ -90,10 +90,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
@@ -209,12 +226,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`