Purpose

This article covers building a widget from scratch using SQL, for cases where the widget library doesn't have what you need. It covers naming and describing the widget, defining its measure, adding filters, wiring it to the dashboard date range, choosing a visualization, mapping data to axes, setting display toggles, configuring drill-downs, and previewing/creating it.

Audience

• BI Analyst — primary author of custom widgets, writes the measure SQL and configures mapping.
  
• Admin — needs admin privileges to author dashboards/widgets at all.

The following video provides a quick walkthrough of this process.

Configuration

Open the widget builder

1. Click the + Create new widget button at the top of the widget library.
   
2. This opens the Create new widget side panel — the configuration form sits on the left, and a live preview renders on the right as soon as all required fields are filled. The form is long, so scroll within the panel to access all sections.

Widget identity

1. Enter a Widget name (required) — the label shown on the widget card. Keep it short and descriptive (e.g. "Offer Acceptance Rate %").
   
2. Enter a Widget description (required) — a one-line subtitle shown under the name, used to clarify the filter context (e.g. "for closed positions, filtered by hire date").
   
3. Optionally add a Metric Definition — a detailed, multi-sentence explanation of what the metric measures, what it includes, what it excludes, and any caveats. This only appears in the widget details panel when a viewer inspects the widget via the kebab menu — it isn't shown on the widget card itself.

Choose a dataset

1. Under Dataset, choose the dataset that holds your data. The dataset decides which columns you can use in the rest of the form.

Define the measure

1. Write the SQL expression that produces the metric — this is wrapped into the dataset query and executed against the underlying engine (StarRocks for native analytics).
   
2. End each measure with AS and a column alias (e.g. "SUM(is_hired) AS total_hires" or "COUNT(applicant_id) AS applicant_count").
   
3. Click + Add Measure to add multiple measures.
   
4. Note: aggregation is required — selecting a non-aggregated column without GROUP BY will fail validation.
5. For a Table widget, Define measure and Group by are optional. Leave them empty to list rows straight from the dataset. Then, under Columns, pick the columns the table shows, and use Add columns to add more. You can pick any dimension column in the dataset, plus any measure you defined.
6. A single measure or group-by expression can be up to 500 characters by default. A longer one shows a message that it "exceeds the maximum length of 500 characters". Eightfold support can raise the limit for your account if needed.

Add filters (optional)

1. Widget-level filters are optional — they're only needed when the metric requires a specific condition beyond dashboard-level filters (e.g. a "Hired Only" widget that should always exclude non-hire applications).
   
2. Each filter is a triple: Column, Operator, Value. Once a dataset is selected, every column it exposes is selectable as a filter target via the Column dropdown.
   
3. Choose an Operator from the full SQL set: =, !=, >, <, >=, <=, LIKE, IN, NOT IN, IS NULL, IS NOT NULL.
   
4. Set the Value — a single value for most operators, multi-select for IN/NOT IN, or no value needed for IS NULL/IS NOT NULL.
   
5. Click + Add filter to stack additional filters — all filters combine with AND/OR semantics (a row must satisfy every filter to be counted
   
6. Use widget-level filters for context that should never change (e.g. "Hired only"); use dashboard-level filters for context viewers may want to vary (e.g. business unit, date range).

Apply the date/time filter

1. This setting wires the widget into the dashboard's Date range pill — without it, the widget ignores the dashboard date range entirely.
   
2. The dropdown is dataset-driven and lists only columns of a date or timestamp type from the chosen dataset (e.g. application_ts, hired_ts, offer_ts, closed_at, creation_ts).
   
3. Choose the column that matches what the metric represents — e.g. anchor a "Total Hires" widget on hired_ts, and an "Open Applications" widget on application_ts, so the dashboard date range is interpreted correctly for each.

Choose a visualization type

1. Open the Visualization dropdown and pick from eight types:

Map the data

1. The fields shown depend on the visualization type — a Card has no axes, while Bar/Line/Area expose X-Axis, Y-Axis, and Group by.
2. Set X-Axis — the dimension along the horizontal axis (typically a date/time column for time-series, or a categorical column for comparisons).
3. Set Y-Axis — the measure values plotted vertically, usually the alias from the Define measure step.
4. Set Group by — the dimension that splits the visualization into series; required for Pie and Funnel, optional (producing stacked/multi-series output) for Bar/Line/Area.
5. A Pivot table maps its data differently — it uses Rows, Columns, and Values instead of axes. The Pivot Configuration section replaces the axis fields, and appears directly under the Visualization dropdown. See Configure the pivot grid below. The same field can appear in Values more than once, as long as each copy uses a different aggregation or Show values as option. For example, show a field as COUNT and as % of grand total side by side. The dropdowns leave out combinations already in use, so you can't add an exact duplicate.
6. A Combo (Bar + Line) widget plots one metric as bars on the left Y-axis and another as a line on a second Y-axis on the right. Each axis has its own scale, so a rate or percentage stays readable next to large counts. To map a combo chart:
   • Under Group by, choose the column to plot along the bottom, like a month or a source. A combo chart needs a Group by column. Until you pick one, the axis fields stay unavailable.
   • Under X-Axis, choose the Group by column.
   • Under Y-axis (Bar), choose the metric to draw as bars. Under Y-axis (Line), choose the metric to draw as a line. A metric picked for one axis isn't offered for the other. Put the larger-volume metric on the bars and the rate or percentage on the line.
   • Optional: under Split By (Line), choose a column to draw one line per value, like one line per source. Split By (Line) is available only when Y-axis (Line) has one metric.
   • Optional: under Order by, choose X-Axis or Y-Axis, then choose the sort direction. Sorting by Y-Axis orders the categories by the bar metric.
   • Optional: under Axis, enter an X-Axis Label, a Primary Y-Axis Label, and a Secondary Y-Axis Label. If you leave them blank, the X-axis and the left axis use the column name. If the line has more than one metric, the right axis has no title unless you enter one. With two scales, fill in both Y-axis labels so viewers know which axis belongs to which metric.
   • A combo chart is always vertical. It has no orientation setting.

Set display toggles

1. Adjust as needed — toggles that don't apply to the chosen visualization are hidden automatically:

Configure break-down

1. Open the Select break down dropdown and pick one or more dimensions.
   
2. Save the widget — a break-down chevron then appears on the widget click of the rendered dashboard.
   
3. When a viewer clicks on a breakdown option, the widget re-renders one level deeper using the break-down dimension.
   
4. Design tip: Break-down should follow a natural narrative, starting broad and narrowing down (e.g. source category → source → recruiter) rather than the reverse.

Preview and create

1. Check the Preview panel on the right — it stays empty until all required fields are filled, then updates live as the form is completed.
   
2. If the preview shows "No data available," confirm the dataset is correct, filters aren't over-restrictive, the date/time column has data in the active dashboard date range, and the measure SQL compiles.
   
3. Once the preview renders correctly, click Create — the widget is added to the widget library and can be dragged onto the canvas.
   
4. Note: Widgets created within this builder are globally scoped across all dashboards. Because the widget library functions cross-dashboard, you can seamlessly reuse any widget in other locations.