cube-js · keydunov · Jun 3, 2026 · Jun 2, 2026 · Jun 2, 2026 · Jun 2, 2026
@@ -61,7 +61,7 @@ them together.
 
 When a chart is attached, the agent receives a read-only snapshot of it — the
 underlying SQL, the data, and the chart spec — along with the dashboard's
-**current filter and time-grain state**. It uses this as context; it does not
+**current filter and time-granularity state**. It uses this as context; it does not
 modify any of it.
 
 ## What the Dashboard Agent can and can't do
@@ -81,7 +81,7 @@ The published Dashboard Agent is **read-only by design**.
 **It can't:**
 
 - Edit the dashboard, or add/remove widgets
-- Change filters or the time grain (see [Limitations](#limitations))
+- Change filters or the time granularity (see [Limitations](#limitations))
 - Create reports or workbooks
 - Change the data model
 
@@ -99,7 +99,7 @@ contents — text, PDF, ZIP, and image files are supported.
 
 ## Limitations
 
-- **Filters are read-only.** The agent can tell you which filters and time grain
+- **Filters are read-only.** The agent can tell you which filters and time granularity
   are currently applied and reason about them, but it **cannot change them** for
   you yet. This is the most common expectation gap — if you ask the agent to
   "filter the dashboard to last quarter," it will explain the current state

@@ -13,7 +13,7 @@ If the picker is empty, create the report first in a workbook tab — only publi
 
 ## Interaction with controls
 
-Charts respect [controls][ref-controls] — filters and time grain switchers — placed on the same dashboard. A single control can drive multiple charts at once: its value is applied to every chart whose query references the targeted dimension.
+Charts respect [controls][ref-controls] — filters and time granularity switchers — placed on the same dashboard. A single control can drive multiple charts at once: its value is applied to every chart whose query references the targeted dimension.
 
 ## Updating charts
 

@@ -1,16 +1,16 @@
 ---
 title: Controls
-description: Filter and time grain switcher widgets that let dashboard viewers change what's shown on the dashboard.
+description: Filter and time granularity switcher widgets that let dashboard viewers change what's shown on the dashboard.
 ---
 
 Controls are widgets that let dashboard viewers change what's shown without leaving the dashboard. The dashboard builder offers two control types — both target a dimension from your semantic model and apply the selected value to every [chart][ref-charts] on the dashboard whose query references that dimension.
 
 - [Filter](#filter) — Narrow the data shown on the dashboard
-- [Time grain switcher](#time-grain-switcher) — Change the granularity of time-based dimensions
+- [Time granularity switcher](#time-granularity-switcher) — Change the granularity of time-based dimensions
 
 ## Filter
 
-Filter widgets let viewers narrow down the data shown on the dashboard. In the [dashboard builder][ref-workbooks], click **Add Filter** in the toolbar. The new filter is added in an unconfigured state — click **Configure Filter** (or open the widget's settings menu) to pick a semantic view and a dimension.
+Filter widgets let viewers narrow down the data shown on the dashboard. In the [dashboard builder][ref-workbooks], click **Filter** under **Add Controls** in the toolbar. The new filter is added in an unconfigured state — click **Configure Filter** (or open the widget's settings menu) to pick a semantic view and a dimension.
 
 ### Operators by dimension type
 
@@ -74,27 +74,27 @@ When multiple filters target dimensions from the same semantic view, you can mar
 
 For example, on a sales dashboard with a **Country** filter and a **City** filter, marking both as faceted means selecting `United States` in the Country filter limits the City filter to U.S. cities only.
 
-## Time grain switcher
+## Time granularity switcher
 
-Time grain switchers let viewers change the granularity of time-based dimensions on the dashboard — for example, switching a revenue chart from daily to weekly or monthly. The widget targets a single time dimension and applies the chosen [granularity][ref-granularities] to every chart that groups by that dimension.
+Time granularity switchers let viewers change the granularity of time-based dimensions on the dashboard — for example, switching a revenue chart from daily to weekly or monthly. The widget targets a single time dimension and applies the chosen [granularity][ref-granularities] to every chart that groups by that dimension.
 
-In the [dashboard builder][ref-workbooks], click **Add Time Grain** in the toolbar. The new switcher is added in an unconfigured state — open its settings to pick a semantic view and a time dimension.
+In the [dashboard builder][ref-workbooks], click **Time Granularity** under **Add Controls** in the toolbar. The new switcher is added in an unconfigured state — open its settings to pick a semantic view and a time dimension.
 
-### Allowed grains
+### Allowed granularities
 
-By default, viewers can choose between **day**, **week**, **month**, **quarter**, and **year**. You can narrow this list in the widget's settings to only expose the grains that make sense for the dashboard.
+By default, viewers can choose between **day**, **week**, **month**, **quarter**, and **year**. You can narrow this list in the widget's settings to only expose the granularities that make sense for the dashboard.
 
-For time dimensions backed by a `TIMESTAMP` or `DATETIME` column, sub-day grains (**second**, **minute**, **hour**) are also available. `DATE`-typed columns don't expose sub-day grains, since they would bucket the entire day into a single point.
+For time dimensions backed by a `TIMESTAMP` or `DATETIME` column, sub-day granularities (**second**, **minute**, **hour**) are also available. `DATE`-typed columns don't expose sub-day granularities, since they would bucket the entire day into a single point.
 
-Custom granularities defined in the [data model][ref-granularities] appear in the list alongside the built-in grains.
+Custom granularities defined in the [data model][ref-granularities] appear in the list alongside the built-in granularities.
 
-### Default grain
+### Default granularity
 
-You can configure a default grain that's applied when the dashboard loads. If no default is set, charts use the grain that was saved on the underlying report — viewers can still switch grains, but the dashboard opens with each chart at its original granularity.
+You can configure a default granularity that's applied when the dashboard loads. If no default is set, charts use the granularity that was saved on the underlying report — viewers can still switch granularities, but the dashboard opens with each chart at its original granularity.
 
 ## Visibility
 
-Each control has a **Visibility** setting that determines how it appears on the published dashboard. The setting applies to both filters and time grain switchers.
+Each control has a **Visibility** setting that determines how it appears on the published dashboard. The setting applies to both filters and time granularity switchers.
 
 | Visibility | Behavior on the published dashboard |
 |---|---|
@@ -125,11 +125,11 @@ Three states show up in the mapping sidebar:
 | **Manually mapped** | You (or an AI agent) picked a specific dimension for this chart. **Reset** restores the automatic mapping. |
 | **Can't map automatically** | The control targets a dimension that doesn't exist on the chart's semantic view. The chart is unaffected by the control until you map it manually. |
 
-For [time grain switchers][ref-time-grain], the dimension picker is restricted to time-typed dimensions on the chart's semantic view, since other dimension types can't be resolved by the time grain pipeline.
+For [time granularity switchers][ref-time-grain], the dimension picker is restricted to time-typed dimensions on the chart's semantic view, since other dimension types can't be resolved by the time granularity pipeline.
 
 Mappings are also configurable by AI agents when they build or edit a dashboard, so an agent can wire controls across charts that use different semantic views without you needing to revisit each chart manually.
 
-[ref-time-grain]: #time-grain-switcher
+[ref-time-grain]: #time-granularity-switcher
 
 [ref-workbooks]: /docs/explore-analyze/workbooks
 [ref-charts]: /docs/explore-analyze/dashboards/widgets/charts

@@ -11,9 +11,9 @@ The dashboard builder supports the following widget types:
 
 - [Charts](/docs/explore-analyze/dashboards/widgets/charts) — Visualize reports from your workbook
 - [Text](/docs/explore-analyze/dashboards/widgets/text) — Add titles, descriptions, and rich formatting in Markdown
-- [Controls](/docs/explore-analyze/dashboards/widgets/controls) — Let viewers filter the data or switch the time grain
+- [Controls](/docs/explore-analyze/dashboards/widgets/controls) — Let viewers filter the data or switch the time granularity
 - [AI summary](/docs/explore-analyze/dashboards/widgets/ai-summary) — Generate narrative summaries of dashboard data on demand
 
-In the dashboard builder, add widgets using the toolbar at the top of the canvas: pick reports from the **Charts** picker to add charts, or click **Add Text**, **Add Filter**, **Add Time Grain**, or **Add AI Summary** for the other types.
+In the dashboard builder, add widgets using the toolbar at the top of the canvas: pick reports from the **Charts** picker to add charts, click **Add Text** or **Add AI Summary**, or add a **Filter** or **Time Granularity** control from the **Add Controls** group.
 
 [ref-workbooks]: /docs/explore-analyze/workbooks