Lookup operators

FuseQL provides lookup operators that let you enrich your query results with data from external lookup tables. Create and manage lookup tables in the Kloudfuse UI before using these operators in queries.

For information on creating and managing lookup tables programmatically, see Logs API Reference.

cat

Reads all rows from a lookup table and injects them into the query pipeline as a result set. Unlike lookup (which joins a table against live log results), cat is a source operator — use it to query or filter the contents of a lookup table directly, or to join a static dataset against live logs in a subsequent pipe stage.

Syntax

cat <lookup_table_name>
none

Parameters

Parameter Required Description

<lookup_table_name>

Required

Name of an existing lookup table in the Kloudfuse UI. All rows and columns are returned.

Example

Read the userinfo lookup table and filter to rows where the username equals "alice".

cat userinfo
| where username = "alice"
Expected output (illustrative)
user_id username last_seen

u-10482

alice

2026-06-27T18:54:00Z

cat is a source operator and must appear at the start of a query (not after a |). Pipe additional operators after cat to filter, transform, or aggregate the table contents. The lookup table must exist and be populated before the query runs — use save to populate it from log results.

lookupContains

Returns true if a log field’s value exists in a lookup table’s key column, and false otherwise. Use lookupContains inside a where clause to filter log events based on membership in a pre-defined set — for example, restricting results to VIP users, known bad IPs, or a list of monitored service names.

Syntax

| where lookupContains(<table_name>, <log_field> = <table_field>)
none

Parameters

Parameter Required Description

<table_name>

Required

Name of an existing lookup table in the Kloudfuse UI.

<log_field>

Required

The log field whose value is checked against the lookup table. Can be a facet, label, or field extracted with parse.

<table_field>

Required

The lookup table column to match against.

Example

Filter nginx access logs to only include requests from VIP users, identified by matching user_id against the id column in the vip_users lookup table.

source="nginx"
| parse "* - - [*] \"* *\" * * *" as ip,date,method,url,status,bytes,rest
| where lookupContains(vip_users, user_id = id)
| count as vip_requests by method
Expected output (illustrative)
method vip_requests

GET

12,430

POST

3,211

The lookup table must exist and be populated before the query runs. lookupContains evaluates each log row independently — it does not perform a full join, so it is more efficient than lookup when you only need membership testing rather than field enrichment. To retrieve fields from the table, use lookup instead.

lookup

Retrieves fields from a pre-defined lookup table and adds them to log query results by matching on one or more key fields. Use lookup to enrich log data with external context — for example, adding a user’s country and city from a UserLocations table, or expanding an error code into a human-readable description.

Syntax

| lookup <table_field> as <alias>[, <table_field2> as <alias2>, ...]
    from "<table_name>"
    on <log_field> = <table_key>[, <log_field2> = <table_key2>, ...]
none

Parameters

Parameter Required Description

<table_field> as <alias>

Required

One or more fields to retrieve from the lookup table, each with an alias for the output column.

from "<table_name>"

Required

Name of the lookup table (created and populated in the Kloudfuse UI).

on <log_field> = <table_key>

Required

Join condition matching a log field to the lookup table’s primary key. Multiple conditions are comma-separated.

Example

Enrich nginx access logs with user country and city by joining on userId against the UserLocations lookup table.

source="nginx"
| parse "* - - [*] \"* *\" * * *" as ip,date,method,url,status,bytes,rest
| lookup country as userCountry, city as userCity
    from "UserLocations"
    on userId = userID
| count as requests by userCountry
Expected output (illustrative)
userCountry requests

United States

842,301

Germany

97,443

Japan

54,812

Create and populate lookup tables in the Kloudfuse UI before referencing them in queries. Lookup tables have a maximum size of 50 MB. Join conditions must use compatible data types and the table’s primary key(s). Rows with no matching key in the lookup table are dropped (inner-join semantics; left-join semantics are not supported).

save

Inserts or updates rows in a lookup table using the current query’s result set. If a result row’s primary key matches an existing row, that row is updated; if no match exists, a new row is added. This operation combines merge and append semantics. Use save to keep a lookup table current with live log data — for example, tracking the latest login timestamp per user.

Syntax

| save <lookup_table_name>
none

Parameters

Parameter Required Description

<lookup_table_name>

Required

Name of an existing lookup table in the Kloudfuse UI. The query result’s column names must match the table schema.

Example

Extract user details from login application logs and save them to the userinfo lookup table. Existing rows for the same user are updated; new users are inserted.

source="login_application"
| json "user_id", "username", "email", "last_seen"
| save userinfo
Expected output (illustrative — rows written to the userinfo table)
user_id username last_seen

u-10482

alice

2026-06-27T18:54:00Z

u-20917

bob

2026-06-27T18:55:00Z

The lookup table must already exist in the Kloudfuse UI with a schema that matches the query’s output columns. The save operator is a terminal stage — it writes results and does not pass rows downstream. After saving, use cat to read the table contents back into a query or lookup to join it against another log source.