Documentation

The Chart widget visualizes metrics over time as bars, lines, or area series — combining dimensions, calculated metrics, and optional custom SQL queries. The use cases below show common ways to build and configure it.

Build your chart

1. Add a Chart widget to your dashboard

Display time-series data for one or more metrics from your connected data source.

1. Open your dashboard in edit mode.
2. Click Select a default data table in the header and choose your data source (e.g. cross_channel_automated_recipe).
3. Click + Chart in the bottom toolbar. The widget appears on the canvas and the Properties Panel opens automatically.
4. In the Data section, click one or more metrics (e.g. Spend, Revenue) to populate the chart.
5. Close the Properties Panel to see the finished widget.

Result: The chart renders with a time-series bar or line for each selected metric. The default title is Performance Over Time.

2. Select metrics

Add or remove the numeric series displayed on the chart.

1. Open the Properties Panel and click the Data section.
2. Use the search input to find a metric by name (e.g. Spend, Clicks).
3. Click a metric to add it as a series on the chart.
4. Click a selected metric again to remove it.

Result: The chart updates immediately. A badge next to the Data section label shows the current count (e.g. 2 metrics). The legend updates to reflect active series.

3. Add a calculated metric

Plot ratio-based metrics such as ROAS or CTR alongside raw spend or impression data.

1. Open the Data section.
2. Select a base metric (e.g. Spend).
3. Search for and select a calculated metric (e.g. ROAS, CTR, CPC).

Result: The chart displays two series. Because calculated metrics use a different scale than raw metrics, the chart may assign a secondary Y-axis automatically.

4. Add multiple calculated metrics

Compare several performance ratios on the same chart.

1. Open the Data section.
2. Search for and select two or more calculated metrics (e.g. ROAS and CTR).

Result: Each calculated metric renders as a separate series with ratio values, not raw sums.

Tip: If one series appears as a flat line near zero, both metrics share a Y-axis with very different scales. Switch to Tabbed view mode to inspect each series independently.

5. Break down by dimension

Split a single metric into one series per dimension value — useful for comparing performance across channels, campaigns, or advertisers.

1. Open the Data section in the Properties Panel.
2. Select a metric (e.g. Spend).
3. In the Dimensions picker, click a categorical field (e.g. Data Source Type, Campaign Name).

Result: The chart reloads showing one colored series per unique dimension value. The legend lists each value by name.

Choose visualization type

6. Switch a metric between bar and line

Control how each metric is rendered — as vertical bars or as a continuous line.

1. Open the Data section.
2. Find the metric in the Selected Metrics list.
3. Click Bar or Line next to the metric name to change the chart type for that series.

Result: Bar mode renders columns per time period. Line mode draws a continuous curve connecting data points. Both types can coexist on the same chart — for example, Spend as bars and ROAS as a line on a secondary axis.

7. Stack or group bars

Layer bars on top of each other to show totals, or place them side by side to compare individual values.

1. Open the Data section with at least two metrics selected.
2. Click the expand arrow on a metric row to open its options.
3. Under Bar Mode, click Stacked to layer bars, or Grouped to place them side by side.

Result: Stacked mode shows total contribution across metrics. Grouped mode makes individual values easier to compare directly.

Note: Bar Mode only appears when the metric visualization type is set to Bar.

8. Flip bar orientation

Switch between vertical columns and horizontal bars — useful when dimension labels are long.

1. Open the Properties Panel and ensure the chart includes at least one Bar metric.
2. Find the Bar Orientation selector in the Basics or Data section.
3. Select Vertical for upward-growing bars, or Horizontal for left-to-right bars.

Result: Horizontal orientation moves category labels to the Y-axis, making long dimension names easier to read.

9. Switch to combined or tabbed view

Display all metrics overlaid on a single chart area, or give each metric its own tab.

1. Open the Properties Panel and go to the Basics section.
2. Find the View Mode selector.
3. Select Combined to overlay all metrics on one chart.
4. Select Tabbed to show one metric at a time — tab buttons appear above the chart for switching between series.

Result: Combined mode is best for comparing trends side by side. Tabbed mode is helpful when metrics have very different scales that are difficult to visualize together.

Format the display

10. Show value labels on bars

Display exact numeric values directly on each bar so viewers can read data without hovering.

1. Open the Data section and click the expand arrow next to a metric to open its options.
2. Check Show value labels to enable per-bar numeric labels.
3. Set the Visibility dropdown to All to show a label on every bar. The default (Auto) hides labels automatically when the chart is too dense to display them all.
4. Uncheck Show value labels to remove the labels.

Note: Additional Visibility options — Hover, Ends, Min/Max, Every 2nd, Sparse — reduce visual clutter on charts with wide date ranges.

11. Format X-axis dates

Choose how date labels are displayed along the bottom axis of a time-series chart.

1. Open the Properties Panel and find the X-Axis or Appearance section.
2. Change the Date Format dropdown to one of the available options:
   • Oct 15 — abbreviated month name
   • October 15, 2025 — full month name
   • 10/15/2025 — numeric US format
   • 2025-10-15 — ISO 8601 format

Result: X-axis labels update immediately.

Note: Longer formats may cause labels to overlap on narrow charts or short date ranges.

12. Configure the Y-axis

Add a descriptive label to the Y-axis and control how tick values are formatted.

1. Open the Y-Axis (or Axes) section in the Properties Panel.
2. Type a label in the axis title input (e.g. Total Spend ($)).
3. Change the Format setting to match your data: Currency, Percentage, Number, or Custom.

Result: The Y-axis title appears alongside the axis. Tick values update to the chosen format (e.g. $1,000 for currency). The axis renders 5–12 tick labels depending on the data range and widget height.

13. Inspect values with the hover tooltip

Move the cursor over any data point to see a tooltip showing the date and metric value for that period.

1. Close the Properties Panel so the chart is fully visible.
2. Move the cursor over the chart area (not the axis labels).
3. Hover over a bar or line data point.

Result: A tooltip appears showing the date and metric value for that period (e.g. $2,084.47). Move the cursor across the chart to inspect different data points.

14. Toggle and position the legend

Show or hide the series legend, and choose where it appears relative to the chart area.

1. Open the Properties Panel and go to the Layout section.
2. Use the Show Legend toggle to show or hide the legend.
3. When the legend is visible, open the Legend Position dropdown and select Top, Bottom, Left, or Right.

Result: The legend moves to the selected position. Bottom is the default. Top placement is useful when the chart has limited vertical space.

Filter and limit data

15. Change period grouping

Aggregate time-series data by day, week, month, quarter, or year to control chart granularity.

1. Open the Filters section in the Properties Panel.
2. Find the Period Comparison dropdown (default: Daily).
3. Select a grouping: Daily, Weekly, Monthly, Quarterly, or Yearly.

Result: The chart re-fetches data and displays fewer, aggregated data points as the grouping gets coarser — for example, ~30 points for Daily vs ~4–5 for Weekly over a 30-day range.

Tip: Enable Show period toggle on chart (also in the Filters section) to let viewers switch the grouping directly on the published chart.

16. Set rows and series limits

Control how much data the chart fetches and how many dimension series are displayed at once.

1. Open the Filters section in the Properties Panel.
2. Set Rows Limit to control the total number of data rows fetched (e.g. 100, 365, 1000, 5000).
3. Set Series Limit to show only the top N dimension values (e.g. top 5 campaigns by spend).
4. Enable Show Others to add an Others series that aggregates all values beyond the series limit.

Result: With Series Limit set to 5 and Show Others enabled, the chart shows the top 5 series plus one Others series. This keeps the chart readable without hiding the aggregate impact of lower-ranked items.

Note: Series Limit and Show Others are only relevant when a dimension breakdown is active.

Custom SQL

17. Write and execute custom SQL

Replace the auto-generated query with your own SQL to calculate or filter data exactly as needed.

1. Open the Properties Panel and scroll to the Query section (the last accordion in the panel).
2. Click Write Custom SQL (or Customize Query if a query already exists).
3. Clear the editor and type your SQL. Use {schema}.{table} as the table reference and {where_date} for the date filter placeholder.
4. Wait a few seconds for the query to execute. The editor shows the number of rows returned.

Result: The widget displays data from your custom query. A Custom SQL indicator confirms that auto mode is off.

Note: The SQL editor has a 1-second debounce — the query runs shortly after you stop typing.

18. Custom SQL with dimension breakdown

Write SQL that returns a date column and a categorical dimension to create a multi-series chart colored by dimension value.

1. Open the Query section and click Write Custom SQL.
2. Write a query that returns a date, a dimension, and a metric. For example: SELECT toDate(date) as date, channel, SUM(spend) as spend FROM {table} WHERE 1=1{where_filters} GROUP BY date, channel ORDER BY date LIMIT 500
3. Wait for the query to execute and confirm the row count is greater than zero.
4. Open the Data section — the dimension column (e.g. channel) should appear automatically in the Dimensions area.

Result: The chart renders one colored series per unique dimension value, detected automatically from the SQL result columns.

19. Edit custom SQL and revert to auto

Modify an existing custom query, then discard the changes and return the widget to its auto-generated query.

1. Open the Query section and click Customize Query to see the current auto-generated SQL.
2. Edit the SQL (e.g. add LIMIT 1 at the end) and verify the widget updates.
3. Click Revert to Auto to discard the custom SQL and restore auto-generated mode.

Result: The SQL editor closes and the widget returns to its original auto-generated query and data.

20. Reset custom SQL to snapshot

Restore the SQL to the version captured when you first entered custom mode, without fully reverting to auto mode.

1. Open the Query section and click Customize Query. The auto-generated SQL is saved as a snapshot.
2. Modify the SQL (e.g. replace SUM(spend) with COUNT(*)) and verify the widget reflects the change.
3. Click Reset in the SQL editor to restore the snapshot.

Result: The SQL reverts to the snapshot version and the widget displays the original data again. Unlike Revert to Auto, Reset keeps the widget in custom SQL mode — it only undoes your edits.

21. Handle an invalid SQL query

The widget shows a clear error state when a query fails, without crashing the dashboard or other widgets.

1. Open the Query section and click Write Custom SQL.
2. Type invalid SQL (e.g. SELEKT * FORM nonexistent_table) and wait for the query to execute.
3. Observe the error state in the widget and Query section.
4. Replace the invalid SQL with a valid query and wait for it to execute.

Result: The widget shows an error indicator without crashing the dashboard. Replacing the SQL with a valid query clears the error and restores the widget data.