Mixpanel Lookup Tables: Enrich Your Data Without Re-Tracking Anything

Here’s a request I get every few months from e-commerce clients: “We want to see purchases broken down by product category and brand. But we only track product_id.”

The usual instinct is to add category and brand to the tracking code. That works, but only for future events, and it means every developer touching checkout has to keep those values in sync with the product catalog forever. When a product moves categories, the historical data is stuck with the old one.

There’s a better way, and it doesn’t involve touching the tracking code at all. It’s called a lookup table.

What lookup tables are

Mixpanel describes lookup tables as a way to enrich event or user profile properties with extra attributes. You upload a CSV that has a join key column plus additional property columns, then map a Mixpanel property to that join key.

If you come from a database background, Mixpanel’s own comparison is helpful: lookup tables are like dimension tables or join tables.

Mixpanel’s example uses music. You track song_id on your events. You upload a CSV with song_id, artist, genre, release date and so on. From then on, any event with song_id can be filtered and broken down by artist or genre, as if those properties had been tracked all along.

The key benefit: it applies to historical data. Mixpanel joins the lookup table onto all prior events or profiles with the mapped property, not just new ones.

Use cases that come up again and again

  • Product catalog. Map product_id to category, brand, margin tier, supplier.
  • Content metadata. Map article_id to author, topic, word count, publish date.
  • Account data from your CRM. Map account_id to industry, company size, account manager, contract tier.
  • Locations. Map store_id or city_id to region, country, sales territory.
  • Campaign data. Map a campaign ID to campaign name, owner, budget tier and objective.
  • Readable labels for IDs. Map internal error codes to readable descriptions.

In every case, the pattern is the same: you already track an ID, and the descriptive data lives in another system.

How to create a lookup table

Step 1: Prepare the CSV

The first column is the join key. Mixpanel assumes the first column is the ID and joins on it. The other columns become the new properties.

product_idcategorybrandmargin_tier
SKU-1001FootwearNorthpeakHigh
SKU-1002FootwearTrailformMedium
SKU-2001OuterwearNorthpeakHigh

A few format rules from Mixpanel’s docs:

  • The CSV must be valid according to RFC 4180.
  • Lookup table property values don’t support objects or lists of objects.
  • Property names come from the CSV header row and can’t be renamed with a Lexicon display name later. Choose good column names before you upload. I use the same snake_case convention as the rest of the tracking plan.
  • The ID values must match the tracked property’s values exactly, including case and formatting. sku-1001 won’t match SKU-1001.

Step 2: Upload it

Go to Lexicon, open Lookup Tables, and import your CSV. The exact menu wording has shifted between versions of the docs, so look for the import option in the Lookup Tables section.

Step 3: Map it to a property

Map the lookup table to the event or profile property that holds the ID (for example, product_id). Once mapped, you’ll see the new columns appear under that property in reports, and you can use them as filters, breakdowns, or even inside custom properties (post 16).

Global vs local mapping

There are two ways to map:

  • Globally in Lexicon. Available to everyone in the project. Only Owners and Admins can create global mappings.
  • Locally in a report. Anyone can upload and map a lookup table within a single report. Free plan users can do this too. The mapping only lives in that report.

My recommendation: test locally first, check that the join works and the values look right, then ask an admin to make it global.

Mapping rules to know

  • One property can map to only one lookup table in Lexicon.
  • Many properties can map to the same lookup table. Mixpanel’s example is a first_location and a last_location property both mapped to one City table.
  • Need two lookup tables on the same property? Mixpanel’s suggested workaround is to create several custom properties that simply contain the original property (no functions), then map a different lookup table to each one.

Keeping lookup tables up to date

This is where many implementations fall over. A product catalog changes weekly. CRM data changes daily. A lookup table uploaded once and forgotten quietly goes stale.

You have three ways to refresh a table:

  1. Re-upload in the UI. Fine for small, rarely changing tables.
  2. The Replace Lookup Table API. Create the table once in the UI, then replace its contents programmatically with a PUT request authenticated with a service account. Mixpanel’s API reference notes it returns details for up to 10 rows that fail validation, which helps when debugging.
  3. Warehouse Connectors. If the source data already lives in BigQuery, Snowflake or another supported warehouse, sync the lookup table on a schedule (post 20).

For anything that changes more than monthly, I set up option 2 or 3 so nobody has to remember.

When not to use lookup tables

Lookup tables have limits. Per Mixpanel’s docs:

  • 100MB per CSV, roughly 1 million rows. Community answers also mention a total row limit across all tables.
  • They’re not a replacement for user profiles. Mixpanel is more optimized for profiles, which have no comparable scale limits and support workflows like clicking into a report to see the list of users. If you want to enrich users, set profile properties instead.

Also avoid lookup tables when the value genuinely belongs to the moment of the event. A product’s price at the time of purchase should be tracked on the purchase event, not looked up later. Otherwise a price change rewrites your revenue history.

That’s the core trade-off: lookup tables show current attributes on historical events. That’s perfect for “which category is this product in?” and wrong for “what did this product cost when it was bought?”

Managing lookup tables with Claude

Mixpanel’s MCP server includes tools to create, read and update lookup tables, including previewing a table’s schema, row count and rows. It’s a fast way to check whether a table is stale or whether the join key format matches the tracked values.

Mistakes to avoid

  • Mismatched ID formats between the CSV and the tracked property. The join silently fails.
  • Bad column names you can’t rename later.
  • Uploading once and never refreshing.
  • Using lookup tables for time-sensitive values like price or status at the time of an event.
  • Using them for user data that belongs on profiles.

Final thoughts

Lookup tables are one of the highest-leverage features in Mixpanel. A ten-minute CSV upload can add rich business context to years of event data without a single code change. Get the join key right, name your columns well, and automate the refresh.

Sources