Metabase User Guide

Metabase is an open-source business intelligence (BI) platform. It lets you ask questions about your data and display the answers in formats that make sense — whether that's a bar chart, a map, or a detailed table — without writing code. You can also write SQL directly, build interactive dashboards, set up automated reports, and let teammates explore data on their own.

This guide is for the people who use Metabase day to day: analysts, business users, and anyone who needs answers from their company's data. It covers installing and setting up Metabase, connecting a database, asking questions, visualizing and sharing results, building dashboards, and the everyday tasks in between. Architecture, deployment, and the full configuration reference live in the companion Admin Guide.

Note

Metabase ships in two editions: a free, MIT-licensed Open Source Edition (OSS) and a commercial Pro/Enterprise Edition (EE) with extra features (advanced permissions, SSO, serialization, and more). This guide notes where a feature requires a paid plan. You can also run Metabase as a fully hosted service on Metabase Cloud.

1. Quick Start

The fastest way to try Metabase locally is with Docker. If you don't have Docker, jump to Installation for the Java JAR method.

docker run -d -p 3000:3000 --name metabase metabase/metabase

Unable to find image 'metabase/metabase:latest' locally
latest: Pulling from metabase/metabase
...
Status: Downloaded newer image for metabase/metabase:latest
<container id>

Metabase listens on port 3000 by default. Give it a minute to start, then open:

http://localhost:3000/setup/

You'll be guided through a short setup wizard:

1. Pick your language.
2. Create your admin account (name, email, password).
3. Optionally connect your first database (you can skip and do it later).
4. Choose your data-usage preferences.

When the wizard finishes, you land on your home page. Metabase ships with a built-in Sample Database so you can start exploring immediately.

Tip

The first time Metabase boots it prints a setup URL to its logs, for example Please use the following URL to setup your Metabase installation: http://localhost:3000/setup/. If you lose track of the page, that log line has the link.

Your first question in 60 seconds

1. Click + New → Question.
2. Choose Sample Database → the Orders table.
3. Click Summarize, pick Count of rows, and group by Created At: Month.
4. Click Visualize. Metabase draws a line chart of orders over time.
5. Click Save to keep it.

You just built a question without writing any SQL. The rest of this guide explains how to go further.

2. Core Concepts

A few terms appear throughout Metabase. Learning them now makes everything else easier.

Note

Metabase reads your data to answer questions. The only times it writes back are when you explicitly use Actions (which run INSERT/UPDATE/DELETE against a writable database) or Uploads (which create tables from CSV files). Both are off unless an admin enables them.

3. Installation

Metabase is a Java application distributed as a single executable JAR or as a Docker image. Self-hosting is free with the Open Source Edition.

3.1 Requirements

• Java: A recent OpenJDK (Java 21 is the current target for modern releases) is required to run the JAR. Docker images bundle Java for you.
• Memory: Start with at least 1–2 GB of RAM available to the JVM.
• A modern browser: Chrome, Firefox, Safari, or Edge (current versions).

Important

Out of the box, Metabase stores its own application data in an embedded H2 file database. H2 is perfect for evaluation but not for production. Before you rely on Metabase, migrate the application database to PostgreSQL or MySQL — see the Admin Guide for the exact steps. This is about Metabase's own storage, not the databases you analyze.

3.2 Install methods

Docker

docker run -d -p 3000:3000 --name metabase metabase/metabase

Then open http://localhost:3000. To persist data and configuration, mount a volume and point Metabase at an external application database (see the Admin Guide).

Java JAR

Download metabase.jar from the releases page, then run:

java --add-opens java.base/java.nio=ALL-UNNAMED -jar metabase.jar

Starting Metabase version v0.XX.X ...
Setting up and migrating Metabase DB. Please sit tight, this may take a minute...
...
Metabase Initialization COMPLETE

Metabase serves on http://localhost:3000.

Metabase Cloud

Sign up at store.metabase.com. Cloud handles hosting, backups, upgrades, an SMTP server, and SSL for you. Nothing to install.

Tip

Change the port with the MB_JETTY_PORT environment variable, e.g. docker run -d -p 8080:8080 -e MB_JETTY_PORT=8080 metabase/metabase. The full environment-variable reference is in the Admin Guide.

3.3 Verify it's running

Metabase exposes lightweight health endpoints:

curl http://localhost:3000/api/health

{"status":"ok"}

While Metabase is still starting, /api/health returns a 503 with {"status":"initializing", ...}. Once you see {"status":"ok"}, you're ready.

4. Connecting Your Data

Metabase becomes useful once it's connected to your own database. The Sample Database is a sandbox; your real work starts here.

4.1 Add a database

1. Click the gear icon (⚙) → Admin settings → Databases → Add database. (You need admin rights.)
2. Choose your database type.
3. Fill in the connection details (host, port, database name, username, password).
4. Click Save.

Metabase ships with built-in support for many engines. Core engines (PostgreSQL, MySQL/MariaDB, H2) are always present; many others ship as drivers, including data warehouses and analytics engines (for example ClickHouse, Starburst/Trino, and more). Each driver knows how to translate Metabase questions into that engine's SQL dialect.

Note

Connection details are stored in Metabase's application database. If you set an encryption key (MB_ENCRYPTION_SECRET_KEY), those credentials are encrypted at rest. See the Admin Guide for encryption setup.

4.2 Secure connection options

These are configured in the database's connection form.

4.3 Syncing and scanning

After you connect a database, Metabase runs two background processes:

• Sync discovers the schema: tables, columns, and their data types. Runs on a schedule (hourly by default) so new tables and columns appear automatically.
• Scan (fingerprinting) samples column values to learn things like which columns are categories, what the value ranges are, and which fields to offer as filter dropdowns.

You can trigger a manual sync or change the schedule from Admin settings → Databases → [your database].

Warning

A very large database can take a while to sync the first time. If Metabase's UI shows tables but filters don't list values yet, the scan is probably still running. Give it time, or trigger Re-scan field values now from the database settings.

Caution

If Metabase's application database is MySQL, table-name case sensitivity can cause sync to miss tables whose names differ only by letter case (for example two BigQuery tables that differ only in capitalization). This is a known limitation; using PostgreSQL for the application database avoids it.

4.4 Uploading data (CSV)

If an admin enables Uploads, you can create tables directly from spreadsheet files without touching a database client.

1. Click + New → Upload (or use the upload button on a collection).
2. Choose a .csv (or supported spreadsheet) file.
3. Metabase infers column types, creates a table in the configured upload database/schema, and opens it as a model you can query.

Tip

Uploads are great for joining a one-off spreadsheet against your warehouse data. If number columns aren't detected the way you expect, check that the file uses a consistent decimal/thousands format — Metabase infers types from the sampled values.

5. Asking Questions

A question is a query plus its result. Metabase gives you two ways to build one: the visual query builder (no SQL needed) and the native SQL editor (full control).

Start any question with + New → Question (query builder) or + New → SQL query (native editor).

5.1 The query builder

The query builder lets you assemble a query step by step. Pick a data source (a table, a model, or a saved question), then add steps:

Each step shows a live preview, so you can build incrementally and see the effect immediately.

Filtering

Click Filter and choose a column. The available operators depend on the column type:

• Dates: relative ranges ("Previous 30 days"), specific ranges, "on", "before", "after", "between".
• Numbers: =, ≠, >, <, between, "is empty".
• Text/category: "is", "is not", "contains", "starts with", dropdown of known values.

Note

When filtering a timestamp column with between, be aware the upper bound has historically been treated as exclusive in some cases. If a "between" range on a timestamp seems to drop rows at the very end of the range, add a day or use "before [next day]" to be explicit.

Summarizing and grouping

Summarize chooses the measure (what to calculate). Group by chooses the dimensions (how to slice it). For example: Sum of Total, grouped by Product → Category and Created At: Quarter, produces revenue per category per quarter — ready to chart.

Custom expressions

When the built-in aggregations aren't enough, write a custom expression. Expressions support arithmetic, conditional logic (case), string functions, date functions, and aggregations.

# A custom column flagging high-value orders
case([Total] > 100, "High", "Standard")

# A custom metric: average order value
Sum([Total]) / Count()

There's a full function reference in the expression editor (click the ƒx helper). Functions cover math, text (concat, lower, regexextract), dates (datetimeDiff, month, now), and logic (case, coalesce).

Joining data

Click Join data, pick the table or saved question to join, and set the join condition (the columns that match). Metabase supports left, right, inner, and full outer joins. You can chain multiple joins.

5.2 The native SQL editor

For full control — window functions, CTEs, database-specific syntax — use the native query editor (+ New → SQL query). Pick the database, write SQL, and run it.

SELECT category, SUM(total) AS revenue
FROM orders o
JOIN products p ON o.product_id = p.id
GROUP BY category
ORDER BY revenue DESC;

The editor includes autocomplete for tables and columns, SQL formatting, and a side panel (the data reference) for browsing schema while you write.

SQL parameters and variables

Make native queries dynamic with variables, written as {{variable_name}}:

SELECT *
FROM orders
WHERE created_at >= {{start_date}}
  AND category = {{category}}

Each variable becomes an input widget above the editor. Variable types include Text, Number, Date, and Field Filter (which maps a variable to a real column so you get a smart filter widget, including dropdowns and date pickers).

Optional clauses use [[ ... ]] so a filter only applies when the variable is set:

SELECT *
FROM orders
WHERE true
  [[ AND category = {{category}} ]]

Snippets

Save reusable SQL fragments as snippets (e.g. a standard set of joins or a WHERE clause) and reference them with {{snippet: Active customers}}. Snippets can be organized into folders, and (on paid plans) folders can have permissions.

Referencing saved questions and models

You can query a saved question or model as if it were a table:

SELECT * FROM {{#42-active-customers}}

where 42 is the question/model ID. This lets you layer SQL on top of curated models.

6. Visualizing Results

Once a question returns data, click Visualization to choose how to display it. Metabase picks a sensible default and lets you switch freely.

6.1 Available visualizations

6.2 Formatting and settings

Each visualization has a settings panel (the gear on the chart) where you can:

• Rename axes and series, set axis ranges, and add goal lines.
• Choose colors per series.
• Format numbers (currency, percent, decimals), dates, and times.
• Add conditional formatting to tables (color cells by value).
• Show/hide the legend, data labels, and trend lines.

Tip

Formatting you set on a field in the data model (e.g. "Total is USD currency") becomes the default everywhere that field appears, saving you from reformatting in every question.

6.3 Exporting results

From any question or dashboard card, use the download button to export results as CSV, Excel (.xlsx), or JSON. Public/embedded questions can also expose downloads when enabled.

7. Saving and Organizing

7.1 Save a question

Click Save, give it a name and optional description, and choose a collection to store it in. Saved questions can be reused on dashboards, referenced from SQL, and turned into models.

7.2 Collections

Collections are folders. Use them to group related content (e.g. "Marketing", "Finance") and to control who can see or edit what — permissions are granted per collection (see the Admin Guide for the permission model).

• Our analytics is the top-level collection.
• Your personal collection is private to you — a scratch space.
• Nest collections to mirror your team structure.

7.3 Search, browse, and bookmarks

• Search (top bar) finds questions, dashboards, models, metrics, tables, and more by name. Already-documented matches and frequently used items surface first.
• Browse lets you explore Databases (raw tables) and Models separately from collections.
• Bookmarks pin your most-used items to the sidebar. Click the ribbon icon on any item to bookmark it.

7.4 History, trash, and verification

• History: Metabase versions questions and dashboards. Open an item's history to see who changed what and revert to a previous version.
• Trash: Deleted items go to the Trash, where they can be restored or purged.
• Content verification (paid): reviewers can mark trusted items with a verified checkmark so others know they're reliable.

8. Data Modeling

Models, metrics, and segments turn raw tables into a curated, self-service layer your whole team can build on.

8.1 Models

A model is a reusable, cleaned-up dataset. Build one from a query (visual or SQL), then enrich it: rename columns, set human-friendly descriptions, fix data types, and mark which columns are keys or have special semantics. Questions built on a model inherit all that metadata.

• Model persistence (for supported databases): Metabase can materialize a model's results into a table on a schedule, so questions built on it run fast.

8.2 Metrics

A metric is an official, named calculation — "Total Revenue", "Active Users", "Conversion Rate". Define the aggregation once; everyone reuses the same definition, so numbers stay consistent across the organization. Metrics appear as starting points in the query builder and can be combined and grouped like any measure.

8.3 Segments

A segment is a named, reusable filter — for example "Completed orders" (status = 'completed'). Apply a segment in the query builder instead of re-creating the same filter every time.

8.4 Table metadata and field types

Admins (and data managers) can edit table metadata: friendly table/column names, descriptions, visibility, and semantic types (e.g. marking a column as Email, Category, Latitude, Currency, Foreign Key). Semantic types drive smarter defaults — currency formatting, map rendering, filter widgets, and automatic relationships.

• JSON unfolding: columns containing JSON can be "unfolded" so nested keys become queryable columns.

9. Dashboards

A dashboard arranges multiple cards on a grid so you can see related metrics together.

9.1 Build a dashboard

1. + New → Dashboard, name it, choose a collection.
2. Click the pencil to edit, then + to add cards (existing questions or new ones).
3. Drag and resize cards on the grid. Add text/heading cards for context and link cards for navigation.
4. Save.

9.2 Dashboard filters

Add filters at the dashboard level (date, category, location, number, text) and wire each filter to the relevant column in each card. One filter widget can then update every card at once.

• Set default values so the dashboard loads with a useful view.
• Link filters so selecting one narrows the options in another.

9.3 Interactive dashboards

Make dashboards explorable:

• Click behavior: clicking a data point can drill through to the underlying rows, filter another card, or navigate to another dashboard, question, or URL.
• Drill-through: clicking a bar or cell offers automatic actions — zoom in, break out by another dimension, see the underlying records, or open the table.

9.4 Subscriptions

Schedule a dashboard to be delivered automatically:

1. Open the dashboard → sharing icon → Subscriptions.
2. Choose Email or Slack.
3. Set the schedule (e.g. every weekday at 8am) and recipients.
4. Optionally apply filter values so each subscription sends a tailored view.

Note

Email subscriptions require an admin to configure SMTP (or use Metabase Cloud's built-in mail). Slack delivery requires a Slack connection. Both are set up in Admin settings.

9.5 Actions on dashboards

If your database is writable and Actions are enabled, you can add action buttons to a dashboard — for example a button + form that inserts or updates a row. See Actions.

10. Exploration: X-rays, Timelines, and Documents

10.1 X-rays

X-rays are instant, auto-generated explorations. Click the X-ray option on a table, a value, or a question and Metabase builds a full dashboard of charts about it — distributions, trends, and breakdowns — with zero setup. It's the fastest way to get a feel for new data.

10.2 Events and timelines

Add events (e.g. "Pricing change", "Marketing campaign launch") to a timeline attached to a collection. Events show up as reference markers on time-series charts, so spikes and dips have context.

10.3 Documents

Documents let you write rich, narrative reports that embed live questions and charts inline — think of a data-driven doc that stays current as the underlying questions refresh. Create one from + New → Document.

11. Actions

Actions let Metabase write back to a connected (writable) database from a question or dashboard — useful for lightweight data entry and operational workflows.

• Basic actions: auto-generated Create, Update, and Delete forms for a model backed by a single table.
• Custom actions: write a parameterized SQL statement (e.g. UPDATE orders SET status = {{new_status}} WHERE id = {{id}}) and expose it as a form.

Add actions as buttons on dashboards, or trigger them from a record detail view.

Caution

Actions modify your data. They run against databases where an admin has enabled write access. Restrict who can run them with permissions, and test against non-production data first.

12. AI: Metabot

Metabase includes Metabot, an AI assistant that helps you explore data in plain language.

• Ask in natural language: describe what you want ("show me revenue by region last quarter") and Metabot drafts a question for you.
• Metabot in Slack: ask questions from Slack and get answers back in-channel.
• Agent API / MCP server: programmatic and Model Context Protocol interfaces let external tools and AI agents query Metabase.

Note

AI features are governed by AI settings and usage controls that admins configure, including which models are used and what data may be sent. If you don't see Metabot, an admin may not have enabled it. See the Admin Guide and the AI privacy documentation for details.

13. Alerts

Set an alert on a question to be notified when something happens:

1. Open a saved question → sharing/notification icon → Create alert.
2. Choose the condition:
   • When this has results — for questions that usually return nothing (e.g. "errors in the last hour").
   • When a goal is met — for a line/bar chart with a goal line.
   • On a schedule — send the current results periodically.
3. Pick delivery (email or Slack) and frequency.

Alerts and dashboard subscriptions together cover most "tell me when / send me this regularly" needs.

14. Sharing and Embedding (User View)

• Public links: if an admin has enabled public sharing, you can generate a public URL (or an embeddable iframe snippet) for a question or dashboard that anyone with the link can view — no login required.
• Embedding: Metabase questions and dashboards can be embedded into other applications. There are several modes (static/guest, signed, SSO, and the Embedded Analytics SDK). Embedding setup is primarily an admin/developer task — see the Admin Guide.

Warning

A public link exposes the underlying results to anyone who has the URL. Only share public links for data that's safe to be public, and revoke them when no longer needed.

15. Account Settings

Click your avatar → Account settings to manage your own profile:

• Profile: name, email, and language.
• Password: change your password (subject to the complexity policy your admin set).
• Login history: review recent sign-ins.
• Notifications: see the alerts and subscriptions you're part of.

If you forget your password, an admin can trigger a reset (or, for self-hosters, the server operator can run the reset-password command — see the Admin Guide).

16. Keyboard Shortcuts

Metabase has shortcuts for common navigation and editing. Press ? anywhere to open the shortcuts cheat sheet. Highlights include quickly opening search, creating a new question, and toggling the data reference panel in the SQL editor.

17. Troubleshooting

Each entry below follows: symptom → likely cause → fix.

Error: {"status":"initializing"} when opening Metabase

Cause: Metabase is still booting (running database migrations and loading sample content). Fix: Wait until /api/health returns {"status":"ok"}, then refresh. First boots can take a minute or more. Prevention: Give the server adequate memory; large application databases take longer to migrate.

Tables are missing or columns are out of date

Cause: The database hasn't been synced since the schema changed. Fix: Admin settings → Databases → [your DB] → Sync database schema now. Prevention: Leave the scheduled sync enabled; it runs hourly by default.

Filter dropdowns are empty or show no suggested values

Cause: Field scanning (fingerprinting) hasn't run, or the field's value list isn't being cached. Fix: Admin settings → Databases → [your DB] → Re-scan field values now. Check the field's setting is "A list of all values". Prevention: Allow scans to complete after the first connection.

A between filter on a timestamp drops rows at the end of the range

Cause: The upper bound of a timestamp range can be treated as exclusive. Fix: Extend the range by a day, or use "before [the next day]" to be explicit about the boundary. Prevention: Prefer date (not timestamp) granularity when you want inclusive day ranges.

Sync says "The sync is taking too long. Something is wrong."

Cause: The connected database is very large, slow, or the connection is flaky. Fix: Reduce the schemas/tables Metabase syncs (database settings let you choose), verify network/credentials, and retry. Prevention: For huge warehouses, restrict Metabase to the schemas you actually analyze.

Uploaded CSV numbers imported as text

Cause: Inconsistent number formatting in the file confused type detection. Fix: Normalize the column (consistent decimal separator, no stray symbols) and re-upload, or fix the column type in the resulting model's metadata. Prevention: Export source spreadsheets with plain numeric formats.

Two tables differing only by letter case don't both appear

Cause: Case-insensitive collation in a MySQL application database treats the names as identical. Fix: Use PostgreSQL for Metabase's application database. Prevention: Choose Postgres for the app DB in production (recommended anyway).

Custom expression error: Invalid expression

Cause: A syntax error — mismatched brackets, an unknown function, or a column reference that doesn't exist. Fix: Use the ƒx helper to insert functions and [Column] references correctly; check that every ( has a matching ). Prevention: Build expressions incrementally and use the live preview.

Can't sign in / "session expired" too often

Cause: The session age is short, or cookies are being cleared. Fix: Ask your admin to review the session expiration setting (MAX_SESSION_AGE, default 14 days). Prevention: Don't use private/incognito sessions for daily work.

A chart looks wrong after switching visualizations

Cause: The new visualization needs different columns (e.g. a map needs a geographic field; a pie needs one dimension + one measure). Fix: Open the visualization settings and assign the correct fields to each role (X/Y, dimension/measure, latitude/longitude). Prevention: Summarize/group your data to match the chart you want before switching.

Dashboard subscription or alert didn't arrive

Cause: Email (SMTP) or Slack isn't configured, or the recipient/filter is wrong. Fix: Confirm with an admin that email/Slack is set up; check the subscription's recipients and schedule. Prevention: Send a test, and verify the delivery channel in Admin settings.

18. Frequently Asked Questions

Q: Is Metabase free? Yes — the Open Source Edition is free and MIT-licensed. Paid Pro and Enterprise plans (self-hosted or on Metabase Cloud) add features like advanced permissions, SSO, serialization, and more.

Q: Does Metabase store or copy my data? No. Metabase queries your database live and caches only query results (and sampled values for filters). Your source data stays in your database. The exceptions are Uploads and Actions, which you explicitly opt into.

Q: Do I need to know SQL? No. The query builder handles filtering, summarizing, grouping, and joining visually. SQL is available when you want full control.

Q: What databases can Metabase connect to? Many — PostgreSQL, MySQL/MariaDB, SQL Server, and a wide range of data warehouses and analytics engines via drivers (BigQuery, Snowflake, Redshift, ClickHouse, Starburst/Trino, and others). Admins add databases in Admin settings.

Q: How do I share a question with someone who doesn't have an account? Use a public link (if your admin enabled public sharing) or embed the question. Otherwise, give them a Metabase account and the right collection permissions.

Q: What's the difference between a question, a model, and a metric? A question answers one thing. A model is a reusable, curated dataset you build other questions on. A metric is a reusable, named calculation (like "Revenue") for consistent numbers everywhere.

Q: How do I get a number emailed to me every morning? Set a dashboard subscription or an alert with an email (or Slack) delivery on a schedule.

Q: Why don't I see Admin settings? Admin settings are visible only to administrators. Ask an existing admin to grant you the rights or make the change for you.

Q: Can I undo a change to a question or dashboard? Yes. Open the item's history and revert to any previous version.

Q: How do I move a question into a different folder? Open it (or select it in a collection) and use Move. You need edit permission on both the source and destination collections.

Q: My query is slow. What can I do? Filter to fewer rows, summarize before charting, build on a model (optionally persisted), and ask your admin about enabling result caching.

Q: Can Metabase write back to my database? Only through Actions (and Uploads), which an admin must enable and which run against databases configured for write access.

Q: How do I change the language? Set it per-user in Account settings → Language, or instance-wide in Admin settings (localization).

Q: Where can I learn more? The official docs at metabase.com/docs and the learning hub at metabase.com/learn cover everything in depth. The community forum is at discourse.metabase.com.