An entity key is the value that uniquely identifies a row in a table. In Metabase specifically, “Entity Key” is the name of the field type you assign to that column, so that Metabase knows the column identifies a record rather than describing one.
Entity key vs. primary key
The two terms point at the same column most of the time, but they live in different layers:
- A primary key is a database constraint. The database enforces it — writes that would create a duplicate or a null are rejected.
- An entity key is a metadata label in Metabase’s semantic layer. Nothing is enforced; the label tells Metabase how to treat the column.
That distinction matters most with analytical databases and warehouse tables, which frequently don’t declare primary key constraints at all. There’s no PRIMARY KEY for Metabase to read, but the table still has a column that identifies each record — so you mark it as the Entity Key yourself.
What the label changes
Tagging a column as the Entity Key affects how Metabase behaves around that field:
- Metabase can show the detail view for a single record when you drill through on a value.
- Columns tagged Foreign Key elsewhere can be connected to it, which is what makes joins suggest themselves in the query builder and makes related-record links work.
- Metabase treats the column as an identifier rather than a number to be summed or averaged — you rarely want the average of an ID.
You’ll also see a companion field type, Entity Name: the human-readable label for the same record, like customers.name next to customers.id. Entity Key is what the machine matches on; Entity Name is what people read.
Setting it
Metabase picks up entity keys automatically during sync wherever a database declares a primary key. Where it doesn’t, an admin sets the field type on the Data Model page in the Admin panel, and the change applies everywhere in Metabase. You can also set field types on the columns of a model, which is useful when the model’s output has a natural identifier that no underlying table declares.
Picking the right column
The column you tag should be genuinely unique at the grain of the table. A common mistake is tagging a column that looks like an ID but repeats — order_items.order_id, say, which appears once per line item and identifies the order, not the row. Tagging that as the Entity Key means drill-through lands on the wrong record. If nothing in the table is unique on its own, the table’s real identifier is a combination of columns, and the honest fix is upstream: give the table a surrogate key in your ETL layer before it reaches Metabase.
Related terms
Further reading
Put it to work
- Build a data pipeline — Integration
- Customer health dashboard — Dashboard
- Ecommerce analytics — Overview
