ansible.builtin.csvfile lookup – read data from a TSV or CSV file

Note

This lookup plugin is part of ansible-core and included in all Ansible installations. In most cases, you can use the short plugin name csvfile. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.csvfile for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same lookup plugin name.

Synopsis

  • The csvfile lookup reads the contents of a file in CSV (comma-separated value) format. The lookup looks for the row where the first column matches keyname (which can be multiple words) and returns the value in the col column (default 1, which indexed from 0 means the second column in the file).

  • At least one keyname is required, provided as a positional argument(s) to the lookup.

Keyword parameters

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('ansible.builtin.csvfile', key1=value1, key2=value2, ...) and query('ansible.builtin.csvfile', key1=value1, key2=value2, ...)

Parameter

Comments

col

string

column to return (0 indexed).

Default: "1"

default

string

what to return if the value is not found in the file.

delimiter

string

field separator in the file, for a tab you can specify TAB or \t.

Default: "TAB"

encoding

string

Encoding (character set) of the used CSV file.

Default: "utf-8"

file

string

name of the CSV/TSV file to open.

Default: "ansible.csv"

keycol

integer

added in ansible-core 2.17

column to search in (0 indexed).

Default: 0

Notes

Note

  • The default is for TSV files (tab delimited) not CSV (comma delimited) … yes the name is misleading.

  • As of version 2.11, the search parameter (text that must match the first column of the file) and filename parameter can be multi-word.

  • For historical reasons, in the search keyname, quotes are treated literally and cannot be used around the string unless they appear (escaped as required) in the first column of the file you are parsing.

See Also

See also

Task paths

Search paths used for relative files.

Examples

- name:  Match 'Li' on the first column, return the second column (0 based index)
  ansible.builtin.debug: msg="The atomic number of Lithium is {{ lookup('ansible.builtin.csvfile', 'Li file=elements.csv delimiter=,') }}"

- name: msg="Match 'Li' on the first column, but return the 3rd column (columns start counting after the match)"
  ansible.builtin.debug: msg="The atomic mass of Lithium is {{ lookup('ansible.builtin.csvfile', 'Li file=elements.csv delimiter=, col=2') }}"

- name: Define Values From CSV File, this reads file in one go, but you could also use col= to read each in it's own lookup.
  ansible.builtin.set_fact:
    loop_ip: "{{ csvline[0] }}"
    int_ip: "{{ csvline[1] }}"
    int_mask: "{{ csvline[2] }}"
    int_name: "{{ csvline[3] }}"
    local_as: "{{ csvline[4] }}"
    neighbor_as: "{{ csvline[5] }}"
    neigh_int_ip: "{{ csvline[6] }}"
  vars:
    csvline: "{{ lookup('ansible.builtin.csvfile', bgp_neighbor_ip, file='bgp_neighbors.csv', delimiter=',') }}"
  delegate_to: localhost

# Contents of debug.csv
# test1 ret1.1 ret2.1
# test2 ret1.2 ret2.2
# test3 ret1.3 ret2.3

- name: "Lookup multiple keynames in the first column (index 0), returning the values from the second column (index 1)"
  debug:
    msg: "{{ lookup('csvfile', 'test1', 'test2', file='debug.csv', delimiter=' ') }}"

- name: Lookup multiple keynames using old style syntax
  debug:
    msg: "{{ lookup('csvfile', term1, term2) }}"
  vars:
    term1: "test1 file=debug.csv delimiter=' '"
    term2: "test2 file=debug.csv delimiter=' '"

Return Value

Key

Description

Return value

list / elements=string

value(s) stored in file column

Returned: success

Authors

  • Jan-Piet Mens (@jpmens) <jpmens(at)gmail.com>

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.