> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bondata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Dictionary Lookup

> Map field values using inline or entity-based lookup dictionaries

Maps values from a source field to new values using a lookup dictionary - similar to VLOOKUP in spreadsheets. Supports inline key-value pairs, entity-based dictionaries, and fuzzy matching.

## Configuration

| Setting                 | Description                                                                                   |
| ----------------------- | --------------------------------------------------------------------------------------------- |
| **Source Field**        | The field to use as the lookup key                                                            |
| **Dictionary Source**   | **Inline** (key-value pairs defined in the node) or **Entity** (from a connected integration) |
| **Result Field Name**   | Name for the output field (default: `lookup_result`)                                          |
| **Default Value**       | Value to use when no match is found                                                           |
| **Match Mode**          | How to match keys (see below)                                                                 |
| **Case Sensitive**      | Whether matching is case-sensitive (default: off)                                             |
| **Virtual Object Name** | Namespace prefix for output fields (default: `dictionary_lookup`)                             |

### Inline Dictionary

| Setting     | Description             |
| ----------- | ----------------------- |
| **Entries** | List of key-value pairs |

### Entity Dictionary

| Setting                       | Description                                    |
| ----------------------------- | ---------------------------------------------- |
| **Dictionary Key Field**      | Field in the reference entity to match against |
| **Dictionary Value Field(s)** | Field(s) to return from matching rows          |
| **Dictionary Filter Field**   | Optional field for filtering/grouping lookups  |

### Match Modes

| Mode            | Description                                                 |
| --------------- | ----------------------------------------------------------- |
| **Exact**       | Key must match exactly (default)                            |
| **Fuzzy**       | Uses similarity scoring with configurable threshold (0-100) |
| **Fuzzy Top N** | Returns top N fuzzy candidates                              |
| **Regex**       | Dictionary keys are regex patterns - first match wins       |
| **Substring**   | Longest matching substring wins                             |
| **Collect All** | Joins all matching values from a filtered group             |

### Fuzzy Matching Options

| Setting               | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| **Fuzzy Threshold**   | Minimum similarity score (0-100, default: 70)                  |
| **Fuzzy Scorer**      | Scoring algorithm: **WRatio** (default) or **Token Set Ratio** |
| **Noise Words**       | Words to strip before matching                                 |
| **Normalize Umlauts** | Normalize German umlauts (ä→ae, etc.)                          |
| **Substring Boost**   | Boost substring matches to score 95                            |

## How It Works

<Steps>
  <Step title="Select the source field">
    Choose which field contains the values to look up.
  </Step>

  <Step title="Define the dictionary">
    Use inline key-value pairs for simple mappings, or reference an entity for larger dictionaries.
  </Step>

  <Step title="Choose a match mode">
    Use **Exact** for clean data, **Fuzzy** for messy data, or **Regex** for pattern-based mapping.
  </Step>
</Steps>

## Output

A new field containing the matched dictionary value. For entity mode with multiple value fields, multiple columns are returned (like a multi-column VLOOKUP).

## Examples

### Inline: Map country codes to names

* Source Field: Country Code
* Dictionary Source: Inline
* Entries: `US → United States`, `GB → United Kingdom`, `DE → Germany`
* Default: "Unknown"

### Entity: Fuzzy company name matching

* Source Field: Company Name
* Dictionary Source: Entity (reference list of canonical company names)
* Match Mode: Fuzzy
* Threshold: 80
* Noise Words: "Inc, LLC, Ltd, Corp"

## Best Practices

* Use **Inline** for small, static dictionaries (\< 50 entries)
* Use **Entity** for large or frequently updated dictionaries
* Start with a higher fuzzy threshold (80+) and lower gradually if needed
* Use **Noise Words** to strip common suffixes before fuzzy matching (e.g., company suffixes)
* Use **Collect All** mode when you need to aggregate all matching values

## Related Nodes

* **[Reference Lookup](/guide/nodes/enrichment/reference-lookup-node)** - looks up matching rows and formats as text
* **[Transform](/guide/nodes/transform/transform-node)** - use CASE expressions for simple value mapping without a dictionary
* **[Find Duplicates](/guide/nodes/enrichment/find-duplicates-node)** - fuzzy matching across records rather than against a dictionary