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
even without specifying the collections:
keyword.
However, we recommend you use the FQCN for easy linking to the
plugin documentation and to avoid conflicting with other collections that may have
the same lookup plugin 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 |
Comments |
---|---|
column to return (0 indexed). Default: “1” |
|
what to return if the value is not found in the file. |
|
field separator in the file, for a tab you can specify Default: “TAB” |
|
Encoding (character set) of the used CSV file. Default: “utf-8” |
|
name of the CSV/TSV file to open. Default: “ansible.csv” |
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, this reads file in one go, but you could also use col= to read each in it's own lookup.
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('csvfile', bgp_neighbor_ip, file='bgp_neighbors.csv', delimiter=',') }}"
delegate_to: localhost
Return Values
Common return values are documented here, the following are the fields unique to this lookup:
Key |
Description |
---|---|
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.