Lookups

A lookup is a keyed reference dataset that enriches events through the Hamelin LOOKUP operator.

A lookup wraps a backing dataset and a primary key (keyColumns). LOOKUP left-joins a dataset onto the current one on the condition its ON clause states, so a query might read | LOOKUP lookups.malicious_ips ON source.ip == malicious_ips.ip. The ON clause is required and takes a boolean expression, so the match is whatever the query names rather than the lookup's key. Any dataset may sit on the right of either LOOKUP or JOIN. Reach for a lookup over a plain view or table when the goal is a keyed enrichment set such as an allow or deny list, an asset inventory, or CIDR reputation. A lookup is content, prefixed LKP_.

Variants

A lookup comes in two variants, fixed at creation and derived from the query text.

• A computed lookup reads FROM existing datasets and is backed by a materialized view.
• A static lookup reads FROM source and is backed by a static table whose rows come from file uploads (in the web app, on the lookup's "Uploads" tab).

Inputs

Field	Type	Required	Description
name	string	Required	Freeform display name. Perpetual derives the backing dataset's schema.name from it.
query	string	Required	The Hamelin query defining the lookup. Computed reads FROM existing datasets. Static reads FROM source. Send an empty string for a static lookup with sourceFormat csv.
keyColumns	array<string>	Optional	Columns forming the backing dataset's primary key, used to deduplicate and sort its rows. Not the LOOKUP match condition, which the query supplies through ON. May be empty on a draft, but at least one is required before a changeset commits.
sourceFormat	enum	Optional	Upload format for a static lookup: parsed_lines or csv. csv takes the schema from the header row and leaves query empty. Ignored for computed. Defaults to parsed_lines.
deploy	boolean	Required	Whether the lookup materializes its backing dataset. true creates the backing view or table. false leaves it as saved content.
archived	boolean	Optional	Whether the lookup is archived. Archived lookups do not materialize.
folderPath	string	Optional	Path of the folder holding the lookup.

Outputs

Field	Type	Description
folderId	string	ID of the folder holding the lookup. Null for none.
deploymentStatus	enum	Materialization state of the backing dataset: UNDEPLOYED, DEPLOY_PENDING, DEPLOY_IN_PROGRESS, DEPLOYED, UPDATE_PENDING, UPDATE_IN_PROGRESS, REFRESH_IN_PROGRESS, FAILED, ARCHIVED, CLEANUP_PENDING, CLEANUP_IN_PROGRESS.
table	object	The backing dataset, or null before deploy. Carries the backing id, resourceKind (Table for static, View for computed), name, deploymentStatus, sourceFormat, and keyColumns.

Plus the common resource fields.

Related

• Views and Tables, the datasets that back a computed and a static lookup.
• Deployable content, where a lookup sits among Perpetual's resources.
• Enrichment, how LOOKUP joins reference data onto events.
• Changesets, how lookup edits are staged and committed.