Reference tables

A reference table is a lookup table you upload as a CSV — a CRM export, a price list, a mapping from an internal code to a human-readable label — that an enrichment function can read by key while an event is being processed. It's the standard way to attach data your event stream doesn't carry on its own, without hardcoding it into a Python function.

Creating one

From the Reference tables catalog: pick a name, download the CSV template if you want a starting point with the expected shape (a header row, comma-separated), choose your own CSV file, and pick which column is the key column — the column an enrichment will look values up by (a phone number, an account id, an internal code). It defaults to the first column, but any column works:

Creating crm_contacts — CSV chosen, key column defaulted to “phone”.

Column types (String, Int64, Float64) are detected automatically from the CSV's own content — there's no schema to define by hand. Once created, the table shows up in the catalog alongside every other one, with its row count and key column at a glance:

The Reference tables catalog, showing row count and key column per table.

Looking at what you uploaded

Opening a table shows its columns (with their detected types), a preview of the first rows, and a Download CSV link that exports every row exactly as stored — useful for confirming a lookup will actually match what you expect before wiring it into an enrichment:

crm_contacts — columns with detected types, a row preview, and Replace data below.

Updating the data

Replace data uploads a new CSV and swaps out every row at once — there's no version history for reference tables the way there is for dashboards and enrichments, so this is a full replace, not a merge. Worth remembering if you're updating a CRM export on a schedule: the new file needs every row you still want, not just the ones that changed.

Restricting who can see one

By default, every reference table is visible to everyone on the account. If a table holds something sensitive — personal contact details, internal pricing — its own Access page can restrict visibility to Admins plus a specific list of Analysts and Viewers, the same access model dashboards use:

Restrict visibility, turned on — only Admins and the picked users below can see this table.

Note. Creating, replacing, and deleting a reference table is Admin-only, even though viewing an already-created one can be opened up to Analysts and Viewers — the same split as a dashboard's own edit-vs-view permissions.

Using it from an enrichment

Inside any enrichment function, reference_tables['<table_name>'].get(<key>) returns the matching row as a dict (or nothing, if the key isn't found). See Enrichments for a full worked example using exactly this table.