How to work with dashboard widgets

A widget presents one data slice on a dashboard. Its usefulness depends on a clear title, correct source, and shared filters.

This describes the prepared editor implementation. Persistence in the running environment and browser acceptance remain unverified; this document does not announce a release.

1. Choose one question per widget

A widget should answer one question, such as “how did revenue change by month?”. Do not combine unrelated measures in a single block.

2. Verify the source

Confirm that the related report or dataset contains the required fields and uses expected filters.

3. Use shared filters

Apply a dashboard filter to compare widgets in one period or segment. Different datasets require explicit glossary bindings. Exclusions need a reason; missing or ambiguous bindings block the query instead of silently disabling a condition.

4. Create or edit a widget

The dashboard owner selects an accessible dataset, fields, conditions, ordering, and row limit. Supported types are flat and pivot tables; line, area, bar, and pie charts; and metric cards. Preview is capped at 1000 rows, while a saved query is capped at 10,000; neither fetches all rows. Time axes support day granularity, and pivot tables use original values without coarser time bins.

Saving supports unambiguous root-dataset members only. Joined members, other time grains, and incompatible settings are rejected explicitly. Editing a shared definition cannot implicitly change its dataset or visualization group. Dashboard ownership does not replace definition-level rights.

When adding a placement to pinned filters, the current editor supports an explicit exclusion with a reason. Bindings can be configured afterward in filter settings; the exclusion is visible to viewers. Removing a placement preserves the definition and its other placements.

5. Create a report snapshot

In a saved report, select Create widget from report and choose an editable target dashboard. The snapshot uses applied settings, including unsaved changes, not filter drafts, result pagination, or selected rows. Source attribution is stored and the widget title links to the original report. Later report changes do not update the snapshot.

Segment comparisons, aggregated-measure filters, detail rows, partial sampling, reliability estimates, conditional formatting, and other unsupported settings are not silently dropped: creation is blocked with a reason. A report version number is not a saved revision ID.

Access and validation failures display a reason without replaying the write. After a lost response, reconcile first; retry only the same command after confirming that it was not committed. An unconfirmed write is not success.

Next step

Read working with dashboards to use widgets for regular monitoring.