> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/operate-and-monitor/create-a-custom-dashboard/dashboard.md).

# Dashboard

The dashboard object: scopes, sections, cards, charts, filters, and transformations.

## Your goal

Understand the dashboard structure well enough to lay one out deliberately - and to work in advanced mode when the interface cannot do what you need.

## The object model

A dashboard is a **DashboardRegistration**: a title, **scopes**, and a **DashboardContent**. The content is composed of **sections** and **cards**, and cards organise **charts**.

```mermaid
flowchart TD
    D["Dashboard<br/>title, scopes"]
    C["DashboardContent"]
    S1["Section<br/>title + grid of cards"]
    S2["Section"]
    CA1["Card"]
    CA2["Card"]
    CH1["Chart"]
    CH2["Chart"]
    D --> C
    C --> S1
    C --> S2
    S1 --> CA1
    S1 --> CA2
    CA1 --> CH1
    CA1 --> CH2
```

## Scopes: where a dashboard appears

| Scope      | Where it displays                                                                             |
| ---------- | --------------------------------------------------------------------------------------------- |
| `home`     | The datamart's home page.                                                                     |
| `segments` | The segments page - all segments, or a specific set with segment IDs in `segment_ids`.        |
| `builders` | Standard segment builders - all of them, or a specific set with builder IDs in `builder_ids`. |

You can have **several dashboards at the same scope**. When you do, tabs are created to switch between them; with a single dashboard there are no tabs.

{% hint style="success" %}
**Prefer several dashboards to one big one.** It prevents too many requests being executed simultaneously - which is the usual cause of a dashboard that feels slow.
{% endhint %}

## Sections and cards

Each **section** has a title and cards arranged on a grid. Each **card** is a white block organising charts horizontally or vertically.

The grid is **12 columns wide**, with as many rows as needed. Size and position come from four properties:

| Property | Meaning                                                    |
| -------- | ---------------------------------------------------------- |
| `h`      | The number of rows the card takes.                         |
| `w`      | The number of columns the card takes.                      |
| `x`, `y` | The coordinates of the card's top-left corner on the grid. |

So a full-width card is `w: 12`, and two side-by-side cards are `w: 6` with `x: 0` and `x: 6`.

## Charts

Each chart has a title, a type, a dataset, and optionally colours and options.

```json
{
    "title": "Device form factors",
    "type": "Bars",
    "dataset": {
        "type": "OTQL",
        "query_id": "50171"
    },
    "options": {}
}
```

| Field     | Notes                                                                                       |
| --------- | ------------------------------------------------------------------------------------------- |
| `title`   | Can be an empty string.                                                                     |
| `type`    | `Bars`, `Pie`, `Metric`, or `Radar`.                                                        |
| `dataset` | The data source - an OTQL query referenced by `query_id`, or an activities analytics query. |
| `options` | Depends on the chart type.                                                                  |

{% hint style="info" %}
A chart's dataset references a **saved query by ID**, which is why the Query API asks you to save queries. See [Query API](/setup-and-monitor/operate-and-monitor/query-your-datamart/query-api.md#when-a-query-has-to-be-saved).
{% endhint %}

<details>

<summary>Options for a <code>Bars</code> chart</summary>

```json
"options": {
    "legend": {
        "enabled": false,          // Show or hide the legend. Defaults to FALSE.
        "position": "bottom"       // "bottom" or "right". Defaults to "bottom".
    },
    "colors": [],                  // Defaults to the current theme colours
    "format": "count",             // "count", "percentage", or "index".
                                   // Pass percentage or index when the dataset comes from
                                   // the matching transformation, to adapt labels and tooltips.
    "drilldown": false,            // Enables drill down if the dataset is compatible. Defaults to FALSE.
    "stacking": false,             // Enables stacking if the dataset is compatible.
                                   // Takes priority over drilldown. Defaults to FALSE.
    "type": "column",              // "bar" for horizontal bars, "column" for vertical. Defaults to "column".
    "plot_line_value": 0,          // Draws a line at the specified value
    "hide_x_axis": false,
    "hide_y_axis": false,
    "tooltip": { "format": "" },   // Defaults to "{point.y}", or "{point.y}% ({point.count})"
                                   // when the dataset has a count field
    "big_bars": true               // TRUE for large bars close together, FALSE for smaller,
                                   // more spaced bars. Defaults to TRUE.
}
```

`Area`, `Pie`, `Metric`, and `Radar` charts have their own option sets, following the same pattern.

</details>

## Working in advanced mode

{% stepper %}
{% step %}

### Save the query as a technical query

Run it in the [Query Tool](/setup-and-monitor/operate-and-monitor/query-your-datamart/query-tool.md) and save it as a **technical query**. Note the query ID.
{% endstep %}

{% step %}

### Open the dashboard

In the Computing Console, go to **Dashboards** and add or edit a dashboard. Choose a name and save.
{% endstep %}

{% step %}

### Switch to the Advanced tab

Edit the JSON - the whole `DashboardContent` for the dashboard, or a single chart from that chart's own advanced tab, where you can preview your changes.
{% endstep %}
{% endstepper %}

{% hint style="success" %}
**Cloning a dashboard:** open the one you want to clone, go to its **Advanced** tab and copy the whole JSON; create a new dashboard, open its Advanced tab, and paste. Then keep editing in either mode.
{% endhint %}

## Filters

A dashboard can have **filters in the top action bar** - a compartment or channel selector, for example. The user picks a value and every query in the dashboard adapts to it.

Filters can only be set up **in advanced mode**, through the `available_filters` property of the `DashboardContent`.

```json5
{
    // Using technical names of compartments, segments or channels
    // results in IDs being replaced by names in the interface
    "technical_name": "String",
    "title": "String",
    "values_retrieve_method": "Query",   // The only available value at the moment
    // An OTQL query returning the list of selectable values.
    // Use a query string here, not a query ID.
    "values_query": "String",
    // How each query in the dashboard adapts to the selected value(s)
    "query_fragments": [],
    "multi_select": false
}
```

{% hint style="info" %}
Note the asymmetry: a **chart** dataset references a saved query **by ID**, while a **filter** takes a query **string**.
{% endhint %}

## Transformations

Transformations reshape a dataset before it is charted. The available ones:

| Transformation   | What it does                                                                                                                                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `to-list`        | Turns a result into a list.                                                                                                                                                                            |
| `join`           | Combines datasets.                                                                                                                                                                                     |
| `to-percentages` | Converts values to percentages.                                                                                                                                                                        |
| `ratio`          | Calculates a ratio between values.                                                                                                                                                                     |
| `index`          | Produces an index - the basis of audience comparison charts.                                                                                                                                           |
| `format-dates`   | Formats date keys.                                                                                                                                                                                     |
| `reduce`         | Reduces a series to a single value - for instance to display a `@cardinality` query as a metric.                                                                                                       |
| `get-decorators` | Resolves [schema decorators](/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/schema-definition.md#decorators-changing-how-the-schema-reads) so labels read properly. |

Worked uses are in [Dashboard cookbook](/setup-and-monitor/operate-and-monitor/create-a-custom-dashboard/dashboard-cookbook.md).

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Create a custom dashboard</strong></td><td>The workflow, and the advanced-mode caveat.</td><td><a href="/setup-and-monitor/operate-and-monitor/create-a-custom-dashboard.md">Create a custom dashboard</a></td></tr><tr><td><strong>Dashboard cookbook</strong></td><td>Recipes for the common shapes.</td><td><a href="/setup-and-monitor/operate-and-monitor/create-a-custom-dashboard/dashboard-cookbook.md">Dashboard cookbook</a></td></tr><tr><td><strong>Query API</strong></td><td>Saving the queries a chart references.</td><td><a href="/setup-and-monitor/operate-and-monitor/query-your-datamart/query-api.md">Query API</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/setup-and-monitor/operate-and-monitor/create-a-custom-dashboard/dashboard.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.