## Overview

The **Lookup Tables** are a way for you to store data that you can then use in **Templates**, **Flows** and **Journeys**. Create your Lookup Tables through the dashboard, and then dynamically reference data in these table

Lookup Tables in Bird store and centralize data references, which can be looked up when creating email templates using Liquid templating language in HTML.

For example, every country's flags, abbreviations, or currency can be stored and updated centrally as a lookup table. Every time it is used in building an email, it can be referenced from this lookup table.

> **Important limitations:**
>
> - Each table can have up to 10 separate data items stored in it.
> - Each item may contain up to roughly 300kB of data.

## Create a Lookup Table

Go to Content > Lookup Tables and click on Create.

- Enter a display name
- Enter a slug with no spaces

![Lookup tables page with the Create a new lookup table panel showing name and slug fields](https://framerusercontent.com/images/bh2eA0wgSKqmaoZKdVJH9U4CEhQ.png)

The Slug is used to reference this table and may only contain alphanumeric characters. Note that this slug is used in referencing the email template

- Click on Save

![Lookup tables list showing the saved App Engagement table with its slug and item count](https://framerusercontent.com/images/rVxWCE6umj72EYmoRCcQFba805s.png)

##

## Creating an item in a table

Click on the table you've created

From the context menu that pops up, select "View"

![App Engagement lookup table detail view with the JSON text editor showing a key value pair](https://framerusercontent.com/images/XvsjGOGrCYl9ynUhjm3PwMAhUuI.png)

Each item in a table is essentially a JSON document. This means you can build up a tree-structure of keys and values, where the values can be text, numbers, booleans, arrays or objects themselves. You can either enter a JSON document directly, using JSON syntax or you can use a UI editor to construct the JSON document.

### JSON Editor

- Once you have saved, you will see a JSON editor. You can select either the Text or UI editor based on your preference.
- Update the lookup table using a JSON structure.

### Adding an item

To add an item in a JSON for organization, click on +Add Item on the left pane.

- Type a name on the top
- Click on Add Item button
- Once created, you can see the item created on the left pane.

### Write the JSON

Use the JSON format to define any object structure and key-value pairs below:

For example, a JSON which gives countryname and local currency based on country abbreviation

```text
{

 "NL": {

   "countryname": "Netherlands",

   "local_currency": "EUR"

 },

 "US": {

   "countryname": "United States",

   "local_currency": "USD"

 }

}
```

You can also use the UI editor to define the JSON structure.

![App Engagement lookup table UI editor building a key value pair from a row of fields](https://framerusercontent.com/images/RLeUk9jZd82Cuc8xyMkfMbQiJiQ.png)

## Use Lookup Table in Email Template

To use a lookup table in an email template, you can add the following liquid syntax to your HTML template or to an HTML element used in a drag-and-drop builder:

```text
{% assign variable_name = "lookup-table-slug" | lookup: "item-name", "object-value" %}

{{variable_name.key_name}}
```

Here,

- **variable_name** is any name you can define
- **lookup-table-slug** is the slug you have given when creating the lookup table
- **item-name** is the name of the item you have created
- **object-value** is the value you have given for the JSON item
- **key_name** is the name of the key in the key-value pair defined under item-value

For example,

To render the local currency of a defined country, we can use the below syntax

- **variable_name** here is defined as currency (any name that the user can define)
- **lookup-table-slug** here is **country-flags** as defined when the lookup table was created
- **item-name** is the **country** as created earlier and shown in the left pane
- **object-value** is **AD,** which is the value defined in the JSON**.** Note that this can also be a variable
- **key_name** is the local_currency, which is defined in the JSON

```text
{% assign currency = "country-flags" | lookup: "country", "AD" %}

{{currency.local_currency}}
```

When used in the email template builder in an HTML block, the above syntax will render the value of the _**local_currency**_ as stored under the _**AD**_ object under the country item in the lookup table **country-flags**

You can switch to the preview section to see the output value displayed dynamically in the email template. Below, it is showing EUR as the value fetched from the look-up table.

## Using lookup tables in Flows

You can read lookup tables in Flows to reuse centrally defined data.

To use a lookup table, first create one as described in above.

1.  Navigate to the Workflows > Flows
2.  Create an initial flow using a trigger type of your choosing.

Add a new **Perform Lookup** step to your flow. Click on **Add New Action** and either select it from the **Lookup Tables** group or search for it using the Search capability on the right:

![Flow action picker searching for and showing the Perform Lookup action](https://framerusercontent.com/images/boDLOrbqM2oOMlWdTpfZbVq5Ybs.png)

You'll be shown a configuration screen where you can select the table to read from and configure how exactly you want to perform this lookup:

![Perform Lookup configuration screen with Lookup Table Slug, Lookup path, and Replace sections](https://framerusercontent.com/images/hSrveoww8iVfQHPXjwiEJDkDCg.png)

You'll see three components you can configure:

1.  **Lookup Table Slug** indicates what table you want to look at. By clicking in this field, Flows will show you the available lookup tables:

![Lookup Table Slug field dropdown listing the available App engagement lookup table](https://framerusercontent.com/images/ucZ8zgA7dm6fHsMiozeRszf0W8.png)

1.  **Lookup** lets you determine what to retrieve and you can use the various variables available to you to construct this lookup key. Default operation is to return the value your look up points to as the root level value, but if you want to create an object of data - you can use the **As** capability to load it into a specific property:

![Lookup configuration with a Path field using a locales variable and an As field set to download_texts](https://framerusercontent.com/images/dUDvzyWAyIS56Mh2di4wJ5EOGYE.png)

1.  **Replace** lets you replace variables in a returned lookup results with either a static value or a value that is defined somewhere in your lookup table. The following example would replace the text `{{ MyVariableName }}` in any item returned with the Lookup action with the value it finds under key `replacements.<locale>.MyVariableName`:

![Replace section configuring a variable name and lookup path to swap values from the lookup table](https://framerusercontent.com/images/W8992L9IuVdHZySOpWwQWvjpGs.png)

By then clicking the Test button will let you see the resulting data:

![Perform Lookup test succeeded with the JSON output showing the returned lookup result](https://framerusercontent.com/images/fRH0bR5ltjTN4BRob1nT6AbKcoA.png)

Configuring which table to read from required and you must add at least one`Lookup` action. You're not required to add any `Replace` actions.