Metabase Models: A Guide to Building Semantic Layers

Metabase models are reusable, derived datasets that sit between your raw data and your reports. They let non-technical users query your database without touching SQL, while giving you a clean layer to add business logic. Unlike saved questions, which are single queries, models are semantic building blocks that multiple questions and dashboards can build on top of. They're how you turn a chaotic data warehouse into something your whole team can use.

What Are Metabase Models?

A Metabase model is a derived table or view that you define inside Metabase without running any migration or ETL job. It's built on top of your existing tables or other models. Unlike a saved question, a model isn't a single query: it's a reusable data source that other questions can query from. Models let you add a semantic layer of business context: custom column names, descriptions, and data types that make sense to your team, not your database administrator.

Think of models as a middle ground between raw tables and BI dashboards. Your database has tables like orders, customers, and payments. A model might be called "Customer Orders" and could join those tables, filter out cancelled orders, and calculate fields like "order value" or "days since purchase". Once you publish that model, anyone on your team can use it as if it were a table in your database. No SQL required. No copy-paste queries. One source of truth for that business logic.

The key difference from a saved question: a saved question is a complete visualization or export. It has a chart, a table view, and an owner. A model is a data source. You can build multiple questions on top of one model. You can even build models on top of other models, creating a stack of semantic layers that progressively add business context.

Why Use Models Instead of ETL or Raw Queries?

Models sit in a sweet spot between heavy ETL solutions like dbt and lightweight ad-hoc query builders. Here's why they matter.

Speed. If you need a cleaned-up dataset, you have three options: write SQL every time (error-prone, slow), schedule an ETL job (overkill for exploratory data), or publish a model (ready in minutes). Models live in Metabase and update whenever your underlying tables change. You don't maintain a separate pipeline.

Business ownership. With raw queries, every analyst rebuilds logic they think they remember. With models, you define it once and delegate it. A marketing manager doesn't need to know how to filter for active customers. You define that in a model, hide the technical columns, and hand them a clean dataset.

Flexibility. Models aren't as rigid as materialized views or ETL snapshots. You modify them without downtime. You add a column, rename a field, or change a filter. Your changes propagate instantly to every dashboard or report using that model. See how metadata works by reading Adding Metadata: The Model Superpower to understand the full benefit.

Stepping stone to real data engineering. If your model grows complex, you can port it to a real materialized view or dbt project later. Models are low-risk experimentation for semantic layer work.

Creating a Model from a Question

This is the fastest way to build a model. You start with a question, a query you've already tested, and promote it to a model.

Here's the workflow. First, build your question using the query builder or SQL. Test it. Make sure the results are clean and correct. Once you're happy, look for a menu icon (usually three dots) near the title. You'll see a "Turn into a model" or "Move to a model" option. Click it.

Metabase will ask you to choose a name and optionally a description. Use a name that makes sense to non-technical users: "Customer Orders", not "fact_orders_v2_join_customers". Add a short description explaining what the model contains. Then publish it.

That's it. Your model is live. Other users can now query it as if it's a table. You can set permissions so only certain teams see it, or make it available to everyone.

One gotcha: if your question has filters (like "only 2026 data"), those filters are usually applied at query time, not baked into the model. So if you turn a filtered question into a model, the model will contain ALL data by default. You can add a persistence layer later to cache filtered results, but initially, expect the full dataset.

Creating a Model from SQL

If you're more comfortable with SQL, you can write a model query directly instead of using the query builder. This is useful for complex joins, window functions, or logic that the query builder can't express easily.

Go to "New" or "New question" and choose "SQL query". Write your query as if you're selecting from your raw tables. Then, once you've tested it and it runs without errors, look for an option to "Save as a model" or "Turn into a model". Metabase will save it and make it queryable immediately.

SQL models work the same way as query-builder models once published. They're reusable data sources. The only difference is that you wrote the logic in SQL instead of the UI.

Use SQL models when you need complex aggregations, window functions, CTEs (common table expressions), or joins that the query builder doesn't support well. Use the query builder when you want speed and don't want to debug SQL syntax.

Adding Metadata: The Model Superpower

Publishing a model is half the job. The other half is adding metadata: the information that makes your model usable by non-technical users.

Metadata includes:

• Column names: Rename cust_id to Customer ID. Rename amt to Order Amount. Make your model self-documenting.
• Column descriptions: Hover over a column and see "Total revenue from this customer in USD, including cancelled orders" instead of guessing.
• Data types: Mark a column as a number, category, or datetime so Metabase formats it correctly in dashboards.
• Visibility: Hide technical columns that users shouldn't see. If you joined in a staging table's surrogate key, hide it.
• Field formatting: Show currency as $1,234.56, not 123456. Show dates as "Jan 1, 2026", not "2026-01-01".

Good metadata is the difference between a model that only analysts use and a model that powers your entire organization. A CFO can use a model with clear column descriptions and correct formatting. A CFO will panic if they see technical column names and raw timestamps.

To add metadata, open your model and go to the "Data model" or "Metadata" section (depending on your Metabase version). Click on each column and fill in the name, description, type, and formatting. Publish. Done.

Best Practices for Model Organization

As you create more models, you need a system to find them.

Naming conventions matter. Use "Subject Verb" naming: "Customer Orders", "Product Revenue", "Support Tickets". Avoid version numbers (customer_orders_v2) and underscores (use spaces: "Customer Orders", not "customer_orders"). Names should describe the business concept, not the table structure.

Collections. Organize models into Metabase collections by team or subject. A "Sales" collection might contain "Customer Orders", "Deal Pipeline", "Revenue Forecast". A "Product" collection might contain "Feature Usage", "User Sessions", "Onboarding Funnel". Make collections easy to navigate.

Document your models. Add descriptions to each model explaining what data it covers, how often it updates, and when you last modified it. If a calculation is non-obvious, explain it in the description.

Reuse. Build models on top of other models. Don't create "Customer Orders" and "Customer Payments" if both require the same customer cleaning and joining logic. Create a "Customers (Clean)" model first. Then build both on top of it.

Permissions. Be intentional about who can edit and view models. Let business users view them. Restrict editing to people who understand the data. Learn about advanced permissions for Pro and Enterprise options like row-level access control.

Advanced Features: Persistence, Verification & Search

Once you're comfortable with basic models, Metabase offers advanced features for teams that need them.

Model persistence (Pro and Enterprise only) pre-calculates and caches your model results on a schedule you choose. Instead of Metabase running your model query every time someone opens a dashboard, it runs the query once a night and stores the results. This is much faster for large models and complex queries. Downside: results are 1 day old, not live. Use persistence for models where a 1-day lag is acceptable (like historical customer summaries). Don't use it for real-time dashboards (like live error counts).

Record indexing lets users search for individual records inside a model. Normally, Metabase dashboards and questions show aggregations and summaries. Record indexing surfaces individual rows in global search. If you mark a column as "searchable", a user can type a customer ID or email in Metabase's search bar and jump straight to that customer record.

Model verification (Pro and Enterprise) is an audit feature. It logs when a model's results change significantly (like a sudden drop in row count) and alerts you. Useful for catching data quality issues before they break your dashboards.

Model list view is a free feature: once you publish a model, users can view it as a sortable, filterable table. It's not a dashboard: it's just the raw data. But it's useful for teams that need to explore or export data without building custom dashboards.

Using Models in Dashboards & Reports

Once your models are live, using them is simple: they appear as data sources in the question builder, just like your raw tables.

To build a question on a model, go to "New question" and choose your model under "Data". The query builder shows the model's columns with their custom names and descriptions. Build a question the same way you would on a raw table. Save, and add it to a dashboard.

Workflow example: You have a "Customer Orders" model. Someone on your team builds a question: "Orders by region in December". They filter the model to December, group by region, and show a bar chart. The model does all the heavy lifting: the joins, the data cleaning, the business logic. The analyst focuses on the analysis, not the plumbing.

This is the whole point. Your team spends time on insights, not on figuring out which table to join or whether the numbers are correct. The model is the source of truth.

Frequently Asked Questions

What's the difference between a model and a saved question? A saved question is a complete visualization or export: it shows you a chart or table. A model is a data source that other questions can build on. One model can power dozens of questions and dashboards. A saved question is just one query.

Can I edit a model after I publish it? Yes. Open the model and click "Edit". Change the query, the column names, the descriptions, or the filters. Publish your changes. Any questions or dashboards using that model will automatically see the updated data and metadata.

How often do models update? Models update whenever the underlying tables change (or whenever you manually refresh them). If model persistence is disabled, they update in real time. If persistence is enabled, they update on a schedule you set (like nightly).

Do I need SQL skills to create a model? No. You can create models entirely with the query builder UI. You can point, click, join tables, and publish. SQL models are optional, for advanced use cases.

What's the performance impact of models? Minimal. A model is just a query that runs when needed. If you enable persistence, Metabase pre-calculates results, which is faster. Otherwise, you're trading a small performance cost (your model's query runs every time) for a big UX gain (your team gets clean, reusable data).

Can non-technical users modify models? Not usually. Editing a model requires understanding the underlying data schema. Restrict model editing to analysts or data engineers. Non-technical users should view and query models, not edit them.

What's the difference between a model and a materialized view? A materialized view is a permanent database object. A model is a Metabase feature that runs on top of your database without changing it. Models are easier to manage (no database admin required), but materialized views can be faster for very large queries.

The Bottom Line

Metabase models are the fastest way to build a semantic layer without deploying a full data warehouse or ETL tool. They let you add business logic and clean data once, then reuse it across your entire organization. Start with a simple model built from the query builder. Add clear column names and descriptions. Share it with your team. Scale from there.

If you're running Metabase on your own infrastructure, you control the version, the data, and the cost. Explore Opsily's managed Metabase hosting to skip the DevOps work and focus on building your semantic layer.