forcedotcom/sf-skills / skills/tableau-next-asset-create
tableau-next-asset-create
VerifiedBuild and edit Tableau Next semantic models (SDMs), vizzes, and dashboards via MCP. TRIGGER when: building a semantic model or dashboard from CSV/Excel files; ingesting a flat file/database into DLO/DMO; profiling a dataset (grain, measures, dimensions; large/wide files via `infer_object_schema`); adding a dimension, measure, AI-ready metric, join, or logical view; running a semantic query, interpreting a breakdown, analyzing account/customer engagement, or pulling counts/totals from existing Tableau Next data (even unnamed/read-only); creating/editing a viz (filter, forecast, sort, shelf, mark encoding, reference line), widget, or dashboard layout. Also: Data Cloud SQL transforms; show a dashboard; share/revoke access; reuse prod or promote Personal Org assets; provision users/licenses; data alerts ('alert me when'); list/classify verified questions or score agent SQL. DO NOT TRIGGER for: rewriting prose descriptions, layout-only dashboard review, debugging MCP, or writing app code.
references/viz-authoring.md
View on GitHub# Visualization Authoring — Tool Guide & Best Practices
Load this for **Step 10** (create visualizations). Covers tool selection,
chart-type best practices mapped to the available MCP tools, field binding rules,
aggregation handling, naming conventions, and verified payloads.
**Best-practice principles** for dashboard design live in
`references/dashboard-design-principles.md`; this file maps the chart-level
mechanics to what the tools actually support. For chart types not currently
supported by the tools, see §9.
> **⚠ Single-tool surface (verified 2026-07-09):** The MCP server exposes one
> viz creation tool: `create_visualization`. The formerly-documented specialized
> tools (`create_timeseries_viz`, `create_comparative_viz`,
> `create_compositional_viz`, `create_relationship_viz`) are **not available**.
> All chart types are built via `create_visualization` with the appropriate
> `marks.panes.type` and `visualSpecification`. Payloads in §11 are verified
> against the live server.
---
## Contents
- 1. Data Presence Gate (prerequisite — hard stop)
- 2. Chart Type Parameters
- 3. Chart Type Decision Matrix
- 4. Naming Conventions
- 5. Field Selection Priorities
- 6. Color Encoding and Breakdown
- 7. Aggregation Handling
- 8. Year-over-Year Period Overlay Pattern
- 9. Unsupported Chart Types — Fallbacks
- §10 — Filter Security
- 10. Field Reference Shape (`create_visualization`)
- 11. Verified Payloads (`create_visualization`)
- 12. `create_visualization` Encoding Reference
- 13. Quality Checklist
- 14. Filters — WHERE vs. HAVING
- 15. Forecasts (Timeseries Only)
- 16. Calculated-Measure Level → Function Pairing
- 17. Reference Line Knob
- 18. Common Errors
---
## 1. Data Presence Gate (prerequisite — hard stop)
**Never create a visualization on a source with zero rows.**
This is Rule 1 from SKILL.md: field-richness is NOT data-presence. Before
calling any viz creation tool, confirm that Step 9 (`run_semantic_query`)
returned real rows. If the query returned empty → **STOP**. Do not call
`create_visualization`. Communicate clearly that the source is empty and offer
alternatives (different data source, different metric).
---
## 2. Chart Type Parameters
**One tool handles all chart types:** `create_visualization`. Control the
chart type via `marks.panes.type` and `visualSpecification.layout`:
| Chart Type / Pattern | `marks.panes.type` | `layout` | Notes |
|---|---|---|---|
| **Line / Time Series** | `Line` | `Vizql` | Date on columns with `DateTruncMonth`; measure on rows |
| **Multi-series Line** | `Line` | `Vizql` | As above + Color encoding on breakdown dimension |
| **Bar (comparative, sorted)** | `Bar` | `Vizql` | Dim on columns, measure on rows; set `sortIntent: "MeasureDescending"` |
| **Stacked Bar** | `Bar` | `Vizql` | As above + `stack: {isAutomatic: false, isStacked: true}` + Color on second dim |
| **Side-by-Side Bar** | `Bar` | `Vizql` | Dim on columns; `MeasureValues` on rows + `MeasureNames` on Color; see `measureValues` |
| **Donut / Pie** | `Donut` | `Radial` | Measure on **`Angle` encoding** (NOT `rows`); dimension on Color; use when dim has < 5 unique values |
| **Scatter / Correlation** | `Circle` | `Vizql` | X-measure on columns, Y-measure on rows; point dimension on Color |
| **Heatmap** | `Square` | `Vizql` | Two dims on rows/columns; measure on Color encoding |
| **Table** | `Text` | `Table` | Dims in `groups`; measures in `rows`; `marks.panes.type` is ignored |
> **Donut gotcha:** Set `layout: "Radial"`, empty `rows`/`columns`. The measure
> goes on the `Angle` encoding, the dimension on `Color` — NOT on `rows` or
> `columns`. If you put the measure on `rows` the call will fail or render
> incorrectly. See §11 for the verified payload.
---
## 3. Chart Type Decision Matrix
| Business Question | Data Pattern | Chart Type |
|---|---|---|
| "How are we trending over time?" | 1 Date + 1 Measure | Line |
| "How do trends compare across categories?" | 1 Date + 1 Measure + 1 Dimension | Multi-series Line |
| "Which categories perform best?" | 1 Dimension + 1 Measure | Bar (sorted descending) |
| "What's our composition?" (< 5 categories) | 1 Dimension (< 5 vals) + 1 Measure | Donut |
| "What's our composition?" (≥ 5 categories) | 1 Dimension (≥ 5 vals) + 1 Measure | Bar — more readable beyond 4 slices |
| "What's the breakdown by two dimensions?" | 2 Dimensions + 1 Measure | Stacked Bar |
| "How do multiple measures compare?" | 1 Dimension + 2+ Measures | Side-by-Side Bar |
| "Where are the performance hotspots?" | 2 Dimensions + 1 Measure | Heatmap |
| "What correlates with success?" | 2 Continuous Measures + Grouping | Scatter |
| "What are the detailed rankings?" | Multiple Dimensions + Measures | Table |
| "How do 2024 vs 2023 compare month by month?" | Period + Measure + Year | Line (year-over-year — see §8) |
| "Predict next quarter revenue" | 1 Continuous date + 1 Measure | Line + `visualSpecification.forecasts` (HoltWinters / RidgeRegression) |
**Priority rules:**
1. Use the decision matrix first: data pattern → tool
2. When multiple patterns fit, prefer the tool that requires fewer manual
encoding overrides
3. Prefer diverse chart types over defaulting to bar for every request
**Analysis-intent → chart (do this before picking marks):**
| User intent (example) | Analysis type | Tool guidance | §reference |
|---|---|---|---|
| "revenue over time" | trend | Line (date on columns) | §11 Time Series |
| "top categories by sales" | comparison | Bar (dim on columns, sorted) | §11 Bar |
| "market-share breakdown" | part-to-whole | Donut (< 5 vals) or Bar (≥ 5) | §11 Donut |
| "discount vs profit relationship" | correlation | Scatter (2 measures, 1 color dim) | §11 Scatter |
| "predict next quarter revenue" | forecast | Line + `forecasts` map (timeseries only) | §11 Time Series (forecast) |
**Forecast** is supported on timeseries **Line** charts via
`visualSpecification.forecasts` (API 262+): continuous `DateTrunc*` date on the
axis, measure to forecast, `HoltWinters` or `RidgeRegression`, horizon under
`to.forecastInterval`. Non-Line / non-timeseries forecasts fail with
`INVALID_INPUT`.
---
## 4. Naming Conventions
Chart titles are **user-facing**. Every chart must answer a business question
and have a clear, non-technical title (use SDM labels over technical names;
strip suffixes).
**Rules:**
1. Title must be ≥ 3 words describing what the chart answers.
2. Strip technical suffixes from display labels: `_Clc`, `_mtc`, `_MTC`, `_CLC`.
3. Never expose raw field API names or suffixed names (`Region4`, `Amount7`).
4. Make titles actionable: "Sales Performance by Region" not "Sales by Region".
5. The `name` (apiName) returned by the tool must be meaningful if you control
it (e.g. specify `title`); the generated name (`monthly_sales_trend_…`) is
acceptable for dashboard placement but label the chart clearly.
✅ **Good:** `"Sales Performance by Region"`, `"Monthly Revenue Trend"`,
`"Discount vs Profit by Product"`
❌ **Bad:** `"Viz_1"`, `"Account_Industry_2"`, `"Pipeline_Generation_Clc_Trend"`,
`"Chart"`, `"Region4 by Amount7"`
---
## 5. Field Selection Priorities
**Always select meaningful dimensions — never ID fields.** CLC fields rank
highest (calculated, business-ready); ID fields are excluded (thousands of
unique values destroy chart readability).
Priority order (highest to lowest):
1. **CLC fields** (`*_clc`, `*_Clc`) — calculated, business-ready
2. Industry, Type, Stage, Status, Region, Segment, Category, Group, Class, Tier,
Level, Phase
3. Country, State, Territory, Department, Division, Account, Opportunity,
Product, Service
4. Name fields (Account_Name, Product_Name, etc.)
5. **Avoid:** Description, Comment, Note, Detail, Text (generic catch-all fields)
6. **Never:** ID fields (`_id`, `_ids` suffix) — thousands of unique values;
destroys chart readability
**Cardinality thresholds:**
- ≤ 4 unique values → Donut acceptable
- 5–50 values → Bar chart preferred dimension
- 50+ values → Apply a Top-N limit, or group to a higher-level category
(e.g., use `Category` instead of `Product_Name` with 200 values)
---
## 6. Color Encoding and Breakdown
**Color encodes meaning, not decoration.** When a second dimension is available,
always add it as a `breakdown` or Color encoding — this creates multi-series or
stacked visuals automatically.
| Chart type | How to add a color / second dimension |
|---|---|
| **All chart types** | `{ "type": "Color", "fieldKey": "<dim_field_key>" }` in `marks.panes.encodings` |
| **YoY line** | Color fieldKey = date field with `function: "DatePartYear"`, `displayCategory: "Discrete"` |
| **Stacked bar** | Color fieldKey = second dimension; also set `stack: { isAutomatic: false, isStacked: true }` |
| **Donut** | Color fieldKey = the category dimension (same field as Angle slice) |
**Rule:** When 2+ dimensions are available for a bar or line chart, add the
second dimension as a breakdown/Color encoding. Color should reference a
specific field, not be a static palette applied without data binding.
**Color vs. Detail by cardinality.** Use `Color` for series with ≤10 distinct
values, `Detail` for higher cardinality.
**Default stacking:** Bar → stacked, others → not stacked. Override with
`marks.panes.stack: { isAutomatic: false, isStacked: <bool> }`.
**Cross-chart color coordination** (same category = same color across multiple
charts) is a dashboard-level concern, not a per-chart rule.
---
## 7. Aggregation Handling
### UserAgg for CLC / Calculated Fields
CLC fields (e.g., `Win_Rate_Clc`, `Avg_Deal_Size_Clc`) contain expressions like
`SUM([Field]) / COUNT([Field])` that aggregate at their own level.
**Never override UserAgg with Sum, Average, or any other function.**
```jsonc
"fields": {
"F_clc": { "fieldName": "Win_Rate_Clc", "function": "UserAgg", "displayCategory": "Continuous" }
// objectName omitted — calc measures never carry objectName
}
```
Overriding with `Sum` or `Average` causes double-aggregation → mathematically
incorrect results (e.g., `SUM(Average_Deal_Size)` is meaningless).
### Aggregation Selection by Analytical Question
| Question | Aggregation |
|---|---|
| "Total revenue / sum" | `Sum` |
| "Average deal size / mean" | `Avg` |
| "Number of records / count" | `Count` |
| "Unique customer count" | `CountD` |
| "Calculated rate / ratio (CLC field)" | `UserAgg` |
| "Highest / lowest value" | `Max` / `Min` |
### Pre-Aggregated Field Handling
Fields identified as pre-aggregated (marked `[AGG]` or using `usr:` derivation
in the semantic model) must not be re-aggregated. Set `function: "UserAgg"` on
the field's entry in the `fields` map and pass the field directly — the
aggregation is already embedded in the field expression.
---
## 8. Year-over-Year Period Overlay Pattern
**Always use period overlay, NOT a continuous date timeline, for YoY comparison.**
| Approach | X-axis | Color | Result |
|---|---|---|---|
| ✅ Period overlay (correct) | Month/Quarter (`DatePartMonth`) | Year dimension | Multiple aligned lines; seasonal patterns obvious |
| ❌ Continuous timeline (wrong) | Full date range (Jan 2023–Dec 2024) | — | Hard to compare same period across years |
**Why period overlay works:** Each year's January lands on the same X position
(month 1), making the same-period comparison direct and vertical rather than
requiring horizontal eye movement across a 2-year timeline.
**Implementation with `create_visualization`:**
Two date fields from the same date column — one with `DatePartMonth` (X-axis)
and one with `DatePartYear` (Color). No calculated dimension is needed; the
date part functions split the field into the two analytical roles inline:
```jsonc
{
"workspaceId": "1Dy…", "workspaceName": "my_workspace",
"semanticModelName": "My_SDM", "semanticModelLabel": "My SDM",
"fields": {
"F_month": {
"objectName": "Orders", "fieldName": "Order_Date",
"function": "DatePartMonth", "displayCategory": "Discrete",
"label": "Month"
},
"F_year": {
"objectName": "Orders", "fieldName": "Order_Date",
"function": "DatePartYear", "displayCategory": "Discrete",
"label": "Year"
},
"F_meas": {
"objectName": "Orders", "fieldName": "Sales",
"function": "Sum", "displayCategory": "Continuous",
"numberFormat": "Currency"
}
},
"visualSpecification": {
"rows": ["F_meas"],
"columns": ["F_month"],
"layout": "Vizql",
"marks": {
"panes": {
"type": "Line",
"encodings": [{ "fieldKey": "F_year", "type": "Color" }]
}
}
},
"title": "Monthly Sales: Year-over-Year Comparison"
}
```
The `DatePartYear` Color encoding creates one line per year, all sharing the
same 12-month X-axis.
---
## 9. Unsupported Chart Types — Fallbacks
The following types appear in the universal visualization best practices guide
but are **not supported by the current MCP tools**. Use the recommended
fallback and communicate the limitation to the user:
| Unsupported Type | Reason | Recommended Fallback |
|---|---|---|
| **Funnel Chart** | No funnel tool | `create_visualization (Bar marks)`, sorted by stage order; communicate each stage's count |
| **Dot Matrix** | No dot matrix tool | `create_visualization (Circle marks)` for 2 measures, or `create_visualization (Bar marks)` for ranking |
| **Map (Point / Geographic)** | No map tool; lat/lon not routed | `create_visualization (Bar marks)` by Region or Territory dimension |
| **Flow / Sankey** | No flow tool | `create_visualization (Bar marks)` showing source → destination volumes as two separate charts |
| **Nightingale Rose** | Radial layout supports Donut marks only | `create_visualization (Bar marks)` (horizontal bar) |
| **Spoke Bars (Radial)** | Not available in current tools | `create_visualization (Bar marks)` |
| **Radial Heatmap** | Not available | `create_visualization` Square-mark heatmap (2D grid) |
**When the user explicitly requests an unsupported type:** say so clearly —
"This chart type is not currently available. I'll use [fallback] instead, which
answers the same question with [benefit]." Do not silently substitute without
explaining.
**Note:** Funnel, Dot Matrix, Map, Flow/Sankey, Nightingale Rose, and Spoke Bar
chart types cannot be verified via MCP tool call trace with the current toolset.
Validate the fallback communication behavior for these instead.
---
## §10 — Filter Security
### Hidden Filters Are Not a Security Control
When a user asks to hide a filter, lock a filter to a specific value, or restrict
which data users see by hiding a filter dimension, issue this warning before
proceeding:
> **Warning:** Hidden filters in dashboards are not a security control. Any user
> with direct API or URL access to the underlying data source can bypass a hidden
> filter and retrieve the full dataset. Do not rely on hidden filters to enforce
> data access restrictions or row-level security.
>
> **Recommendation:** For genuine data access restrictions, implement row-level
> security at the data source level (e.g., data source permissions,
> entitlement-based filtering in the semantic model). Hidden filters are
> appropriate only for UI/UX convenience (e.g., pre-selecting a default value
> the user can still change).
This warning applies when the user's intent is access restriction — not when they
simply want a pre-set default filter value that the end user can still override.
This applies regardless of whether the user says the restriction is "just for
convenience."
---
## 10. Field Reference Shape (`create_visualization`)
`create_visualization` uses a **`fields` map + `visualSpecification`** format —
NOT the `fieldRef` / `measureFunction` shape from older specialized tools.
```jsonc
"fields": {
"<fieldKey>": {
"objectName": "<SDM data-object apiName>", // OMIT for model-level calc measures
"fieldName": "<field apiName on that object>",
"displayCategory": "Discrete | Continuous",
"function": "<aggregation or date function>", // optional
"level": "Row | AggregateFunction | TableCalc | Lod", // required when calc + function
"label": "<display label override>", // optional
"numberFormat": "Currency | Percent | Abbreviated | Precise", // optional, measures only
"referenceLine": "Average | Sum | Min | Max | Target", // optional, measures only — see §17
"referenceLineValue": 1000000, // required iff referenceLine=Target
"colorScale": "Diverging" // optional, Color-encoded measure — see §11 Heatmap
}
}
```
**Server hydrates the rest — do NOT send these unless overriding:** `type:
"Field"` (auto-filled) and the field's inferred `role` (Measure when any
aggregation `function` is set, else Dimension); and at the spec level
`marks.headers` (default Text mark), `marks.fields` (one per continuous-axis
fieldKey on rows/columns), `legends` (auto-derived from Color encodings),
`referenceLines` (`{}`), `measureValues` (`[]`), `style` (full default
scaffold), `view` (empty), and `interactions` (`[]`).
**Critical rules:**
- `workspaceId` — workspace Id (e.g. `0Za...`). Get from `list_workspaces`
(`id` field). `workspaceName` — workspace API name (no spaces). Get from
`list_workspaces` (`name` field). **Do NOT pass the label-with-spaces.**
- `objectName` is the **SDM data-object apiName** (e.g., `Orders`, `Products`),
NOT the underlying DLO/DMO table name (`orders__dll`, `Orders__dlm`).
- `fieldName` is the field's apiName on that SDM object — use the **suffixed**
apiName for bulk-imported fields (e.g., `Category3` not `Category`; see
`shared-gates.md` G3 / `sdm-tool-reference.md` for the suffix read-back rule).
- **Calculated measures: omit `objectName`** entirely. Including `objectName`
for a calculated measure causes an `UNKNOWN_EXCEPTION`. When supplying
`function` on a calc, also set `level` from
`list_semantic_model_calculated_measures` (`UserAgg` only for
`AggregateFunction` / `TableCalc`).
- `displayCategory: "Continuous"` → measures and `DateTrunc*` date functions.
- `displayCategory: "Discrete"` → plain dimensions and `DatePart*` date functions.
- FieldKeys you define in `fields` must **exactly match** the strings used in
`visualSpecification.rows`, `columns`, and encoding `fieldKey` values
(these are the generate-viz field pointers).
- The tool returns the saved visualization's identifying triple (`id`, `label`,
`name`). **Capture `id` and `name`** for `edit_dashboard`'s
`upsert_visualization_widget`.
To inspect the full hydrated body (style, legends, marks.fields), GET the
visualization by id with `get_visualization`.
**`function` values:**
- Aggregations: `Sum`, `Avg`, `Median`, `Count`, `CountD`, `Min`, `Max`,
`UserAgg` (`UserAgg` only for model-level calc measures at
`AggregateFunction` / `TableCalc`)
- Continuous date trunc: `DateTruncYear`, `DateTruncQuarter`, `DateTruncMonth`,
`DateTruncWeek`, `DateTruncDay` (plus `FiscalDateTrunc*` variants)
- Discrete date part: `DatePartYear`, `DatePartQuarter`, `DatePartMonth`,
`DatePartWeek`, `DatePartDay`
- Fiscal-calendar variants (anchored to the org's fiscal year, no `Day`
granularity): `FiscalDateTruncYear/Quarter/Month/Week` (Continuous),
`FiscalDatePartYear/Quarter/Month/Week` (Discrete) — use only when the
request says "fiscal" explicitly; "this quarter" ≠ "this fiscal quarter".
- Plain dimensions: omit `function`
---
## 11. Verified Payloads (`create_visualization`)
All calls share: `workspaceId`, `workspaceName`, `semanticModelName`, `semanticModelLabel`, `label` (the viz display title).
### Time Series (Line chart)
```jsonc
{
"workspaceId": "1Dy…", "workspaceName": "my_workspace",
"semanticModelName": "My_SDM", "semanticModelLabel": "My SDM",
"label": "Monthly Sales Trend",
"fields": {
"F_date": {
"objectName": "Orders", "fieldName": "Order_Date",
"function": "DateTruncMonth", "displayCategory": "Continuous"
},
"F_meas": {
"objectName": "Orders", "fieldName": "Sales",
"function": "Sum", "displayCategory": "Continuous",
"numberFormat": "Currency"
}
},
"visualSpecification": {
"rows": ["F_meas"],
"columns": ["F_date"],
"layout": "Vizql",
"marks": { "panes": { "type": "Line" } }
}
}
```
With multi-series breakdown (Color = second dimension):
```jsonc
{
"fields": {
"F_date": { "objectName": "Orders", "fieldName": "Order_Date", "function": "DateTruncMonth", "displayCategory": "Continuous" },
"F_meas": { "objectName": "Orders", "fieldName": "Sales", "function": "Sum", "displayCategory": "Continuous" },
"F_dim": { "objectName": "Orders", "fieldName": "Region", "displayCategory": "Discrete" }
},
"visualSpecification": {
"rows": ["F_meas"], "columns": ["F_date"], "layout": "Vizql",
"marks": {
"panes": {
"type": "Line",
"encodings": [{ "fieldKey": "F_dim", "type": "Color" }]
}
}
},
"label": "Monthly Sales Trend by Region"
}
```
With year-over-year period overlay:
```jsonc
{
"fields": {
"F_month": { "objectName": "Orders", "fieldName": "Order_Date", "function": "DatePartMonth", "displayCategory": "Discrete", "label": "Month" },
"F_year": { "objectName": "Orders", "fieldName": "Order_Date", "function": "DatePartYear", "displayCategory": "Discrete", "label": "Year" },
"F_meas": { "objectName": "Orders", "fieldName": "Sales", "function": "Sum", "displayCategory": "Continuous", "numberFormat": "Currency" }
},
"visualSpecification": {
"rows": ["F_meas"], "columns": ["F_month"], "layout": "Vizql",
"marks": {
"panes": {
"type": "Line",
"encodings": [{ "fieldKey": "F_year", "type": "Color" }]
}
}
},
"label": "Monthly Sales: Year-over-Year Comparison"
}
```
With forecast (HoltWinters, 6-month horizon) — fieldKeys are pointers into
`fields`; both `dateDim.fieldKey` and `measureFieldKey` must match:
```jsonc
{
"label": "Sales Forecast — Next 6 Months",
"fields": {
"F_date": {
"objectName": "Orders", "fieldName": "Order_Date",
"function": "DateTruncMonth", "displayCategory": "Continuous"
},
"F_meas": {
"objectName": "Orders", "fieldName": "Sales",
"function": "Sum", "displayCategory": "Continuous",
"numberFormat": "Currency"
}
},
"visualSpecification": {
"rows": ["F_meas"],
"columns": ["F_date"],
"layout": "Vizql",
"marks": { "panes": { "type": "Line" } },
"forecasts": {
"FC1": {
"forecastModel": "HoltWinters",
"dimensionFields": [
{ "dateDim": { "fieldKey": "F_date", "granularity": "InferFromData" } }
],
"measureFieldKey": "F_meas",
"from": { "predefinedDate": "LatestData" },
"to": { "forecastInterval": { "value": 6, "timeUnit": "Months" } },
"includeBounds": true,
"confidenceLevel": 95
}
}
}
}
```
---
### Bar / Comparative (sorted descending)
```jsonc
{
"label": "Top Products by Revenue",
"fields": {
"F_dim": { "objectName": "Products", "fieldName": "Product_Name", "displayCategory": "Discrete" },
"F_meas": { "objectName": "Orders", "fieldName": "Sales", "function": "Sum", "displayCategory": "Continuous", "numberFormat": "Currency" }
},
"visualSpecification": {
"rows": ["F_meas"], "columns": ["F_dim"], "layout": "Vizql",
"marks": { "panes": { "type": "Bar" } }
},
"sortIntent": "MeasureDescending"
}
```
With Color on a second dimension (auto-adds color encoding):
```jsonc
{
"label": "Revenue by Region and Category",
"fields": {
"F_dim1": { "objectName": "Orders", "fieldName": "Region", "displayCategory": "Discrete" },
"F_dim2": { "objectName": "Products", "fieldName": "Category3", "displayCategory": "Discrete" },
"F_meas": { "objectName": "Orders", "fieldName": "Sales", "function": "Sum", "displayCategory": "Continuous" }
},
"visualSpecification": {
"rows": ["F_meas"], "columns": ["F_dim1"], "layout": "Vizql",
"marks": {
"panes": {
"type": "Bar",
"encodings": [{ "fieldKey": "F_dim2", "type": "Color" }]
}
}
},
"sortIntent": "MeasureDescending"
}
```
With a CLC calculated measure (omit `objectName`):
```jsonc
{
"label": "Win Rate by Stage",
"fields": {
"F_clc": { "fieldName": "Win_Rate_Clc", "function": "UserAgg", "displayCategory": "Continuous" },
"F_dim": { "objectName": "Opportunities", "fieldName": "Stage8", "displayCategory": "Discrete" }
},
"visualSpecification": {
"rows": ["F_clc"], "columns": ["F_dim"], "layout": "Vizql",
"marks": { "panes": { "type": "Bar" } }
},
"sortIntent": "MeasureDescending"
}
```
---
### Stacked Bar (2 dimensions + 1 measure)
```jsonc
{
"label": "Revenue by Region and Category",
"fields": {
"F_dim1": { "objectName": "Orders", "fieldName": "Region", "displayCategory": "Discrete" },
"F_dim2": { "objectName": "Products", "fieldName": "Category3", "displayCategory": "Discrete" },
"F_meas": { "objectName": "Orders", "fieldName": "Sales", "function": "Sum", "displayCategory": "Continuous" }
},
"visualSpecification": {
"rows": ["F_meas"], "columns": ["F_dim1"], "layout": "Vizql",
"marks": {
"panes": {
"type": "Bar",
"encodings": [{ "fieldKey": "F_dim2", "type": "Color" }],
"stack": { "isAutomatic": false, "isStacked": true }
}
}
},
"sortIntent": "MeasureDescending"
}
```
---
### Side-by-Side Bar (1 dimension + 2+ measures)
Uses `MeasureNames` / `MeasureValues` synthetic fields. Put `MeasureValues` on
rows, `MeasureNames` on Color. List the real measure fieldKeys in `measureValues`.
> **Required:** `displayCategory` is **not optional** for synthetic fields.
> Omitting it causes an `UNKNOWN_EXCEPTION` (HTTP 500). Always set:
> - `MeasureNames` → `"displayCategory": "Discrete"`
> - `MeasureValues` → `"displayCategory": "Continuous"`
```jsonc
{
"label": "Revenue and Units by Region",
"fields": {
"F_dim": { "objectName": "Orders", "fieldName": "Region", "displayCategory": "Discrete" },
"F_mv": { "type": "MeasureValues", "displayCategory": "Continuous" },
"F_mn": { "type": "MeasureNames", "displayCategory": "Discrete" },
"F_rev": { "objectName": "Orders", "fieldName": "Sales", "function": "Sum", "displayCategory": "Continuous", "numberFormat": "Currency" },
"F_units":{ "objectName": "Orders", "fieldName": "Quantity", "function": "Sum", "displayCategory": "Continuous" }
},
"visualSpecification": {
"rows": ["F_mv"], "columns": ["F_dim"], "layout": "Vizql",
"measureValues": ["F_rev", "F_units"],
"marks": {
"panes": {
"type": "Bar",
"encodings": [{ "fieldKey": "F_mn", "type": "Color" }]
}
}
}
}
```
---
### Multi-Measure (direct shelf listing — separate adjacent axes)
The simpler multi-measure form: just list two (or more) measure fieldKeys on
one shelf — no `MeasureNames`/`MeasureValues` needed. This renders the measures
as **separate adjacent axes** (distinct from the shared-axis Side-by-Side Bar
above, which pivots them onto one axis via the measure-names construct). Works
for Bar and Line.
Multi-measure bar (both measures in `columns`):
```jsonc
{
"label": "Sales and Profit by Category",
"fields": {
"F_dim": { "objectName": "Orders", "fieldName": "Category", "displayCategory": "Discrete" },
"F_sales": { "objectName": "Orders", "fieldName": "Sales", "function": "Sum", "displayCategory": "Continuous" },
"F_profit":{ "objectName": "Orders", "fieldName": "Profit", "function": "Sum", "displayCategory": "Continuous" }
},
"visualSpecification": {
"rows": ["F_dim"], "columns": ["F_sales", "F_profit"], "layout": "Vizql",
"marks": { "panes": { "type": "Bar" } }
}
}
```
Multi-measure line (two lines sharing the date axis — both measures in `columns`):
```jsonc
{
"label": "Sales and Profit over Time",
"fields": {
"F_date": { "objectName": "Orders", "fieldName": "Order_Date", "function": "DateTruncMonth", "displayCategory": "Continuous" },
"F_sales": { "objectName": "Orders", "fieldName": "Sales", "function": "Sum", "displayCategory": "Continuous" },
"F_profit":{ "objectName": "Orders", "fieldName": "Profit", "function": "Sum", "displayCategory": "Continuous" }
},
"visualSpecification": {
"rows": ["F_date"], "columns": ["F_sales", "F_profit"], "layout": "Vizql",
"marks": { "panes": { "type": "Line" } }
}
}
```
Prefer this direct form for a quick side-by-side of a few measures; use the
`MeasureNames`/`MeasureValues` Side-by-Side Bar above when the measures should
share a single axis.
---
### Donut / Compositional (Radial layout)
> **Gotcha:** Set `layout: "Radial"`, empty `rows`/`columns`. Place the measure
> on the **`Angle` encoding**, NOT on `rows`. Putting a measure on `rows` with
> Radial layout causes the call to fail or render incorrectly. Verified working
> shape:
```jsonc
{
"label": "Revenue Distribution by Region",
"fields": {
"F_meas": { "objectName": "Orders", "fieldName": "Sales", "function": "Sum", "displayCategory": "Continuous" },
"F_dim": { "objectName": "Orders", "fieldName": "Region", "displayCategory": "Discrete" }
},
"visualSpecification": {
"layout": "Radial",
"rows": [],
"columns": [],
"marks": {
"panes": {
"type": "Donut",
"encodings": [
{ "fieldKey": "F_meas", "type": "Angle" },
{ "fieldKey": "F_dim", "type": "Color" }
]
}
}
}
}
```
Use when dimension has **< 5 unique values**. For ≥ 5 values, use a Bar chart —
donut slices become unreadable beyond 4.
#### Part-to-whole / Donut — field-binding gotchas (`create_visualization`)
The Donut payload above is the current unified `create_visualization` shape
(`type: "Donut"`, `layout: "Radial"`). Older scripts may still name the retired
`create_compositional_viz` tool — that tool is **not** on the pilot MCP; always
use `create_visualization`.
**`objectName` / `level` for measures (matches generate-viz / IR-v2):**
- **Raw measure** (from `list_semantic_model_measures`): supply BOTH
`objectName` (SDM data-object apiName) and `fieldName`.
```jsonc
"F_meas": { "objectName": "Orders", "fieldName": "Sales", "function": "Sum", "displayCategory": "Continuous" }
```
- **Model-level calculated measure** (from
`list_semantic_model_calculated_measures`): supply ONLY `fieldName` — **omit
`objectName`**. Including `objectName` yields `UNKNOWN_EXCEPTION`. Copy the
calc's `level` from the list call whenever you set `function`:
- `AggregateFunction` / `TableCalc` → `function: "UserAgg"`
- `Row` / `Lod` → ordinary agg (`Avg` for Average, `CountD` for CountDistinct);
do **not** use `UserAgg`
```jsonc
"F_meas": { "fieldName": "Profit_Margin", "level": "AggregateFunction", "function": "UserAgg", "displayCategory": "Continuous" }
```
**FieldKeys are pointers:** every `rows` / `columns` / encoding `fieldKey` must
exactly match a key in the `fields` map — mismatches return
`INVALID_VISUALIZATION_METADATA`.
Validate dimensions/measures via `list_semantic_model_*` **before** calling
`create_visualization`. Donut is donut-only (no pie / treemap); for ≥ 5 unique
dimension values prefer §11 Bar.
---
### Scatter / Correlation (Circle marks)
```jsonc
{
"label": "Discount vs Profit by Product",
"fields": {
"F_x": { "objectName": "Orders", "fieldName": "Discount", "function": "Avg", "displayCategory": "Continuous" },
"F_y": { "objectName": "Orders", "fieldName": "Profit", "function": "Sum", "displayCategory": "Continuous" },
"F_dim": { "objectName": "Products", "fieldName": "Product_Name", "displayCategory": "Discrete" }
},
"visualSpecification": {
"rows": ["F_y"], "columns": ["F_x"], "layout": "Vizql",
"marks": {
"panes": {
"type": "Circle",
"encodings": [{ "fieldKey": "F_dim", "type": "Color" }]
}
}
}
}
```
---
### Heatmap (Square marks + Color(measure))
```jsonc
{
"label": "Sales Performance by Region and Quarter",
"fields": {
"F_dim1": { "objectName": "Orders", "fieldName": "Region", "displayCategory": "Discrete" },
"F_dim2": { "objectName": "Orders", "fieldName": "Quarter3", "displayCategory": "Discrete" },
"F_meas": { "objectName": "Orders", "fieldName": "Sales", "function": "Sum", "displayCategory": "Continuous" }
},
"visualSpecification": {
"rows": ["F_dim1"], "columns": ["F_dim2"], "layout": "Vizql",
"marks": {
"panes": {
"type": "Square",
"encodings": [{ "fieldKey": "F_meas", "type": "Color" }]
}
}
}
}
```
For diverging color scales (values above/below a threshold), add
`"colorScale": "Diverging"` to the measure's field binding — only for a measure
genuinely centered on zero/a target (profit, variance, YoY change); on
all-positive data a diverging scale misleads.
---
### Table
Use `groups` for the categorical grouping column(s) and `rows` for measures
(API version 262+). The `groups`/`rows` split is the recommended form — it
gives the grouping column merged-cell styling. Putting a dimension directly in
`rows` (alongside measures) also works and renders as a plain Text column;
prefer `groups` for the leftmost grouping dimension for cleaner output.
Every field renders as a discrete text column (`marks.panes.type` is ignored).
```jsonc
{
"label": "Top Products by Revenue",
"fields": {
"F_dim": { "objectName": "Products", "fieldName": "Product_Name", "displayCategory": "Discrete" },
"F_meas": { "objectName": "Orders", "fieldName": "Sales", "function": "Sum", "displayCategory": "Continuous" }
},
"visualSpecification": {
"groups": ["F_dim"],
"rows": ["F_meas"],
"layout": "Table",
"marks": { "panes": { "type": "Text" } }
},
"sortIntent": "MeasureDescending"
}
```
Sort the primary measure descending via `sortIntent: "MeasureDescending"` or by
pre-sorting the data query via `run_semantic_query` with `sort_orders: DESC`.
`sortIntent` is an input-only convenience field: the server does not persist it
verbatim — it is translated into an explicit `sortOrders` entry on the
dimension field (`{ byField: <measure>, order: "Descending", type: "Field" }`),
so `get_visualization` will show `sortOrders`, not `sortIntent`.
Top-level `sortIntent` values: `MeasureDescending` | `MeasureAscending` |
`DimensionAscending` | `DimensionDescending` | `None`. Use `DimensionAscending`
for lookup tables (A→Z is the point) and `None` to preserve data order — it
overrides the auto-sort described below.
---
## 12. `create_visualization` Encoding Reference
| Encoding type | Valid mark types | Purpose |
|---|---|---|
| `Color` | Bar, Line, Circle, Square, Donut | Category or measure heat gradient |
| `Label` | All | Text labels on marks |
| `Tooltip` | All | Hover detail |
| `Detail` | Bar, Line, Circle, Square | High-cardinality grouping without color |
| `Size` | Circle | Bubble size mapping (third measure) |
| `Range` | Line | Confidence interval band |
| `Angle` | Donut | Slice sizing (Radial layout) |
**`displayCategory` for field bindings:**
- `"Continuous"` → measures and `DateTrunc*` date functions
- `"Discrete"` → plain dimensions and `DatePart*` date functions
**Number formatting options:**
- `Currency` → `"$1.2M"` (assumes USD)
- `Percent` → `"45.2%"` (expects values stored as 0–1; do NOT use on a value
stored as `45.2`)
- `Abbreviated` → `"1.2K"` / `"1.2M"` (default for large numbers)
- `Precise` → `"1,234,567"` (full digits)
By default (no `numberFormat` set) the server applies `NumberShort` with K/M/B
units at **1 decimal place** — **0 decimals for `Count`/`CountD`** — so axes read
`$1.2M`-style, not `1234567.89`.
**Auto-sort only fires for the single-dim + single-measure case.** A bar chart
with exactly one categorical (non-date) dimension and one measure is sorted by
the measure descending automatically ("unsorted bars are nearly useless"). Date
axes stay chronological regardless. Charts with 2+ shelf dimensions or 2+
measures are left unsorted — the sort key is ambiguous — so use `sortIntent`
explicitly for those.
---
## 13. Quality Checklist
Before submitting any viz creation call:
- [ ] Step 9 confirmed real data (non-empty source) before calling `create_visualization`
- [ ] Title is ≥ 3 words, business-friendly, no raw API names or technical suffixes
- [ ] `fields.<key>.fieldName` uses the **suffixed** apiName from Step 5 (if bulk-imported)
- [ ] `objectName` is **omitted** for calculated measures
- [ ] `function: "UserAgg"` for CLC / calculated fields — not overridden
- [ ] Second dimension added as `breakdown` or Color encoding when available
- [ ] `MeasureNames` synthetic field has `displayCategory: "Discrete"` and `MeasureValues` has `displayCategory: "Continuous"` — both are required; omitting either causes HTTP 500
- [ ] Donut (Radial layout) only for dimension cardinality < 5; measure on `Angle` encoding, NOT `rows`
- [ ] Year-over-year uses `DatePartMonth` + Year breakdown, NOT continuous timeline
- [ ] Unsupported chart type → fallback communicated clearly to user
- [ ] Chart type matches the business question (decision matrix applied)
---
## 14. Filters — WHERE vs. HAVING
`create_visualization`'s optional `filters` array persists filter clauses at
create time (distinct from `edit_visualization`'s `addFilter` op —
`edit-visualization.md` — which mutates an already-saved viz). You don't
choose the bucket; it's derived from the target field's role:
- Filter on a **raw field** (no aggregation `function`) → rows/WHERE —
`Processing_Fee between 0 and 21`.
- Filter on an **aggregated measure** (field carries `Sum`/`Avg`/`Count`/…) →
aggregated groups/HAVING — `SUM(Refund_Amount) between 100 and 500`.
Shape: `{fieldKey, type: "Dimension"|"ValueRange"|"DateRange", ...}`.
Dimension filters take exactly one of `include`/`exclude` (never both/neither)
plus optional `includeNulls` (default false; ignored on range filters, which
always exclude nulls). `ValueRange`/`DateRange` need at least one of
`min`/`max` or `dateStart`/`dateEnd` — one-sided emits a GreaterThanOrEqualTo/
LessThanOrEqualTo, both emits Between (inclusive; `min` must be ≤ `max`) — and
only apply to `Continuous` fields; use a Dimension filter for a `Discrete`
(string) one. `DateRange` bounds must be real calendar dates (ISO 8601
`YYYY-MM-DD` or full timestamp) — a malformed value like `2025-99-99` is
rejected up front. Filters compose with `excludeNulls` (which adds its own
aggregated null filter) without clobbering each other.
**Sorted-dimension subtlety:** filtering the auto-sorted categorical
dimension of a bar chart keeps the auto-sort (filter runs on an internal
copy). Filtering the *measure* the chart sorts by drops the auto-sort — a
measure can't be both a sort key and a filter target.
## 15. Forecasts (Timeseries Only)
`visualSpecification.forecasts` is a map of `forecastKey -> config`, valid
**only** on a Line chart with a continuous `DateTrunc*` dimension on the
timeseries axis — a non-timeseries chart (e.g. Bar) fails `INVALID_INPUT`.
Required: `forecastModel` (`HoltWinters` — seasonality/trend — or
`RidgeRegression` — linear/L2); `dimensionFields` (one entry, `dateDim.
fieldKey` matching a `Continuous` `DateTrunc*` field in `fields`,
`granularity: "InferFromData"` only); `measureFieldKey` (a measure field);
`from: {predefinedDate: "LatestData"}`; `to.forecastInterval` (`value` > 0 +
`timeUnit` ∈ Minutes/Hours/Days/Weeks/Months/Quarters/Years).
Optional: `includeBounds` (default true), `confidenceLevel` (90/95/99,
default 95), `ignoreLastPeriods` (default 0), `fillNullsWithZero` (default
false). A `dateDim`/`measureFieldKey` missing from `fields`, or of the wrong
type, fails `INVALID_INPUT` naming the offending forecastKey.
## 16. Calculated-Measure Level → Function Pairing
When binding a model-level calculated measure (from
`list_semantic_model_calculated_measures`, omit `objectName` — §10), copy its
`level` into the field's `level` property whenever `function` is set, then
pick `function` by that level:
| `level` | `function` |
|---|---|
| `AggregateFunction` / `TableCalc` | `UserAgg` |
| `Row` / `Lod` (LOD) | ordinary aggregation matching `aggregationType` (`Average`→`Avg`, `CountDistinct`→`CountD`), or omit `function` when `aggregationType` is `Auto`/`None` |
A missing or mismatched level/function pair is rejected before the
visualization saves.
## 17. Reference Line Knob
A per-measure-field knob (`fields.<key>.referenceLine`), distinct from
`edit_visualization`'s `addReferenceLine`/`editReferenceLine` operations
(`edit-visualization.md` §6) which target an already-saved viz. Values:
`Average`/`Sum`/`Min`/`Max` (computed line) or `Target` with a required
`referenceLineValue` (constant quota/threshold) — no `Median`. Keep to at
most one per chart.
## 18. Common Errors
| Error | Root cause |
|---|---|
| `INVALID_INPUT` | Missing top-level required field (`workspaceId`/`workspaceName`/`semanticModelName`/`semanticModelLabel`/`label`/`fields`/`visualSpecification`); malformed filter (both `include`+`exclude`, `min`>`max`, empty date bounds); or a forecast referencing a missing/mistyped field, non-Line chart, `forecastInterval.value`≤0, or invalid `confidenceLevel`. |
| `INVALID_VISUALIZATION_METADATA` | A fieldKey used in `rows`/`columns`/an encoding/a filter isn't in the `fields` map, or an encoding type doesn't fit the mark (e.g. `Angle` outside `Donut`). |
| `JSON_PARSER_ERROR` | Body shape mismatch — `fields` must be a map (not an array); `marks.panes` is a single object (not an array of panes); `visualSpecification` must be a top-level object, not nested under `body`. |
| `UNKNOWN_EXCEPTION` | Most common fixable cause: binding a **calculated measure** with `objectName` set — drop it (§10/§16). Also the generic fallback for `MeasureNames`/`MeasureValues` missing `displayCategory`. |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |