# `enrich`

## Description

The `enrich` command adds contextual information to logs by performing lookups against a custom enrichment table. It merges additional columns from the lookup into each log document based on a matching key.

This is particularly useful for attaching static metadata (like user details, service mappings, or IP ownership) to incoming logs without modifying upstream systems. The enrichment is applied **at query time**, meaning you always work with the most recent version of the enrichment table.

Each lookup table must be created and uploaded beforehand as a **Custom Enrichment**. For setup and management instructions, see [Custom Enrichment](https://coralogix.com/docs/user-guides/enrichment_rules/custom_enrichment/index.md).

Note

- All values in a lookup table are stored as strings. Use conversion functions such as `toNumber()` or `toTimestamp()` if a different type is required.
- If a log already contains the enriched key, `enrich` will merge or update only the matching sub-keys; unrelated fields remain unchanged.

## Syntax

```dataprime
enrich <value_to_lookup> into <enriched_key> using <lookup_table>
```

## Example

**Use case: Attach employee information to a user ID**

Suppose your logs contain user IDs, and you maintain an external lookup table with user details such as name and department. You can use `enrich` to join this contextual data dynamically into your logs, enabling richer queries and more meaningful analysis.

**Lookup table (`my_users`):**

| ID  | Name  | Department |
| --- | ----- | ---------- |
| 111 | John  | Finance    |
| 222 | Emily | IT         |

### Example data

```json
{ "userid": "111" },
{ "userid": "222" }
```

### Example query

```dataprime
enrich userid into user_enriched using my_users
```

### Example output

```json
{
    "userid": "111",
    "user_enriched": {
    "ID": "111",
    "Name": "John",
    "Department": "Finance"
    }
},
{
    "userid": "222",
    "user_enriched": {
    "ID": "222",
    "Name": "Emily",
    "Department": "IT"
    }
}
```

The `enrich` command performs a lookup in `my_users` based on the `userid` value and attaches the corresponding data as a nested object under `user_enriched`. This approach ensures logs always reflect the latest lookup information without altering the source data.