> ## 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.

# Reference Lookup

> Look up matching rows from a reference entity and format as text

Looks up matching rows from a reference entity and formats the results as a text field. Useful for enriching records with context from another dataset - for example, attaching related notes, activities, or linked records as formatted text.

## Configuration

| Setting                 | Description                                                          |
| ----------------------- | -------------------------------------------------------------------- |
| **Key Field**           | Field in the reference entity to match against                       |
| **Source Field**        | Lookup key from your workflow data                                   |
| **Display Fields**      | Fields from the reference entity to include in the output            |
| **Limit**               | Maximum matching rows to return per record (default: 5)              |
| **Result Field Name**   | Name for the output field (default: `reference_result`)              |
| **Format Template**     | Template for formatting each matching row (e.g., `{Name}: {Amount}`) |
| **Case Sensitive**      | Key matching case sensitivity (default: off)                         |
| **Virtual Object Name** | Namespace prefix (default: `reference_lookup`)                       |

### Exclusion Options

| Setting                  | Description                                       |
| ------------------------ | ------------------------------------------------- |
| **Exclude Field**        | Field in reference entity for exclusion filtering |
| **Exclude Source Field** | Source field providing the exclusion value        |

## How It Works

<Steps>
  <Step title="Select the reference entity">
    Choose which entity to look up matching rows from.
  </Step>

  <Step title="Define the match">
    Map the key field (in the reference entity) to the source field (in your workflow data).
  </Step>

  <Step title="Choose display fields">
    Select which fields from matching rows should appear in the output.
  </Step>

  <Step title="Format the output (optional)">
    Write a template using `{FieldName}` placeholders to control how matching rows are formatted.
  </Step>
</Steps>

## Output

A text field containing formatted matching rows from the reference entity. This is especially useful as input for AI Enrichment prompts or reports.

## Example

Enrich accounts with their recent support tickets:

* **Key Field:** Zendesk.Ticket.AccountId
* **Source Field:** Salesforce.Account.Id
* **Display Fields:** Subject, Status, Created Date
* **Format Template:** `{Subject} ({Status}) - {Created Date}`
* **Limit:** 3

Result: each account gets a text field like:

```
Login issue (Open) - 2024-01-15
Billing question (Closed) - 2024-01-10
Feature request (Pending) - 2024-01-08
```

## Best Practices

* Set a reasonable **Limit** - too many matching rows creates very long text fields
* Use **Format Template** for clean, readable output
* Use the **Exclusion** options to skip irrelevant matches (e.g., exclude the record itself)
* Reference Lookup output works well as input to [AI Enrichment](/guide/nodes/enrichment/ai-enrichment-node) prompts

## Related Nodes

* **[Dictionary Lookup](/guide/nodes/enrichment/dictionary-lookup-node)** - maps values using key-value pairs rather than returning formatted text
* **[AI Enrichment](/guide/nodes/enrichment/ai-enrichment-node)** - feed Reference Lookup output into an LLM prompt for analysis
* **[Bond Node](/guide/nodes/combine/bond-node)** - creates relationships between entities (structured join vs. text lookup)