SQL Sources

Written by Ilya Sudakov

Updated on Sep 24, 2026

Overview

A SQL source is a named query that a widget reads from instead of a data table. You write the SQL once — joins, calculated columns, cleaned-up labels — and then build the widget on top of it with the same controls you use for any table: pick metrics and dimensions, set the date field, apply filters and limits.

SQL sources are shared across the dashboard. Several widgets can use the same source, each with its own metrics and grouping, and when you edit the source every widget that uses it updates. It works like custom metrics: define the logic once, reuse it everywhere.

SQL sources work with Table, Chart, KPI, Pie, Funnel, Heatmap, Sankey, Geo map and Custom Component widgets.

Create a SQL source

Open the widget's properties panel and go to the Data section.

Switch the source type from Table to SQL.

Open the source picker and choose New SQL source.

Enter a Source name (for example, Marketing performance) and write your query in the SQL editor. Use Format SQL to tidy it up.

Click Save source. The query is checked and its columns become available as metrics and dimensions in the Data section.

Select metrics, dimensions and the date field as usual. The dashboard date range and filters apply to the widget automatically.

Note

Write the query at the grain you need — for example, one row per day and campaign. You don't need placeholders such as {where_date} or {where_filters}: the widget adds the date range, dashboard filters, grouping and limits on top of your SQL.

Open another widget's Data section and switch to SQL.

Open the source picker, search by name and select the source.

Choose the metrics and dimensions for this widget. Each widget keeps its own settings — one can show spend by channel, another a daily revenue trend, both from the same source.

Edit, rename and delete

Edit the SQL — change the query and click Save source. The change applies to every widget that uses this source.
Rename — click the pencil icon next to the picker. Widgets stay connected after a rename.
Delete — sources that no widget uses are marked Not used at the bottom of the picker. Hover one and click the delete icon. A source that is still in use can't be deleted — switch its widgets to another source first.
Go back to a table — click Use dashboard table in the Data section.

Like any other dashboard edit, these changes are saved when you save the dashboard.

Existing custom SQL widgets

Widgets built with the earlier Custom SQL Editor keep working and can still be edited. New widgets that need SQL use SQL sources.

Tips

Give sources clear names — the name is how you and your team find them in the picker.
Return a date column if the widget should follow the dashboard date range.
Keep the source general and let each widget choose its own breakdown — one source can power a whole page.
You can also ask the AI agent to create or update a SQL source for you.