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

# Smart Lookup

> Enrich extracted data by matching it against a reference file you upload.

**Smart Lookup** enriches extracted data by matching it against a reference file. Use it when a value your workflow extracts — a product name, a supplier name, a city — needs to be translated into an identifier defined outside the document, like a SKU, a supplier code, or a location ID.

***

## What it does

[Extraction](/concepts/fields) pulls raw values out of a document. Smart Lookup takes those values and checks them against one or more CSV files you upload, then returns a value from the matching row.

**Example:** an invoice contains the product name "Blue Widget 500ml." Your master file maps product names to SKUs. Smart Lookup matches "Blue Widget 500ml" to its row in the master file and returns the SKU, `SKU-10234`.

Matching is handled by the model — there's no manual step where you pick "the match column" and "the output column." The matcher works from the field's name and description (plus an optional [hint](#lookup-suggestion) you can add), so it can also join on more than one signal at once — for example matching on name **and** city together when name alone isn't unique.

The extracted field and the lookup result stay separate. Smart Lookup does not rewrite or merge into the extraction schema — it marks a field as resolved from the reference file instead of from the document. This keeps it clear what came from the document and what came from your reference data.

***

## When to use it

Use Smart Lookup when extracted values need to map to internal identifiers before they're usable downstream — in an ERP, a CRM, or an inventory system. Typical cases:

* Product name → SKU
* Supplier name → Supplier code
* City → Location ID

<Note>
  If you just need to validate a value against a fixed list of options, use a [select field](/concepts/field-types) with static options instead. Smart Lookup is for when that list lives in an external file and needs to return a different value than the one being matched.
</Note>

***

## Requirements

Smart Lookup is configured on a field, inside an Extract node — not as a separate step in your workflow. Before you can enable it, you need:

* An Extract node
* A field created within that node
* At least one CSV reference file uploaded to that node

***

## Enabling Smart Lookup

Reference files and matching settings are shared across every lookup field in an Extract node; whether a given field actually uses them is set per field.

<Steps>
  <Step title="Upload your reference file(s)">
    Open the Extract node's **Config** tab and add one or more CSV files under **Lookup files**. Every lookup field in this node can draw on them.
  </Step>

  <Step title="Turn Lookup on for a field">
    Open the field you want to enrich (in the node's **Schema** tab) and toggle **Lookup** on.
  </Step>

  <Step title="Choose the lookup mode">
    Pick **Always look up** or **Only if not extracted** — see [Lookup mode](#lookup-mode) below.
  </Step>
</Steps>

***

## Lookup mode

Turning Lookup on for a field swaps where its value comes from:

* **Off** (default) — the field returns only what extraction finds in the document.
* **Always look up** — the field is resolved entirely from the reference file; extraction never attempts to read it from the document at all.
* **Only if not extracted** — extraction runs first; lookup only fills in the field if extraction left it blank. If extraction already found a value, that value is kept even if the lookup finds no match.

***

## Lookup suggestion

An optional free-text hint shown to the matcher, for describing matching rules that aren't obvious from the data alone — for example, "Match supplier names ignoring legal suffixes like GmbH or Ltd."

This is useful when your document values and reference file values are consistent in meaning but differ in formatting in a predictable way. It applies to every lookup field in the node.

***

## Lookup matching effort

Controls how hard the matcher works to reconcile noisy or inexact keys against your reference file — typos, formatting differences, or partial names. Higher effort improves match reliability at the cost of higher latency and cost.

* Default (model) — leave the setting unset; this isn't a value you set explicitly
* Minimal
* Low
* Medium
* High

Start with the **default** and only increase effort if you're seeing missed matches on messy source data.

***

## How results are returned

Lookup fields are visually distinguished from extraction fields so it's clear which values came from the document and which came from your reference file.

* If a match is found, the matched row's value is returned (subject to the [lookup mode](#lookup-mode) above).
* If no match is found: an **Always look up** field returns empty — there's nothing else for it to fall back on. An **Only if not extracted** field keeps whatever extraction already found; it's only left empty if extraction found nothing either. Either way, Smart Lookup never does a partial or guessed match.

***

## Current scope

Smart Lookup currently supports:

* CSV reference files (multiple files per Extract node)
* Any number of lookup fields per node, each resolved independently
* Matching on more than one field at once when that's what disambiguates a row
* Field-level configuration for lookup mode, plus node-level matching effort and an optional matching hint

Not currently supported:

* XLS/XLSX and other binary spreadsheet formats — convert to CSV first
* Multi-step joins or transformations across more than one reference file
* Editing or correcting lookup results after a run — if the reference file was wrong or incomplete, update it and re-run

***

## FAQ

<AccordionGroup>
  <Accordion title="What happens if my extracted value doesn't exactly match anything in the reference file?">
    An **Always look up** field returns empty. An **Only if not extracted** field keeps its extracted value if it had one — only fields extraction also left blank turn up empty. Either way, nothing is guessed or partially filled in.
  </Accordion>

  <Accordion title="Can I update my reference file after I've built the workflow?">
    Yes — replace the uploaded CSV in the Extract node's Lookup files. Future runs use the updated file.
  </Accordion>

  <Accordion title="Can I use the same reference file across multiple fields?">
    Yes. Lookup files are uploaded once per Extract node, and every lookup field in that node can draw on all of them.
  </Accordion>

  <Accordion title={"What's the difference between \"Always look up\" and \"Only if not extracted\"?"}>
    "Always look up" treats the reference file as the source of truth and overwrites whatever extraction found. "Only if not extracted" treats extraction as primary and only uses the lookup to fill gaps extraction missed.
  </Accordion>

  <Accordion title="Does Smart Lookup change my extraction output?">
    No. The original extracted field is unchanged. Smart Lookup marks a field as resolved from the lookup file instead of the document — it doesn't merge into another field.
  </Accordion>
</AccordionGroup>

***

## What's next?

<CardGroup cols={2}>
  <Card title="Fields" icon="table-list" href="/concepts/fields">
    How fields and their properties work
  </Card>

  <Card title="The building blocks" icon="diagram-project" href="/guides/studio/nodes">
    Where Extract fits among Studio's five steps
  </Card>
</CardGroup>