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
Parameters
Notes
Examples
Return Values

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, and returns the value in the second column, unless a different column is specified.

Parameters

Parameter	Choices/Defaults	Comments
col string	Default: "1"	column to return (0 index).
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.

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)

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