Skip to content
Fyrn Docs

Lookup Tables

Lookup tables are named key-value stores used in flow transforms to translate values — country codes to warehouse IDs, status codes to labels, SKUs to product names, etc.

What lookup tables are

Section titled “What lookup tables are”

A lookup table maps string keys to string values. In a flow mapping, the lookup() transform translates a source value by finding it in the table:

mapping:
  warehouse: 'source.country | lookup("country-warehouses", "default-wh")'
  # "US" → "warehouse-east-01"
  # "FI" → "warehouse-eu-01"
  # "JP" → "default-wh" (fallback)

Creating lookup tables

Section titled “Creating lookup tables”

Via CLI

Section titled “Via CLI”
Terminal window
# Create a table
fyrn lookup create country-warehouses --description "Maps ISO country codes to warehouse IDs"


# Add entries one at a time
fyrn lookup set <table-id> US warehouse-east-01
fyrn lookup set <table-id> FI warehouse-eu-01
fyrn lookup set <table-id> DE warehouse-eu-02
fyrn lookup set <table-id> GB warehouse-eu-03

Via API

Section titled “Via API”

Create a lookup table with POST /api/v1/lookup-tables:

Terminal window
curl -X POST https://api.fyrn.ai/api/v1/lookup-tables \
  -H "Authorization: Bearer $FYRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "country-warehouses",
    "description": "Maps ISO country codes to warehouse IDs"
  }'

Response:

{
  "id": "lt_abc123",
  "name": "country-warehouses",
  "description": "Maps ISO country codes to warehouse IDs",
  "version": 1,
  "created_at": "2026-03-05T10:00:00Z"
}

Add entries with PUT /api/v1/lookup-tables/:id/entries. This endpoint upserts — existing keys are updated, new keys are added:

Terminal window
curl -X PUT https://api.fyrn.ai/api/v1/lookup-tables/lt_abc123/entries \
  -H "Authorization: Bearer $FYRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entries": [
      { "key": "US", "value": "warehouse-east-01" },
      { "key": "FI", "value": "warehouse-eu-01" },
      { "key": "DE", "value": "warehouse-eu-02" },
      { "key": "GB", "value": "warehouse-eu-03" }
    ]
  }'

Response:

{
  "id": "lt_abc123",
  "entries_count": 4,
  "version": 2
}

Via MCP

Section titled “Via MCP”
{
  "name": "create_lookup",
  "arguments": {
    "name": "country-warehouses",
    "description": "Maps ISO country codes to warehouse IDs"
  }
}

Then add entries:

{
  "name": "set_lookup_entry",
  "arguments": {
    "table_id": "...",
    "key": "US",
    "value": "warehouse-east-01"
  }
}

Using in transforms

Section titled “Using in transforms”

The lookup(table_name) and lookup(table_name, default) transforms reference lookup tables by name:

mapping:
  # Without fallback — returns undefined if key not found
  warehouse: 'source.country | lookup("country-warehouses")'


  # With fallback — returns "default-wh" if key not found
  warehouse: 'source.country | lookup("country-warehouses", "default-wh")'


  # Chained with other transforms
  warehouse: 'source.country | uppercase | lookup("country-warehouses", "default-wh")'

If the piped value is null or undefined, lookup returns the default or undefined.

Bulk import and update

Section titled “Bulk import and update”

CSV import via CLI

Section titled “CSV import via CLI”

Create a CSV file with key and value columns:

countries.csv
key,value
US,warehouse-east-01
CA,warehouse-north-01
FI,warehouse-eu-01
DE,warehouse-eu-02
GB,warehouse-eu-03
Terminal window
fyrn lookup import <table-id> countries.csv

CSV import via MCP

Section titled “CSV import via MCP”
{
  "name": "import_lookup_csv",
  "arguments": {
    "table_id": "...",
    "csv": "key,value\nUS,warehouse-east-01\nCA,warehouse-north-01\nFI,warehouse-eu-01"
  }
}

Export for backup

Section titled “Export for backup”
Terminal window
fyrn lookup export <table-id> > backup.csv

Managing entries

Section titled “Managing entries”
Terminal window
# View a table and its entries
fyrn lookup show <table-id>


# Search entries
fyrn lookup show <table-id> --search "warehouse-eu"


# Update an entry (same as set — upserts)
fyrn lookup set <table-id> US warehouse-west-01


# Remove an entry
fyrn lookup remove <table-id> US


# Delete the entire table (soft delete)
fyrn lookup delete <table-id>

Common patterns

Section titled “Common patterns”

Country code → warehouse routing

Section titled “Country code → warehouse routing”
mapping:
  warehouse: 'source.shipping_address.country_code | lookup("country-warehouses", "warehouse-default")'

SKU mapping between systems

Section titled “SKU mapping between systems”
mapping:
  erp_sku: 'source.shopify_sku | lookup("sku-mappings") | required'

Status code translation

Section titled “Status code translation”
mapping:
  display_status: 'source.status_code | lookup("status-labels", "Unknown")'
  # "PND" → "Pending"
  # "SHP" → "Shipped"
  # "DLV" → "Delivered"

Currency conversion labels

Section titled “Currency conversion labels”
mapping:
  currency_name: 'source.currency | uppercase | lookup("currency-names", "Unknown Currency")'

Versioning

Section titled “Versioning”

Lookup tables have a version field that increments on each modification. This allows tracking changes over time.

What’s next

Section titled “What’s next”