On this page

Lookup Tables

With Amplitude's Lookup Table feature, you can import your own data and map it to ingested properties to create an enhanced set of event and user properties.

Lookup table benefits

  • Enrich data using ingested property values. Say you've captured an event called Purchased with an event property named SKU. The SKU value itself doesn't inherently hold a lot of meaning. With your list of all the SKUs and their corresponding product names, you can use this feature to create a new property called Product Name that populates automatically based on that list.
  • Bulk change or fix property values. Imagine you've captured a user property called Language Code and passed in language codes (en_US, fr_FR, de_DE, etc.). These codes are difficult to read, so you want a Language property that maps to friendlier values like English, French, and German. Use this feature to create a new property called Language that maps the language codes to the language names.
  • Bulk filter long lists. To analyze user behavior for a specific region when you have a list of all customers and their regions, use this feature to map each customer to a region, creating a new Region property. You can then filter to each region in a chart.

Lookup Tables can't exceed 100MB or 1 million rows. Contact your Amplitude CSM if you have data that exceeds this limit.

Find lookup properties in charts

After you create a lookup property, it appears in chart dropdowns alongside the source property you mapped it from.

Lookup properties based on child (cart) properties

If you create a lookup property that maps from a child (cart) property (a property nested inside an object array), the lookup property doesn't appear in the main property list in charts. Instead, it appears under its parent cart property. To find it, first select the parent cart property (marked with {:}) in the property dropdown, then look for the lookup property as a nested option in the second-level dropdown. For more on cart properties, refer to Cart analysis.

Create a Lookup Table

Before you can start using Lookup Tables, you need:

  • An event property or user property to create a mapping from.
  • A .CSV that has the data you want to map to. The first column data must correspond to the mapping property value and must contain unique values.

Lookup Tables look for exact matches, and are case-sensitive.

To create a new Lookup Table in Amplitude Data, follow these steps:

  1. Navigate to Sources in the project you want to import the .CSV data to.
  2. Click + Add Source. Search for CSV, then click it.
  3. Navigate to your .CSV file and upload it. Then click Next.
  4. Map your event property by selecting it from the dropdown. When you're done, click Finish.

You must be an Admin or Manager of the project to add or manage a source.

Update a Lookup Table

To create a new lookup property or fix an incorrectly mapped property, update the lookup table by following these steps:

  1. In Amplitude, navigate to Sources, find the Lookup Table in the Sources List. Click it to open its General tab.
  2. Open the Edit Lookup Table Configuration tab.
  3. Make your changes. You can change the mapping, or replace the .CSV by uploading a new file.
  4. When you're finished, click Update your lookup table configuration.

Delete a Lookup Table and its properties

To delete a Lookup Table you no longer need, follow these steps:

  1. In Amplitude, navigate to Sources, then find the Lookup Table in the Sources List.
  2. Open the Edit Lookup Table Configuration tab.
  3. Click the trash can and follow the on-screen instructions.

Was this helpful?