Lookup Tables

string

The key to be looked up is an arbitrary string.

Match criterion: The key must be exactly equal to index from one of the entries.

array

The value to be looked up is an integer number from a consecutive set. The set does not need to start at zero or one, but there must be no number missing. So, for example 5,6,7,8,9 would be a valid set of index values, while 1,2,4,5 would not be (due to missing 3).

Match criterion: Looked-up number(key) must be exactly equal to index from one of the entries.

sparseArray

The value to be looked up is an integer value, but there may be gaps inside the set of values (usually there are large gaps). A typical use case would be the matching of IPv4 address information.

Match criterion: A match happens on the first index that is less than or equal to the looked-up key.

Note that index integer numbers are represented by unsigned 32 bits.

lookup_table(name=”<table>” file=”</path/to/file>”…) (object)

Defines the table(identified by the table-name) and allows user to set some properties that control behavior of the table.

lookup_table(name="msg_per_host")

Parameters:

name <string literal, mandatory> : Name of the table.

file <string literal, file path, mandatory> : Path to external json database file.

reloadOnHUP <on|off, default: on> : Whether or not table should be reloaded when process receives HUP signal.

A definition setting all the parameters looks like:

lookup_table(name="host_bu" file="/var/lib/host_billing_unit_mapping.json" reloadOnHUP="on")

lookup(“<table>”, <expr>) (function)

Looks up and returns the value that is associated with the given key (passed as <variable>) in lookup table identified by table-name. If no match is found (according to table-type matching-criteria specified above), the “nomatch” string is returned (or an empty string if it is not defined).

Parameters:

name <string literal, mandatory> : Name of the table.

expr <expression resulting in string or number according to lookup-table type, mandatory> : Key to be looked up.

A lookup call looks like:

set $.bu = lookup("host_bu", $hostname);

if ($.bu == "unknown") then {
    ....
}

Some examples of different match/no-match scenarios:

string table:

{ "nomatch" : "none",
  "type" : "string",
  "table":[
    {"index" : "foo", "value" : "bar" },
    {"index" : "baz", "value" : "quux" }]}

Match/no-Match behaviour:

array table:

{ "nomatch" : "nothing",
  "type" : "array",
  "table":[
    {"index" : 9, "value" : "foo" },
    {"index" : 10, "value" : "bar" },
    {"index" : 11, "value" : "baz" }]}

Match/no-Match behaviour:

sparseArray table:

{ "nomatch" : "no_num",
  "type" : "sparseArray",
  "table":[
    {"index" : "9", "value" : "foo" },
    {"index" : "11", "value" : "baz" }]}

Match/no-Match behaviour:

reload_lookup_table(“<table>”, “<stub value>”) (statement)

Reloads lookup table identified by given table name asynchronously (by internal trigger, as opposed to HUP).

This statement isn’t always useful. It needs to be used only when lookup-table-reload needs to be triggered in response to a message.

Messages will continue to be processed while table is asynchronously reloaded.

Note: For performance reasons, message that triggers reload should be accepted only from a trusted source.

Parameters:

name <string literal, mandatory> : Name of the table.

stub value <string literal, optional> : Value to stub the table in-case reload-attempt fails.

A reload_lookup_table invocation looks like:

if ($.do_reload == "y") then {
    reload_lookup_table("host_bu", "unknown")
}