When you create custom dimensions and metrics inside the Dataset tool (Data Cloud → Datasets), those fields can be made available for use in Template Builder widgets. For custom metrics, they will appear directly once defined. For custom dimensions, you must connect your widget to a Dataset View in order for them to surface in the widget inspector — see Why Custom Dimensions Require a Dataset View below.

How Dataset Custom Columns Appear in the Widget Inspector

When a widget is connected to a Dataset data source, the dimensions and metrics available in the widget inspector come directly from the columns defined in that Dataset — including any custom columns you've created.

Custom columns created in the Dataset tool surface in the widget inspector as follows:

📘

Note: Dataset-sourced custom columns do not automatically appear as Aggregate or Custom dimensions/metrics in the Template Builder. They will only be listed under their specific Dataset source header in the widget inspector — the same way native provider fields appear under their source. Note that platform-level Aggregate dimensions (such as Month of Year, Week of Year) will still appear in the inspector alongside your Dataset's Simple columns — these are standard Template Builder dimensions, not Dataset-specific fields.

Why Custom Dimensions Require a Dataset View

Custom dimensions from a Dataset — including those you can see in the Dataset explorer — will not appear as selectable options in the Template Builder unless you connect the widget to a Dataset View (not the parent Dataset directly).

This applies even if you have created custom dimension columns inside the Dataset tool and can see them in the dataset explorer. It also applies to provider-native dimensions (like Facebook Ads breakdown dimensions such as Age, Gender, or Placement) that appear in the dataset but not in the widget inspector.

Why this happens: When the Template Builder loads fields for a widget, it runs a three-tier resolution waterfall (computePreviewFieldsForDataset()):

1. Tier 1: Looks for schema annotations tagged DIM or MET. Only trusted if ≥80% of fields are annotated. Raw provider Datasets (like Facebook Ads) do NOT have these — they fail this gate.
2. Tier 2: Looks for an explicit dimensions[] array in the Dataset's json_definition record. Parent Datasets typically don't have this populated.
3. Tier 3 (fallback): Returns { dimensions: [], metrics: [] } — nothing shows up.

A Dataset View fixes this because the View editor explicitly writes the annotated schema and a curated dimensions[] list when you save it.

This also explains the asymmetry: custom metrics work without a View because they use a formula string evaluated at query time. Custom dimensions use provider field ID references (inputs[]) that must be resolved from the properly annotated schema, which only a View provides.

The fix: create a Dataset View

• Go to Data Cloud → Datasets and open your Dataset.
• Click the + icon or "Create a view" to create a new View.
• In the View editor, use the Columns selector to include the dimensions you want to expose — including any custom dimension columns you've created.
• Give the View a name and click Save View.
• Back in the Template Builder, connect your widget to the View (not the parent Dataset) — the dimensions will now appear in the widget inspector.

📘

Note: You do not need to include every column from the parent Dataset in your View — only the ones you want available in the Template Builder. If you need different combinations of dimensions, you can create multiple Views from the same Dataset.

How Dataset Views Interact with the Template Builder

Dataset Views let you pre-aggregate and reorganize a Dataset before it reaches the Template Builder. When you connect a widget to a View instead of the base Dataset, the behavior changes in a few important ways:

• Only the columns included in the View will appear in the widget inspector. Columns excluded from the View will not be selectable.
• Aggregation is pre-applied. The View has already grouped and aggregated the data (e.g., SUM of spend, COUNT DISTINCT of users). The Template Builder will query the View's result set — it does not re-aggregate raw rows.
• Date granularity is fixed by the View's dimensions. If your View does not include a date dimension, the Template Builder cannot break results down by date — it will show a single aggregated value for whatever date range is selected.

📘

Note: if a View's columns are not fully annotated in the Dataset tool, the Template Builder may fall back to the parent Dataset's field definitions, which could display fields not actually available in the View.

❗️

Important: If your View pre-sums a metric like Impressions, and you then select a SUM aggregation in the widget inspector as well, you are not double-counting — the widget is simply summing the already-aggregated View output. However, if your View pre-applies a ratio or average (e.g., average CTR), summing that field will produce incorrect results. In those cases, the aggregation function must be corrected at the Dataset column definition level (in the Dataset tool's column editor), not in the widget inspector. The widget inspector does not offer an aggregation override for Dataset-backed metrics — the aggregation type is fixed when the column is defined.

⚠️

Facebook Ads Dataset users: Facebook Ads datasets often contain many breakdown dimensions (Age, Gender, Placement, Region, etc.) that are visible in the Dataset explorer but will not appear in the Template Builder widget inspector when connecting directly to the parent Dataset. This is expected behavior — it is a hardcoded backend limitation (the dimensions[] array is always empty for Facebook datasets at the API level). Creating a Dataset View is the only supported path to use these dimensions in the Template Builder. This same limitation applies to Snowflake Share, S3, FTP, and Adobe Analytics datasets.

Aggregation Conflicts: Dataset Level vs. Widget Level

One of the most common sources of confusion when working with Dataset-backed widgets is the interaction between Dataset-level aggregation and widget-level aggregation settings.

Here's how to think about the two layers:

Layer 1 — Dataset ingestion or View aggregation Data is stored or pre-aggregated at this level. For example, a Dataset might store daily Impressions per Campaign. A View might further aggregate this to total Impressions per Campaign (removing the date dimension).

Layer 2 — Widget inspector aggregation When you add a metric to a widget, the Template Builder applies a second aggregation across the rows returned from the Dataset or View for the selected date range.

What This Means in Practice

⚠️

Warning: The Template Builder does not detect or warn about aggregation mismatches on View-backed metrics. It is the dataset author's responsibility to correctly annotate View columns and communicate their aggregation semantics to report builders.

💡

Best Practice: For derived metrics like CTR, CPC, or ROAS that are computed as ratios, it is generally better to not pre-aggregate them in a View. Instead, bring the raw numerator and denominator columns into the widget and use the Template Builder's Custom Metric formula builder to compute the ratio at display time.

Using Dataset Custom Metrics in the Template Builder's Formula Builder

Yes — custom metric columns created in the Dataset tool can be used in the Template Builder's Custom Metric formula builder.

Here's how:

1. Open a widget connected to your Dataset data source
2. Navigate to the Metrics section of the widget inspector
3. Click + Add Metric → select Custom
4. In the Custom Metric formula builder, browse available fields from your Dataset source — this includes any custom columns you created via column combine, extraction, calculation, or SQL Expression

📘

Note: The formula builder's available inputs are the same fields visible in the widget's Metrics list — not a separate field picker. A field must be a metric-type column (not a dimension) to appear as a formula input.

Limitations to Be Aware Of

• Pre-aggregated View columns are available in the formula builder, but remember that they are already aggregated — performing further ratio calculations on pre-summed metrics works correctly, but dividing two pre-averaged fields does not.
• SQL Expression columns defined as dimensions (text/date type) are available as dimensions in the widget inspector (not as metric formula inputs) — but only when the widget is connected to a Dataset View that includes those columns. They will not appear if the widget is connected to the parent Dataset directly.
• If a custom column name contains special characters or spaces, it will still appear in the formula builder — but confirm it displays correctly in the widget output after saving.

Related Articles

• Dimensions and Metrics — Overview of Simple, Aggregate, and Custom dims/metrics in the Template Builder
• Configuring a Data Widget — Step-by-step for adding custom dims/metrics to widgets
• Dataset Exploration, Organization & Transformation — How to create custom columns in the Dataset tool
• Create New Data Columns with SQL Expressions — Advanced SQL-based column creation
• Control Metric Aggregation with Views — How Dataset Views pre-aggregate data before the Template Builder
• Understanding Unique Metrics and Dataset Discrepancies — Why unique/non-additive metrics behave differently in Dataset-backed widgets