Simple explanation
This lesson covers the configuration step that actually makes an uploaded lookup file usable — turning a static file into something your searches can reference.
Technical explanation
- Creating a definition: Settings > Lookups > Lookup definitions, selecting the uploaded file and specifying it as a "File-based" lookup type (as opposed to other types like KV Store or external/scripted lookups, which are more advanced).
- Match field configuration — specifying which field in your search results should be matched against which column in the lookup file; field names don't have to match exactly between the search and the file, since the definition explicitly maps them.
- Using the lookup manually in a search:
| lookup my_lookup_definition error_code OUTPUT error_description— explicitly invoking the lookup, specifying the match field and which output field(s) to pull in. - Case-sensitivity and exact matching — by default, lookup matching requires an exact match on the specified field's value; this matters when reference data and event data might differ subtly in formatting (extra whitespace, case differences) that would otherwise cause silent match failures.
- Testing a lookup — after creating a definition, running a search using it and confirming the expected additional fields actually appear is an important verification step, since a misconfigured match field will silently fail to enrich rather than throwing an obvious error.
Synonyms / related terms
| Term | Means | |---|---| | File-based lookup | The most common lookup type, referencing an uploaded CSV | | OUTPUT clause | Specifies which fields from the lookup file to pull into search results |
Concept Check
"A lookup is configured, but after running a search, none of the expected additional fields appear, with no error message shown." This is a classic symptom of a match field mismatch — perhaps a case difference or extra whitespace between the search's field value and the lookup file's corresponding value — rather than a lookup system failure; lookups typically fail silently on non-matching values rather than raising a visible error.
Interview-style Q&A
Q: Why might a lookup silently fail to enrich results instead of showing an obvious error? A: "By design — a lookup not matching for a specific event might simply mean that event legitimately has no corresponding reference data, which isn't necessarily an error condition at all. Treating every non-match as an error would create constant, often irrelevant noise. The trade-off is that genuine configuration mistakes (a mismatched field name or format) can look identical to 'this event just doesn't have a match,' which is exactly why testing a new lookup carefully matters."
Memory trick
"Match the Field, Output the Extra" — the two configuration decisions that define any lookup definition: what to match on, and what additional data to pull in.