Skip to content

Lookup Tables

A lookup table answers the question "attribute A has the value x, which value does attribute B get?" from a list, instead of one rule per value. It is meant for long lists: thousands of entries are fine.

You find them under Modules > Lookup Tables.

The table

Give the table a Name (templates refer to it by that name), choose its Mode and paste the list into Table, for example a block copied out of a spreadsheet:

location;datacenter;owner
site-a;DC1;team-a
site-b;DC2;team-b
site-c;DC3;team-c
  • The first line names the columns, the same way as for a pasted list: lower cased, everything that is not a letter, digit or underscore becomes _.
  • In the mode Key / Value the first column is the key, every other column is a value (see Mode).
  • The separator is detected from the first line: tab, semicolon, comma or |.
  • Empty lines are skipped.
  • Up to 100000 entries per table.

The list view shows how many keys a table has and its columns.

Mode: Key / Value or Table

Key / Value (the default) is for lookup(): the first column is the key, every other column is a value. The table needs at least two columns, and a key that appears twice cannot be saved, since it would not be clear which line wins.

Table is a plain list of rows: any number of columns, also a single one, and values may repeat. It is meant for looping over it with lookup_rows(), for example to build a request body. lookup() works on it as well and takes the first line with the key.

site
site-a
site-b

Using it: lookup()

lookup() works in every Jinja field (Custom Attributes, Rewrite Attributes, export rules, ...). In Custom Attributes and Rewrite Attributes the Jinja help button below the value field lists your tables and their columns and inserts the lookup() call for you.

{{ lookup('datacenters', location) }}
{# the second column (datacenter) of the line whose key is the value of location #}

{{ lookup('datacenters', location, 'owner') }}
{# the column owner instead #}

{{ lookup('datacenters', location, default='unknown') }}
{# 'unknown' when there is nothing to find #}

Signature: lookup(table, key, column=None, default=''). The key is compared exactly (surrounding spaces are ignored). An unknown table, key or column, an empty cell or a host without the key attribute all give default.

Looping over a table: lookup_rows()

lookup_rows('datacenters') returns every line of the table as a dict of column name to value, in the order of the table, in both modes. An unknown table gives an empty list. It is meant for building a list or a request body out of the whole table, for example the POST body of a REST API import.

{% for row in lookup_rows('datacenters') %}{{ row.location }}: {{ row.owner }}
{% endfor %}

A Table of one column works the same way:

{% for row in lookup_rows('sites') %}{{ row.site }},{% endfor %}

Example: set the datacenter of a location

Hosts carry a location, and their datacenter attribute is unknown for some of them. Those should get the datacenter of their location from the list above.

Create a Global Custom Attribute rule:

  • Condition: attribute datacenter is unknown
  • Outcome: attribute name datacenter, value {{ lookup('datacenters', location, default='unknown') }}

Hosts with another datacenter are not touched. The same can be done without a condition in a single template:

{% if datacenter == 'unknown' %}{{ lookup('datacenters', location) }}{% else %}{{ datacenter }}{% endif %}

Changes

Saving or deleting a table resets the cached rule outcomes of the hosts, as a rule change does, so the next export uses the new values. A process that is already running (the web interface, a long export) reads a changed table again within a minute.

Lookup tables are part of the Rule Import/Export.