lookup, query and loops · Ansible

lookup() and query() call the same plugin with the same arguments and return different types. That is the whole lesson, and it is worth a lesson because the difference is invisible in the common case and catastrophic in the loop case.

The demonstration

Read-only / Safelq.yml

- name: lookup versus query
hosts: localhost
gather_facts: false
vars:
  pkgs: ['nginx', 'curl', 'jq']
tasks:
  - ansible.builtin.debug:
      msg: "{{ lookup('ansible.builtin.items', pkgs) }}"

  - ansible.builtin.debug:
      msg: "{{ lookup('ansible.builtin.items', pkgs) | type_debug }}"

  - ansible.builtin.debug:
      msg: "{{ query('ansible.builtin.items', pkgs) }}"

  - ansible.builtin.debug:
      msg: "{{ query('ansible.builtin.items', pkgs) | type_debug }}"

Read-only / Safethe same call, two return types— Runs the comparison play. The lookup form returns a comma-joined string; the query form returns a list.

$ ansible-playbook -i localhost, lq.yml

TASK [lookup returns a string] *************************************************
ok: [localhost] => {
  "msg": "nginx,curl,jq"
}

TASK [type of lookup result] ***************************************************
ok: [localhost] => {
  "msg": "str"
}

TASK [query returns a list] ****************************************************
ok: [localhost] => {
  "msg": [
      "nginx",
      "curl",
      "jq"
  ]
}

TASK [type of query result] ****************************************************
ok: [localhost] => {
  "msg": "list"
}

"nginx,curl,jq" — one string, with commas in it. Not a list that prints with commas. The type_debug filter is the proof and it is worth reaching for any time an expression behaves oddly; it answers “what is this actually” in one filter.

lookup() joins. It takes whatever the plugin returned and comma-joins it into a string, because the historical use of a lookup was to produce a scalar for a template.

query() does not. It returns the plugin’s list as a list. It is an alias for lookup(..., wantlist=True):

Read-only / Safequery is wantlist— Confirms that wantlist=True gives the same type as query, and that the default does not.

$ ansible-playbook -i localhost, wantlist.yml

TASK [wantlist type] ***********************************************************
ok: [localhost] => {
  "msg": "list vs str"
}

The loop case

This is where it stops being a curiosity:

Read-only / Safethe bug

- ansible.builtin.debug:
  msg: "item is {{ item }}"
loop: "{{ lookup('ansible.builtin.items', pkgs) }}"

Read-only / Safeansible-core 2.21 refuses— Runs a loop over a lookup that returned a string. The engine rejects it rather than iterating.

$ ansible-playbook -i localhost, lq.yml

TASK [loop over lookup] ********************************************************
[ERROR]: The `loop` value must resolve to a 'list', not 'str'.
Origin: /home/opsuser/project/lq.yml:22:13

20       ansible.builtin.debug:
21         msg: "item is {{ item }}"
22       loop: "{{ lookup('ansible.builtin.items', pkgs) }}"
             ^ column 13

Provide a list of items/templates, or a template resolving to a list.

fatal: [localhost]: FAILED! => {"msg": "The `loop` value must resolve to a 'list', not 'str'."}

A clear error, pointing at the exact line and column, saying precisely what is wrong. That is a good outcome and it is not one you can rely on having in older environments — the historic behaviour of feeding a string to something expecting a sequence is to iterate it, one character at a time.

Why this is dangerous outside `loop`

loop in 2.21 type-checks. Nothing else does.

- ansible.builtin.package:
    name: "{{ lookup('ansible.builtin.items', pkgs) }}"
    state: present

name accepts a string or a list, so "nginx,curl,jq" is a perfectly valid value with no type error to raise — and package managers will happily reject or misinterpret a package literally named nginx,curl,jq.

The same hazard applies anywhere a list-or-string parameter meets a lookup: with_items in legacy code, when conditions on membership, set_fact values that are consumed later. loop catches it; the places where it silently succeeds are the ones to watch.

The habit that removes the whole class: use query() whenever the result feeds anything that expects a list. There is no cost and it documents the intent.

Which to use

Situation	Use
Interpolating a value into a template or a string	`lookup()`
Feeding `loop:`	`query()`
Setting a variable that other tasks will iterate	`query()`
A module parameter that takes a list	`query()`
A module parameter that takes a scalar	`lookup()`
Any lookup that can return more than one result	`query()`, then decide

The default worth adopting: query() unless you specifically want a joined string. A single-element list is easy to handle; a string that should have been a list is a bug that appears months later.

Note that query() always returns a list even for lookups that conceptually return one value:

Read-only / Safequery wraps even a scalar— Compares the types returned by query and lookup for an environment variable, which has exactly one value.

$ ansible-playbook -i localhost, scalar.yml

TASK [single item still a string] **********************************************
ok: [localhost] => {
  "msg": "list / str"
}

So query('env', 'HOME') gives ['/home/opsuser'], not '/home/opsuser'. For a genuinely scalar read, lookup() is the right call and | first on a query result is a smell.

`errors`

Every lookup accepts an errors argument controlling what happens when it cannot do its job. The default is strict.

Read-only / Safethree behaviours for a missing file— Runs the same failing lookup three times with different errors settings. Only the third fails the task.

$ ansible-playbook -i localhost, err.yml

TASK [errors ignore] ***********************************************************
ok: [localhost] => {
  "msg": "got []"
}

TASK [errors warn] *************************************************************
[WARNING]: An error occurred while running the lookup plugin 'ansible.builtin.file': Unable to access the file 'nope.txt': File not found. Use -vvvvv to see paths searched.
ok: [localhost] => {
  "msg": "got []"
}

TASK [errors strict (default)] *************************************************
[ERROR]: Task failed: Finalization of task args for 'ansible.builtin.debug' failed: Error while resolving value for 'msg': The lookup plugin 'ansible.builtin.file' failed: Unable to access the file 'nope.txt': File not found. Use -vvvvv to see paths searched.
fatal: [localhost]: FAILED! => {"msg": "Task failed: Finalization of task args for 'ansible.builtin.debug' failed: Error while resolving value for 'msg': The lookup plugin 'ansible.builtin.file' failed: Unable to access the file 'nope.txt': File not found."}

strict (default) — the lookup failure fails the task. Correct for anything the play depends on.
warn — logs a warning and yields empty. The failure is visible in the run output and does not stop it.
ignore — yields empty silently. got [] with no indication anything went wrong.

`errors='ignore'` on a secret lookup deploys an empty secret

Look at that first task result again: got []. The file did not exist, the lookup produced nothing, and the run reported ok.

Now imagine that expression was fetching an API token for a config template. The template renders with an empty token, the file deploys, the service restarts, and the failure surfaces as an authentication error in an application log at 4am — several steps removed from the task that caused it.

errors='ignore' is defensible for genuinely optional data where the consumer has a sensible default. It is indefensible anywhere the absence of the value is a failure, and credentials are always that.

Where you do use it, pair it with an explicit check:

- ansible.builtin.assert:
    that: token | length > 0
    fail_msg: The API token lookup returned nothing.

Why the default is a joined string at all

It is age. Lookups predate loop — they predate with_items being the common idiom — and the original use was scalar interpolation into a template:

ServerAdmin {{ lookup('ini', 'admin section=web file=site.ini') }}

For that, returning a string is exactly right, and a plugin that happened to return several values needed some way to render. Joining with commas was the choice.

wantlist=True was added when the list case became common, and query() is a friendlier spelling of it. The default could not change without breaking every template written against the old behaviour, so it stayed — and the result is an interface where the more commonly correct option is the one you have to ask for.

The one place the old behaviour is still load-bearing is the with_* family: with_items is defined in terms of a lookup and handles the list conversion itself, which is why legacy code using with_items does not exhibit this bug and code migrated to loop sometimes does. Part XIV covers reading that legacy; here the point is narrow — a with_items to loop conversion is exactly where a lookup() needs to become a query().

What happens if the lookup returns nothing at all?

Both forms succeed and return an empty value, of their respective types: '' from lookup(), [] from query(). Neither is an error, because “no results” is a legitimate answer for most lookups — fileglob matching nothing, varnames finding no variables.

The consequences differ sharply by consumer:

A loop over [] runs zero times and reports ok. The play succeeds having done nothing. This is the silent one: a run that was supposed to configure eight services configures none and reports green.
A template interpolating '' renders an empty field, producing a syntactically valid configuration file with a blank value in it.
A module parameter receiving '' or [] behaves per module, and usually not well.

Where “at least one result” is part of the requirement, say so:

- ansible.builtin.assert:
    that: certs | length > 0
    fail_msg: No certificates matched; expected at least one.
  vars:
    certs: "{{ query('ansible.builtin.fileglob', 'certs/*.pem') }}"

That is three lines that convert a silent no-op into a named failure, and Part XI’s assert material argues for it generally. This is one of the clearest cases for it.

The demonstration

The loop case

Which to use

errors

Knowledge check

`errors`