Skip to content

forcedotcom/sf-skills / skills/tableau-next-asset-create

tableau-next-asset-create

Verified

Build 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.

FileKindSize
SKILL.mdskill md23.9 KB
references/admin-users.mdmarkdown5.9 KB
references/ai-readiness.mdmarkdown17.5 KB
references/alerts.mdmarkdown3.9 KB
references/build-workflow.mdmarkdown41.4 KB
references/dashboard-authoring.mdmarkdown15.5 KB
references/dashboard-design-principles.mdmarkdown18.6 KB
references/data-transform-gotchas.mdmarkdown9.5 KB
references/data-understanding.mdmarkdown26.8 KB
references/deep-reference-index.mdmarkdown4.8 KB
references/destructive-operations.mdmarkdown3.9 KB
references/edit-dashboard.mdmarkdown19.8 KB
references/edit-visualization.mdmarkdown41.5 KB
references/empty-source-handling.mdmarkdown4.9 KB
references/ingest-and-metric-gotchas.mdmarkdown35.4 KB
references/insight-bundle.mdmarkdown2.7 KB
references/large-flat-file-handling.mdmarkdown19.1 KB
references/schemas/edit-dashboard/_envelope.jsonconfig3.1 KB
references/schemas/edit-dashboard/_shared-widget-fields.jsonconfig7.0 KB
references/schemas/edit-dashboard/add_page.jsonconfig1.1 KB
references/schemas/edit-dashboard/delete_page.jsonconfig947 B
references/schemas/edit-dashboard/discard_dashboard.jsonconfig482 B
references/schemas/edit-dashboard/move_widget.jsonconfig1.4 KB
references/schemas/edit-dashboard/move_widget_to_page.jsonconfig1.4 KB
references/schemas/edit-dashboard/place_widget_on_page.jsonconfig1.4 KB
references/schemas/edit-dashboard/remove_widget_from_dashboard.jsonconfig864 B
references/schemas/edit-dashboard/remove_widget_from_page.jsonconfig1.1 KB
references/schemas/edit-dashboard/rename_page.jsonconfig1.0 KB
references/schemas/edit-dashboard/save_dashboard.jsonconfig775 B
references/schemas/edit-dashboard/undo.jsonconfig421 B
references/schemas/edit-dashboard/upsert_button_widget.jsonconfig3.3 KB
references/schemas/edit-dashboard/upsert_container_widget.jsonconfig4.2 KB
references/schemas/edit-dashboard/upsert_filter_widget.jsonconfig8.8 KB
references/schemas/edit-dashboard/upsert_metric_widget.jsonconfig3.8 KB
references/schemas/edit-dashboard/upsert_navigation_widget.jsonconfig4.4 KB
references/schemas/edit-dashboard/upsert_parameter_widget.jsonconfig9.9 KB
references/schemas/edit-dashboard/upsert_text_widget.jsonconfig5.5 KB
references/schemas/edit-dashboard/upsert_visualization_widget.jsonconfig3.4 KB
references/sdm-tool-reference.mdmarkdown33.1 KB
references/semantic-query-and-enrichment.mdmarkdown16.3 KB
references/shared-gates.mdmarkdown17.6 KB
references/sharing-and-promotion.mdmarkdown14.4 KB
references/tasks/ai-readiness-audit.mdmarkdown3.0 KB
references/tasks/analyze-data.mdmarkdown2.5 KB
references/tasks/build-dashboard.mdmarkdown3.7 KB
references/tasks/build-end-to-end.mdmarkdown4.4 KB
references/tasks/create-data-transform.mdmarkdown2.8 KB
references/tasks/create-viz.mdmarkdown3.6 KB
references/tasks/edit-dashboard.mdmarkdown5.0 KB
references/tasks/edit-sdm.mdmarkdown6.5 KB
references/tasks/edit-viz.mdmarkdown2.4 KB
references/tasks/enrich-model.mdmarkdown4.0 KB
references/tasks/ingest-flat-file.mdmarkdown3.9 KB
references/tasks/manage-alert.mdmarkdown1.6 KB
references/tasks/profile-dataset.mdmarkdown2.7 KB
references/tasks/promote-or-reuse.mdmarkdown2.3 KB
references/tasks/provision-user.mdmarkdown1.8 KB
references/tasks/query-model.mdmarkdown5.3 KB
references/tasks/review-verified-questions.mdmarkdown1.9 KB
references/tasks/share-asset.mdmarkdown1.8 KB
references/verified-questions.mdmarkdown4.6 KB
references/viz-authoring.mdmarkdown41.3 KB

references/semantic-query-and-enrichment.md

View on GitHub
# Semantic Query & Enrichment Reference

Field-shape matrix, aggregation mapping, and worked payloads for querying an
SDM and enriching it with calculated fields and metrics. Substitute apiNames
from `list_*` — do not copy example names into a live call.

> **Our MCP is NOT the REST gateway.** Public/Cursor "semantic-query" guides
> target `POST /services/data/vXX/semantic-engine/gateway` with a **camelCase**
> body (`tableField`, `rowGrouping: true`, `semanticAggregationMethod`). The
> MCP `run_semantic_query` tool takes a **proto-shaped snake_case** body
> (`table_field`, `grouping: "ROW_GROUPING"`, `semantic_aggregation_method`).
> Do not copy camelCase payloads — they fail. Use the shapes here.

## Contents

- run_semantic_query — top-level body (`semantic_context` nested there)
- Field-shape matrix
- options block
- Reading the response
- Query recovery
- Worked query (verified): sum of a measure by a joined dimension
- Detail rows (`detailed_rows: true`)
- Filtered query (`filter.binary_predicate`)
- Enrichment — calculated dimension
- Enrichment — calculated measure
- Enrichment — metric (named, time-bound KPI)

## run_semantic_query — top-level body

```jsonc
{
  "semanticModelApiName": "<SDM apiName>",   // NOT semanticModelId (deprecated here)
  "source": "tableau-next-pilot-mcp",
  "dataspace": "default",                     // omit unless multi-dataspace
  "structuredSemanticQuery": { "fields": [...], "options": {...} }
  // OR structuredMetricQuery — mutually exclusive; do not send both
}
```

Only `fields`, `filter` XOR `flatten_filter` (never both), `options`,
`semantic_context`, `aggregate_filter`, `parameters` are valid keys inside
`structuredSemanticQuery`. Putting `limit`, `sort_orders`, or `row_grouping`
at that level fails with `Cannot find field: <key>`. Prefer
`options.limit_options.limit` + `sort_orders` for top-N over proto
`top_n_filter`.

Pass **ONE** of `structuredSemanticQuery` (recommended) **OR**
`structuredMetricQuery` (alternative) — mutually exclusive dispatch paths.
Do not send both. Outer-request `context` (`timezone`, `locale`) is distinct
from per-query `semantic_context`. Most queries omit `semantic_context` — the
engine picks defaults. Pass it when fiscal-year filters or timezone-sensitive
date math matters:

```jsonc
"semantic_context": {
  "timezone": { "id": "America/Los_Angeles" },
  "locale":   { "code": "en_US" }
}
```

Query is org-level / SDM-level — it does **NOT** take a `workspaceId`. Any SDM
visible via `list_semantic_models` is queryable regardless of workspace.

Treat any **2xx** as success (the wrapper has been observed to return 201).
Provisioning is gated on `orgHasDataCloudReportingEnabled` OR
`orgHasSemanticQuery` — a permission error is a **provisioning gap**, not a
caller payload bug.

## Field-shape matrix

| Field kind | expression | grouping / aggregation |
|---|---|---|
| **Raw dimension** | `{ "table_field": { "name": "<dimApiName>", "table_name": "<objApiName>" } }` | `"grouping": "ROW_GROUPING"` |
| **Raw measure** | `{ "table_field": { "name": "<measApiName>", "table_name": "<objApiName>" } }` | `"semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_<AGG>"` |
| **Calculated dimension** | `{ "semantic_field": { "name": "<calcDimApiName>" } }` | `"grouping": "ROW_GROUPING"` |
| **Calculated measure** | `{ "semantic_field": { "name": "<calcMeasApiName>" } }` | `"semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_USER_AGG"` (for AVG/ratio/COUNTD expressions) |

- `table_name` MUST be the SDM **data-object apiName** from
  `list_semantic_model_data_objects` — NOT the `__dll`/`__dlm` source name
  (that → `Failed to resolve table`).
- `name` MUST be the **suffixed** field apiName from
  `list_semantic_model_dimensions` / `list_semantic_model_measures`.
- `semantic_field` is ONLY for **calculated** SDM fields. It takes ONLY
  `name` (no `table_name`). Using `semantic_field` for a raw/physical column
  fails `Failed to resolve semantic field <name>...`. Rule of thumb:
  calculated → `semantic_field`; physical column → `table_field`.
- `alias` convention: `"<objApiName>.<fieldApiName>"` for table fields,
  `"<apiName>"` for semantic (calculated) fields.
- A third shape, on-the-fly `calculated_field`, exists; prefer a pre-defined
  calc on the model over inventing one in the query.
- **In an aggregated query, every measure needs `semantic_aggregation_method`.**
  A measure with no aggregation is treated as a detail row and errors
  `Detail Rows with Metric must have the corresponding dimension` — this fires
  on the **MISSING aggregation**, NOT a missing dimension (adding
  `ROW_GROUPING` does NOT satisfy it). A grouping dimension is optional
  (measure-only = grand total). **Exception:** `options.detailed_rows: true` is
  the one shape where omitting the aggregation method is valid.

### Aggregation method enum

Valid query-time suffixes only: `SUM`, `AVG`, `COUNT`, `MIN`, `MAX`,
`UNIQUE_COUNT`, `USER_AGG`. Map the model's `aggregationType` enum value (left)
to the query-time suffix (right): `Sum→SUM`, `Average→AVG`, `Count→COUNT`,
`CountDistinct→UNIQUE_COUNT`, `Min→MIN`, `Max→MAX`. Note the model enum uses
`Average` (not `Avg`), and there is no `SEMANTIC_AGGREGATION_METHOD_COUNTDISTINCT`
at query time — `CountDistinct` maps to `SEMANTIC_AGGREGATION_METHOD_UNIQUE_COUNT`,
a distinct enum value from plain `COUNT` (`COUNT` counts all rows; `UNIQUE_COUNT`
counts distinct values). A calculated measure whose expression already
aggregates uses `USER_AGG`.

## options block

```jsonc
"options": {
  "limit_options": { "limit": 10 },
  "sort_orders": [ { "simple_sort_order": { "sort_by_field_alias": "<alias>", "sorting_order": "DESC" } } ],
  "grand_total": true        // OR "detailed_rows": true — never both
}
```

- Aggregate query (≥1 measure/calc measure): `grand_total: true` adds a total
  row. Detail query (dimensions only): `detailed_rows: true`. (These two
  option flags are documented independently in the schema; whether they
  combine is **unverified** — the worked query below used neither.)
- Aggregate queries should include ≥1 dimension with `ROW_GROUPING` (a
  measure-only query returns a single grand-total row — valid for "total X").

## Reading the response

Double-wrapped: parse `JSON.parse(response.defaultExc)`. Treat any **2xx** as
success (wrapper has been observed to return 201). Then:
`status === "SUCCESS"`; `queryResults.queryMetadata.fields[<alias>].placeInOrder`
indexes into each `queryResults.queryData.rows[i].values[]`. A `null` grouping
value is the unmatched/blank bucket (verified: a `null` region row appeared
alongside the real groups). `status != "SUCCESS"` is a failure — read
`errorMessage`. `status != "SUCCESS"` with an **empty** `errorMessage` is an
unknown failure — ask the user to check the org's CDP / Reporting
configuration. A confirmed **permission** error is the provisioning-gap
signal (`orgHasDataCloudReportingEnabled` / `orgHasSemanticQuery`), not a
caller payload bug.

**Display rules.** Render rows as a markdown table for ≤20 rows, else row
count + first 10 + "… and N more". Order by `placeInOrder`. Do **NOT** echo
the raw `queryResults` JSON. Surface `errorMessage` verbatim on failure.

## Query recovery

| Signal | Cause / fix |
|---|---|
| `Failed to resolve table` | Used `__dll`/`__dlm` instead of the SDM data-object apiName |
| `Failed to resolve semantic field` | Used `semantic_field` for a raw/physical column — use `table_field` |
| `Cannot find field: <key>` | Non-proto top-level key (`limit`/`sort_orders`/`row_grouping` outside `options`) |
| `Query returns more records than allowed. The limit is: 5000` | Add `limit_options` or aggregate |
| `USER_ILLEGAL_ARGUMENT_RESOLVE_ENTITY_ERROR` | Typo / wrong table / physical column as `table_field.name` |
| `Detail Rows with Metric must have the corresponding dimension` | Missing `semantic_aggregation_method` on a measure (not a missing dimension) |
| Permission error | `orgHasDataCloudReportingEnabled` / `orgHasSemanticQuery` provisioning gap |
| `status != SUCCESS` with empty `errorMessage` | Unknown failure — check org CDP / Reporting configuration |

## Worked query (verified): sum of a measure by a joined dimension

```jsonc
{
  "semanticModelApiName": "ZZ_Trap_base0",
  "source": "tableau-next-pilot-mcp",
  "structuredSemanticQuery": {
    "fields": [
      { "expression": { "table_field": { "name": "region18", "table_name": "Accounts" } },
        "alias": "Accounts.region18", "grouping": "ROW_GROUPING" },
      { "expression": { "table_field": { "name": "Amount7", "table_name": "Opportunities" } },
        "alias": "Opportunities.Amount7",
        "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_SUM" }
    ],
    "options": { "limit_options": { "limit": 10 },
      "sort_orders": [ { "simple_sort_order": { "sort_by_field_alias": "Opportunities.Amount7", "sorting_order": "DESC" } } ] }
  }
}
```

Returned per-region sums by traversing the Accounts↔Opportunities join.

## Detail rows (`detailed_rows: true`)

The one shape where a measure may omit `semantic_aggregation_method`. Do not
also set `grand_total`. Field names below are illustrative — copy apiNames from
`list_*`.

```jsonc
{
  "semanticModelApiName": "Sales_Performance_SDM",
  "structuredSemanticQuery": {
    "fields": [
      { "expression": { "table_field": { "name": "Account_ID", "table_name": "Account" } },
        "alias": "account_id" },
      { "expression": { "table_field": { "name": "Account_Name", "table_name": "Account" } },
        "alias": "account_name" },
      { "expression": { "table_field": { "name": "Revenue", "table_name": "Account" } },
        "alias": "revenue" }
    ],
    "options": {
      "detailed_rows": true,
      "limit_options": { "limit": 20 }
    }
  },
  "dataspace": "default"
}
```

## Filtered query (`filter.binary_predicate`)

`filter` XOR `flatten_filter` — never both. Count-distinct uses
`SEMANTIC_AGGREGATION_METHOD_UNIQUE_COUNT` (not `COUNTDISTINCT`).

```jsonc
{
  "semanticModelApiName": "Sales_Performance_SDM",
  "structuredSemanticQuery": {
    "fields": [
      {
        "expression": {
          "table_field": { "name": "Account_ID", "table_name": "Account" }
        },
        "semantic_aggregation_method": "SEMANTIC_AGGREGATION_METHOD_UNIQUE_COUNT",
        "alias": "distinct_accounts"
      }
    ],
    "filter": {
      "binary_predicate": {
        "left_expression": { "table_field": { "name": "Segment", "table_name": "Account" } },
        "binary_operator": "BINARY_OPERATOR_EQUALS",
        "right_expression": { "string_expression": "Enterprise" }
      }
    }
  }
}
```

## Enrichment — calculated dimension

`add_semantic_model_calculated_dimension`. TuA expression with **bracketed
qualified references** `[ObjApiName].[FieldApiName]` (suffixed apiNames). Bare
identifiers fail with "Missing reference". Verified:

```jsonc
{
  "modelApiNameOrId": "ZZ_Trap_base0",
  "apiName": "Region_Upper",
  "label": "Region Upper",
  "expression": "UPPER([Accounts].[region18])",
  "dataType": "Text",
  "displayCategory": "Discrete"
}
```

Row-level expression → server sets `level: "Row"` automatically.

- Calculated-measure TuA conditionals are **simple CASE only**:
  `CASE <expr> WHEN <value> THEN <result> ... [ELSE <result>] END`.
  Searched CASE (`CASE WHEN <condition> THEN ...`) and `IF(condition, then, else)`
  are rejected (`Syntax Error - no viable alternative at input 'WHEN'` /
  `mismatched input ','`). Key the CASE off a value, not a boolean predicate.
  Block `IF`/`ELSEIF`/`END` and `IIF(...)` are **pending live verification** —
  do not use them in a calc measure or dimension until confirmed.

## Enrichment — calculated measure

`add_semantic_model_calculated_measure`. Verified (level-aware AVG):

```jsonc
{
  "modelApiNameOrId": "ZZ_Trap_base0",
  "apiName": "Avg_Deal_Size",
  "label": "Avg Deal Size",
  "expression": "AVG([Opportunities].[Amount7])",
  "dataType": "Number",
  "aggregationType": "UserAgg",      // required when the expression aggregates
  "displayCategory": "Continuous"
}
```

- Expression that already aggregates (`AVG`, `SUM/COUNT`, `COUNTD`) → must use
  `aggregationType: "UserAgg"`; a bare `Average`/`Sum` is rejected with
  "AggregativeFunction-level calculated fields require UserAgg". Server sets
  `level: "AggregateFunction"`.
- Row-level arithmetic (`[O].[Profit] / [O].[Sales]`) → `aggregationType: "Auto"`.
- The server overlays defaults that were not passed (`decimalPlace: 2`,
  `directionality: "Up"`, `sentiment`, `totalAggregationType: "Sum"`,
  `level: "Row"`, `shouldTreatNullsAsZeros: false`) — set them explicitly to
  override.
- No arithmetic check: `/ 0` is accepted and fails only at query time.
- Do not set `externalLevel` or `externalConnectionApiName` unless connecting
  to an external definition.
- Updates are **full PUT**: GET via `get_semantic_model_calculated_measure`,
  then send the complete object. Omitted fields reset to those defaults.

To query a UserAgg calc measure, reference it as a `semantic_field` with
`SEMANTIC_AGGREGATION_METHOD_USER_AGG` (verified returning per-group averages).

## Enrichment — metric (named, time-bound KPI)

`add_semantic_model_metric`. `label` is required. **Create a metric by default
when the request implies a tracked business number** (revenue, win rate,
engagement, count over time) **and a business-meaningful event date exists to
anchor it** — not only on explicit demand. Set EXACTLY ONE shape on
`measurementReference` (and on `timeDimensionReference`). Verified shape:

```jsonc
{
  "modelApiNameOrId": "Pipeline_Analysis",
  "apiName": "Total_Pipeline",
  "label": "Total Pipeline",
  "measurementReference": { "tableFieldReference": { "tableApiName": "Opportunities", "fieldApiName": "Amount7" } },
  // OR a derived measure: "measurementReference": { "calculatedFieldApiName": "Avg_Deal_Size" }
  "timeDimensionReference": { "tableFieldReference": { "tableApiName": "Opportunities", "fieldApiName": "Created_Date14" } },
  "aggregationType": "Sum",   // matches the RAW-measure branch (sum of Amount). For the
                              // calculatedFieldApiName branch, set the calc field's own
                              // aggregation (e.g. "UserAgg" for Avg_Deal_Size) — do NOT Sum an average.
  "timeGrains": ["Day", "Week", "Month", "Quarter", "Year"],
  "insightsSettings": {       // REQUIRED — omit identifyingDimension and the metric UI crashes
    "identifyingDimension": {
      "identifierDimensionReference": {
        "tableFieldReference": { "tableApiName": "Opportunities", "fieldApiName": "Opportunity_Id5" }
      }
    }
  },
  "additionalDimensions": [   // must include identifyingDimension (and every insights/filter field)
    { "tableFieldReference": { "tableApiName": "Opportunities", "fieldApiName": "Opportunity_Id5" } }
  ]
}
```

Do not ship this block without `insightsSettings`, and always mirror
`identifyingDimension` into `additionalDimensions` (create fails with
`Insight dimension (...) is missing from the metric additional dimensions`).
Nouns, extra `additionalDimensions`, and `insightsDimensionsReferences` live in
`ingest-and-metric-gotchas.md` §B and `build-workflow.md` Step 8.

- `aggregationType` enum values: `Sum`, `Average`, `Count`, `CountDistinct`,
  `Min`, `Max`, `UserAgg`, `Auto`, etc. (note `Average`, not `Avg`).
- `fieldApiName` on BOTH references is the **suffixed** apiName **from the
  object that owns the field**. A date field from a *different* object is
  rejected with `Table field with table name: (X) and field name: (Y) was not
  found in the model` (the exact error hit when an Accounts date dim was passed
  for an Opportunities reference). Read each object's own dimensions with
  `list_semantic_model_dimensions` and match the owner.
- The time dimension must be a **business-meaningful** `Date`/`DateTime`
  dimension (`dataType: "Date"`) — a real event date (created/close/order/
  activity), NOT a `cdp_sys_PartitionDate`, `*_SourceVersion`, or load
  timestamp. A metric on a plumbing date is worse than no metric.
- With `filters`, also pass `filterLogic` (e.g. `"1"` / `"1 AND 2"`) and
  fully-qualify filter `fieldName` as `<tableApiName>.<fieldApiName>`.
- Skip the metric only if no meaningful date dimension resolves.
- Pass **ONE** of `structuredSemanticQuery` **OR** `structuredMetricQuery` on
  `run_semantic_query` — mutually exclusive. Prefer `structuredMetricQuery`
  when querying a named metric (see `build-workflow.md` Step 9). Do not
  reconstruct the metric from raw fields unless no metric exists.
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 119kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall
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: 118kUpdated Claude CodeCodexVerifiedInstall