---
title: "File Lookup"
description: "enrich TenXObjects with lookup table values"
source: "https://github.com/log-10x/modules/tree/main/pipelines/run/modules/initialize/lookup/module.yaml"
icon: "material/table-eye"

---
Enrich TenXObjects using CSV [lookup](https://doc.log10x.com/api/js/#TenXLookup "Load and query the values of text lookup tables (.csv, .tsv) and geoIP DB files (.mmdb).") files.

Example: map [HTTP status codes](https://github.com/Mr-Pi/httpStatusCodes/blob/master/priv/http-status-codes-1.csv?plain=1){target="\_blank"} to human-readable messages.

Lookup files [reload](https://doc.log10x.com/run/reload/ "Monitor changes to configuration and symbol files") on disk changes. The engine can pull them from a [GitHub repo](https://doc.log10x.com/config/github/) or a [Kubernetes ConfigMap](https://doc.log10x.com/config/k8s/) via the @kubernetes launch macro, which polls the ConfigMap over the Kubernetes API and writes each key atomically into a watched temp folder, so an edit propagates without redeploying the pod. (A ConfigMap mounted as a pod volume is not equivalent: kubelet swaps the underlying symlink and most file watchers miss the change. The default key filter is `*.csv` and `*.json`; TSV requires an explicit keys override on the macro.)

## :material-wrench-outline: Config Files

To configure the File Lookup module, [:material-cog: Edit](https://doc.log10x.com/config/app/#module-config "Learn how to edit app and module configurations") these files.  

Below is the default configuration from: [lookup/config.yaml](https://github.dev/log-10x/config/blob/main/pipelines/run/initialize/lookup/config.yaml "lookup/config.yaml"){target="\_blank"}.  
  
<div class="edit-options">
    <a class="md-button tenx-edit-online-button" data-tooltip="Edit online on github.dev" href="https://github.dev/log-10x/config/blob/main/pipelines/run/initialize/lookup/config.yaml" target="_blank" rel="noopener noreferrer">
        <span class="twemoji" style="margin-right: 0.3rem;">
            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
                <path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"></path>
            </svg>
        </span> Edit Online
    </a>
    <button class="md-button tenx-config.yaml0-edit-button" data-tooltip="Edit configuration file" data-dialog-id="config-yaml0-dialog">
        <span style="margin-right: 0.3rem;">
            <span class="twemoji">
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
                    <path d="M20.71,7.04C21.1,6.65 21.1,6 20.71,5.63L18.37,3.29C18,2.9 17.35,2.9 16.96,3.29L15.12,5.12L18.87,8.87M3,17.25V21H6.75L17.81,9.93L14.06,6.18L3,17.25Z"></path>
                </svg>
            </span>
        </span>Edit Locally
    </button>
</div>

<dialog id="config-yaml0-dialog" class="md-dialog md-dialog--editor">
    <div class="editor-dialog-wrapper">
        <div class="editor-dialog-header">
            <span class="editor-dialog-title">Edit config.yaml Locally</span>
            <div class="editor-header-actions">
                <button class="editor-toolbar-btn yaml-editor-locations" data-tooltip="Save">
                    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="currentColor" d="M5 20h14v-2H5v2m14-9h-4V3H9v8H5l7 7 7-7Z"></path></svg>
                </button>
                <button class="editor-toolbar-btn yaml-editor-reset" data-tooltip="Reset to default">
                    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="currentColor" d="M12.5 8c-2.65 0-5.05 1-6.9 2.6L2 7v9h9l-3.62-3.62c1.39-1.16 3.16-1.88 5.12-1.88 3.54 0 6.55 2.31 7.6 5.5l2.37-.78C21.08 11.03 17.15 8 12.5 8z"></path></svg>
                </button>
                <button class="editor-toolbar-btn yaml-editor-copy" data-tooltip="Copy to clipboard">
                    <svg class="icon-copy" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="currentColor" d="M19 21H8V7h11m0-2H8a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2m-3-4H4a2 2 0 0 0-2 2v14h2V3h12V1Z"></path></svg>
                    <svg class="icon-check" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" style="display:none;"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg>
                </button>
                <span class="header-divider"></span>
                <button class="editor-toolbar-btn yaml-editor-fullscreen" data-tooltip="Fullscreen">
                    <svg class="icon-maximize" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="currentColor" d="M5,5H10V7H7V10H5V5M14,5H19V10H17V7H14V5M17,14H19V19H14V17H17V14M10,17V19H5V14H7V17H10Z"></path></svg>
                    <svg class="icon-minimize" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" style="display:none;"><path fill="currentColor" d="M5,16H8V19H10V14H5V16M14,14V19H16V16H19V14H14M16,5V8H19V10H14V5H16M10,5V10H5V8H8V5H10Z"></path></svg>
                </button>
                <span class="header-divider"></span>
                <button class="editor-toolbar-btn editor-dialog-close" onclick="closeDialog('config-yaml0-dialog')" data-tooltip="Close">
                    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="currentColor" d="M19,6.41L17.59,5L12,10.59L6.41,5L5,6.41L10.59,12L5,17.59L6.41,19L12,13.41L17.59,19L19,17.59L13.41,12L19,6.41Z"></path></svg>
                </button>
            </div>
        </div>
        <div class="editor-dialog-content">
            <div class="yaml-editor-container"></div>
        </div>
        <div class="yaml-editor-statusbar">
            <span class="yaml-editor-status"></span>
        </div>
    </div>
    <!-- Locations Popup -->
    <div class="locations-popup" style="display: none;">
        <div class="locations-popup-content">
            <div class="locations-popup-header">
                <span class="locations-header-label">Download and save to:</span>
                <button class="locations-popup-close" aria-label="Close">
                    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16">
                        <path fill="currentColor" d="M19,6.41L17.59,5L12,10.59L6.41,5L5,6.41L10.59,12L5,17.59L6.41,19L12,13.41L17.59,19L19,17.59L13.41,12L19,6.41Z"></path>
                    </svg>
                </button>
            </div>
            <ul class="locations-list">
                <li>
                    <span class="location-label">Linux / Docker / macOS
                        <span class="help-icon" data-tooltip="Default system location. The engine automatically reads configs from here at startup. Best for production deployments.">
                            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="12" height="12"><path fill="currentColor" d="M11 18h2v-2h-2v2m1-16A10 10 0 0 0 2 12a10 10 0 0 0 10 10 10 10 0 0 0 10-10A10 10 0 0 0 12 2m0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-14a4 4 0 0 0-4 4h2a2 2 0 0 1 2-2 2 2 0 0 1 2 2c0 2-3 1.75-3 5h2c0-2.25 3-2.5 3-5a4 4 0 0 0-4-4Z"/></svg>
                        </span>
                    </span>
                    <div class="location-path-row">
                        <code class="default-path location-path" data-tooltip=""
                            data-copy-osx="/etc/log10x/config/run/initialize/lookup/config.yaml"
                            data-copy-nix="/etc/log10x/config/run/initialize/lookup/config.yaml"
                            data-copy-win="C:\log10x\configs/run/initialize/lookup/config.yaml"></code>
                        <button class="copy-btn" data-tooltip="Copy path">
                            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14">
                                <path fill="currentColor" d="M19 21H8V7h11m0-2H8a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2m-3-4H4a2 2 0 0 0-2 2v14h2V3h12V1Z"></path>
                            </svg>
                        </button>
                    </div>
                </li>
                <li>
                    <span class="location-label">Custom directory
                        <span class="help-icon" data-tooltip="Set TENX_CONFIG environment variable to point to a custom config directory. Useful when you want configs in a non-standard location.">
                            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="12" height="12"><path fill="currentColor" d="M11 18h2v-2h-2v2m1-16A10 10 0 0 0 2 12a10 10 0 0 0 10 10 10 10 0 0 0 10-10A10 10 0 0 0 12 2m0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-14a4 4 0 0 0-4 4h2a2 2 0 0 1 2-2 2 2 0 0 1 2 2c0 2-3 1.75-3 5h2c0-2.25 3-2.5 3-5a4 4 0 0 0-4-4Z"/></svg>
                        </span>
                    </span>
                    <div class="location-path-row">
                        <code class="location-path" data-tooltip="$TENX_CONFIG/run/initialize/lookup/config.yaml">$TENX_CONFIG/run/initialize/lookup/config.yaml</code>
                        <button class="copy-btn" data-tooltip="Copy path">
                            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14">
                                <path fill="currentColor" d="M19 21H8V7h11m0-2H8a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2m-3-4H4a2 2 0 0 0-2 2v14h2V3h12V1Z"></path>
                            </svg>
                        </button>
                    </div>
                </li>
                <li>
                    <span class="location-label">Within cloned repo
                        <span class="help-icon" data-tooltip="First run: git clone github.com/log-10x/config. Then save the file to this path within the cloned folder. Use for version control.">
                            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="12" height="12"><path fill="currentColor" d="M11 18h2v-2h-2v2m1-16A10 10 0 0 0 2 12a10 10 0 0 0 10 10 10 10 0 0 0 10-10A10 10 0 0 0 12 2m0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8 8 3.59 8 8-3.59 8-8 8m0-14a4 4 0 0 0-4 4h2a2 2 0 0 1 2-2 2 2 0 0 1 2 2c0 2-3 1.75-3 5h2c0-2.25 3-2.5 3-5a4 4 0 0 0-4-4Z"/></svg>
                        </span>
                    </span>
                    <div class="location-path-row">
                        <code class="location-path" data-tooltip="./pipelines/run/initialize/lookup/config.yaml">./pipelines/run/initialize/lookup/config.yaml</code>
                        <button class="copy-btn" data-tooltip="Copy path">
                            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14">
                                <path fill="currentColor" d="M19 21H8V7h11m0-2H8a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h11a2 2 0 0 0 2-2V7a2 2 0 0 0-2-2m-3-4H4a2 2 0 0 0-2 2v14h2V3h12V1Z"></path>
                            </svg>
                        </button>
                    </div>
                </li>
            </ul>
            <div class="locations-popup-footer">
                <button class="locations-download-btn" title="Download config file">
                    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="14" height="14">
                        <path fill="currentColor" d="M5 20h14v-2H5v2m14-9h-4V3H9v8H5l7 7 7-7Z"></path>
                    </svg>
                    <span>Download</span>
                </button>
            </div>
        </div>
    </div>
</dialog>

<template class="tenx-config-schema" data-encoding="base64">ewogICJ0eXBlIiA6ICJvYmplY3QiLAogICJwcm9wZXJ0aWVzIiA6IHsKICAgICJpbmNsdWRlIiA6IHsKICAgICAgInR5cGUiIDogInN0cmluZyIKICAgIH0sCiAgICAidGVueCIgOiB7CiAgICAgICJ0eXBlIiA6ICJzdHJpbmciCiAgICB9LAogICAgImxvb2t1cCIgOiB7CiAgICAgICJ0eXBlIiA6ICJvYmplY3QiLAogICAgICAiYWRkaXRpb25hbFByb3BlcnRpZXMiIDogZmFsc2UsCiAgICAgICJwcm9wZXJ0aWVzIiA6IHsKICAgICAgICAiZmlsZSIgOiB7CiAgICAgICAgICAidHlwZSIgOiBbCiAgICAgICAgICAgICJzdHJpbmciLAogICAgICAgICAgICAibnVsbCIKICAgICAgICAgIF0sCiAgICAgICAgICAibWFya2Rvd25EZXNjcmlwdGlvbiIgOiAiVFNWL0NTViBmaWxlIHRvIGxvYWRcblxuVGhlIHRhcmdldCAudHN2Ly5jc3YgbG9va3VwIGZpbGUgdG8gbG9hZCIKICAgICAgICB9LAogICAgICAgICJrZXlGaWVsZCIgOiB7CiAgICAgICAgICAidHlwZSIgOiBbCiAgICAgICAgICAgICJzdHJpbmciLAogICAgICAgICAgICAibnVsbCIKICAgICAgICAgIF0sCiAgICAgICAgICAibWFya2Rvd25EZXNjcmlwdGlvbiIgOiAiVGVuWE9iamVjdCBmaWVsZCBuYW1lIHRvIHVzZSBhcyBsb29rdXAga2V5XG5cblNwZWNpZmllcyBhIGZpZWxkIG5hbWUgd2hvc2UgdmFsdWUgdG8gZXh0cmFjdCBmcm9tIGEgdGFyZ2V0IFRlblhPYmplY3QgdG8gdXNlIGFzIHRoZSBsb29rdXAga2V5LCB0aGF0IGlzIHRoZSB2YWx1ZSB1c2VkIHRvIHNlYXJjaCBmb3IgYSBtYXRjaGluZyB2YWx1ZSB3aXRoaW4gdGhlIGxvb2t1cCBmaWxlLiIKICAgICAgICB9LAogICAgICAgICJ2YWx1ZUZpZWxkIiA6IHsKICAgICAgICAgICJ0eXBlIiA6IFsKICAgICAgICAgICAgInN0cmluZyIsCiAgICAgICAgICAgICJudWxsIgogICAgICAgICAgXSwKICAgICAgICAgICJtYXJrZG93bkRlc2NyaXB0aW9uIiA6ICJUZW5YT2JqZWN0IGZpZWxkIG5hbWUgdG8gdXNlIGFzIHRoZSBsb29rdXAgdmFsdWVcblxuU3BlY2lmaWVzIHRoZSBmaWVsZCBuYW1lIHdpdGggdGhlIHRhcmdldCBUZW5YT2JqZWN0IHRvIHNldCB3aXRoIHRoZSByZXN1bHQgbG9va3VwIHZhbHVlIGFjcXVpcmVkIGJ5IHNlYXJjaGluZyB0aGUgdGFibGUgZm9yIHRoZSB2YWx1ZSBvZiBbbG9va3VwS2V5RmllbGRdKGh0dHBzOi8vZG9jLmxvZzEweC5jb20vcnVuL2luaXRpYWxpemUvbG9va3VwLyNsb29rdXBrZXlmaWVsZCkuIgogICAgICAgIH0sCiAgICAgICAgInZhbHVlQ29sdW1uIiA6IHsKICAgICAgICAgICJ0eXBlIiA6IFsKICAgICAgICAgICAgInN0cmluZyIsCiAgICAgICAgICAgICJudWxsIgogICAgICAgICAgXSwKICAgICAgICAgICJtYXJrZG93bkRlc2NyaXB0aW9uIiA6ICJOYW1lIG9mIGxvb2t1cCB2YWx1ZSBjb2x1bW5cblxuU3BlY2lmaWVzIGEgY29sdW1uIGluIHRoZSBbbG9va3VwRmlsZV0oaHR0cHM6Ly9kb2MubG9nMTB4LmNvbS9ydW4vaW5pdGlhbGl6ZS9sb29rdXAvI2xvb2t1cGZpbGUpIHdob3NlIHZhbHVlIHRvIGFzc2lnbiBmcm9tIHRoZSBmaXJzdCBjb2x1bW4gaW4gdGhlIHRhYmxlIChpLmUuLCB0aGUga2V5IGNvbHVtbikgaW50byBbbG9va3VwVmFsdWVGaWVsZF0oaHR0cHM6Ly9kb2MubG9nMTB4LmNvbS9ydW4vaW5pdGlhbGl6ZS9sb29rdXAvI2xvb2t1cHZhbHVlZmllbGQpIGJhc2VkIG9uIHRoZSB2YWx1ZSBvZiAgdGhlIFtsb29rdXBLZXlGaWVsZF0oaHR0cHM6Ly9kb2MubG9nMTB4LmNvbS9ydW4vaW5pdGlhbGl6ZS9sb29rdXAvI2xvb2t1cGtleWZpZWxkKSBmaWVsZCB2YWx1ZS4gKERlZmF1bHQ6IHNlY29uZCBjb2x1bW4gaW4gdGFibGUgKGZpcnN0IGNvbHVtbiBpcyBhc3N1bWVkIGFzIHRoZSBrZXkpKSIsCiAgICAgICAgICAiZGVmYXVsdCIgOiAic2Vjb25kIGNvbHVtbiBpbiB0YWJsZSAoZmlyc3QgY29sdW1uIGlzIGFzc3VtZWQgYXMgdGhlIGtleSkiCiAgICAgICAgfQogICAgICB9LAogICAgICAicmVxdWlyZWQiIDogWwogICAgICAgICJmaWxlIiwKICAgICAgICAia2V5RmllbGQiLAogICAgICAgICJ2YWx1ZUZpZWxkIgogICAgICBdCiAgICB9CiAgfSwKICAiYWRkaXRpb25hbFByb3BlcnRpZXMiIDogdHJ1ZQp9</template>

```yaml
# 🔟❎ 'run' lookup file configuration

# Configuration text lookup to enrich TenXObjects
# To learn more see https://doc.log10x.com/run/initialize/lookup/

# Set the 10x pipeline to 'run'
tenx: run

# =============================== Dependencies ================================

include: run/modules/initialize/lookup

# ============================== Lookup Options ===============================

lookup:

  # 'file' specifies the .csv/.tsv lookup table file
  file: $=path("pipelines/run/initialize/lookup/http.csv")

  # 'keyField' specifies the field whose value is query lookup key.
  #  The calculated code field below captures the penultimate HTTP code value from a web log event.
  #  For example, 200 for: Mar 10 12:34:56 webserver nginx: 192.168.1.10 - - [10/Mar/2025:12:34:56 +0000] "GET /index.html HTTP/1.1" 200 1024
  keyField: $=yield TenXEnv.get("httpCodeField")

  # 'valueField' specifies the name of the result field to assign to the lookup table value
  valueField: http_message
```

## :material-menu: Options

Specify the options below to [configure](/config "configure") the File Lookup:

|Name|Description|
|---|---|
|[lookupFile](#lookupfile "TSV/CSV file to load")|TSV/CSV file to load|
|[lookupKeyField](#lookupkeyfield "TenXObject field name to use as lookup key")|TenXObject field name to use as lookup key|
|[lookupValueField](#lookupvaluefield "TenXObject field name to use as the lookup value")|TenXObject field name to use as the lookup value|
|[lookupValueColumn](#lookupvaluecolumn "name of lookup value column")|Name of lookup value column|

### :material-menu-right-outline:**`lookupFile`**

TSV/CSV file to load.

|Type|Required|
|---|---|
|File|✔|

The target .tsv/.csv lookup file to load.


### :material-menu-right-outline:**`lookupKeyField`**

TenXObject field name to use as lookup key.

|Type|Required|
|---|---|
|String|✔|

Specifies a field name whose value to extract from a target TenXObject to use as the lookup key, that is the
value used to search for a matching value within the lookup file.


### :material-menu-right-outline:**`lookupValueField`**

TenXObject field name to use as the lookup value.

|Type|Required|
|---|---|
|String|✔|

Specifies the field name with the target TenXObject to set with the result lookup value acquired by searching
the table for the value of [lookupKeyField](https://doc.log10x.com/run/initialize/lookup/#lookupkeyfield "TenXObject field name to use as lookup key").


### :material-menu-right-outline:**`lookupValueColumn`**

Name of lookup value column.

|Type|Default|
|---|---|
|String|second column in table (first column is assumed as the key)|

Specifies a column in the [lookupFile](https://doc.log10x.com/run/initialize/lookup/#lookupfile "TSV/CSV file to load") whose value to
assign from the first column in the table (i.e., the key column) into [lookupValueField](https://doc.log10x.com/run/initialize/lookup/#lookupvaluefield "TenXObject field name to use as the lookup value") based on the value of
the [lookupKeyField](https://doc.log10x.com/run/initialize/lookup/#lookupkeyfield "TenXObject field name to use as lookup key") field value.


<br/>:material-github: This module is defined in [lookup/module.yaml](https://github.com/log-10x/modules/tree/main/pipelines/run/modules/initialize/lookup/module.yaml "lookup/module.yaml"){target="\_blank"}.