Skip to main content
The query builder is Metabase’s graphical interface for creating questions. It lets you build sophisticated queries by clicking and selecting options - no SQL required.

​
What you can do with the query builder

The query builder provides a visual way to:

Pick and join data

Select tables and combine data from multiple sources

Filter records

Narrow down data based on conditions and criteria

Summarize and group

Calculate metrics and break them down by dimensions

Create custom columns

Add calculated fields using expressions

​
The query builder interface

When you create a question with the query builder, you’ll see the editor interface: Query builder editor The editor uses a step-by-step approach with three default steps:
  1. Picking data: Select your data source
  2. Filtering: Narrow down the records
  3. Summarizing: Calculate metrics and group by dimensions
You can add additional steps for joining tables, creating custom columns, sorting results, and limiting rows.
Click the Preview button (play icon) next to any step to see the first 10 rows of your results up to that point. This helps you validate your query as you build it.

​
Picking your data

1

Select your data source

Choose from:
  • Models: Curated datasets prepared by your team
  • Tables: Raw database tables
  • Saved questions: Build on existing question results
  • Metrics: Pre-defined calculations
You can search by typing or browse through databases and collections.
2

Choose columns to include

Click the arrow next to your data source to expand the column list. Uncheck any columns you don’t need in your results.
Unchecked columns are still available for filters and groupings - they just won’t appear in the final results.
3

Open in new tab (optional)

Cmd/Ctrl + Click on the data source name to view it in a new browser tab.
Hiding columns in visualization settings does NOT secure data. Anyone with view access can unhide columns. To exclude columns from query results entirely, uncheck them in the data picker.

​
Joining data from multiple tables

Combine data from multiple tables to enrich your analysis:
1

Add a join step

Click + Join data in the query builder to add a join step between your data and filtering steps.
2

Select the table to join

Choose which table you want to join with your current data source.
3

Configure the join

  • Join type: Choose from inner join, left outer join, right outer join, or full outer join
  • Join condition: Specify which columns to match between the tables
  • Columns: Select which columns to include from the joined table
You can add multiple joins to combine data from several tables. Joins are executed in the order you add them.

​
Filtering your data

Filters narrow down your data based on conditions:

​
Adding filters

  1. Click the Filter step
  2. Select the column you want to filter
  3. Choose your filter condition
  4. Enter the value(s) to filter by

​
Filter types by data type

  • Equal to
  • Not equal to
  • Greater than / less than
  • Between
  • Greater than or equal to / less than or equal to
  • Is empty / is not empty

​
Custom filter expressions

For complex conditions, use custom expressions: 
[Subtotal] > 100 OR [Quantity] < 10
Custom expressions support:
  • Comparison operators: >, <, >=, <=, =, !=
  • Boolean operators: AND, OR, NOT
  • Parentheses for grouping
  • Spreadsheet-like functions

​
Filtering by segments

If your administrators have created segments (pre-defined filter combinations), they’ll appear at the top of the filter menu with a star icon. Segments are shortcuts for commonly used filter combinations like “Active Users” or “High-Value Customers.”
You can add multiple filters to a question. All filters are combined with AND logic - records must match all filter conditions to be included.

​
Summarizing and grouping data

Summarizing lets you calculate metrics and group them by dimensions:

​
Choosing metrics

Select one or more aggregations to calculate:
  • Count of rows: Total number of records
  • Sum: Add up values in a column
  • Average: Calculate the mean
  • Distinct values: Count unique values
  • Minimum / Maximum: Find lowest or highest values

​
Grouping your metrics

Break down metrics by dimensions:
1

Select a grouping column

Click to choose the dimension you want to group by (time, category, location, etc.).
2

Configure grouping options

  • Date/time columns: Choose granularity (day, week, month, quarter, year)
  • Numeric columns: Set binning ranges to create histograms
  • Text columns: Group by unique values
3

Add multiple groupings

Click the + icon to add additional grouping dimensions for cross-tabulation.
When you group by date, Metabase automatically creates a time series chart. Grouping by categories creates bar charts. You can always change the visualization type afterward.

​
Multiple summarization steps

You can add multiple summarize steps to perform multi-stage aggregations:
  1. First summarization: Count of orders per month
  2. Filter: Where count > 100
  3. Second summarization: Average of count
This is similar to SQL’s HAVING clause for filtering aggregated results.

​
Creating custom columns

Custom columns add calculated fields to your question:
1

Add a custom column step

Click + Custom column in the query builder.
2

Write your expression

Create formulas using:
  • Math operators: +, -, *, /
  • Column references: [Column Name]
  • Functions: sqrt, power, abs, round, etc.
  • String functions: concat, lower, upper, trim
  • Date functions: year, month, day, now
3

Name your column

Give your calculated column a descriptive name.

​
Example custom columns

([Revenue] - [Cost]) / [Revenue] * 100
Custom columns are only added to the question results - they don’t modify your database tables.

​
Sorting results

Control the order of your results:
  1. Add a Sort step
  2. Select the column to sort by
  3. Choose ascending (↑) or descending (↓)
  4. Add additional sort columns for multi-level sorting
Sorting combined with row limits lets you create top-N lists, like “Top 10 customers by revenue.”

​
Setting row limits

Limit the number of results returned:
  1. Add a Row limit step (always the last step)
  2. Enter the maximum number of rows to return
Row limits are applied after all other query operations. To further analyze limited results, save the question and use it as a data source for a new question.

​
Interactive drill-through

When viewing results, click on data points to explore further:
  • See underlying records
  • Filter dashboard by value
  • Break out by related dimensions
  • Zoom in on time ranges
Drill-through options vary based on your data type and context. Query builder questions have richer drill-through capabilities than SQL questions.

​
Viewing the generated SQL

See the SQL that powers your question:
  1. Click View SQL in the top right
  2. Metabase shows the native query in a sidebar
To view SQL, you need both query builder and native query permissions for the database.

​
Converting to SQL

You can convert a query builder question to SQL:
  1. Click the Console icon in the upper right
  2. Select Convert this question to SQL
Converting to SQL is one-way. You cannot convert a SQL question back to the query builder.

​
Best practices

Preview frequently

Use the preview button after each step to validate your results before running the full query.

Start simple, build up

Begin with basic queries and add complexity incrementally. Easier to debug when issues arise.

Name custom columns clearly

Use descriptive names for calculated fields so others understand what they represent.

Use relative dates

Choose relative date filters (“Previous 30 days”) over fixed dates to keep questions current automatically.

​
Query builder limits

By default, Metabase limits aggregated queries to 10,000 rows. Administrators can adjust this with the MB_AGGREGATED_QUERY_ROW_LIMIT environment variable.
Some saved questions can’t be used as data sources:
  • Druid questions
  • MongoDB questions
  • Questions with cumulative sum or count
  • Questions with duplicate or similar column names
Time grouping parameters can only connect to fields in the last stage of a query. If your query’s final stage is a filter or sort, time grouping won’t work on earlier date fields.

​
Next steps

SQL editor

Learn when and how to use SQL for more complex queries

Native queries

Understand native query capabilities for different databases

Creating dashboards

Combine multiple questions into interactive dashboards

Build docs developers (and LLMs) love

Get started for freeTalk to us