> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cube.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Drill-through

> Let viewers click a chart's data on a published dashboard to open another dashboard filtered by what they clicked.

A drill-through links a chart to another dashboard in the same deployment. A viewer of the published dashboard clicks a bar, a point, a table cell or a map marker, chooses **Open in** and the target dashboard's title, and the target opens filtered by the values they clicked. Use it to build overview → detail flows from any chart, without defining [links on a dimension][ref-dimension-links] in the data model.

## Adding a drill-through

In the dashboard builder, open the chart's **⋮** menu and choose **Add drill-through**. A chart inside a stack, a grid or a tab gets the same item. The dialog lists every dashboard in the deployment that you can see, except the one you are editing, from A to Z by name. A chart never drills through to its own dashboard: [cross-filtering][ref-cross-filtering] already filters that dashboard by a clicked point, and adding such a drill-through through the Workbook Agent or the API is refused with that reason. A dashboard with a [slug][ref-slug] is shown as its slug in brackets followed by its name, such as `[order-details] · Order details`, and a dashboard without one by its name alone. Type in the search field to narrow the list by name or slug. Above the list, a note says what a target needs for this chart: "A target dashboard needs a slug and filters enabled for" followed by the titles of the chart's dimensions.

Picking a dashboard shows, below the list, what it needs for this chart: its **Slug**, which the drill-through stores, and an **Enable a filter for** box for each of the chart's dimensions that the target can't [take](#how-the-target-applies-the-values) yet through a placed [filter][ref-filter] or its [Dynamic controls][ref-dynamic-controls] widget. What you can do there depends on your access to the target:

* **You can edit the target, and it doesn't require [review][ref-reviews].** The slug is editable. A target without a slug gets one made from the first three words of its title, with `-2`, `-3` and so on added while another dashboard holds it. Every box starts checked. **Save** stays disabled while the slug is empty or a box is unchecked.
* **You can only view the target, or it requires review.** The slug and the boxes are read-only and show the target as it is: an empty slug when it has none, and the boxes unchecked. A warning names the target's owner, with their email, and asks you to have them set what is missing, such as "Ask Dana ([dana@example.com](mailto:dana@example.com)) to set a slug and enable filters for Status in this dashboard's settings." **Save** stays disabled until the target has a slug and takes every dimension; then it stores the drill-through and changes nothing on the target.

When you can edit the target, **Save** readies it first, in this order, and stores the drill-through only once every step succeeds:

1. A changed slug is saved, after the same checks as the **Slug** field in the target's dashboard options: see [Changing the target's slug](#changing-the-targets-slug). Cancelling there writes nothing to the target.
2. The checked dimensions are added to the filters the Dynamic controls widget in the target's draft allows. A draft without the widget gets one at its top.
3. The same change is published at once, as a new version of the target built from the version its viewers see now, so the target's other unpublished changes stay unpublished. The dialog says "Save publishes these filters on this dashboard. Its unpublished changes stay unpublished."

A target that was never published gets its slug and the draft change only, and the dialog says that viewers can open it from this chart once it is published. When a step fails, a message names what wasn't saved, the dialog stays open, and the drill-through isn't stored.

> [!WARNING]
>
> **Cancel** and **Esc** change nothing on the target. **Save** changes the target's slug and its published filters straight away, before you publish the dashboard you are editing, and **Undo** in the dashboard builder reverts only the chart's drill-through, not the target's slug or filters.

Once a chart has a drill-through, the item in its **⋮** menu reads **Edit drill-through**, and the chart's header shows the drill-through icon, with the tooltip "Drill-through enabled": click it to open the same dialog. The dialog opens on the stored target: pick another dashboard and press **Save** to replace it, or press **Remove** to delete the drill-through. **Cancel** or **Esc** closes the dialog and changes nothing; with text in the search field, the first **Esc** clears the search and the next closes the dialog. Storing, replacing and removing the drill-through are each one step that **Undo** reverts. Viewers get the change once you publish the dashboard.

When no dashboard holds the stored slug any more (its slug was changed or cleared, or it was deleted), the **Edit drill-through** dialog says so above the list and selects nothing: pick another dashboard, or remove the drill-through. When the stored slug is now the slug of the dashboard you are editing, for example after it [took over the slug](#changing-the-targets-slug), the dialog says that a chart can't drill through to the dashboard it is on, and **Save** stays disabled until you pick another dashboard.

Bar, line, area, scatter, pie and composite charts, maps and tables can have a drill-through: the chart types that can start a [cross-filter][ref-cross-filtering]. On a heatmap, box plot, funnel, KPI, Sankey or HTML chart the item is disabled, with the tooltip "This chart type doesn't support drill-through".

You can also ask the [Workbook Agent][ref-workbook-agent] in the dashboard builder to add a drill-through, for example *"when I click a bar on Orders by status, open the Order details dashboard"*, to remove one, or to tell you where a chart drills through to. The agent finds the target by its name. For a dashboard without a slug, it adds no drill-through and tells you to set a slug in that dashboard's settings first.

## Opening the target

On the published dashboard, a chart with a drill-through shows the drill-through icon when you hover the chart, with the tooltip "Drill-through enabled". It sits to the left of the chart's buttons that appear with it, since it only marks the chart: clicking it does nothing. On a touch screen, tap the chart to show them. Over the bars, points, lines, areas and slices of such a chart the pointer is a hand, as on a chart with cross-filtering on, even where the dashboard has cross-filtering off.

Clicking a data point of a chart with a drill-through opens a menu whose first item is **Open in** followed by the target dashboard's title, in a section of its own above **Drill down**, **Comment on this point** and the [cross-filter][ref-cross-filtering] items. The chart opens this menu even on a dashboard with cross-filtering off. Choose the item to open the target in the same tab; **Cmd**+click (macOS) or **Ctrl**+click (Windows and Linux) on it opens the target in a new tab. The browser's **Back** button returns to the dashboard you came from, with its controls and cross-filters as you left them.

The target opens with one [filter parameter][ref-url-params] for each dimension of the point you clicked:

* a bar, a line or area point, or a pie slice carries its category, plus its color or series value on a stacked, grouped or multi-series chart, and a scatter point carries every dimension it has;
* a table cell of a dimension column carries that value, and a cell of a measure column carries every dimension value in its row. In a pivot table, a value cell carries its row's and its column's values. A group row offers no **Open in** item;
* a map marker carries its row's dimension values, and a map region carries the region. A cluster of markers offers no **Open in** item.

Each value is an `is` filter, except a date shown at a granularity, which is a `between` filter over the period you clicked: the March 2024 bar of a monthly chart opens the target filtered from `2024-03-01T00:00:00.000` to `2024-03-31T23:59:59.999`. In a table, **Open in** comes after the links that the column's [data model][ref-dimension-links] defines.

Drill-through works on published dashboards in Cube and on [embedded dashboards][ref-embedding], with private and signed embedding alike. An embedded dashboard opens the embedded target, inside the embed. In a signed embed, the item always opens the target in the same tab, **Cmd**/**Ctrl**+click included. In the dashboard builder, the version history and a review's preview, a click on a chart does what it does on a chart with no drill-through.

The item is shown disabled, with a tooltip saying why, when it can't open the target:

| Item | Tooltip | When |
| - | - | - |
| **Open in …** | Loading the target dashboard | The target's title is still loading. The open menu shows the title as soon as it arrives. |
| **Open in** and the title | Drill-through doesn't apply to empty values | A value of the clicked point is empty (null). |
| **Open in dashboard** | You don't have access to the target dashboard | The viewer can't open the target. In a signed embed, also when signed embedding isn't allowed on the target. |
| **Open in dashboard** | The target dashboard isn't published or no longer exists | No published dashboard holds the slug. |
| **Open in dashboard** | Couldn't load the target dashboard | Any other error. |

The title is read from the slug when the dashboard opens, so once another dashboard takes over the slug, the item names and opens that dashboard.

## How the target applies the values

The target dashboard applies each value it arrives with, in this order:

1. To a placed [filter][ref-filter] on the same field.
2. To a placed filter on the same cube dimension in another semantic view, when that view includes the dimension once. The filter parameter in the URL is rewritten to that field.
3. To a filter added to the target's [Dynamic controls][ref-dynamic-controls] widget, when the widget allows filters on that field or, failing that, on the same cube dimension in another semantic view. The added filter shows the value, and the URL carries it as a `dc_` parameter.

A value that none of these take is dropped from the URL, and the dashboard shows the message "Unable to filter by" followed by the field's title, once for each such field. So does a value whose placed filter can't apply it: the filter's [visibility][ref-visibility] is **Disabled**, its **Allowed values** keep none of the value, or it can't take the value's condition, such as a [Top N][ref-top-n] value on a filter over a [calculated dimension][ref-calculated-dimensions]. The message names a calculated dimension by its title. To make a dashboard a good target, place a filter, or allow a dynamic filter, on every dimension of the charts that drill through to it.

The same applies to every link that opens a published dashboard with filter parameters, such as a `dashboard:` [link on a dimension][ref-dimension-links] or a link you write by hand. The target decides once, when it opens. [Downloads][ref-downloads], the print version, [dashboard deliveries][ref-dashboard-deliveries] and [alerts][ref-alerts] render the URL as it is, without these steps: a value that no control on the dashboard takes is left out, without a message. A download of a target you opened through a drill-through keeps the filters the drill-through added.

## Changing the target's slug

The dashboard builder warns you before you change or clear a slug that drill-throughs use. Changing it in the **Slug** field of the dashboard options opens a dialog listing the dashboards whose charts drill through to the slug, in their draft or published version. Dashboards you can't open are counted, not named. **Change anyway** saves the new slug: those drill-throughs then open no dashboard until someone edits them. **Keep current slug** leaves the slug as it is. A drill-through is never rewritten for you.

When you take over a slug another dashboard holds, the dialog says that the charts drilling through to that slug will then open your dashboard.

[ref-dimension-links]: https://docs.cube.dev/docs/data-modeling/dimensions.md#links

[ref-slug]: https://docs.cube.dev/docs/explore-analyze/dashboards#dashboard-slug

[ref-cross-filtering]: https://docs.cube.dev/docs/explore-analyze/dashboards/cross-filtering.md

[ref-url-params]: https://docs.cube.dev/docs/explore-analyze/dashboards/widgets/controls.md#sharing-the-current-selection

[ref-embedding]: https://docs.cube.dev/embedding/iframe/dashboards.md

[ref-filter]: https://docs.cube.dev/docs/explore-analyze/dashboards/widgets/controls.md#filter

[ref-dynamic-controls]: https://docs.cube.dev/docs/explore-analyze/dashboards/widgets/controls.md#dynamic-controls

[ref-reviews]: https://docs.cube.dev/docs/explore-analyze/dashboards/reviews.md

[ref-workbook-agent]: https://docs.cube.dev/docs/explore-analyze/workbooks/workbook-agent.md

[ref-visibility]: https://docs.cube.dev/docs/explore-analyze/dashboards/widgets/controls.md#visibility

[ref-top-n]: https://docs.cube.dev/docs/explore-analyze/dashboards/widgets/controls.md#top-n-and-bottom-n

[ref-calculated-dimensions]: https://docs.cube.dev/docs/explore-analyze/dashboards/widgets/controls.md#calculated-dimensions

[ref-downloads]: https://docs.cube.dev/docs/explore-analyze/dashboards#download-as-png-or-pdf

[ref-dashboard-deliveries]: https://docs.cube.dev/docs/explore-analyze/dashboard-deliveries.md

[ref-alerts]: https://docs.cube.dev/docs/explore-analyze/alerts.md


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.