Skip to content

csvfile

Collection Note

This module is part of the ansible.builtin collection. To install the collection, use:

ansible-galaxy collection install ansible.builtin
Added in version 1.5.

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 O(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.

Parameters

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

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)
  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') }}"

# Contents of bgp_neighbors.csv
# 127.0.0.1,10.0.0.1,24,nones,lola,pepe,127.0.0.2
# 128.0.0.1,10.1.0.1,20,notes,lolita,pepito,128.0.0.2
# 129.0.0.1,10.2.0.1,23,nines,aayush,pepete,129.0.0.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:
    '{{ columns[item|int] }}': "{{ csvline }}"
  vars:
    csvline: "{{ lookup('csvfile', bgp_neighbor_ip, file='bgp_neighbors.csv', delimiter=',', col=item) }}"
    columns: ['loop_ip', 'int_ip', 'int_mask', 'int_name', 'local_as', 'neighbour_as', 'neight_int_ip']
    bgp_neighbor_ip: '127.0.0.1'
  loop: '{{ range(columns|length|int) }}'
  delegate_to: localhost
  delegate_facts: true

# Contents of people.csv
# # Last,First,Email,Extension
# Smith,Jane,jsmith@example.com,1234

- name: Specify the column (by keycol) in which the string should be searched
  assert:
    that:
    - lookup('ansible.builtin.csvfile', 'Jane', file='people.csv', delimiter=',', col=0, keycol=1) == "Smith"

# 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 Values

Key Data Type Description Returned
_raw list value(s) stored in file column

Authors

  • Jan-Piet Mens (@jpmens)