Visual Selector

Determine the optimal Power BI visual type for a given query based on the number and classification of measures and dimensions. This skill analyzes the data profile from the semantic mapper output and produces a visual type recommendation with field-to-bucket mappings.

When to Use This Skill

• Choosing the best visual type for a Genie query result
• Mapping measures and dimensions to visual data buckets (Category, Y, Data, Values, etc.)
• Selecting chart types as part of the query-to-pbip pipeline (Stage 2)
• Recommending page layouts based on visual type

Inputs

• Measures — List of measure names, data types, and format types from Stage 1
• Dimensions — List of dimension names, source tables, and data types from Stage 1
• Derived fields — SQL aliases materialized in Stage 1 as calculated columns or measures
• Query intent (optional) — Original natural language query for override signal detection

Outputs

• visualType — The PBIR visual type string (e.g., cardVisual, clusteredColumnChart, lineChart)
• bucketMapping — Which fields go into which visual data buckets
• layoutPosition — Recommended position coordinates for the visual

Visual Selection Decision Tree

The selection rules below serve as defaults. The agent has the flexibility to decide the best way to display any visual by utilizing the available tables, models, and relationships from the semantic model. When the semantic model provides sort columns, hierarchies, or other metadata that informs a better display choice, the agent should leverage that information rather than rigidly following the decision tree.

Step 1: Count Measures and Dimensions

From the semantic mapper output, count:

• Measures: Aggregated values (SUM, COUNT, AVG, etc.)
• Dimensions: Grouping/slicing columns

Step 2: Classify Each Dimension

Derived field classification defaults:

• Derived text/binary aliases (CASE, bucketing labels, flags) => Nominal
• Derived date/time aliases (DATE_TRUNC, period buckets) => Temporal
• Derived numeric aggregates/ratios => Measure

Role-specific temporal routing:

• Purchase/order trends default to dim_date
• Delivery/shipping/fulfilled trends default to the matching role-playing date table (for example dim_date_delivery)
• If the measure compares two dates but the query says "by delivery month", use the delivery date role for Category and filters
• If the measure compares two dates but the query says "by purchase month" or just "monthly orders/revenue", use dim_date

Step 3: Apply the Selection Matrix

Step 4: Check for Override Signals

Scan the original query text for keywords that override the default selection:

Step 5: Apply Derived Field Routing Rules

When derived fields are available from Stage 1, map them using these defaults:

• If a derived categorical field exists and chart already has a primary category axis, place the derived field in Series (legend/color split).
• If a derived binary flag exists (for example Top Flag), prioritize Series mapping over replacing the main category.
• If a derived temporal field exists, prefer it for Category on trend visuals.
• If a derived numeric aggregate/ratio exists, map it to value buckets (Y, Values, Size) as a measure.
• For tableEx and pivotTable, include derived fields as explicit columns/rows/values rather than legend-only metadata.

Query Bucket Mapping

After selecting the visual type, map fields to the correct data buckets:

cardVisual

{
  "Data": ["<measure>"]
}

clusteredColumnChart / clusteredBarChart

{
  "Category": ["<dimension>"],
  "Y": ["<measure1>", "<measure2>"],
  "Series": ["<optional_derived_categorical_dimension>"]
}

lineChart

{
  "Category": ["<temporal_dimension>"],
  "Y": ["<measure>"],
  "Series": ["<optional_nominal_dimension>"]
}

lineClusteredColumnComboChart

{
  "Category": ["<temporal_dimension>"],
  "Y": ["<primary_measure>"],
  "Y2": ["<secondary_measure>"]
}

tableEx

{
  "Values": ["<dim1>", "<dim2>", "<measure1>", "<measure2>"]
}

pivotTable (matrix)

{
  "Rows": ["<dimension1>"],
  "Columns": ["<dimension2>"],
  "Values": ["<measure>"]
}

slicer

{
  "Values": ["<dimension>"]
}

filledMap

{
  "Category": ["<geographic_dimension>"],
  "Size": ["<measure>"]
}

scatter-bubble-chart

{
  "X": ["<x_measure>"],
  "Y": ["<y_measure>"],
  "Details": ["<category_dimension>"],
  "Size": ["<optional_size_measure>"]
}

azure-map-gradient

{
  "Location": ["<geographic_dimension>"],
  "Gradient": ["<measure>"]
}

azure-map-bubble

{
  "Location": ["<geographic_dimension>"],
  "Size": ["<measure>"]
}

slicer-between-date

{
  "Values": ["<date_dimension>"]
}

slicer-dropdown

{
  "Values": ["<dimension>"]
}

slicer-list-multiselect

{
  "Values": ["<dimension>"]
}

Visual Type to PBIR Type Mapping

Template Source Priority

The visual-selector references templates from two sources with the following priority:

1. Primary: skills/query-to-pbip/assets/visual-templates/ - These templates are checked first
2. Secondary: cn-dataworks-pbir-visuals research templates - Used when primary templates don't cover the use case

When multiple visual types could satisfy the same query pattern, prefer the primary source template. Secondary templates are used for specialized visualizations not available in the primary set (e.g., scatter plots, Azure maps, enhanced slicers).

Layout Recommendations

Example Walkthroughs

"What is total revenue?"

• Measures: 1 (Total Revenue)
• Dimensions: 0
• Result: cardVisual, Data: [Total Revenue]

"Revenue by state"

• Measures: 1 (Total Revenue)
• Dimensions: 1 (customer_state → Nominal)
• Result: clusteredColumnChart, Category: [customer_state], Y: [Total Revenue]

"Units sold by category with top flag"

• Measures: 1 (Units Sold)
• Dimensions: 2 (category_name, derived Top Flag)
• Result: clusteredBarChart
• Bucket mapping: Category: [category_name], Y: [Units Sold], Series: [Top Flag]

"Monthly revenue trend"

• Measures: 1 (Total Revenue)
• Dimensions: 1 (month → Temporal)
• Result: lineChart, Category: [month], Y: [Total Revenue]

"Revenue and rolling revenue by month"

• Measures: 2 (Total Revenue, Rolling 1 Month)
• Dimensions: 1 (month_name → Temporal)
• Result: lineClusteredColumnComboChart, Category: [month_name], Y: [Total Revenue], Y2: [Rolling 1 Month]

"Average delivery time by delivery month for the latest 12 months in the data"

• Measures: 1 (Avg Delivery Time)
• Dimensions: 1 (dim_date_delivery month/date → Temporal)
• Filter intent: data-anchored last 12 months
• Result: lineChart, Category: [dim_date_delivery month hierarchy], Y: [Avg Delivery Time]

"Average delivery time trend for the last 12 months"

• Measures: 1 (Avg Delivery Time)
• Dimensions: 1 (temporal)
• Filter intent: current-date-relative last 12 months
• Result: lineChart, Category aligned to the requested business timeline, Y: [Avg Delivery Time]

"Revenue by state and category"

• Measures: 1 (Total Revenue)
• Dimensions: 2 (customer_state → Nominal, category_name → Nominal)
• Result: pivotTable, Rows: [customer_state], Columns: [category_name], Values: [Total Revenue]

Error Handling

Reference Templates

Before constructing a visual.json output, consult the template files in skills/visual-selector/references/. Each template provides a complete worked example showing a user question, the corresponding Genie SQL query, and the full visual.json output. Use these templates as learning material to inform decisions about visual type selection, field-to-bucket mappings, formatting options, sorting configuration, and filter application.

When building a visual.json, find the reference template that most closely matches the target visual type and follow its patterns for:

• Query structure — How queryState buckets (Category, Series, Y, Tooltips) are populated with field projections
• Sort definitions — How sortDefinition is configured for the visual type
• Object formatting — How objects properties (axis settings, labels, legends, gridlines, markers) are set
• Visual container objects — How titles, backgrounds, borders, and other container-level properties are configured
• Filter configuration — How filterConfig entries are structured, including TopN subquery filters and Advanced filters

references/

• barChart.md — Bar chart template with Category/Series/Y buckets, categorical axis configuration, and ascending sort
• lineChart.md — Line chart template with temporal Category hierarchy, Series dimension, marker/line styles, and TopN filter
• lineClusteredColumnComboChart.md — Combo chart template with Y column axis, reference lines (min/max/average/median/percentile), and Advanced measure filters
• pieChart.md — Pie chart template with Category/Y buckets, outside label positioning with percent-of-total style, and TopN filter
• stackedColumnChart.md — Stacked column chart template with Category hierarchy, Series split, Tooltip measures, and multi-filter configuration
• clusteredColumnChart.md — Clustered column chart template with Category/Y buckets, categorical axis configuration, and descending sort