Models

Create curated datasets that serve as starting points for analysis

Models are a fundamental building block in Metabase. They curate data from tables to anticipate the kinds of questions people will ask. Think of them as derived tables or special saved questions designed to be reused as starting points for new questions.

Models can be based on SQL or query builder questions, allowing you to include custom calculated columns and complex transformations.

What models can do

Models provide powerful capabilities for organizing and enhancing your data:

• Enhanced metadata: Update column descriptions and customize metadata to create intuitive starting points for exploration
• Improved discoverability: Show up higher in search results and get highlighted when users start new questions
• Organized in collections: Keep models separate from complex database schemas by storing them in collections
• Searchable records: Surface individual records in search results by indexing specific columns
• Performance optimization: Can be persisted for faster loading times

Use cases for models

Business concepts

Create intuitive representations of business concepts like “Customer” by pulling together data from multiple tables and adding calculated columns like lifetime value (LTV)

Enable exploration

Let people explore SQL query results with the query builder by properly setting column types

Summary tables

Create summary tables that aggregate and combine data from multiple sources

Clean datasets

Simplify tables by filtering out unnecessary columns and rows

Creating a model

Before creating a new model, search for existing ones that might meet your needs.

From scratch

1. Open the model creation dialog

   Navigate to the Models tab in the sidebar (under Data section) and click the + button, or use the command palette (Cmd/Ctrl + K) and type “model”

2. Choose your query method

   Select either the query builder or SQL. The query builder allows Metabase to automatically fill out some metadata; SQL requires manual metadata configuration

3. Build and save your query

   Select your data source, create your query, and save it. Models are automatically pinned to the current collection

From a saved question

1. Create or open a question

   Ask a question using the query builder or SQL editor, or open an existing saved question

2. Save the question

   Make sure your question is saved

3. Convert to model

   Click the … menu and select Turn this into a model

Model metadata

Metadata is the key to making models powerful. When you write SQL queries, Metabase can display results but doesn’t automatically understand the data types. Adding metadata enables query builder exploration and improves filtering and visualization.

If you only set one type of metadata, set the Column type to enable Metabase’s query builder features.

Display name

The user-facing name for the column that appears throughout Metabase

Description

Helpful context about what the column contains and how it should be used

Database column mapping

For SQL-based models, map columns to existing database columns to inherit their types

Column type

Set the semantic type (e.g., Email, URL, Currency). Required for SQL models to enable query builder exploration

Visibility settings

Choose whether columns appear in table views, detail views only, or both

Display format

Configure how values display (as text or clickable links)

Search indexing

Enable individual records to appear in search results by indexing string fields with integer primary keys. Limited to 25,000 unique values per field

Model list view

List view helps you explore records one by one instead of sorting through large tables.

1. Open metadata settings

   Visit the model and click the three-dot menu, then select Edit metadata

2. Navigate to Settings

   Go to the Settings tab

3. Enable list view

   Under “What should the default view of this data be?”, toggle to List

4. Customize layout

   Click Customize the List layout to configure which columns appear and their positioning

Customizing list layout

Each list item includes:

• Entity icon: Displays an image if the record has an image link
• Left column: Shows the title or primary identifier
• Right column: Displays up to 5 additional columns

You can search for columns, drag them to reorder, and remove unwanted columns. A preview with sample data updates as you make changes.

Referencing models in SQL

You can reference models in SQL queries just like tables:

SELECT * FROM {{#1-customer-model}}

Or use them as common table expressions (CTEs):

WITH model AS {{#3807-invoice-model}}
SELECT *
FROM model;

Type {{#}} in the SQL editor to search for models, questions, and tables. You can also use the data reference sidebar (book icon) to browse available models.

Editing models

Click the down arrow next to a model’s name and select Edit query definition to modify the underlying query.

Changes to models overwrite the existing definition. To create a new model from an existing one, use Duplicate this model instead.

Checking for breaking changes

Available on Pro and Enterprise plans

When saving model changes, Metabase detects whether changes would break dependent questions and dashboards. For example, removing or renaming a column triggers a warning if downstream entities use that column.

Currently, Metabase detects broken column references but cannot detect changes to column types or computation logic.

Model details and history

Click the info button to view:

• Overview: Description, creator, last editor, field list, and Entity ID
• History: Change log with previous 15 versions (you can revert to earlier versions)
• Relationships: Questions using the model and linked tables
• Actions: Actions created based on the model
• Insights: Usage analytics (Pro/Enterprise only)

Model persistence

Models can be persisted to improve query performance. Persisted models cache results in your database, allowing faster loading times for frequently accessed data.

For detailed information, see the Model persistence documentation.

Verification and permissions

Admins and users with appropriate permissions can verify models to indicate they’re trusted and ready for use. Verified models display a checkmark badge in the interface.

For more information, see Content verification.

Further reading

Model persistence

Learn how to persist models for faster query performance

Metrics

Create reusable calculations based on models

Troubleshooting models

Common issues and solutions for working with models

Models tutorial

Step-by-step guide to using models effectively