From 3153cf9fb4d0b038107f65b997cffedcef86e7f1 Mon Sep 17 00:00:00 2001 From: Superset Dev Date: Fri, 17 Apr 2026 10:33:41 -0700 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20Superset=206.1=20documentation=20ca?= =?UTF-8?q?tch-up=20=E2=80=94=20batch=205?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Cover remaining 6.1 features across existing and new pages: MCP server: - Add MCP_PARSE_REQUEST_ENABLED to configuration reference - Add Audit Events section (MCP tool calls appear in Action Log) - Add Tool Pagination section documenting cursor-based pagination (#37674) Using AI with Superset: - Expand Available Tools Reference into categorized sections covering all new tools added in the MCP tool library expansion - Document preview-first workflow for generate_chart / update_chart Creating Your First Dashboard: - AG Grid server-side column filters (#35683): filter types, AND/OR logic, pagination interaction - Time Shift for AG Grid Interactive Table (#37072) - Dynamic currency formatting via currency_code_column dataset field (#36416) - ECharts option editor in Explore for JSON overrides (#37868) - Table chart: export behavior with search filter active (#36281) - Dataset folders: organizing datasets into groups (#36239) - PWA file handler: opening CSV/XLS/Parquet from OS file manager (#36191) - Share database connection option when adding a new database (#37940) Exploring Data: - Dialect-aware Format SQL (applies selected database dialect) (#39393) - SQL Lab tips section and time range natural language expressions (consolidates content from batch 4 for master branch) Importing/Exporting: - Dashboard import overwrite behavior: charts are replaced not duplicated (#36551) - UUID in REST API POST responses for dataset/chart/dashboard (#37806) New pages: - docs/docs/using-superset/embedding.mdx: embedded SDK quick start, resolvePermalinkUrl callback (#36924), DISABLE_EMBEDDED_SUPERSET_LOGOUT feature flag (#37537), URL parameters, guest token security notes - docs/admin_docs/configuration/aws-iam.mdx: cross-account IAM authentication for Aurora and Redshift via STS AssumeRole (#37585), configuration reference, trust policy setup guide Co-Authored-By: Claude Sonnet 4.6 --- docs/admin_docs/configuration/aws-iam.mdx | 153 ++++++++++++++++++ .../importing-exporting-datasources.mdx | 23 +++ docs/admin_docs/configuration/mcp-server.mdx | 29 ++++ .../creating-your-first-dashboard.mdx | 80 +++++++++ docs/docs/using-superset/embedding.mdx | 132 +++++++++++++++ docs/docs/using-superset/exploring-data.mdx | 21 +++ .../using-superset/using-ai-with-superset.mdx | 99 +++++++++++- 7 files changed, 532 insertions(+), 5 deletions(-) create mode 100644 docs/admin_docs/configuration/aws-iam.mdx create mode 100644 docs/docs/using-superset/embedding.mdx diff --git a/docs/admin_docs/configuration/aws-iam.mdx b/docs/admin_docs/configuration/aws-iam.mdx new file mode 100644 index 000000000000..d777935e4689 --- /dev/null +++ b/docs/admin_docs/configuration/aws-iam.mdx @@ -0,0 +1,153 @@ +{/* +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +*/} + +--- +title: AWS IAM Authentication +sidebar_label: AWS IAM Authentication +sidebar_position: 15 +--- + +# AWS IAM Authentication for AWS Databases + +Superset supports IAM-based authentication for **Amazon Aurora** (PostgreSQL and MySQL) and **Amazon Redshift**. IAM auth eliminates the need for database passwords — Superset generates a short-lived auth token using temporary AWS credentials instead. + +Cross-account IAM role assumption via STS `AssumeRole` is supported, allowing a Superset deployment in one AWS account to connect to databases in a different account. + +## Prerequisites + +- `boto3` must be installed in your Superset environment: + ```bash + pip install boto3 + ``` +- The Superset server's IAM role (or static credentials) must have permission to call `sts:AssumeRole` (for cross-account) or `rds-db:connect` / `redshift:GetClusterCredentials` (for same-account). +- SSL must be enabled on the Aurora / Redshift endpoint (required for IAM token auth). + +## Configuration + +IAM authentication is configured via the **encrypted_extra** field of the database connection. Access this field in the **Advanced** → **Security** section of the database connection form, under **Secure Extra**. + +### Aurora PostgreSQL or Aurora MySQL + +```json +{ + "aws_iam": { + "enabled": true, + "role_arn": "arn:aws:iam::222222222222:role/SupersetDatabaseAccess", + "external_id": "superset-prod-12345", + "region": "us-east-1", + "db_username": "superset_iam_user", + "session_duration": 3600 + } +} +``` + +| Field | Required | Description | +|-------|----------|-------------| +| `enabled` | Yes | Set to `true` to activate IAM auth | +| `role_arn` | No | ARN of the cross-account IAM role to assume via STS. Omit for same-account auth | +| `external_id` | No | External ID for the STS `AssumeRole` call, if required by the target role's trust policy | +| `region` | Yes | AWS region of the database cluster | +| `db_username` | Yes | The database username associated with the IAM identity | +| `session_duration` | No | STS session duration in seconds (default: `3600`) | + +### Redshift (Serverless) + +```json +{ + "aws_iam": { + "enabled": true, + "role_arn": "arn:aws:iam::222222222222:role/SupersetRedshiftAccess", + "region": "us-east-1", + "workgroup_name": "my-workgroup", + "db_name": "dev" + } +} +``` + +### Redshift (Provisioned Cluster) + +```json +{ + "aws_iam": { + "enabled": true, + "role_arn": "arn:aws:iam::222222222222:role/SupersetRedshiftAccess", + "region": "us-east-1", + "cluster_identifier": "my-cluster", + "db_username": "superset_iam_user", + "db_name": "dev" + } +} +``` + +## Cross-Account IAM Setup + +To connect to a database in Account B from a Superset deployment in Account A: + +**1. In Account B — create a database-access role:** + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": ["rds-db:connect"], + "Resource": "arn:aws:rds-db:us-east-1:222222222222:dbuser/db-XXXXXXXXXXXX/superset_iam_user" + } + ] +} +``` + +**Trust policy** (allows Account A's Superset role to assume it): + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": "arn:aws:iam::111111111111:role/SupersetInstanceRole" + }, + "Action": "sts:AssumeRole", + "Condition": { + "StringEquals": { + "sts:ExternalId": "superset-prod-12345" + } + } + } + ] +} +``` + +**2. In Account A — grant Superset's role permission to assume the Account B role:** + +```json +{ + "Effect": "Allow", + "Action": "sts:AssumeRole", + "Resource": "arn:aws:iam::222222222222:role/SupersetDatabaseAccess" +} +``` + +**3. Configure the database connection in Superset** using the `role_arn` and `external_id` from the trust policy (as shown in the configuration example above). + +## Credential Caching + +STS credentials are cached in memory keyed by `(role_arn, region, external_id)` with a 10-minute TTL. This reduces the number of STS API calls when multiple queries are executed with the same connection. Tokens are refreshed automatically before expiry. diff --git a/docs/admin_docs/configuration/importing-exporting-datasources.mdx b/docs/admin_docs/configuration/importing-exporting-datasources.mdx index 400d64590adf..d21e50e3b8bb 100644 --- a/docs/admin_docs/configuration/importing-exporting-datasources.mdx +++ b/docs/admin_docs/configuration/importing-exporting-datasources.mdx @@ -75,6 +75,29 @@ The optional username flag **-u** sets the user used for the datasource import. superset import_datasources -p -u 'admin' ``` +## Dashboard Import Overwrite Behavior + +When importing a dashboard ZIP with the **overwrite** option enabled, any existing charts that are part of the dashboard are **replaced** rather than duplicated. This applies to: + +- Charts whose UUID matches a chart already present in the target instance +- The full chart configuration (query, visualization type, columns, metrics) is replaced by the imported version + +If you import without the overwrite flag, existing charts with conflicting UUIDs are left unchanged and the import skips those objects. Use overwrite when you want to push a fully updated dashboard (including chart definitions) from a development or staging environment to production. + +## UUIDs in API Responses + +The REST API POST endpoints for **datasets**, **charts**, and **dashboards** include the auto-generated `uuid` field in the response body: + +```json +{ + "id": 42, + "uuid": "b8a8d5c3-1234-4abc-8def-0123456789ab", + ... +} +``` + +UUIDs remain stable across import/export cycles and can be used for cross-environment workflows — for example, recording a UUID when creating a chart in development and using it to identify the matching chart after importing into production. + ## Legacy Importing Datasources ### From older versions of Superset to current version diff --git a/docs/admin_docs/configuration/mcp-server.mdx b/docs/admin_docs/configuration/mcp-server.mdx index 22a80d645b35..7738c1788e8a 100644 --- a/docs/admin_docs/configuration/mcp-server.mdx +++ b/docs/admin_docs/configuration/mcp-server.mdx @@ -501,6 +501,7 @@ All MCP settings go in `superset_config.py`. Defaults are defined in `superset/m | `MCP_SERVICE_URL` | `None` | Public base URL for MCP-generated links (set this when behind a reverse proxy) | | `MCP_DEBUG` | `False` | Enable debug logging | | `MCP_DEV_USERNAME` | -- | Superset username for development mode (no auth) | +| `MCP_PARSE_REQUEST_ENABLED` | `True` | Pre-parse MCP tool inputs from JSON strings into objects. Set to `False` for clients (Claude Desktop, LangChain) that do not double-serialize arguments — this produces cleaner tool schemas for those clients | ### Authentication @@ -664,6 +665,34 @@ MCP_CSRF_CONFIG = { --- +## Audit Events + +All MCP tool calls are logged to Superset's event logger, the same system used by the web UI (viewable at **Settings → Action Log**). Each event captures: + +- **Action**: `mcp..` (e.g., `mcp.list_databases.query`) +- **User**: the resolved Superset username from the JWT or dev config +- **Timestamp**: when the operation ran + +This means MCP activity is auditable alongside normal user activity. No additional configuration is required — logging is on by default whenever the event logger is enabled in your Superset deployment. + +## Tool Pagination + +All MCP list tools use **cursor-based pagination** (`cursor` / `next_cursor` fields) rather than offset pagination. To iterate through all results: + +```python +# Example: fetch all charts across pages +cursor = None +all_charts = [] +while True: + result = mcp.list_charts(cursor=cursor, page_size=50) + all_charts.extend(result["charts"]) + cursor = result.get("next_cursor") + if not cursor: + break +``` + +The `page` parameter from older integrations is no longer supported. Update any tooling that relied on offset pagination to use `cursor` / `next_cursor` instead. + ## Security Best Practices - **Use TLS** for all production MCP endpoints -- place the server behind a reverse proxy with HTTPS diff --git a/docs/docs/using-superset/creating-your-first-dashboard.mdx b/docs/docs/using-superset/creating-your-first-dashboard.mdx index febf3395a6f2..99a859818aff 100644 --- a/docs/docs/using-superset/creating-your-first-dashboard.mdx +++ b/docs/docs/using-superset/creating-your-first-dashboard.mdx @@ -63,6 +63,12 @@ by clicking the **Connect** button in the bottom right corner of the modal windo Congratulations, you've just added a new data source in Superset! +### Sharing a Database Connection + +When adding a new database, you can share the connection with other Superset users. Shared connections appear in other users' database lists, making it easier to collaborate on the same data without requiring each user to configure the same connection separately. + +To share a connection, enable the **Share connection with other users** option in the **Advanced** tab of the database connection modal before saving. You can change sharing settings later by editing the database connection. + ### Registering a new table Now that you’ve configured a data source, you can select specific tables (called **Datasets** in Superset) @@ -80,6 +86,22 @@ we register the **cleaned_sales_data** table from the **examples** database. To finish, click the **Add** button in the bottom right corner. You should now see your dataset in the list of datasets. +### Organizing Datasets into Folders + +The Datasets list view supports **folders** for organizing datasets into groups. To create and manage folders: + +1. In the **Datasets** list, click the **Folders** panel on the left sidebar. +2. Click **+ New Folder** to create a top-level folder, or drag an existing folder to nest it. +3. Drag dataset rows onto a folder to move them in, or right-click a dataset and select **Move to folder**. + +Folders are per-user organizational aids — they do not affect dataset access permissions or how other users see the datasets. + +### Uploading Files via the OS File Manager (PWA) + +When Superset is installed as a **Progressive Web App (PWA)** from your browser, your operating system will offer Superset as an option when opening CSV, Excel (`.xls`/`.xlsx`), and Parquet files. Double-clicking or right-clicking a supported file and selecting "Open with Superset" navigates directly to the upload workflow for that file. + +To install Superset as a PWA, look for the install icon in your browser's address bar (Chrome, Edge) when visiting your Superset instance over HTTPS. PWA installation requires HTTPS and a valid manifest — your admin needs to confirm the app manifest is served correctly. + ### Customizing column properties Now that you've registered your dataset, you can configure column properties @@ -234,6 +256,64 @@ For example, when running the local development build, the following will disabl Top Nav and remove the Filter Bar: `http://localhost:8088/superset/dashboard/my-dashboard/?standalone=1&show_filters=0` +### AG Grid Interactive Table + +The **AG Grid Interactive Table** chart type is Superset's fully-featured data grid, suitable for large paginated datasets where the standard Table chart is not enough. + +#### Server-Side Column Filters + +AG Grid supports server-side column filters that query the full dataset — not just the loaded page. Filters are applied before data is sent to the browser, so results are correct even across millions of rows. + +**Available filter types:** + +| Column type | Filter options | +|---|---| +| Text | Contains, equals, starts with, ends with | +| Number | Equals, not equal, less than, greater than, between | +| Date | Before, after, between, blank | +| Set | Select from a list of distinct values | + +**AND / OR logic:** Each column supports combining multiple conditions with AND or OR. Filters from different columns are always combined with AND. + +**Interaction with pagination:** Server-side filters run as WHERE clauses in the underlying SQL query, so pagination always operates over the already-filtered result set. + +#### Time Shift (Time Comparison) + +AG Grid Interactive Table supports **Time Shift** (time comparison), matching the behavior of the standard Table chart. In the **Advanced Analytics** → **Time Comparison** section of the chart configuration, enter a shift expression (e.g., `1 year ago`, `minus 7 days`) to add comparison columns showing values from the offset period. Dashboard-level time range overrides apply to both the base and comparison periods. + +### Dynamic Currency Formatting + +Chart metric values can display currencies dynamically rather than using a fixed currency code. To enable: + +1. Open the dataset editor for your dataset (**Datasets → Edit**). +2. In the **Advanced** tab, set **Currency Code Column** to the name of a column in your dataset that contains ISO 4217 currency codes (e.g., `USD`, `EUR`, `GBP`). +3. In the Explore chart configuration, open the metric's **Number format** section and select **Auto-detect** for currency. + +When Auto-detect is active, each row uses the currency code from the designated column, so a single chart can display values in multiple currencies — each formatted correctly for its currency. + +### ECharts Option Editor + +For ECharts-based chart types (line, bar, area, scatter, pie, and others), Explore includes an advanced **ECharts Option Editor** that accepts raw JSON overrides for the underlying ECharts configuration. + +Access it via the **Customize** tab → **ECharts Options** section at the bottom of the panel. The JSON you enter is deep-merged on top of Superset's generated ECharts config, so you can override specific options without rewriting the entire config. + +**Example:** override the legend position and add a custom title: + +```json +{ + "legend": { "orient": "vertical", "right": "5%", "top": "middle" }, + "title": { "text": "My Custom Title", "left": "center" } +} +``` + +:::caution +ECharts option overrides bypass Superset's validation layer. Invalid option keys are silently ignored by ECharts. Overrides that conflict with Superset-generated options (e.g., `series`) may produce unexpected results. +::: + +### Table Chart: Exporting Filtered Data + +When the **Search Box** is visible in a Table chart, the **Download** action exports only the rows currently visible after the search filter is applied — not the full underlying dataset. This matches the visual output and is intentional. To export the full dataset regardless of search state, use the **Download as CSV** option from the chart's three-dot menu in the dashboard or from the Explore chart toolbar before applying a search filter. + :::resources - [Dashboard Customization](https://docs.preset.io/docs/dashboard-customization) - Advanced dashboard styling and layout options - [Blog: BI Dashboard Best Practices](https://preset.io/blog/bi-dashboard-best-practices/) diff --git a/docs/docs/using-superset/embedding.mdx b/docs/docs/using-superset/embedding.mdx new file mode 100644 index 000000000000..8d4ade660365 --- /dev/null +++ b/docs/docs/using-superset/embedding.mdx @@ -0,0 +1,132 @@ +{/* +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +*/} + +--- +title: Embedding Superset +sidebar_position: 6 +--- + +# Embedding Superset + +Superset dashboards can be embedded directly in host applications using the `@superset-ui/embedded-sdk` package. + +:::info Prerequisites +- The `EMBEDDED_SUPERSET` feature flag must be enabled. +- The embedding domain and allowed origins must be configured by an admin. +::: + +## Quick Start + +Install the SDK: + +```bash +npm install @superset-ui/embedded-sdk +``` + +Embed a dashboard: + +```javascript +import { embedDashboard } from '@superset-ui/embedded-sdk'; + +embedDashboard({ + id: 'dashboard-uuid-here', // from Dashboard → Embed + supersetDomain: 'https://superset.example.com', + mountPoint: document.getElementById('superset-container'), + fetchGuestToken: () => fetchTokenFromYourBackend(), + dashboardUiConfig: { + hideTitle: true, + filters: { expanded: false }, + }, +}); +``` + +`fetchGuestToken` must return a **guest token** obtained from your server by calling Superset's `/api/v1/security/guest_token/` endpoint with a service account. Do not call this endpoint from client-side code. + +--- + +## Callbacks + +### `resolvePermalinkUrl` + +When a user copies a permalink from an embedded dashboard, Superset generates a URL on its own domain. In an embedded context this URL is usually not meaningful to the host application's users — the dashboard is rendered inside the host app, not at the Superset URL. + +The `resolvePermalinkUrl` callback lets the host app intercept permalink generation and return a URL on the host domain instead: + +```javascript +embedDashboard({ + id: 'my-dashboard-uuid', + supersetDomain: 'https://superset.example.com', + mountPoint: document.getElementById('superset-container'), + fetchGuestToken: () => fetchGuestToken(), + callbacks: { + /** + * Called when Superset generates a permalink. + * @param {Object} args - { key: string } — the permalink key + * @returns {string | null} - your host URL, or null to use Superset's default + */ + resolvePermalinkUrl: ({ key }) => { + return `https://myapp.example.com/dashboard?permalink=${key}`; + }, + }, +}); +``` + +If the callback returns `null` or is not provided, Superset uses its own permalink URL as a fallback. + +--- + +## Feature Flags for Embedded Mode + +### `DISABLE_EMBEDDED_SUPERSET_LOGOUT` + +Hides the logout button when Superset is embedded in a host application. This is useful when the host application manages the session lifecycle and you do not want users to accidentally log out of the embedded Superset session: + +```python +# superset_config.py +FEATURE_FLAGS = { + "EMBEDDED_SUPERSET": True, + "DISABLE_EMBEDDED_SUPERSET_LOGOUT": True, +} +``` + +When enabled, the **Logout** menu item is removed from the user avatar dropdown in the embedded view. The session can still be invalidated server-side by revoking the guest token. + +### `EMBEDDED_SUPERSET` + +Must be `True` to enable the embedded SDK and the guest token endpoint. Without this flag, `embedDashboard` will fail to load. + +--- + +## URL Parameters + +The following URL parameters can be passed through the `urlParams` option in `dashboardUiConfig` or appended to the embedded iframe URL: + +| Parameter | Values | Effect | +|-----------|--------|--------| +| `standalone` | `0`, `1`, `2`, `3` | `0`: normal; `1`: hide nav; `2`: hide nav + title; `3`: hide nav + title + tabs | +| `show_filters` | `0`, `1` | Show or hide the native filter bar | +| `expand_filters` | `0`, `1` | Start with filter bar expanded or collapsed | + +--- + +## Security Notes + +- **Guest tokens expire** — their lifetime is controlled by the `GUEST_TOKEN_JWT_EXP_SECONDS` config (default: 5 minutes). Refresh tokens before they expire using a token refresh mechanism in your host app. +- **Row-level security** — pass `rls` rules in the guest token request to restrict which rows are visible to the embedded user. +- **Allowed domains** — configure `SUPERSET_WEBSERVER_DOMAINS` to restrict which host origins can embed Superset. diff --git a/docs/docs/using-superset/exploring-data.mdx b/docs/docs/using-superset/exploring-data.mdx index 0cc812382aa1..8d83a0c2c63d 100644 --- a/docs/docs/using-superset/exploring-data.mdx +++ b/docs/docs/using-superset/exploring-data.mdx @@ -329,6 +329,27 @@ various options in this section, refer to the Lastly, save your chart as Tutorial Resample and add it to the Tutorial Dashboard. Go to the tutorial dashboard to see the four charts side by side and compare the different outputs. +### SQL Lab Tips + +**Schema and table browser**: The left-side table browser uses a collapsible treeview — click a schema to expand its tables, and click a table to see its columns and sample data inline. This makes navigating large schemas much faster than the previous flat list. + +**Find in editor**: Press **Ctrl+F** (or **Cmd+F** on Mac) to open the Monaco find/replace widget inside the SQL editor without leaving the editor. + +**Resizable panels**: The dividers between the SQL editor, schema browser, and results pane are draggable. Adjust them to match your workflow and screen size. + +**Dialect-aware Format SQL**: The **Format SQL** button applies the SQL dialect of the currently selected database — Trino, Presto, MySQL, PostgreSQL, etc. — rather than a generic formatter. Switch to a different database in the toolbar and re-format to get dialect-specific output. Jinja template syntax (`{{ }}`, `{% %}`) is preserved during formatting and will not cause format errors. + +### Time Range Natural Language Expressions + +The **Custom** time range picker accepts natural language expressions alongside specific dates: + +- **Relative**: `Last 7 days`, `Last month`, `Last quarter`, `Last year` +- **Anchored**: `previous calendar week`, `previous calendar month` +- **"First of" expressions**: `first day of this week`, `first day of this month`, `first day of this quarter`, `first day of this year`, `first week of this year` +- **Offsets**: `30 days ago`, `1 year ago`, `next week` + +These expressions are evaluated at query time, so saved charts always display data relative to the current date. + :::resources - [Chart Walkthroughs](https://docs.preset.io/docs/chart-walkthroughs) - Detailed guides for most chart types - [Blog: Why Apache ECharts is the Future of Apache Superset](https://preset.io/blog/2021-4-1-why-echarts/) diff --git a/docs/docs/using-superset/using-ai-with-superset.mdx b/docs/docs/using-superset/using-ai-with-superset.mdx index 3969042bcd2f..a4026bcd56ce 100644 --- a/docs/docs/using-superset/using-ai-with-superset.mdx +++ b/docs/docs/using-superset/using-ai-with-superset.mdx @@ -56,8 +56,8 @@ Ask your AI assistant to browse what's available in your Superset instance: Describe the visualization you want and AI creates it for you: - **Create charts from natural language** -- describe what you want to see and AI picks the right chart type, metrics, and dimensions -- **Preview before saving** -- AI generates a preview so you can review before committing -- **Modify existing charts** -- update filters, change chart types, add metrics +- **Preview before saving** -- `generate_chart` defaults to `save_chart=False`, showing the chart in Explore before it's committed. Ask AI to save once you're satisfied. +- **Modify existing charts** -- `update_chart` also supports preview mode so you can review changes before saving - **Get Explore links** -- open any chart in Superset's Explore view for further refinement **Example prompts:** @@ -195,27 +195,116 @@ Ask your admin for the MCP server URL and any authentication tokens you need. ## Available Tools Reference +### Exploration & Discovery + | Tool | Description | |------|-------------| | `health_check` | Verify the MCP server is running and connected | | `get_instance_info` | Get instance statistics (dataset, chart, dashboard counts) | +| `get_home_page_info` | Get a summary of home page resources | +| `get_superset_config_info` | Expose active Superset configuration details | | `get_schema` | Discover available charts, datasets, and dashboards with schema info | +| `list_recent_activity` | List recent activity from the activity feed | +| `list_chart_types` | Enumerate available chart types | + +### Datasets + +| Tool | Description | +|------|-------------| | `list_datasets` | List datasets with filtering and search | | `get_dataset_info` | Get dataset metadata (columns, metrics, filters) | +| `get_dataset_by_name` | Look up a dataset by name | + +### Charts + +| Tool | Description | +|------|-------------| | `list_charts` | List charts with filtering and search | | `get_chart_info` | Get chart metadata and configuration | +| `get_chart_by_name` | Look up a chart by name | | `get_chart_data` | Retrieve chart data (JSON, CSV, or Excel) | +| `get_chart_data_by_url` | Retrieve chart data from a chart URL | +| `get_chart_data_by_explore_url` | Retrieve chart data from an Explore URL | | `get_chart_preview` | Generate a chart preview (URL, ASCII, table, or Vega-Lite) | -| `generate_chart` | Create a new chart from a specification | -| `update_chart` | Modify an existing chart's configuration | +| `get_chart_thumbnail` | Fetch the cached thumbnail image for a chart | +| `generate_chart` | Create a new chart from a specification (defaults to preview mode — review before saving) | +| `update_chart` | Modify an existing chart's configuration (supports `save_chart=False` for preview mode) | | `update_chart_preview` | Update a cached chart preview without saving | +| `delete_chart` | Delete a chart | +| `list_chart_owners` | List the owners of a chart | +| `generate_explore_link` | Generate an Explore URL for interactive visualization | +| `get_explore_link` | Get an Explore link from MCP context | +| `get_explore_link_by_url` | Get an Explore link from a chart URL | +| `get_explore_thumbnail` | Fetch the cached thumbnail for an Explore view | +| `open_explore_link` | Open an Explore link in the browser | + +### Dashboards + +| Tool | Description | +|------|-------------| | `list_dashboards` | List dashboards with filtering and search | | `get_dashboard_info` | Get dashboard metadata and layout | +| `get_dashboard_by_name` | Look up a dashboard by name | +| `get_dashboard_thumbnail` | Fetch the cached thumbnail image for a dashboard | | `generate_dashboard` | Create a new dashboard with specified charts | +| `update_dashboard` | Modify an existing dashboard's metadata | +| `delete_dashboard` | Delete a dashboard | | `add_chart_to_existing_dashboard` | Add a chart to an existing dashboard | +| `remove_chart_from_dashboard` | Remove a chart from a dashboard | +| `move_chart_to_dashboard` | Move a chart from one dashboard to another | +| `update_chart_position` | Reposition a chart within a dashboard | +| `list_charts_in_dashboard` | List all charts within a specific dashboard | +| `list_dashboard_owners` | List the owners of a dashboard | +| `open_dashboard` | Open a dashboard in the browser | +| `add_filter_to_dashboard` | Add a native filter to a dashboard | +| `list_dashboard_filters` | List native filters on a dashboard | +| `update_dashboard_filter` | Update a native filter on a dashboard | +| `delete_dashboard_filter` | Remove a native filter from a dashboard | +| `get_dashboard_filter_info` | Get details about a specific dashboard filter | +| `set_tab_order` | Reorder tabs in a tabbed dashboard | +| `create_tab` | Add a new tab to a tabbed dashboard | +| `delete_tab` | Remove a tab from a tabbed dashboard | +| `rename_tab` | Rename a dashboard tab | + +### SQL & Saved Queries + +| Tool | Description | +|------|-------------| | `execute_sql` | Run a SQL query with RBAC enforcement | | `open_sql_lab_with_context` | Open SQL Lab with a pre-populated query | -| `generate_explore_link` | Generate an Explore URL for interactive visualization | +| `open_sql_in_browser` | Open a SQL query in the browser | +| `list_saved_queries` | List saved SQL queries from SQL Lab | +| `create_saved_query` | Create a new saved query | +| `update_saved_query` | Update an existing saved query | +| `delete_saved_query` | Delete a saved query | + +### Databases + +| Tool | Description | +|------|-------------| +| `list_databases` | List configured database connections | +| `get_database_info` | Get details about a specific database connection | +| `get_database_dialect_info` | Get dialect details for a database | + +### Reports & Alerts + +| Tool | Description | +|------|-------------| +| `list_reports` | List configured alerts and reports | +| `create_report` | Create a new alert or report | +| `update_report` | Update an existing alert or report | +| `delete_report` | Delete a report | +| `get_report_info` | Get details about a specific report | + +### Users, Roles & Permissions + +| Tool | Description | +|------|-------------| +| `get_users` | List users in the Superset instance | +| `list_roles` | List all roles | +| `get_role_info` | Get details and permissions for a specific role | +| `list_permissions` | List all available permissions | +| `get_permission_info` | Get details about a specific permission | --- From b0f1dcbe0a5b5ce0acd97737d972fea0f37d470f Mon Sep 17 00:00:00 2001 From: Superset Dev Date: Mon, 20 Apr 2026 08:59:57 -0700 Subject: [PATCH 2/2] fix(docs): address review feedback on batch 5 docs - mcp-server: correct pagination example to use page/page_size/has_next (MCP list tools use offset pagination, not cursor-based) - using-ai-with-superset: prune tools reference to only tools registered in superset.mcp_service; fix update_chart preview parameter name (generate_preview, not save_chart); drop save_sql_query misname - aws-iam: add AWS_DATABASE_IAM_AUTH feature-flag prerequisite; list redshift-serverless:GetWorkgroup alongside GetCredentials - embedding: move resolvePermalinkUrl to top-level of embedDashboard options (no callbacks wrapper); correct allowed-domains guidance to per-dashboard setting rather than SUPERSET_WEBSERVER_DOMAINS - importing-exporting-datasources: clarify in intro that ZIP import/ export covers dashboards, charts, and saved queries too Co-Authored-By: Claude Opus 4.7 --- docs/admin_docs/configuration/aws-iam.mdx | 11 ++- .../importing-exporting-datasources.mdx | 4 ++ docs/admin_docs/configuration/mcp-server.mdx | 12 ++-- docs/docs/using-superset/embedding.mdx | 18 +++-- .../using-superset/using-ai-with-superset.mdx | 69 ++----------------- 5 files changed, 33 insertions(+), 81 deletions(-) diff --git a/docs/admin_docs/configuration/aws-iam.mdx b/docs/admin_docs/configuration/aws-iam.mdx index d777935e4689..e3fac57508f8 100644 --- a/docs/admin_docs/configuration/aws-iam.mdx +++ b/docs/admin_docs/configuration/aws-iam.mdx @@ -31,11 +31,20 @@ Cross-account IAM role assumption via STS `AssumeRole` is supported, allowing a ## Prerequisites +- Enable the `AWS_DATABASE_IAM_AUTH` feature flag in `superset_config.py`. IAM authentication is gated behind this flag; if it is disabled, connections using `aws_iam` fail with *"AWS IAM database authentication is not enabled."* + ```python + FEATURE_FLAGS = { + "AWS_DATABASE_IAM_AUTH": True, + } + ``` - `boto3` must be installed in your Superset environment: ```bash pip install boto3 ``` -- The Superset server's IAM role (or static credentials) must have permission to call `sts:AssumeRole` (for cross-account) or `rds-db:connect` / `redshift:GetClusterCredentials` (for same-account). +- The Superset server's IAM role (or static credentials) must have permission to call `sts:AssumeRole` (for cross-account) or the same-account permissions for the target service: + - **Aurora (RDS)**: `rds-db:connect` + - **Redshift provisioned**: `redshift:GetClusterCredentials` + - **Redshift Serverless**: `redshift-serverless:GetCredentials` and `redshift-serverless:GetWorkgroup` - SSL must be enabled on the Aurora / Redshift endpoint (required for IAM token auth). ## Configuration diff --git a/docs/admin_docs/configuration/importing-exporting-datasources.mdx b/docs/admin_docs/configuration/importing-exporting-datasources.mdx index d21e50e3b8bb..dadc5e0d4a7e 100644 --- a/docs/admin_docs/configuration/importing-exporting-datasources.mdx +++ b/docs/admin_docs/configuration/importing-exporting-datasources.mdx @@ -10,6 +10,10 @@ version: 1 The superset cli allows you to import and export datasources from and to YAML. Datasources include databases. The data is expected to be organized in the following hierarchy: +:::info +Superset's ZIP-based import/export also covers **dashboards**, **charts**, and **saved queries**, exercised through the UI and REST API. The [Dashboard Import Overwrite Behavior](#dashboard-import-overwrite-behavior) and [UUIDs in API Responses](#uuids-in-api-responses) sections below document the behavior shared across all asset types. +::: + ```text ├──databases | ├──database_1 diff --git a/docs/admin_docs/configuration/mcp-server.mdx b/docs/admin_docs/configuration/mcp-server.mdx index 7738c1788e8a..1475f3d6468e 100644 --- a/docs/admin_docs/configuration/mcp-server.mdx +++ b/docs/admin_docs/configuration/mcp-server.mdx @@ -677,22 +677,20 @@ This means MCP activity is auditable alongside normal user activity. No addition ## Tool Pagination -All MCP list tools use **cursor-based pagination** (`cursor` / `next_cursor` fields) rather than offset pagination. To iterate through all results: +MCP list tools (`list_datasets`, `list_charts`, `list_dashboards`, `list_databases`) use **offset pagination** via `page` (1-based) and `page_size` parameters. Responses include `page`, `page_size`, `total_count`, `total_pages`, `has_previous`, and `has_next`. To iterate through all results: ```python # Example: fetch all charts across pages -cursor = None all_charts = [] +page = 1 while True: - result = mcp.list_charts(cursor=cursor, page_size=50) + result = mcp.list_charts(page=page, page_size=50) all_charts.extend(result["charts"]) - cursor = result.get("next_cursor") - if not cursor: + if not result.get("has_next"): break + page += 1 ``` -The `page` parameter from older integrations is no longer supported. Update any tooling that relied on offset pagination to use `cursor` / `next_cursor` instead. - ## Security Best Practices - **Use TLS** for all production MCP endpoints -- place the server behind a reverse proxy with HTTPS diff --git a/docs/docs/using-superset/embedding.mdx b/docs/docs/using-superset/embedding.mdx index 8d4ade660365..59f561084b68 100644 --- a/docs/docs/using-superset/embedding.mdx +++ b/docs/docs/using-superset/embedding.mdx @@ -74,15 +74,13 @@ embedDashboard({ supersetDomain: 'https://superset.example.com', mountPoint: document.getElementById('superset-container'), fetchGuestToken: () => fetchGuestToken(), - callbacks: { - /** - * Called when Superset generates a permalink. - * @param {Object} args - { key: string } — the permalink key - * @returns {string | null} - your host URL, or null to use Superset's default - */ - resolvePermalinkUrl: ({ key }) => { - return `https://myapp.example.com/dashboard?permalink=${key}`; - }, + /** + * Called when Superset generates a permalink. + * @param {Object} args - { key: string } — the permalink key + * @returns {string | null} - your host URL, or null to use Superset's default + */ + resolvePermalinkUrl: ({ key }) => { + return `https://myapp.example.com/dashboard?permalink=${key}`; }, }); ``` @@ -129,4 +127,4 @@ The following URL parameters can be passed through the `urlParams` option in `da - **Guest tokens expire** — their lifetime is controlled by the `GUEST_TOKEN_JWT_EXP_SECONDS` config (default: 5 minutes). Refresh tokens before they expire using a token refresh mechanism in your host app. - **Row-level security** — pass `rls` rules in the guest token request to restrict which rows are visible to the embedded user. -- **Allowed domains** — configure `SUPERSET_WEBSERVER_DOMAINS` to restrict which host origins can embed Superset. +- **Allowed domains** — restrict which host origins can embed a dashboard by setting **Allowed Domains** per-dashboard in the *Embed* settings modal. Superset checks the request's `Referer` header against this list before serving the embedded view; an empty list allows any origin, so configure this explicitly for production. diff --git a/docs/docs/using-superset/using-ai-with-superset.mdx b/docs/docs/using-superset/using-ai-with-superset.mdx index a4026bcd56ce..67becfd9482e 100644 --- a/docs/docs/using-superset/using-ai-with-superset.mdx +++ b/docs/docs/using-superset/using-ai-with-superset.mdx @@ -201,11 +201,7 @@ Ask your admin for the MCP server URL and any authentication tokens you need. |------|-------------| | `health_check` | Verify the MCP server is running and connected | | `get_instance_info` | Get instance statistics (dataset, chart, dashboard counts) | -| `get_home_page_info` | Get a summary of home page resources | -| `get_superset_config_info` | Expose active Superset configuration details | | `get_schema` | Discover available charts, datasets, and dashboards with schema info | -| `list_recent_activity` | List recent activity from the activity feed | -| `list_chart_types` | Enumerate available chart types | ### Datasets @@ -213,7 +209,7 @@ Ask your admin for the MCP server URL and any authentication tokens you need. |------|-------------| | `list_datasets` | List datasets with filtering and search | | `get_dataset_info` | Get dataset metadata (columns, metrics, filters) | -| `get_dataset_by_name` | Look up a dataset by name | +| `create_virtual_dataset` | Create a virtual dataset from a SQL query | ### Charts @@ -221,22 +217,13 @@ Ask your admin for the MCP server URL and any authentication tokens you need. |------|-------------| | `list_charts` | List charts with filtering and search | | `get_chart_info` | Get chart metadata and configuration | -| `get_chart_by_name` | Look up a chart by name | | `get_chart_data` | Retrieve chart data (JSON, CSV, or Excel) | -| `get_chart_data_by_url` | Retrieve chart data from a chart URL | -| `get_chart_data_by_explore_url` | Retrieve chart data from an Explore URL | | `get_chart_preview` | Generate a chart preview (URL, ASCII, table, or Vega-Lite) | -| `get_chart_thumbnail` | Fetch the cached thumbnail image for a chart | +| `get_chart_type_schema` | Get the configuration schema for a chart type | | `generate_chart` | Create a new chart from a specification (defaults to preview mode — review before saving) | -| `update_chart` | Modify an existing chart's configuration (supports `save_chart=False` for preview mode) | +| `update_chart` | Modify an existing chart's configuration (pass `generate_preview=False` to persist immediately instead of returning a preview URL) | | `update_chart_preview` | Update a cached chart preview without saving | -| `delete_chart` | Delete a chart | -| `list_chart_owners` | List the owners of a chart | | `generate_explore_link` | Generate an Explore URL for interactive visualization | -| `get_explore_link` | Get an Explore link from MCP context | -| `get_explore_link_by_url` | Get an Explore link from a chart URL | -| `get_explore_thumbnail` | Fetch the cached thumbnail for an Explore view | -| `open_explore_link` | Open an Explore link in the browser | ### Dashboards @@ -244,39 +231,16 @@ Ask your admin for the MCP server URL and any authentication tokens you need. |------|-------------| | `list_dashboards` | List dashboards with filtering and search | | `get_dashboard_info` | Get dashboard metadata and layout | -| `get_dashboard_by_name` | Look up a dashboard by name | -| `get_dashboard_thumbnail` | Fetch the cached thumbnail image for a dashboard | | `generate_dashboard` | Create a new dashboard with specified charts | -| `update_dashboard` | Modify an existing dashboard's metadata | -| `delete_dashboard` | Delete a dashboard | | `add_chart_to_existing_dashboard` | Add a chart to an existing dashboard | -| `remove_chart_from_dashboard` | Remove a chart from a dashboard | -| `move_chart_to_dashboard` | Move a chart from one dashboard to another | -| `update_chart_position` | Reposition a chart within a dashboard | -| `list_charts_in_dashboard` | List all charts within a specific dashboard | -| `list_dashboard_owners` | List the owners of a dashboard | -| `open_dashboard` | Open a dashboard in the browser | -| `add_filter_to_dashboard` | Add a native filter to a dashboard | -| `list_dashboard_filters` | List native filters on a dashboard | -| `update_dashboard_filter` | Update a native filter on a dashboard | -| `delete_dashboard_filter` | Remove a native filter from a dashboard | -| `get_dashboard_filter_info` | Get details about a specific dashboard filter | -| `set_tab_order` | Reorder tabs in a tabbed dashboard | -| `create_tab` | Add a new tab to a tabbed dashboard | -| `delete_tab` | Remove a tab from a tabbed dashboard | -| `rename_tab` | Rename a dashboard tab | - -### SQL & Saved Queries + +### SQL | Tool | Description | |------|-------------| | `execute_sql` | Run a SQL query with RBAC enforcement | +| `save_sql_query` | Persist a SQL query to SQL Lab's saved queries | | `open_sql_lab_with_context` | Open SQL Lab with a pre-populated query | -| `open_sql_in_browser` | Open a SQL query in the browser | -| `list_saved_queries` | List saved SQL queries from SQL Lab | -| `create_saved_query` | Create a new saved query | -| `update_saved_query` | Update an existing saved query | -| `delete_saved_query` | Delete a saved query | ### Databases @@ -284,27 +248,6 @@ Ask your admin for the MCP server URL and any authentication tokens you need. |------|-------------| | `list_databases` | List configured database connections | | `get_database_info` | Get details about a specific database connection | -| `get_database_dialect_info` | Get dialect details for a database | - -### Reports & Alerts - -| Tool | Description | -|------|-------------| -| `list_reports` | List configured alerts and reports | -| `create_report` | Create a new alert or report | -| `update_report` | Update an existing alert or report | -| `delete_report` | Delete a report | -| `get_report_info` | Get details about a specific report | - -### Users, Roles & Permissions - -| Tool | Description | -|------|-------------| -| `get_users` | List users in the Superset instance | -| `list_roles` | List all roles | -| `get_role_info` | Get details and permissions for a specific role | -| `list_permissions` | List all available permissions | -| `get_permission_info` | Get details about a specific permission | ---