From aea6d7679e90123423c5ef09a0cee685aef8f5c8 Mon Sep 17 00:00:00 2001
From: "patchback[bot]" <45432694+patchback[bot]@users.noreply.github.com>
Date: Wed, 11 Dec 2024 11:51:23 +0000
Subject: [PATCH] Link to templating functions from the variables page (#2258)
 (#2281)

* Link to templating functions from the variables page

Add query/q templating function to the working with playbooks page

* fix typos, simplify example

(cherry picked from commit 2b7145d199189be6679186cbd35dd570c41bd160)

Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com>
---
 .../rst/playbook_guide/playbooks_lookups.rst  | 30 +++++++++++++++++--
 .../playbook_guide/playbooks_variables.rst    |  4 +++
 2 files changed, 31 insertions(+), 3 deletions(-)

diff --git a/docs/docsite/rst/playbook_guide/playbooks_lookups.rst b/docs/docsite/rst/playbook_guide/playbooks_lookups.rst
index 5ab335ae061..0df8b0c2b94 100644
--- a/docs/docsite/rst/playbook_guide/playbooks_lookups.rst
+++ b/docs/docsite/rst/playbook_guide/playbooks_lookups.rst
@@ -8,10 +8,10 @@ Lookup plugins retrieve data from outside sources such as files, databases, key/
 
 .. _lookups_and_variables:
 
-Using lookups in variables
-==========================
+The lookup function
+===================
 
-You can populate variables using lookups. Ansible evaluates the value each time it is executed in a task (or template).
+You can use the ``lookup`` function to populate variables dynamically. Ansible evaluates the value each time it is executed in a task (or template).
 
 .. code-block:: yaml+jinja
 
@@ -21,6 +21,30 @@ You can populate variables using lookups. Ansible evaluates the value each time
       - debug:
           msg: "motd value is {{ motd_value }}"
 
+The first argument to the ``lookup`` function is required and specifies the name of the lookup plugin. If the lookup plugin is in a collection, the fully qualified name must be provided, since the :ref:`collections keyword<collections_keyword>` does not apply to lookup plugins.
+
+The ``lookup`` function also accepts an optional boolean keyword ``wantlist``, which defaults to ``False``. When ``True``, the result of the lookup is ensured to be a list.
+
+Refer to the lookup plugin's documentation to see plugin-specific arguments and keywords.
+
+.. _lookups_and_variables_query:
+
+The query/q function
+====================
+
+This function is shorthand for ``lookup(..., wantlist=True)``. These are equivalent:
+
+.. code-block:: yaml+jinja
+
+   block:
+     - debug:
+         msg: "{{ item }}"
+       loop: "{{ lookup('ns.col.lookup_items', wantlist=True) }}"
+
+     - debug:
+         msg: "{{ item }}"
+       loop: "{{ q('ns.col.lookup_items') }}"
+
 For more details and a list of lookup plugins in ansible-core, see :ref:`plugins_lookup`. You may also find lookup plugins in collections. You can review a list of lookup plugins installed on your control machine with the command ``ansible-doc -l -t lookup``.
 
 .. seealso::
diff --git a/docs/docsite/rst/playbook_guide/playbooks_variables.rst b/docs/docsite/rst/playbook_guide/playbooks_variables.rst
index 31fe23cc385..856240bf872 100644
--- a/docs/docsite/rst/playbook_guide/playbooks_variables.rst
+++ b/docs/docsite/rst/playbook_guide/playbooks_variables.rst
@@ -41,6 +41,10 @@ This table gives examples of valid and invalid variable names:
 
 .. _Python keywords: https://docs.python.org/3/reference/lexical_analysis.html#keywords
 
+.. note:: Certain :ref:`variables<special_variables>` are defined internally, and cannot be defined by the user.
+
+.. note:: You may want to avoid variable names that would overwrite Jinja2 global functions listed in :ref:`working_with_playbooks`, such as :ref:`lookup<lookups_and_variables>`, :ref:`query<lookups_and_variables_query>`, :ref:`q<lookups_and_variables_query>`, :ref:`now<templating_now>`, and :ref:`undef<templating_undef>`.
+
 Simple variables
 ================