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

Note

This module is part of ansible-base and included in all Ansible installations. In most cases, you can use the short module name csvfile even without specifying the collections: keyword. Despite that, we recommend you use the FQCN for easy linking to the module documentation and to avoid conflicting with other collections that may have the same module name.

New in version 1.5: of ansible.builtin

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).

Parameters

Parameter Choices/Defaults Configuration Comments
col
string
Default:
"1"
column to return (0 indexed).
default
string
Default:
""
what to return if the value is not found in the file.
delimiter
string
Default:
"TAB"
field separator in the file, for a tab you can specify TAB or \t.
encoding
string
added in 2.1 of ansible.builtin
Default:
"utf-8"
Encoding (character set) of the used CSV file.
file
string
Default:
"ansible.csv"
name of the CSV/TSV file to open.

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.

Examples

- name:  Match 'Li' on the first column, return the second column (0 based index)
  debug: msg="The atomic number of Lithium is {{ lookup('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)"
  debug: msg="The atomic mass of Lithium is {{ lookup('csvfile', 'Li file=elements.csv delimiter=, col=2') }}"

- name: Define Values From CSV File
  set_fact:
    loop_ip: "{{ lookup('csvfile', bgp_neighbor_ip +' file=bgp_neighbors.csv delimiter=, col=1') }}"
    int_ip: "{{ lookup('csvfile', bgp_neighbor_ip +' file=bgp_neighbors.csv delimiter=, col=2') }}"
    int_mask: "{{ lookup('csvfile', bgp_neighbor_ip +' file=bgp_neighbors.csv delimiter=, col=3') }}"
    int_name: "{{ lookup('csvfile', bgp_neighbor_ip +' file=bgp_neighbors.csv delimiter=, col=4') }}"
    local_as: "{{ lookup('csvfile', bgp_neighbor_ip +' file=bgp_neighbors.csv delimiter=, col=5') }}"
    neighbor_as: "{{ lookup('csvfile', bgp_neighbor_ip +' file=bgp_neighbors.csv delimiter=, col=6') }}"
    neigh_int_ip: "{{ lookup('csvfile', bgp_neighbor_ip +' file=bgp_neighbors.csv delimiter=, col=7') }}"
  delegate_to: localhost

Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key Returned Description
_raw
list / elements=string
success
value(s) stored in file column


Authors

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

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/ansible/builtin/csvfile_lookup.html