On This Page

Home / Search/ Enrich and Automate/Lookups

Lookups

Enrich events with lookup tables.

Lookups are tables of data referenced by the lookup and ip-lookup operators to enrich events. For example, you can use lookups to map user IDs to additional attributes like names or addresses, and return this enriched data in the search results.

You can access the Lookups page, which provides a management interface for all lookups, by selecting Knowledge > Lookups.

This lookups table is searchable, and you can add Tags to each lookup as necessary. There’s full support for .csv files. Compressed files are supported, but must be in gzip format (.gz extension).

Lookups page
Lookups page

For details about who can access and modify this resource, see Search Member Permissions. With appropriate Permissions, you can export, share, and import lookups in Packs.

Add a Lookup
​

As an alternative to using the Lookups page to add a lookup, you can use the export operator in a query to create or update a lookup. The export operator can write a maximum of 10,000 rows to the table.

  1. On the top right, select Add Lookup File.
  2. Select Upload a New File or Create with Text Editor.
  3. Give your lookup a unique Filename. You’ll use this to identify the lookup table in a lookup operation.
  4. Optionally, enter a Description.
  5. Optionally, enter any desired Tags.
  6. If you selected Create with Text Editor, enter your lookup table in the text box. Use CSV (comma-separated values) format with the header values on the first row as the field names, and the field values in the subsequent rows.

    Lookup field names must use letters, numbers, and underscores only.

  7. Select Save.

Example Lookup Table
​

service_name,port_number,transport
tcpmux,1,tcp
tcpmux,1,udp
compressnet,2,tcp
compressnet,2,udp
compressnet,3,tcp
compressnet,3,udp
rje,5,tcp
rje,5,udp
echo,7,tcp

Modify a Lookup
​

To re-upload, expand, edit, or delete an existing lookup, select its row on the Lookups page.

If the lookup you want to delete belongs to a Pack, see Delete a Pack Resource.

In the resulting modal, you can edit files in Table or Text mode. However, Text mode is disabled for files larger than 1 MB. The maximum lookup size is 10,000 rows.

Editing in Table mode
Editing in Table mode
Editing in Text mode
Editing in Text mode
Editing Regex with Quotation Marks
​

When a regex contains quotes, edit it in Text mode. Do not edit it in Table mode, which can cause the regex to behave in unexpected ways.

Export a Lookup
​

To export a lookup file, including any modifications that you’ve made, you have two options:

  • From a lookup’s configuration modal, select the Download File button.

  • From the Lookups page, Open the Actions Actions button menu on the lookup file’s table row, then select Download.

List Available Lookups
​

You can list all your lookup files straight from the query box, using the $vt_lookups virtual table:

// lists all lookups available to the current user
dataset="$vt_lookups"
Run in Cribl Search

Search the Contents of Your Lookups
​

You can use the $vt_lookups virtual table to search the contents of your lookups.

For example, to get the contents of a lookup named service_names_port_numbers.csv:

dataset="$vt_lookups" lookupFile="service_names_port_numbers"
Run in Cribl Search