You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@superset.apache.org by ru...@apache.org on 2026/10/04 04:57:35 UTC
(superset) branch master updated: docs(mcp): document semantic-layer MCP tools (#44130)
This is an automated email from the ASF dual-hosted git repository.
rusackas pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/superset.git
The following commit(s) were added to refs/heads/master by this push:
new 68f19947a80 docs(mcp): document semantic-layer MCP tools (#44130)
68f19947a80 is described below
commit 68f19947a8012ac587bb407c469abacbebae61ca
Author: Evan Rusackas <ev...@preset.io>
AuthorDate: Sat Oct 3 21:57:29 2026 -0700
docs(mcp): document semantic-layer MCP tools (#44130)
Co-authored-by: Claude Sonnet 5 <no...@anthropic.com>
---
docs/admin_docs/configuration/mcp-server.mdx | 1 +
.../docs/using-superset/using-ai-with-superset.mdx | 35 ++++++++++++++++++++++
2 files changed, 36 insertions(+)
diff --git a/docs/admin_docs/configuration/mcp-server.mdx b/docs/admin_docs/configuration/mcp-server.mdx
index b0358d3d375..6734952a23a 100644
--- a/docs/admin_docs/configuration/mcp-server.mdx
+++ b/docs/admin_docs/configuration/mcp-server.mdx
@@ -989,6 +989,7 @@ Each tool declares one or more required FAB permissions. The table below maps to
| `list_dashboards`, `get_dashboard_info`, `generate_dashboard`, `add_chart_to_existing_dashboard` | `can_read` on `Dashboard` (read), `can_write` on `Dashboard` (mutate) |
| `get_dashboard_data` | `can_read` on `Dashboard` **and** `can_read` on `Chart` (it reads chart data across the dashboard) |
| `list_datasets`, `get_dataset_info`, `create_virtual_dataset` | `can_read` on `Dataset` (read), `can_write` on `Dataset` (mutate) |
+| `list_metrics`, `get_table`, `get_compatible_dimensions`, `get_compatible_metrics` | `can_read` on `Dataset`, plus a data-model metadata permission (`can_get_drill_info`, `can_get_or_create_dataset`, or `can_write` on `Dataset`); external semantic views also enforce their own datasource access check |
| `list_databases`, `get_database_info` | `can_read` on `Database` |
| `get_catalog` | `can_read` on the requested asset class (`Database`, `Dataset`, `Chart`, or `Dashboard`); databases and datasets also require data-model metadata access, otherwise the page is marked `restricted` |
| `execute_sql` | `can_execute_sql_query` on `SQLLab` |
diff --git a/docs/docs/using-superset/using-ai-with-superset.mdx b/docs/docs/using-superset/using-ai-with-superset.mdx
index c444166096c..7c3ed34d0cc 100644
--- a/docs/docs/using-superset/using-ai-with-superset.mdx
+++ b/docs/docs/using-superset/using-ai-with-superset.mdx
@@ -126,6 +126,32 @@ Build ad-hoc SQL datasets that can be used as the basis for charts:
> "Create a dataset from: SELECT region, SUM(revenue) as total_revenue FROM orders GROUP BY region"
> "Make a virtual dataset called 'monthly_signups' from the users table filtered to last 12 months"
+### Query the Semantic Layer
+
+Discover and query metrics across both built-in datasets and external semantic
+views (when your deployment has semantic views registered), without writing SQL:
+
+- **Discover metrics** -- search metrics by name or description across every dataset and semantic view you can access, optionally including each metric's compatible dimensions
+- **Query by metric and dimension** -- get tabular results by naming metrics and dimensions instead of writing SQL, with optional filters and time ranges
+- **Progressively refine a query** -- given metrics and/or dimensions already picked, see which dimensions and metrics are compatible with that selection
+
+**Example prompts:**
+
+> "What metrics are available related to revenue?"
+> "Show me revenue by region for the last 30 days"
+> "I've picked the revenue metric -- what dimensions can I break it down by?"
+
+:::tip Recommended workflow
+1. **`list_metrics`** -- search for a metric; note its `dataset_id` (built-in) or `view_id` (external semantic view), plus its `semantic_selection_version` when non-null
+2. **`get_table`** -- pass that `dataset_id`/`view_id` (and, for a versioned external view, its `semantic_selection_version`) along with metric and dimension names to get results
+3. **`get_compatible_dimensions`** / **`get_compatible_metrics`** -- as the user adds selections, check what can validly be combined. `get_compatible_dimensions` returns the full compatible set (including dimensions already selected), so filter out your current picks client-side; `get_compatible_metrics` already excludes selected metrics for built-in datasets but not for external semantic views
+
+Built-in datasets accept any combination of saved metrics and groupby-enabled
+columns since a SQL `GROUP BY` has no metric-level constraints. External
+semantic views can impose additional compatibility rules, which these tools
+surface instead of failing the query outright.
+:::
+
### Run SQL Queries
Execute SQL directly through your AI assistant:
@@ -292,6 +318,15 @@ that those charts may need repair; deletion does not rewrite charts. References
embedded in SQL expressions are not inferred. If a chart has malformed query-context
JSON, impact reporting still checks its saved form data and other accessible charts.
+### Semantic Layer
+
+| Tool | Description |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `list_metrics` | Discover metrics by name/description across built-in datasets and external semantic views; pass `include_compatible_dimensions` to embed each metric's compatible dimensions (off by default) |
+| `get_table` | Query a dataset or semantic view by metric and dimension names, with optional filters, time range, and sorting |
+| `get_compatible_dimensions` | Given metrics/dimensions already selected, return the full set of dimensions compatible with that selection (may include ones already selected) |
+| `get_compatible_metrics` | Given metrics/dimensions already selected, return the compatible metrics; already-selected metrics are excluded for built-in datasets, while external semantic views return whatever their connector reports and may include ones already selected |
+
### Charts
| Tool | Description |