Lookup tables

Overview

Create a Lookup Table

Use Lookup Table in Email Template

Using lookup tables in Flows

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

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

Creating an item in a table

Click on the table you've created

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

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

{

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

Go to Content > Lookup Tables and click on Create.

Enter a display name
Enter a slug with no spaces

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

Creating an item in a table

Click on the table you've created

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

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

{

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

Go to Content > Lookup Tables and click on Create.

Enter a display name
Enter a slug with no spaces

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

Creating an item in a table

Click on the table you've created

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

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

{

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

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:

{% 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

{% 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.

Navigate to the Workflows > Flows
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:

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:

You'll see three components you can configure:

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 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:

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:

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

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

How to use lookup tables

Overview

Overview

Overview

Create a Lookup Table

Creating an item in a table

JSON Editor

Adding an item

Write the JSON

Creating an item in a table

JSON Editor

Adding an item

Write the JSON

Creating an item in a table

JSON Editor

Adding an item

Write the JSON

Use Lookup Table in Email Template

Using lookup tables in Flows

More How-to’s

Explore additional videos and step-by-step guides to help you move forward.

Create personalized emails for cart, browse, and order events

Create personalized emails for cart, browse, and order events

Create a message template

Create a message template

Create personalized emails for cart, browse, and order events

Create a message template

Create an Email template

The complete AI-native platform that scales with your business.

The complete AI-native platform that scales with your business.

The complete AI-native platform that scales with your business.