> For the complete documentation index, see [llms.txt](https://help.branch.io/llms.txt).

# Custom Dimensions (New)

> Create custom dimensions in Branch Analysis to group values from your data into your own categories.

## Overview

Custom dimensions let you create your own groupings and categories from existing data in your Branch widgets. By defining conditional logic, you can combine values from one or more columns into meaningful groups that reflect how your team thinks about your data.

You create custom dimensions at the widget level. They're especially useful when the default columns available in your data source don't capture the exact breakdown you need. For example, you can group creative IDs from different ad partners into a single category, or bucket campaigns by theme regardless of naming conventions.

To learn more about Analysis dashboards, widgets, and data sources, read our [Dashboards Overview](https://help.branch.io/marketer-hub/analysis-dashboards-overview-new.md) and [Analysis Data Sources Reference](https://help.branch.io/marketer-hub/analysis-data-sources-new.md) articles.

> **Attention**
>
> Branch's new experience is rolling out in phases, so your interface may differ. This article covers the Analysis page in the new experience. To learn more, see [New Branch Overview](https://help.branch.io/account-hub/new-branch-overview.md).

## Key terms

This guide uses the following terms.

| Term | Definition |
| --- | --- |
| Custom dimension | A user-defined grouping of values from one or more existing columns. Custom dimensions let you create new categories by combining or re-labeling data using conditional logic. |
| Column set | A set based on a single column's data. You define groups by selecting specific values from that column. |
| Query set | A set based on a query that uses one or more columns of data. You define groups using conditions across multiple columns. |
| Group | An individual category within a custom dimension. Each group contains the values or conditions that define it. |

## Types of custom dimensions

Analysis has two types of custom dimensions, column sets and query sets. You create both in the widget editor.

### Column sets

A column set groups values from a single column into custom categories. This is the simplest type of custom dimension and is ideal when you want to re-label or consolidate values within one field.

For example, you could use the **Branch Channel** column and create a group for paid channels and a separate group for organic channels.

### Query sets

A query set groups data using conditions across multiple columns. This is more powerful than a column set and is useful when your grouping logic depends on more than one dimension.

For example, you could select **OS**, **Feature**, and **Campaign Name** as your base query, then create a group where **OS** = Android, **Feature** = paid advertising, and **Campaign Name** = spring_solstice.

## Create a custom dimension

To add or edit custom dimensions, you need edit access to the dashboard. The **Edit** and **Add new widget** options appear only when dashboard editing is turned on for your account.

To create a custom dimension:

1. Navigate to the dashboard containing the widget you want to add a custom dimension to.
2. Select **Add new widget**, or edit an existing widget.
3. Select **+ Add**.
4. Select **Column set** or **Query set** depending on your needs.
5. For a column set, select the base column you want to group values from. For a query set, select all the columns your conditions will reference.
6. Under **Columns**, give the default group a descriptive name that reflects the values it contains. Or select **+ Add group** to add a new one.
7. Define the group. For a column set, select or enter the values to include. For a query set, enter the conditions.
8. Add more groups as needed by repeating steps 6–7.
9. (Optional) Create a final group to capture all remaining values that don't match your other groups (for example, "Other" or "Miscellaneous").
10. Name the custom dimension under **Set name**.
11. (Optional) Add a note describing its purpose under **Set description**.
12. Select **Go** to run the data for your widget.
13. For a new widget, select **Pin** to add it to your dashboard. For an existing widget, select **Save**.

## Edit a custom dimension

To edit an existing custom dimension:

1. Navigate to the dashboard containing the widget with the custom dimension you want to edit.
2. Hover over the widget and select the **three-dot icon** that appears.
3. Select **Edit**.
4. In the **Columns** section, expand **Sets** and find your custom dimension.
5. Select the custom dimension to open its configuration. From here, you can add, remove, or rename groups, and update the values or conditions within each group.
6. When you're finished, select **Go** to refresh the data, then select **Save**.

## Delete a custom dimension

> **Warning**
>
> Deleting a custom dimension removes it from the widget permanently. You can't undo this action.

To delete a custom dimension:

1. Navigate to the dashboard containing the widget with the custom dimension.
2. Hover over the widget and select the **three-dot icon**, then select **Edit**.
3. In the **Columns** section, expand **Sets** and find the custom dimension you want to delete.
4. Hover over the custom dimension and select the **X icon** to remove it.
5. Select **Save** to confirm your changes.

## Use cases

Custom dimensions are flexible and support a wide range of reporting scenarios. Below are common use cases to help you get started.

### Creative-level reporting

One of the most impactful uses of custom dimensions is creative-level reporting. Marketers frequently run the same creative asset across multiple ad partners, but each partner assigns its own creative ID and may store different creative names. That makes a simple question hard to answer. How is this creative performing across all my campaigns?

Custom dimensions solve this by letting you define groups that map different creative IDs back to a single creative concept.

#### The problem

Imagine you're running the same ad image across three ad partners. Each partner generates a unique creative ID when you upload the asset, and your team may have used slightly different naming conventions for the creative name across each platform.

Without custom dimensions, you'd need to manually look up and add together the performance metrics for each of these separate entries. With dozens of creatives and partners, this becomes impractical.

#### The solution

Using a column set based on the **Creative Id** column, you can group all the IDs that correspond to the same visual creative into a single category. To do this:

1. Create or edit a widget.
2. Select **+ Add**, select **Column set**, and choose **Creative Id** as the base column.
3. Create a group for one creative, and select all the creative IDs from different ad partners that belong to it. For example, name the group "3-Day Trial Red Creative."
4. Repeat for each creative you want to track.
5. (Optional) Add a catch-all group called "Other Creatives" for everything else.
6. Name the custom dimension, such as "My Creative Sets," and then select **Go**.
7. Add a measure such as **Click**, **Install**, or **Revenue** alongside your new custom dimension to see aggregated performance by creative.

Your widget now displays a single row per creative group with the combined metrics from all matching IDs, regardless of which ad partner they came from. This gives you the unified view you need to compare creative performance and make optimization decisions.

> **Tip**
>
> If you need to update which creative IDs belong to a group, edit the custom dimension and add the new IDs. For example, you might do this when you launch on a new ad partner. The widget reflects the updated grouping the next time you run it.

### Channel grouping

Use a column set based on **Branch Channel** to group your channels into high-level categories, such as "Paid" and "Organic." This simplifies reporting when you want to compare paid versus organic performance at a glance without drilling into individual channels.

### Campaign theming

Use a query set to group campaigns by theme or initiative. For example, create a group that captures all campaigns where **Campaign Name** contains "spring" and **Feature** is "paid advertising," and another group for "summer" campaigns. This lets you compare seasonal performance across ad partners and channels.

### Platform-specific reporting

Use a query set that combines **OS** and **Feature** conditions to create groups such as "Android Paid," "Android Organic," "iOS Paid," and "iOS Organic." This is useful for understanding how platform and acquisition source interact in driving performance.

## Best practices

These practices keep your custom dimensions easy for your team to read and keep up to date.

- **Use descriptive names**: Name your custom dimensions and groups clearly, so teammates can understand the logic without opening the configuration.
- **Add a description**: When you create a custom dimension, use **Set description** to record what it tracks and why. For example, "Tracking Q1 creative performance across Moloco, Snap, and Facebook."
- **Include a catch-all group**: An "Other" or "Miscellaneous" group makes sure all your data is counted and avoids missing values in your widget.
- **Keep groupings updated**: When you add a new ad partner or launch a new campaign, update your custom dimensions with the new IDs or values.
- **Start simple**: Begin with column sets for straightforward groupings. Move to query sets only when your logic needs conditions across multiple columns.

## FAQ

> **What is a custom dimension?**
>
> A custom dimension is a user-defined grouping of values from one or more existing columns. It lets you create new categories by combining or re-labeling data using conditional logic.

> **What is the difference between a column set and a query set?**
>
> A column set groups values from a single column. A query set groups data using conditions across multiple columns. Use column sets for simple re-labeling and query sets for more complex, multi-column logic.

> **Can I use a custom dimension across multiple widgets?**
>
> You define custom dimensions at the widget level. To use the same custom dimension in another widget, recreate it there. If dashboard editing is turned on for your account, you can also copy the widget to another dashboard, and the custom dimension is included.

> **Can I use custom dimensions with Ivy?**
>
> Yes, when you prompt Ivy from the widget itself. Ivy then uses the widget's custom dimension as context for its answers, and you can ask Ivy to break down data using your custom groups. The **Ivy** button on a widget appears only when it's turned on for your account.
>
> The **Ask Ivy** box at the top of a dashboard doesn't use custom dimensions. To learn more about Ivy, read the AI section of our [Dashboards Overview](https://help.branch.io/marketer-hub/analysis-dashboards-overview-new.md#ai) article.

> **Which data sources support custom dimensions?**
>
> You can create custom dimensions using columns from any data source you see in Analysis. The available columns depend on which data source your widget is using. For the list of data sources, see the [Analysis Data Sources Reference](https://help.branch.io/marketer-hub/analysis-data-sources-new.md).